AudioTrackShared.h revision 751a9c8cbc391a91604dd1052fb95d3e4d278c2f
1/* 2 * Copyright (C) 2007 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_TRACK_SHARED_H 18#define ANDROID_AUDIO_TRACK_SHARED_H 19 20#include <stdint.h> 21#include <sys/types.h> 22 23#include <utils/threads.h> 24#include <utils/Log.h> 25#include <utils/RefBase.h> 26#include <media/nbaio/roundup.h> 27#include <media/SingleStateQueue.h> 28#include <private/media/StaticAudioTrackState.h> 29 30namespace android { 31 32// ---------------------------------------------------------------------------- 33 34// for audio_track_cblk_t::mFlags 35#define CBLK_UNDERRUN 0x01 // set by server immediately on output underrun, cleared by client 36#define CBLK_FORCEREADY 0x02 // set: track is considered ready immediately by AudioFlinger, 37 // clear: track is ready when buffer full 38#define CBLK_INVALID 0x04 // track buffer invalidated by AudioFlinger, need to re-create 39#define CBLK_DISABLED 0x08 // output track disabled by AudioFlinger due to underrun, 40 // need to re-start. Unlike CBLK_UNDERRUN, this is not set 41 // immediately, but only after a long string of underruns. 42// 0x10 unused 43#define CBLK_LOOP_CYCLE 0x20 // set by server each time a loop cycle other than final one completes 44#define CBLK_LOOP_FINAL 0x40 // set by server when the final loop cycle completes 45#define CBLK_BUFFER_END 0x80 // set by server when the position reaches end of buffer if not looping 46#define CBLK_OVERRUN 0x100 // set by server immediately on input overrun, cleared by client 47#define CBLK_INTERRUPT 0x200 // set by client on interrupt(), cleared by client in obtainBuffer() 48#define CBLK_STREAM_END_DONE 0x400 // set by server on render completion, cleared by client 49 50//EL_FIXME 20 seconds may not be enough and must be reconciled with new obtainBuffer implementation 51#define MAX_RUN_OFFLOADED_TIMEOUT_MS 20000 //assuming upto a maximum of 20 seconds of offloaded 52 53struct AudioTrackSharedStreaming { 54 // similar to NBAIO MonoPipe 55 // in continuously incrementing frame units, take modulo buffer size, which must be a power of 2 56 volatile int32_t mFront; // read by server 57 volatile int32_t mRear; // write by client 58 volatile int32_t mFlush; // incremented by client to indicate a request to flush; 59 // server notices and discards all data between mFront and mRear 60 volatile uint32_t mUnderrunFrames; // server increments for each unavailable but desired frame 61}; 62 63typedef SingleStateQueue<StaticAudioTrackState> StaticAudioTrackSingleStateQueue; 64 65struct AudioTrackSharedStatic { 66 StaticAudioTrackSingleStateQueue::Shared 67 mSingleStateQueue; 68 // This field should be a size_t, but since it is located in shared memory we 69 // force to 32-bit. The client and server may have different typedefs for size_t. 70 uint32_t mBufferPosition; // updated asynchronously by server, 71 // "for entertainment purposes only" 72}; 73 74// ---------------------------------------------------------------------------- 75 76// Important: do not add any virtual methods, including ~ 77struct audio_track_cblk_t 78{ 79 // Since the control block is always located in shared memory, this constructor 80 // is only used for placement new(). It is never used for regular new() or stack. 81 audio_track_cblk_t(); 82 /*virtual*/ ~audio_track_cblk_t() { } 83 84 friend class Proxy; 85 friend class ClientProxy; 86 friend class AudioTrackClientProxy; 87 friend class AudioRecordClientProxy; 88 friend class ServerProxy; 89 friend class AudioTrackServerProxy; 90 friend class AudioRecordServerProxy; 91 92 // The data members are grouped so that members accessed frequently and in the same context 93 // are in the same line of data cache. 94 95 uint32_t mServer; // Number of filled frames consumed by server (mIsOut), 96 // or filled frames provided by server (!mIsOut). 97 // It is updated asynchronously by server without a barrier. 98 // The value should be used "for entertainment purposes only", 99 // which means don't make important decisions based on it. 100 101 size_t frameCount_; // used during creation to pass actual track buffer size 102 // from AudioFlinger to client, and not referenced again 103 // FIXME remove here and replace by createTrack() in/out 104 // parameter 105 // renamed to "_" to detect incorrect use 106 107 volatile int32_t mFutex; // event flag: down (P) by client, 108 // up (V) by server or binderDied() or interrupt() 109#define CBLK_FUTEX_WAKE 1 // if event flag bit is set, then a deferred wake is pending 110 111private: 112 113 // This field should be a size_t, but since it is located in shared memory we 114 // force to 32-bit. The client and server may have different typedefs for size_t. 115 uint32_t mMinimum; // server wakes up client if available >= mMinimum 116 117 // Channel volumes are fixed point U4.12, so 0x1000 means 1.0. 118 // Left channel is in [0:15], right channel is in [16:31]. 119 // Always read and write the combined pair atomically. 120 // For AudioTrack only, not used by AudioRecord. 121 uint32_t mVolumeLR; 122 123 uint32_t mSampleRate; // AudioTrack only: client's requested sample rate in Hz 124 // or 0 == default. Write-only client, read-only server. 125 126 // client write-only, server read-only 127 uint16_t mSendLevel; // Fixed point U4.12 so 0x1000 means 1.0 128 129 uint16_t mPad2; // unused 130 131public: 132 133 volatile int32_t mFlags; // combinations of CBLK_* 134 135 // Cache line boundary (32 bytes) 136 137public: 138 union { 139 AudioTrackSharedStreaming mStreaming; 140 AudioTrackSharedStatic mStatic; 141 int mAlign[8]; 142 } u; 143 144 // Cache line boundary (32 bytes) 145}; 146 147// ---------------------------------------------------------------------------- 148 149// Proxy for shared memory control block, to isolate callers from needing to know the details. 150// There is exactly one ClientProxy and one ServerProxy per shared memory control block. 151// The proxies are located in normal memory, and are not multi-thread safe within a given side. 152class Proxy : public RefBase { 153protected: 154 Proxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount, size_t frameSize, bool isOut, 155 bool clientInServer); 156 virtual ~Proxy() { } 157 158public: 159 struct Buffer { 160 size_t mFrameCount; // number of frames available in this buffer 161 void* mRaw; // pointer to first frame 162 size_t mNonContig; // number of additional non-contiguous frames available 163 }; 164 165protected: 166 // These refer to shared memory, and are virtual addresses with respect to the current process. 167 // They may have different virtual addresses within the other process. 168 audio_track_cblk_t* const mCblk; // the control block 169 void* const mBuffers; // starting address of buffers 170 171 const size_t mFrameCount; // not necessarily a power of 2 172 const size_t mFrameSize; // in bytes 173 const size_t mFrameCountP2; // mFrameCount rounded to power of 2, streaming mode 174 const bool mIsOut; // true for AudioTrack, false for AudioRecord 175 const bool mClientInServer; // true for OutputTrack, false for AudioTrack & AudioRecord 176 bool mIsShutdown; // latch set to true when shared memory corruption detected 177 size_t mUnreleased; // unreleased frames remaining from most recent obtainBuffer 178}; 179 180// ---------------------------------------------------------------------------- 181 182// Proxy seen by AudioTrack client and AudioRecord client 183class ClientProxy : public Proxy { 184protected: 185 ClientProxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount, size_t frameSize, 186 bool isOut, bool clientInServer); 187 virtual ~ClientProxy() { } 188 189public: 190 static const struct timespec kForever; 191 static const struct timespec kNonBlocking; 192 193 // Obtain a buffer with filled frames (reading) or empty frames (writing). 194 // It is permitted to call obtainBuffer() multiple times in succession, without any intervening 195 // calls to releaseBuffer(). In that case, the final obtainBuffer() is the one that effectively 196 // sets or extends the unreleased frame count. 197 // On entry: 198 // buffer->mFrameCount should be initialized to maximum number of desired frames, 199 // which must be > 0. 200 // buffer->mNonContig is unused. 201 // buffer->mRaw is unused. 202 // requested is the requested timeout in local monotonic delta time units: 203 // NULL or &kNonBlocking means non-blocking (zero timeout). 204 // &kForever means block forever (infinite timeout). 205 // Other values mean a specific timeout in local monotonic delta time units. 206 // elapsed is a pointer to a location that will hold the total local monotonic time that 207 // elapsed while blocked, or NULL if not needed. 208 // On exit: 209 // buffer->mFrameCount has the actual number of contiguous available frames, 210 // which is always 0 when the return status != NO_ERROR. 211 // buffer->mNonContig is the number of additional non-contiguous available frames. 212 // buffer->mRaw is a pointer to the first available frame, 213 // or NULL when buffer->mFrameCount == 0. 214 // The return status is one of: 215 // NO_ERROR Success, buffer->mFrameCount > 0. 216 // WOULD_BLOCK Non-blocking mode and no frames are available. 217 // TIMED_OUT Timeout occurred before any frames became available. 218 // This can happen even for infinite timeout, due to a spurious wakeup. 219 // In this case, the caller should investigate and then re-try as appropriate. 220 // DEAD_OBJECT Server has died or invalidated, caller should destroy this proxy and re-create. 221 // -EINTR Call has been interrupted. Look around to see why, and then perhaps try again. 222 // NO_INIT Shared memory is corrupt. 223 // Assertion failure on entry, if buffer == NULL or buffer->mFrameCount == 0. 224 status_t obtainBuffer(Buffer* buffer, const struct timespec *requested = NULL, 225 struct timespec *elapsed = NULL); 226 227 // Release (some of) the frames last obtained. 228 // On entry, buffer->mFrameCount should have the number of frames to release, 229 // which must (cumulatively) be <= the number of frames last obtained but not yet released. 230 // buffer->mRaw is ignored, but is normally same pointer returned by last obtainBuffer(). 231 // It is permitted to call releaseBuffer() multiple times to release the frames in chunks. 232 // On exit: 233 // buffer->mFrameCount is zero. 234 // buffer->mRaw is NULL. 235 void releaseBuffer(Buffer* buffer); 236 237 // Call after detecting server's death 238 void binderDied(); 239 240 // Call to force an obtainBuffer() to return quickly with -EINTR 241 void interrupt(); 242 243 size_t getPosition() { 244 return mEpoch + mCblk->mServer; 245 } 246 247 void setEpoch(size_t epoch) { 248 mEpoch = epoch; 249 } 250 251 void setMinimum(size_t minimum) { 252 // This can only happen on a 64-bit client 253 if (minimum > UINT32_MAX) { 254 minimum = UINT32_MAX; 255 } 256 mCblk->mMinimum = (uint32_t) minimum; 257 } 258 259 // Return the number of frames that would need to be obtained and released 260 // in order for the client to be aligned at start of buffer 261 virtual size_t getMisalignment(); 262 263 size_t getEpoch() const { 264 return mEpoch; 265 } 266 267 size_t getFramesFilled(); 268 269private: 270 size_t mEpoch; 271}; 272 273// ---------------------------------------------------------------------------- 274 275// Proxy used by AudioTrack client, which also includes AudioFlinger::PlaybackThread::OutputTrack 276class AudioTrackClientProxy : public ClientProxy { 277public: 278 AudioTrackClientProxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount, 279 size_t frameSize, bool clientInServer = false) 280 : ClientProxy(cblk, buffers, frameCount, frameSize, true /*isOut*/, 281 clientInServer) { } 282 virtual ~AudioTrackClientProxy() { } 283 284 // No barriers on the following operations, so the ordering of loads/stores 285 // with respect to other parameters is UNPREDICTABLE. That's considered safe. 286 287 // caller must limit to 0.0 <= sendLevel <= 1.0 288 void setSendLevel(float sendLevel) { 289 mCblk->mSendLevel = uint16_t(sendLevel * 0x1000); 290 } 291 292 // caller must limit to 0 <= volumeLR <= 0x10001000 293 void setVolumeLR(uint32_t volumeLR) { 294 mCblk->mVolumeLR = volumeLR; 295 } 296 297 void setSampleRate(uint32_t sampleRate) { 298 mCblk->mSampleRate = sampleRate; 299 } 300 301 virtual void flush(); 302 303 virtual uint32_t getUnderrunFrames() const { 304 return mCblk->u.mStreaming.mUnderrunFrames; 305 } 306 307 bool clearStreamEndDone(); // and return previous value 308 309 bool getStreamEndDone() const; 310 311 status_t waitStreamEndDone(const struct timespec *requested); 312}; 313 314class StaticAudioTrackClientProxy : public AudioTrackClientProxy { 315public: 316 StaticAudioTrackClientProxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount, 317 size_t frameSize); 318 virtual ~StaticAudioTrackClientProxy() { } 319 320 virtual void flush(); 321 322#define MIN_LOOP 16 // minimum length of each loop iteration in frames 323 void setLoop(size_t loopStart, size_t loopEnd, int loopCount); 324 size_t getBufferPosition(); 325 326 virtual size_t getMisalignment() { 327 return 0; 328 } 329 330 virtual uint32_t getUnderrunFrames() const { 331 return 0; 332 } 333 334private: 335 StaticAudioTrackSingleStateQueue::Mutator mMutator; 336 size_t mBufferPosition; // so that getBufferPosition() appears to be synchronous 337}; 338 339// ---------------------------------------------------------------------------- 340 341// Proxy used by AudioRecord client 342class AudioRecordClientProxy : public ClientProxy { 343public: 344 AudioRecordClientProxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount, 345 size_t frameSize) 346 : ClientProxy(cblk, buffers, frameCount, frameSize, 347 false /*isOut*/, false /*clientInServer*/) { } 348 ~AudioRecordClientProxy() { } 349}; 350 351// ---------------------------------------------------------------------------- 352 353// Proxy used by AudioFlinger server 354class ServerProxy : public Proxy { 355protected: 356 ServerProxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount, size_t frameSize, 357 bool isOut, bool clientInServer); 358public: 359 virtual ~ServerProxy() { } 360 361 // Obtain a buffer with filled frames (writing) or empty frames (reading). 362 // It is permitted to call obtainBuffer() multiple times in succession, without any intervening 363 // calls to releaseBuffer(). In that case, the final obtainBuffer() is the one that effectively 364 // sets or extends the unreleased frame count. 365 // Always non-blocking. 366 // On entry: 367 // buffer->mFrameCount should be initialized to maximum number of desired frames, 368 // which must be > 0. 369 // buffer->mNonContig is unused. 370 // buffer->mRaw is unused. 371 // ackFlush is true iff being called from Track::start to acknowledge a pending flush. 372 // On exit: 373 // buffer->mFrameCount has the actual number of contiguous available frames, 374 // which is always 0 when the return status != NO_ERROR. 375 // buffer->mNonContig is the number of additional non-contiguous available frames. 376 // buffer->mRaw is a pointer to the first available frame, 377 // or NULL when buffer->mFrameCount == 0. 378 // The return status is one of: 379 // NO_ERROR Success, buffer->mFrameCount > 0. 380 // WOULD_BLOCK No frames are available. 381 // NO_INIT Shared memory is corrupt. 382 virtual status_t obtainBuffer(Buffer* buffer, bool ackFlush = false); 383 384 // Release (some of) the frames last obtained. 385 // On entry, buffer->mFrameCount should have the number of frames to release, 386 // which must (cumulatively) be <= the number of frames last obtained but not yet released. 387 // It is permitted to call releaseBuffer() multiple times to release the frames in chunks. 388 // buffer->mRaw is ignored, but is normally same pointer returned by last obtainBuffer(). 389 // On exit: 390 // buffer->mFrameCount is zero. 391 // buffer->mRaw is NULL. 392 virtual void releaseBuffer(Buffer* buffer); 393 394protected: 395 size_t mAvailToClient; // estimated frames available to client prior to releaseBuffer() 396 int32_t mFlush; // our copy of cblk->u.mStreaming.mFlush, for streaming output only 397}; 398 399// Proxy used by AudioFlinger for servicing AudioTrack 400class AudioTrackServerProxy : public ServerProxy { 401public: 402 AudioTrackServerProxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount, 403 size_t frameSize, bool clientInServer = false) 404 : ServerProxy(cblk, buffers, frameCount, frameSize, true /*isOut*/, clientInServer) { } 405protected: 406 virtual ~AudioTrackServerProxy() { } 407 408public: 409 // return value of these methods must be validated by the caller 410 uint32_t getSampleRate() const { return mCblk->mSampleRate; } 411 uint16_t getSendLevel_U4_12() const { return mCblk->mSendLevel; } 412 uint32_t getVolumeLR() const { return mCblk->mVolumeLR; } 413 414 // estimated total number of filled frames available to server to read, 415 // which may include non-contiguous frames 416 virtual size_t framesReady(); 417 418 // Currently AudioFlinger will call framesReady() for a fast track from two threads: 419 // FastMixer thread, and normal mixer thread. This is dangerous, as the proxy is intended 420 // to be called from at most one thread of server, and one thread of client. 421 // As a temporary workaround, this method informs the proxy implementation that it 422 // should avoid doing a state queue poll from within framesReady(). 423 // FIXME Change AudioFlinger to not call framesReady() from normal mixer thread. 424 virtual void framesReadyIsCalledByMultipleThreads() { } 425 426 bool setStreamEndDone(); // and return previous value 427 428 // Add to the tally of underrun frames, and inform client of underrun 429 virtual void tallyUnderrunFrames(uint32_t frameCount); 430 431 // Return the total number of frames which AudioFlinger desired but were unavailable, 432 // and thus which resulted in an underrun. 433 virtual uint32_t getUnderrunFrames() const { return mCblk->u.mStreaming.mUnderrunFrames; } 434 435 // Return the total number of frames that AudioFlinger has obtained and released 436 virtual size_t framesReleased() const { return mCblk->mServer; } 437}; 438 439class StaticAudioTrackServerProxy : public AudioTrackServerProxy { 440public: 441 StaticAudioTrackServerProxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount, 442 size_t frameSize); 443protected: 444 virtual ~StaticAudioTrackServerProxy() { } 445 446public: 447 virtual size_t framesReady(); 448 virtual void framesReadyIsCalledByMultipleThreads(); 449 virtual status_t obtainBuffer(Buffer* buffer, bool ackFlush); 450 virtual void releaseBuffer(Buffer* buffer); 451 virtual void tallyUnderrunFrames(uint32_t frameCount); 452 virtual uint32_t getUnderrunFrames() const { return 0; } 453 454private: 455 ssize_t pollPosition(); // poll for state queue update, and return current position 456 StaticAudioTrackSingleStateQueue::Observer mObserver; 457 size_t mPosition; // server's current play position in frames, relative to 0 458 size_t mEnd; // cached value computed from mState, safe for asynchronous read 459 bool mFramesReadyIsCalledByMultipleThreads; 460 StaticAudioTrackState mState; 461}; 462 463// Proxy used by AudioFlinger for servicing AudioRecord 464class AudioRecordServerProxy : public ServerProxy { 465public: 466 AudioRecordServerProxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount, 467 size_t frameSize) 468 : ServerProxy(cblk, buffers, frameCount, frameSize, false /*isOut*/, 469 false /*clientInServer*/) { } 470protected: 471 virtual ~AudioRecordServerProxy() { } 472}; 473 474// ---------------------------------------------------------------------------- 475 476}; // namespace android 477 478#endif // ANDROID_AUDIO_TRACK_SHARED_H 479