1 /* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef ANDROID_AUDIO_FIFO_INDEX_H 18 #define ANDROID_AUDIO_FIFO_INDEX_H 19 20 #include <atomic> 21 #include <stdint.h> 22 #include <time.h> 23 24 /** 25 * An index that may optionally be placed in shared memory. 26 * Must be Plain Old Data (POD), so no virtual methods are allowed. 27 * If in shared memory, exactly one process must explicitly call the constructor via placement new. 28 * \see #audio_utils_fifo_sync 29 */ 30 class audio_utils_fifo_index { 31 32 public: 33 audio_utils_fifo_index() : mIndex(0) { } 34 ~audio_utils_fifo_index() { } 35 36 /** 37 * Load value of index now with memory order 'acquire'. 38 * 39 * \return Index value 40 */ 41 uint32_t loadAcquire(); 42 43 /** 44 * Store new value into index now with memory order 'release'. 45 * 46 * \param value New value to store into index 47 */ 48 void storeRelease(uint32_t value); 49 50 // TODO op should be set in the constructor. 51 /** 52 * Wait for value of index to change from the specified expected value. 53 * 54 * \param op Either FUTEX_WAIT or FUTEX_WAIT_PRIVATE. 55 * \param timeout Indicates the maximum time to block while waiting for value to change. 56 * NULL means to block forever. 57 * Time is expressed as relative CLOCK_MONOTONIC. 58 * We use the Linux kernel representation of time for the very lowest levels, 59 * and save other representations for the APIs that are built on top of this. 60 * This permits APIs to choose the int64_t representation if desired, or the 61 * Linux representation without a double conversion. 62 * 63 * \return Zero for success, or a negative error code as specified at "man 2 futex". 64 */ 65 int wait(int op, uint32_t expected, const struct timespec *timeout); 66 67 // TODO op should be set in the constructor. 68 /** 69 * Wake up any threads waiting for the value of index to change. 70 * 71 * \param op Either FUTEX_WAIT or FUTEX_WAIT_PRIVATE. 72 * \param waiters Maximum number of waiting threads to wake up. 73 * 74 * \return Actual number of threads woken up. 75 */ 76 int wake(int op, int waiters = 1); 77 78 // specialized use only, prefer loadAcquire in most cases 79 uint32_t loadConsume(); 80 81 private: 82 // Linux futex is 32 bits regardless of platform. 83 // It would make more sense to declare this as atomic_uint32_t, but there is no such type name. 84 // TODO Support 64-bit index with 32-bit futex in low-order bits. 85 std::atomic_uint_least32_t mIndex; // accessed by both sides using atomic operations 86 static_assert(sizeof(mIndex) == sizeof(uint32_t), "mIndex must be 32 bits"); 87 }; 88 89 static_assert(sizeof(audio_utils_fifo_index) == sizeof(uint32_t), 90 "audio_utils_fifo_index must be 32 bits"); 91 92 // TODO 93 // From a design POV, these next two classes should be related. 94 // Extract a base class (that shares their property of being a reference to a fifo index) 95 // This should be good in the case if there is a need for generic manipulations on these references. 96 // Or can we perhaps define a template and make two specializations of it. 97 // This is in the case when compile-time polymorphism is sufficient. 98 99 /** 100 * A reference to an audio_utils_fifo_index with deferred store-release and deferred wake. 101 * 102 * TODO Currently the index and futex share the same 32-bit cell. 103 * In the future, the index may optionally be increased to 64-bits, 104 * and the futex will either be the low-order 32 bits of the index, 105 * or an unrelated 32-bit cell used as a set of event flags. 106 * Both of these will require a change to the API. 107 */ 108 class RefIndexDeferredStoreReleaseDeferredWake 109 { 110 public: 111 RefIndexDeferredStoreReleaseDeferredWake(audio_utils_fifo_index& index); 112 ~RefIndexDeferredStoreReleaseDeferredWake(); 113 114 // Place 'value' into the cache but do not store it to memory yet. 115 void set(uint32_t value); 116 117 // If there is a new value in the cache, store it now with memory order 'release'. 118 void writeback(); 119 120 // Place 'value' into the cache and then store it with memory order 'release'. 121 void writethrough(uint32_t value); 122 123 // op is FUTEX_WAKE or FUTEX_WAKE_PRIVATE 124 // TODO op should be set in the constructor, and should be abstracted. 125 // waiters is number of waiting threads to wake up 126 void wakeDeferred(int op, int waiters = 1); 127 void wakeNowIfNeeded(); 128 // TODO op should be set in the constructor. 129 void wakeNow(int op, int waiters = 1); 130 131 private: 132 audio_utils_fifo_index& mIndex; // reference to associated index 133 uint32_t mValue; // cached value to be stored 134 bool mWriteback; // whether the cached value needs to be stored 135 int mWaiters; // number of waiters to wake 136 int mWakeOp; // which kind of wake operation to use 137 }; 138 139 /** 140 * A reference to an audio_utils_fifo_index with cached load-acquire, and deferred wait. 141 * 142 * TODO Same as RefIndexDeferredStoreReleaseDeferredWake. 143 */ 144 class RefIndexCachedLoadAcquireDeferredWait 145 { 146 public: 147 RefIndexCachedLoadAcquireDeferredWait(audio_utils_fifo_index& index); 148 ~RefIndexCachedLoadAcquireDeferredWait(); 149 150 // If value is already cached, return the cached value. 151 // Otherwise load now with memory order 'acquire', cache for later, and return the value. 152 uint32_t get(); 153 154 // If value is already cached, this is a no-op. 155 // Otherwise load now with memory order 'acquire' and cache the value for later use. 156 void prefetch(); 157 158 // Discard any value in the cache. 159 void invalidate(); 160 161 #if 0 162 /** 163 * Load a fresh value for index, ignoring any previously cached information. 164 */ 165 uint32_t readthrough(); 166 #endif 167 168 // TODO This is an immediate wait, but we needed deferred wait 169 /** 170 * Wait for value of index to change from when it was most recently read with get(). 171 * To avoid a race condition, the caller must have already read the index with get(), 172 * and then made the decision to call wait() based on that value. 173 * 174 * \param op Either FUTEX_WAIT or FUTEX_WAIT_PRIVATE. 175 * \param timeout Indicates the maximum time to block while waiting for value to change. 176 * NULL means to block forever. 177 * Time is expressed as relative CLOCK_MONOTONIC. 178 * See above for explanation of why representation is struct timespec. 179 * 180 * \return Zero for success, or a negative error code as specified at "man 2 futex". 181 * \retval -EINVAL caller did not call get() prior to wait() 182 */ 183 int wait(int op, const struct timespec *timeout); 184 185 private: 186 audio_utils_fifo_index& mIndex; // reference to associated index 187 uint32_t mValue; // most recently cached value 188 bool mLoaded; // whether mValue is valid 189 }; 190 191 #endif // !ANDROID_AUDIO_FIFO_INDEX_H 192
