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 <audio_utils/roundup.h>
28 #include <media/AudioResamplerPublic.h>
29 #include <media/AudioTimestamp.h>
30 #include <media/Modulo.h>
31 #include <media/nbaio/SingleStateQueue.h>
32 
33 namespace android {
34 
35 // ----------------------------------------------------------------------------
36 
37 // for audio_track_cblk_t::mFlags
38 #define CBLK_UNDERRUN   0x01 // set by server immediately on output underrun, cleared by client
39 #define CBLK_FORCEREADY 0x02 // set: track is considered ready immediately by AudioFlinger,
40                              // clear: track is ready when buffer full
41 #define CBLK_INVALID    0x04 // track buffer invalidated by AudioFlinger, need to re-create
42 #define CBLK_DISABLED   0x08 // output track disabled by AudioFlinger due to underrun,
43                              // need to re-start.  Unlike CBLK_UNDERRUN, this is not set
44                              // immediately, but only after a long string of underruns.
45 // 0x10 unused
46 #define CBLK_LOOP_CYCLE 0x20 // set by server each time a loop cycle other than final one completes
47 #define CBLK_LOOP_FINAL 0x40 // set by server when the final loop cycle completes
48 #define CBLK_BUFFER_END 0x80 // set by server when the position reaches end of buffer if not looping
49 #define CBLK_OVERRUN   0x100 // set by server immediately on input overrun, cleared by client
50 #define CBLK_INTERRUPT 0x200 // set by client on interrupt(), cleared by client in obtainBuffer()
51 #define CBLK_STREAM_END_DONE 0x400 // set by server on render completion, cleared by client
52 
53 //EL_FIXME 20 seconds may not be enough and must be reconciled with new obtainBuffer implementation
54 #define MAX_RUN_OFFLOADED_TIMEOUT_MS 20000 // assuming up to a maximum of 20 seconds of offloaded
55 
56 struct AudioTrackSharedStreaming {
57     // similar to NBAIO MonoPipe
58     // in continuously incrementing frame units, take modulo buffer size, which must be a power of 2
59     volatile int32_t mFront;    // read by consumer (output: server, input: client)
60     volatile int32_t mRear;     // written by producer (output: client, input: server)
61     volatile int32_t mFlush;    // incremented by client to indicate a request to flush;
62                                 // server notices and discards all data between mFront and mRear
63     volatile int32_t mStop;     // set by client to indicate a stop frame position; server
64                                 // will not read beyond this position until start is called.
65     volatile uint32_t mUnderrunFrames; // server increments for each unavailable but desired frame
66     volatile uint32_t mUnderrunCount;  // server increments for each underrun occurrence
67 };
68 
69 // Represents a single state of an AudioTrack that was created in static mode (shared memory buffer
70 // supplied by the client).  This state needs to be communicated from the client to server.  As this
71 // state is too large to be updated atomically without a mutex, and mutexes aren't allowed here, the
72 // state is wrapped by a SingleStateQueue.
73 struct StaticAudioTrackState {
74     // Do not define constructors, destructors, or virtual methods as this is part of a
75     // union in shared memory and they will not get called properly.
76 
77     // These fields should both be size_t, but since they are located in shared memory we
78     // force to 32-bit.  The client and server may have different typedefs for size_t.
79 
80     // The state has a sequence counter to indicate whether changes are made to loop or position.
81     // The sequence counter also currently indicates whether loop or position is first depending
82     // on which is greater; it jumps by max(mLoopSequence, mPositionSequence) + 1.
83 
84     uint32_t    mLoopStart;
85     uint32_t    mLoopEnd;
86     int32_t     mLoopCount;
87     uint32_t    mLoopSequence; // a sequence counter to indicate changes to loop
88     uint32_t    mPosition;
89     uint32_t    mPositionSequence; // a sequence counter to indicate changes to position
90 };
91 
92 typedef SingleStateQueue<StaticAudioTrackState> StaticAudioTrackSingleStateQueue;
93 
94 struct StaticAudioTrackPosLoop {
95     // Do not define constructors, destructors, or virtual methods as this is part of a
96     // union in shared memory and will not get called properly.
97 
98     // These fields should both be size_t, but since they are located in shared memory we
99     // force to 32-bit.  The client and server may have different typedefs for size_t.
100 
101     // This struct information is stored in a single state queue to communicate the
102     // static AudioTrack server state to the client while data is consumed.
103     // It is smaller than StaticAudioTrackState to prevent unnecessary information from
104     // being sent.
105 
106     uint32_t mBufferPosition;
107     int32_t  mLoopCount;
108 };
109 
110 typedef SingleStateQueue<StaticAudioTrackPosLoop> StaticAudioTrackPosLoopQueue;
111 
112 struct AudioTrackSharedStatic {
113     // client requests to the server for loop or position changes.
114     StaticAudioTrackSingleStateQueue::Shared
115                     mSingleStateQueue;
116     // position info updated asynchronously by server and read by client,
117     // "for entertainment purposes only"
118     StaticAudioTrackPosLoopQueue::Shared
119                     mPosLoopQueue;
120 };
121 
122 typedef SingleStateQueue<AudioPlaybackRate> PlaybackRateQueue;
123 
124 typedef SingleStateQueue<ExtendedTimestamp> ExtendedTimestampQueue;
125 
126 // ----------------------------------------------------------------------------
127 
128 // Important: do not add any virtual methods, including ~
129 struct audio_track_cblk_t
130 {
131                 // Since the control block is always located in shared memory, this constructor
132                 // is only used for placement new().  It is never used for regular new() or stack.
133                             audio_track_cblk_t();
~audio_track_cblk_taudio_track_cblk_t134                 /*virtual*/ ~audio_track_cblk_t() { }
135 
136                 friend class Proxy;
137                 friend class ClientProxy;
138                 friend class AudioTrackClientProxy;
139                 friend class AudioRecordClientProxy;
140                 friend class ServerProxy;
141                 friend class AudioTrackServerProxy;
142                 friend class AudioRecordServerProxy;
143 
144     // The data members are grouped so that members accessed frequently and in the same context
145     // are in the same line of data cache.
146 
147                 uint32_t    mServer;    // Number of filled frames consumed by server (mIsOut),
148                                         // or filled frames provided by server (!mIsOut).
149                                         // It is updated asynchronously by server without a barrier.
150                                         // The value should be used
151                                         // "for entertainment purposes only",
152                                         // which means don't make important decisions based on it.
153 
154                 uint32_t    mPad1;      // unused
155 
156     volatile    int32_t     mFutex;     // event flag: down (P) by client,
157                                         // up (V) by server or binderDied() or interrupt()
158 #define CBLK_FUTEX_WAKE 1               // if event flag bit is set, then a deferred wake is pending
159 
160 private:
161 
162                 // This field should be a size_t, but since it is located in shared memory we
163                 // force to 32-bit.  The client and server may have different typedefs for size_t.
164                 uint32_t    mMinimum;       // server wakes up client if available >= mMinimum
165 
166                 // Stereo gains for AudioTrack only, not used by AudioRecord.
167                 gain_minifloat_packed_t mVolumeLR;
168 
169                 uint32_t    mSampleRate;    // AudioTrack only: client's requested sample rate in Hz
170                                             // or 0 == default. Write-only client, read-only server.
171 
172                 PlaybackRateQueue::Shared mPlaybackRateQueue;
173 
174                 // client write-only, server read-only
175                 uint16_t    mSendLevel;      // Fixed point U4.12 so 0x1000 means 1.0
176 
177                 uint16_t    mPad2 __attribute__((__unused__)); // unused
178 
179                 // server write-only, client read
180                 ExtendedTimestampQueue::Shared mExtendedTimestampQueue;
181 
182                 // This is set by AudioTrack.setBufferSizeInFrames().
183                 // A write will not fill the buffer above this limit.
184     volatile    uint32_t   mBufferSizeInFrames;  // effective size of the buffer
185 
186 public:
187 
188     volatile    int32_t     mFlags;         // combinations of CBLK_*
189 
190 public:
191                 union {
192                     AudioTrackSharedStreaming   mStreaming;
193                     AudioTrackSharedStatic      mStatic;
194                     int                         mAlign[8];
195                 } u;
196 
197                 // Cache line boundary (32 bytes)
198 };
199 
200 // ----------------------------------------------------------------------------
201 
202 // Proxy for shared memory control block, to isolate callers from needing to know the details.
203 // There is exactly one ClientProxy and one ServerProxy per shared memory control block.
204 // The proxies are located in normal memory, and are not multi-thread safe within a given side.
205 class Proxy : public RefBase {
206 protected:
207     Proxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount, size_t frameSize, bool isOut,
208             bool clientInServer);
~Proxy()209     virtual ~Proxy() { }
210 
211 public:
212     struct Buffer {
213         size_t  mFrameCount;            // number of frames available in this buffer
214         void*   mRaw;                   // pointer to first frame
215         size_t  mNonContig;             // number of additional non-contiguous frames available
216     };
217 
frameCount()218     size_t frameCount() const { return mFrameCount; }
219 
220 protected:
221     // These refer to shared memory, and are virtual addresses with respect to the current process.
222     // They may have different virtual addresses within the other process.
223     audio_track_cblk_t* const   mCblk;  // the control block
224     void* const     mBuffers;           // starting address of buffers
225 
226     const size_t    mFrameCount;        // not necessarily a power of 2
227     const size_t    mFrameSize;         // in bytes
228     const size_t    mFrameCountP2;      // mFrameCount rounded to power of 2, streaming mode
229     const bool      mIsOut;             // true for AudioTrack, false for AudioRecord
230     const bool      mClientInServer;    // true for OutputTrack, false for AudioTrack & AudioRecord
231     bool            mIsShutdown;        // latch set to true when shared memory corruption detected
232     size_t          mUnreleased;        // unreleased frames remaining from most recent obtainBuffer
233 };
234 
235 // ----------------------------------------------------------------------------
236 
237 // Proxy seen by AudioTrack client and AudioRecord client
238 class ClientProxy : public Proxy {
239 public:
240     ClientProxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount, size_t frameSize,
241             bool isOut, bool clientInServer);
~ClientProxy()242     virtual ~ClientProxy() { }
243 
244     static const struct timespec kForever;
245     static const struct timespec kNonBlocking;
246 
247     // Obtain a buffer with filled frames (reading) or empty frames (writing).
248     // It is permitted to call obtainBuffer() multiple times in succession, without any intervening
249     // calls to releaseBuffer().  In that case, the final obtainBuffer() is the one that effectively
250     // sets or extends the unreleased frame count.
251     // On entry:
252     //  buffer->mFrameCount should be initialized to maximum number of desired frames,
253     //      which must be > 0.
254     //  buffer->mNonContig is unused.
255     //  buffer->mRaw is unused.
256     //  requested is the requested timeout in local monotonic delta time units:
257     //      NULL or &kNonBlocking means non-blocking (zero timeout).
258     //      &kForever means block forever (infinite timeout).
259     //      Other values mean a specific timeout in local monotonic delta time units.
260     //  elapsed is a pointer to a location that will hold the total local monotonic time that
261     //      elapsed while blocked, or NULL if not needed.
262     // On exit:
263     //  buffer->mFrameCount has the actual number of contiguous available frames,
264     //      which is always 0 when the return status != NO_ERROR.
265     //  buffer->mNonContig is the number of additional non-contiguous available frames.
266     //  buffer->mRaw is a pointer to the first available frame,
267     //      or NULL when buffer->mFrameCount == 0.
268     // The return status is one of:
269     //  NO_ERROR    Success, buffer->mFrameCount > 0.
270     //  WOULD_BLOCK Non-blocking mode and no frames are available.
271     //  TIMED_OUT   Timeout occurred before any frames became available.
272     //              This can happen even for infinite timeout, due to a spurious wakeup.
273     //              In this case, the caller should investigate and then re-try as appropriate.
274     //  DEAD_OBJECT Server has died or invalidated, caller should destroy this proxy and re-create.
275     //  -EINTR      Call has been interrupted.  Look around to see why, and then perhaps try again.
276     //  NO_INIT     Shared memory is corrupt.
277     //  NOT_ENOUGH_DATA Server has disabled the track because of underrun: restart the track
278     //              if still in active state.
279     // Assertion failure on entry, if buffer == NULL or buffer->mFrameCount == 0.
280     status_t    obtainBuffer(Buffer* buffer, const struct timespec *requested = NULL,
281             struct timespec *elapsed = NULL);
282 
283     // Release (some of) the frames last obtained.
284     // On entry, buffer->mFrameCount should have the number of frames to release,
285     // which must (cumulatively) be <= the number of frames last obtained but not yet released.
286     // buffer->mRaw is ignored, but is normally same pointer returned by last obtainBuffer().
287     // It is permitted to call releaseBuffer() multiple times to release the frames in chunks.
288     // On exit:
289     //  buffer->mFrameCount is zero.
290     //  buffer->mRaw is NULL.
291     void        releaseBuffer(Buffer* buffer);
292 
293     // Call after detecting server's death
294     void        binderDied();
295 
296     // Call to force an obtainBuffer() to return quickly with -EINTR
297     void        interrupt();
298 
getPosition()299     Modulo<uint32_t> getPosition() {
300         return mEpoch + mCblk->mServer;
301     }
302 
setEpoch(const Modulo<uint32_t> & epoch)303     void        setEpoch(const Modulo<uint32_t> &epoch) {
304         mEpoch = epoch;
305     }
306 
setMinimum(size_t minimum)307     void        setMinimum(size_t minimum) {
308         // This can only happen on a 64-bit client
309         if (minimum > UINT32_MAX) {
310             minimum = UINT32_MAX;
311         }
312         mCblk->mMinimum = (uint32_t) minimum;
313     }
314 
315     // Return the number of frames that would need to be obtained and released
316     // in order for the client to be aligned at start of buffer
317     virtual size_t  getMisalignment();
318 
getEpoch()319     Modulo<uint32_t> getEpoch() const {
320         return mEpoch;
321     }
322 
getBufferSizeInFrames()323     uint32_t      getBufferSizeInFrames() const { return mBufferSizeInFrames; }
324     // See documentation for AudioTrack::setBufferSizeInFrames()
325     uint32_t      setBufferSizeInFrames(uint32_t requestedSize);
326 
getTimestamp(ExtendedTimestamp * timestamp)327     status_t    getTimestamp(ExtendedTimestamp *timestamp) {
328         if (timestamp == nullptr) {
329             return BAD_VALUE;
330         }
331         (void) mTimestampObserver.poll(mTimestamp);
332         *timestamp = mTimestamp;
333         return OK;
334     }
335 
clearTimestamp()336     void        clearTimestamp() {
337         mTimestamp.clear();
338     }
339 
stop()340     virtual void stop() { }; // called by client in AudioTrack::stop()
341 
342 private:
343     // This is a copy of mCblk->mBufferSizeInFrames
344     uint32_t   mBufferSizeInFrames;  // effective size of the buffer
345 
346     Modulo<uint32_t> mEpoch;
347 
348     // The shared buffer contents referred to by the timestamp observer
349     // is initialized when the server proxy created.  A local zero timestamp
350     // is initialized by the client constructor.
351     ExtendedTimestampQueue::Observer mTimestampObserver;
352     ExtendedTimestamp mTimestamp; // initialized by constructor
353 };
354 
355 // ----------------------------------------------------------------------------
356 
357 // Proxy used by AudioTrack client, which also includes AudioFlinger::PlaybackThread::OutputTrack
358 class AudioTrackClientProxy : public ClientProxy {
359 public:
360     AudioTrackClientProxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount,
361             size_t frameSize, bool clientInServer = false)
ClientProxy(cblk,buffers,frameCount,frameSize,true,clientInServer)362         : ClientProxy(cblk, buffers, frameCount, frameSize, true /*isOut*/,
363           clientInServer),
364           mPlaybackRateMutator(&cblk->mPlaybackRateQueue) {
365     }
366 
~AudioTrackClientProxy()367     virtual ~AudioTrackClientProxy() { }
368 
369     // No barriers on the following operations, so the ordering of loads/stores
370     // with respect to other parameters is UNPREDICTABLE. That's considered safe.
371 
372     // caller must limit to 0.0 <= sendLevel <= 1.0
setSendLevel(float sendLevel)373     void        setSendLevel(float sendLevel) {
374         mCblk->mSendLevel = uint16_t(sendLevel * 0x1000);
375     }
376 
377     // set stereo gains
setVolumeLR(gain_minifloat_packed_t volumeLR)378     void        setVolumeLR(gain_minifloat_packed_t volumeLR) {
379         mCblk->mVolumeLR = volumeLR;
380     }
381 
setSampleRate(uint32_t sampleRate)382     void        setSampleRate(uint32_t sampleRate) {
383         mCblk->mSampleRate = sampleRate;
384     }
385 
setPlaybackRate(const AudioPlaybackRate & playbackRate)386     void        setPlaybackRate(const AudioPlaybackRate& playbackRate) {
387         mPlaybackRateMutator.push(playbackRate);
388     }
389 
390     // Sends flush and stop position information from the client to the server,
391     // used by streaming AudioTrack flush() or stop().
392     void sendStreamingFlushStop(bool flush);
393 
394     virtual void flush();
395 
396             void stop() override;
397 
getUnderrunFrames()398     virtual uint32_t    getUnderrunFrames() const {
399         return mCblk->u.mStreaming.mUnderrunFrames;
400     }
getUnderrunCount()401     virtual uint32_t    getUnderrunCount() const {
402         return mCblk->u.mStreaming.mUnderrunCount;
403     }
404 
405     bool        clearStreamEndDone();   // and return previous value
406 
407     bool        getStreamEndDone() const;
408 
409     status_t    waitStreamEndDone(const struct timespec *requested);
410 
411 private:
412     PlaybackRateQueue::Mutator   mPlaybackRateMutator;
413 };
414 
415 class StaticAudioTrackClientProxy : public AudioTrackClientProxy {
416 public:
417     StaticAudioTrackClientProxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount,
418             size_t frameSize);
~StaticAudioTrackClientProxy()419     virtual ~StaticAudioTrackClientProxy() { }
420 
421     virtual void    flush();
422 
423     void stop() override;
424 
425 #define MIN_LOOP    16  // minimum length of each loop iteration in frames
426 
427             // setLoop(), setBufferPosition(), and setBufferPositionAndLoop() set the
428             // static buffer position and looping parameters.  These commands are not
429             // synchronous (they do not wait or block); instead they take effect at the
430             // next buffer data read from the server side. However, the client side
431             // getters will read a cached version of the position and loop variables
432             // until the setting takes effect.
433             //
434             // setBufferPositionAndLoop() is equivalent to calling, in order, setLoop() and
435             // setBufferPosition().
436             //
437             // The functions should not be relied upon to do parameter or state checking.
438             // That is done at the AudioTrack level.
439 
440             void    setLoop(size_t loopStart, size_t loopEnd, int loopCount);
441             void    setBufferPosition(size_t position);
442             void    setBufferPositionAndLoop(size_t position, size_t loopStart, size_t loopEnd,
443                                              int loopCount);
444             size_t  getBufferPosition();
445                     // getBufferPositionAndLoopCount() provides the proper snapshot of
446                     // position and loopCount together.
447             void    getBufferPositionAndLoopCount(size_t *position, int *loopCount);
448 
getMisalignment()449     virtual size_t  getMisalignment() {
450         return 0;
451     }
452 
getUnderrunFrames()453     virtual uint32_t getUnderrunFrames() const override {
454         return 0;
455     }
456 
getUnderrunCount()457     virtual uint32_t getUnderrunCount() const override {
458         return 0;
459     }
460 
461 private:
462     StaticAudioTrackSingleStateQueue::Mutator   mMutator;
463     StaticAudioTrackPosLoopQueue::Observer      mPosLoopObserver;
464                         StaticAudioTrackState   mState;   // last communicated state to server
465                         StaticAudioTrackPosLoop mPosLoop; // snapshot of position and loop.
466 };
467 
468 // ----------------------------------------------------------------------------
469 
470 // Proxy used by AudioRecord client
471 class AudioRecordClientProxy : public ClientProxy {
472 public:
AudioRecordClientProxy(audio_track_cblk_t * cblk,void * buffers,size_t frameCount,size_t frameSize)473     AudioRecordClientProxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount,
474             size_t frameSize)
475         : ClientProxy(cblk, buffers, frameCount, frameSize,
476             false /*isOut*/, false /*clientInServer*/) { }
~AudioRecordClientProxy()477     ~AudioRecordClientProxy() { }
478 
479     // Advances the client read pointer to the server write head pointer
480     // effectively flushing the client read buffer. The effect is
481     // instantaneous. Returns the number of frames flushed.
flush()482     uint32_t    flush() {
483         int32_t rear = android_atomic_acquire_load(&mCblk->u.mStreaming.mRear);
484         int32_t front = mCblk->u.mStreaming.mFront;
485         android_atomic_release_store(rear, &mCblk->u.mStreaming.mFront);
486         return (Modulo<int32_t>(rear) - front).unsignedValue();
487     }
488 };
489 
490 // ----------------------------------------------------------------------------
491 
492 // Proxy used by AudioFlinger server
493 class ServerProxy : public Proxy {
494 protected:
495     ServerProxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount, size_t frameSize,
496             bool isOut, bool clientInServer);
497 public:
~ServerProxy()498     virtual ~ServerProxy() { }
499 
500     // Obtain a buffer with filled frames (writing) or empty frames (reading).
501     // It is permitted to call obtainBuffer() multiple times in succession, without any intervening
502     // calls to releaseBuffer().  In that case, the final obtainBuffer() is the one that effectively
503     // sets or extends the unreleased frame count.
504     // Always non-blocking.
505     // On entry:
506     //  buffer->mFrameCount should be initialized to maximum number of desired frames,
507     //      which must be > 0.
508     //  buffer->mNonContig is unused.
509     //  buffer->mRaw is unused.
510     //  ackFlush is true iff being called from Track::start to acknowledge a pending flush.
511     // On exit:
512     //  buffer->mFrameCount has the actual number of contiguous available frames,
513     //      which is always 0 when the return status != NO_ERROR.
514     //  buffer->mNonContig is the number of additional non-contiguous available frames.
515     //  buffer->mRaw is a pointer to the first available frame,
516     //      or NULL when buffer->mFrameCount == 0.
517     // The return status is one of:
518     //  NO_ERROR    Success, buffer->mFrameCount > 0.
519     //  WOULD_BLOCK No frames are available.
520     //  NO_INIT     Shared memory is corrupt.
521     virtual status_t    obtainBuffer(Buffer* buffer, bool ackFlush = false);
522 
523     // Release (some of) the frames last obtained.
524     // On entry, buffer->mFrameCount should have the number of frames to release,
525     // which must (cumulatively) be <= the number of frames last obtained but not yet released.
526     // It is permitted to call releaseBuffer() multiple times to release the frames in chunks.
527     // buffer->mRaw is ignored, but is normally same pointer returned by last obtainBuffer().
528     // On exit:
529     //  buffer->mFrameCount is zero.
530     //  buffer->mRaw is NULL.
531     virtual void        releaseBuffer(Buffer* buffer);
532 
533     // Return the total number of frames that AudioFlinger has obtained and released
framesReleased()534     virtual int64_t     framesReleased() const { return mReleased; }
535 
536     // Expose timestamp to client proxy. Should only be called by a single thread.
setTimestamp(const ExtendedTimestamp & timestamp)537     virtual void        setTimestamp(const ExtendedTimestamp &timestamp) {
538         mTimestampMutator.push(timestamp);
539     }
540 
getTimestamp()541     virtual ExtendedTimestamp getTimestamp() const {
542         return mTimestampMutator.last();
543     }
544 
545     // Flushes the shared ring buffer if the client had requested it using mStreaming.mFlush.
546     // If flush occurs then:
547     //   cblk->u.mStreaming.mFront, ServerProxy::mFlush and ServerProxy::mFlushed will be modified
548     //   client will be notified via Futex
549     virtual void    flushBufferIfNeeded();
550 
551     // Returns the rear position of the AudioTrack shared ring buffer, limited by
552     // the stop frame position level.
553     virtual int32_t getRear() const = 0;
554 
555     // Total count of the number of flushed frames since creation (never reset).
framesFlushed()556     virtual int64_t     framesFlushed() const { return mFlushed; }
557 
558     // Safe frames ready query with no side effects.
559     virtual size_t      framesReadySafe() const = 0;
560 
561     // Get dynamic buffer size from the shared control block.
getBufferSizeInFrames()562     uint32_t            getBufferSizeInFrames() const {
563         return android_atomic_acquire_load((int32_t *)&mCblk->mBufferSizeInFrames);
564     }
565 
566 protected:
567     size_t      mAvailToClient; // estimated frames available to client prior to releaseBuffer()
568     int32_t     mFlush;         // our copy of cblk->u.mStreaming.mFlush, for streaming output only
569     int64_t     mReleased;      // our copy of cblk->mServer, at 64 bit resolution
570     int64_t     mFlushed;       // flushed frames to account for client-server discrepancy
571     ExtendedTimestampQueue::Mutator mTimestampMutator;
572 };
573 
574 // Proxy used by AudioFlinger for servicing AudioTrack
575 class AudioTrackServerProxy : public ServerProxy {
576 public:
577     AudioTrackServerProxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount,
578             size_t frameSize, bool clientInServer = false, uint32_t sampleRate = 0)
ServerProxy(cblk,buffers,frameCount,frameSize,true,clientInServer)579         : ServerProxy(cblk, buffers, frameCount, frameSize, true /*isOut*/, clientInServer),
580           mPlaybackRateObserver(&cblk->mPlaybackRateQueue),
581           mUnderrunCount(0), mUnderrunning(false), mDrained(true) {
582         mCblk->mSampleRate = sampleRate;
583         mPlaybackRate = AUDIO_PLAYBACK_RATE_DEFAULT;
584     }
585 protected:
~AudioTrackServerProxy()586     virtual ~AudioTrackServerProxy() { }
587 
588 public:
589     // return value of these methods must be validated by the caller
getSampleRate()590     uint32_t    getSampleRate() const { return mCblk->mSampleRate; }
getSendLevel_U4_12()591     uint16_t    getSendLevel_U4_12() const { return mCblk->mSendLevel; }
getVolumeLR()592     gain_minifloat_packed_t getVolumeLR() const { return mCblk->mVolumeLR; }
593 
594     // estimated total number of filled frames available to server to read,
595     // which may include non-contiguous frames
596     virtual size_t      framesReady();
597 
598     size_t              framesReadySafe() const override; // frames available to read by server.
599 
600     // Currently AudioFlinger will call framesReady() for a fast track from two threads:
601     // FastMixer thread, and normal mixer thread.  This is dangerous, as the proxy is intended
602     // to be called from at most one thread of server, and one thread of client.
603     // As a temporary workaround, this method informs the proxy implementation that it
604     // should avoid doing a state queue poll from within framesReady().
605     // FIXME Change AudioFlinger to not call framesReady() from normal mixer thread.
framesReadyIsCalledByMultipleThreads()606     virtual void        framesReadyIsCalledByMultipleThreads() { }
607 
608     bool     setStreamEndDone();    // and return previous value
609 
610     // Add to the tally of underrun frames, and inform client of underrun
611     virtual void        tallyUnderrunFrames(uint32_t frameCount);
612 
613     // Return the total number of frames which AudioFlinger desired but were unavailable,
614     // and thus which resulted in an underrun.
getUnderrunFrames()615     virtual uint32_t    getUnderrunFrames() const { return mCblk->u.mStreaming.mUnderrunFrames; }
616 
617     // Return the playback speed and pitch read atomically. Not multi-thread safe on server side.
618     AudioPlaybackRate getPlaybackRate();
619 
620     // Set the internal drain state of the track buffer from the timestamp received.
setDrained(bool drained)621     virtual void        setDrained(bool drained) {
622         mDrained.store(drained);
623     }
624 
625     // Check if the internal drain state of the track buffer.
626     // This is not a guarantee, but advisory for determining whether the track is
627     // fully played out.
isDrained()628     virtual bool        isDrained() const {
629         return mDrained.load();
630     }
631 
632     int32_t             getRear() const override;
633 
634     // Called on server side track start().
635     virtual void        start();
636 
637 private:
638     AudioPlaybackRate             mPlaybackRate;  // last observed playback rate
639     PlaybackRateQueue::Observer   mPlaybackRateObserver;
640 
641     // Last client stop-at position when start() was called. Used for streaming AudioTracks.
642     std::atomic<int32_t>          mStopLast{0};
643 
644     // The server keeps a copy here where it is safe from the client.
645     uint32_t                      mUnderrunCount; // echoed to mCblk
646     bool                          mUnderrunning;  // used to detect edge of underrun
647 
648     std::atomic<bool>             mDrained; // is the track buffer drained
649 };
650 
651 class StaticAudioTrackServerProxy : public AudioTrackServerProxy {
652 public:
653     StaticAudioTrackServerProxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount,
654             size_t frameSize);
655 protected:
~StaticAudioTrackServerProxy()656     virtual ~StaticAudioTrackServerProxy() { }
657 
658 public:
659     virtual size_t      framesReady();
660     virtual size_t      framesReadySafe() const override;
661     virtual void        framesReadyIsCalledByMultipleThreads();
662     virtual status_t    obtainBuffer(Buffer* buffer, bool ackFlush);
663     virtual void        releaseBuffer(Buffer* buffer);
664     virtual void        tallyUnderrunFrames(uint32_t frameCount);
getUnderrunFrames()665     virtual uint32_t    getUnderrunFrames() const { return 0; }
666 
667     int32_t getRear() const override;
668 
start()669     void start() override { } // ignore for static tracks
670 
671 private:
672     status_t            updateStateWithLoop(StaticAudioTrackState *localState,
673                                             const StaticAudioTrackState &update) const;
674     status_t            updateStateWithPosition(StaticAudioTrackState *localState,
675                                                 const StaticAudioTrackState &update) const;
676     ssize_t             pollPosition(); // poll for state queue update, and return current position
677     StaticAudioTrackSingleStateQueue::Observer  mObserver;
678     StaticAudioTrackPosLoopQueue::Mutator       mPosLoopMutator;
679     size_t              mFramesReadySafe; // Assuming size_t read/writes are atomic on 32 / 64 bit
680                                           // processors, this is a thread-safe version of
681                                           // mFramesReady.
682     int64_t             mFramesReady;     // The number of frames ready in the static buffer
683                                           // including loops.  This is 64 bits since loop mode
684                                           // can cause a track to appear to have a large number
685                                           // of frames. INT64_MAX means an infinite loop.
686     bool                mFramesReadyIsCalledByMultipleThreads;
687     StaticAudioTrackState mState;         // Server side state. Any updates from client must be
688                                           // passed by the mObserver SingleStateQueue.
689 };
690 
691 // Proxy used by AudioFlinger for servicing AudioRecord
692 class AudioRecordServerProxy : public ServerProxy {
693 public:
AudioRecordServerProxy(audio_track_cblk_t * cblk,void * buffers,size_t frameCount,size_t frameSize,bool clientInServer)694     AudioRecordServerProxy(audio_track_cblk_t* cblk, void *buffers, size_t frameCount,
695             size_t frameSize, bool clientInServer)
696         : ServerProxy(cblk, buffers, frameCount, frameSize, false /*isOut*/, clientInServer) { }
697 
getRear()698     int32_t getRear() const override {
699         return mCblk->u.mStreaming.mRear; // For completeness only; mRear written by server.
700     }
701 
702     size_t framesReadySafe() const override; // frames available to read by client.
703 
704 protected:
~AudioRecordServerProxy()705     virtual ~AudioRecordServerProxy() { }
706 };
707 
708 // ----------------------------------------------------------------------------
709 
710 }; // namespace android
711 
712 #endif // ANDROID_AUDIO_TRACK_SHARED_H
713