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