• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2 **
3 ** Copyright 2012, The Android Open Source Project
4 **
5 ** Licensed under the Apache License, Version 2.0 (the "License");
6 ** you may not use this file except in compliance with the License.
7 ** You may obtain a copy of the License at
8 **
9 **     http://www.apache.org/licenses/LICENSE-2.0
10 **
11 ** Unless required by applicable law or agreed to in writing, software
12 ** distributed under the License is distributed on an "AS IS" BASIS,
13 ** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 ** See the License for the specific language governing permissions and
15 ** limitations under the License.
16 */
17 
18 #ifndef INCLUDING_FROM_AUDIOFLINGER_H
19     #error This header file should only be included from AudioFlinger.h
20 #endif
21 
22 // base for record and playback
23 class TrackBase : public ExtendedAudioBufferProvider, public RefBase {
24 
25 public:
26     enum track_state : int32_t {
27         IDLE,
28         FLUSHED,        // for PlaybackTracks only
29         STOPPED,
30         // next 2 states are currently used for fast tracks
31         // and offloaded tracks only
32         STOPPING_1,     // waiting for first underrun
33         STOPPING_2,     // waiting for presentation complete
34         RESUMING,       // for PlaybackTracks only
35         ACTIVE,
36         PAUSING,
37         PAUSED,
38         STARTING_1,     // for RecordTrack only
39         STARTING_2,     // for RecordTrack only
40     };
41 
42     // where to allocate the data buffer
43     enum alloc_type {
44         ALLOC_CBLK,     // allocate immediately after control block
45         ALLOC_READONLY, // allocate from a separate read-only heap per thread
46         ALLOC_PIPE,     // do not allocate; use the pipe buffer
47         ALLOC_LOCAL,    // allocate a local buffer
48         ALLOC_NONE,     // do not allocate:use the buffer passed to TrackBase constructor
49     };
50 
51     enum track_type {
52         TYPE_DEFAULT,
53         TYPE_OUTPUT,
54         TYPE_PATCH,
55     };
56 
57                         TrackBase(ThreadBase *thread,
58                                 const sp<Client>& client,
59                                 const audio_attributes_t& mAttr,
60                                 uint32_t sampleRate,
61                                 audio_format_t format,
62                                 audio_channel_mask_t channelMask,
63                                 size_t frameCount,
64                                 void *buffer,
65                                 size_t bufferSize,
66                                 audio_session_t sessionId,
67                                 pid_t creatorPid,
68                                 uid_t uid,
69                                 bool isOut,
70                                 alloc_type alloc = ALLOC_CBLK,
71                                 track_type type = TYPE_DEFAULT,
72                                 audio_port_handle_t portId = AUDIO_PORT_HANDLE_NONE,
73                                 std::string metricsId = {});
74     virtual             ~TrackBase();
75     virtual status_t    initCheck() const;
76 
77     virtual status_t    start(AudioSystem::sync_event_t event,
78                              audio_session_t triggerSession) = 0;
79     virtual void        stop() = 0;
getCblk()80             sp<IMemory> getCblk() const { return mCblkMemory; }
cblk()81             audio_track_cblk_t* cblk() const { return mCblk; }
sessionId()82             audio_session_t sessionId() const { return mSessionId; }
uid()83             uid_t       uid() const { return mUid; }
creatorPid()84             pid_t       creatorPid() const { return mCreatorPid; }
85 
portId()86             audio_port_handle_t portId() const { return mPortId; }
87     virtual status_t    setSyncEvent(const sp<SyncEvent>& event);
88 
getBuffers()89             sp<IMemory> getBuffers() const { return mBufferMemory; }
buffer()90             void*       buffer() const { return mBuffer; }
bufferSize()91             size_t      bufferSize() const { return mBufferSize; }
92     virtual bool        isFastTrack() const = 0;
93     virtual bool        isDirect() const = 0;
isOutputTrack()94             bool        isOutputTrack() const { return (mType == TYPE_OUTPUT); }
isPatchTrack()95             bool        isPatchTrack() const { return (mType == TYPE_PATCH); }
isExternalTrack()96             bool        isExternalTrack() const { return !isOutputTrack() && !isPatchTrack(); }
97 
invalidate()98     virtual void        invalidate() {
99                             if (mIsInvalid) return;
100                             mTrackMetrics.logInvalidate();
101                             mIsInvalid = true;
102                         }
isInvalid()103             bool        isInvalid() const { return mIsInvalid; }
104 
terminate()105             void        terminate() { mTerminated = true; }
isTerminated()106             bool        isTerminated() const { return mTerminated; }
107 
attributes()108     audio_attributes_t  attributes() const { return mAttr; }
109 
isSpatialized()110     virtual bool        isSpatialized() const { return false; }
111 
112 #ifdef TEE_SINK
dumpTee(int fd,const std::string & reason)113            void         dumpTee(int fd, const std::string &reason) const {
114                                 mTee.dump(fd, reason);
115                         }
116 #endif
117 
118             /** returns the buffer contents size converted to time in milliseconds
119              * for PCM Playback or Record streaming tracks. The return value is zero for
120              * PCM static tracks and not defined for non-PCM tracks.
121              *
122              * This may be called without the thread lock.
123              */
bufferLatencyMs()124     virtual double      bufferLatencyMs() const {
125                             return mServerProxy->framesReadySafe() * 1000 / sampleRate();
126                         }
127 
128             /** returns whether the track supports server latency computation.
129              * This is set in the constructor and constant throughout the track lifetime.
130              */
131 
isServerLatencySupported()132             bool        isServerLatencySupported() const { return mServerLatencySupported; }
133 
134             /** computes the server latency for PCM Playback or Record track
135              * to the device sink/source.  This is the time for the next frame in the track buffer
136              * written or read from the server thread to the device source or sink.
137              *
138              * This may be called without the thread lock, but latencyMs and fromTrack
139              * may be not be synchronized. For example PatchPanel may not obtain the
140              * thread lock before calling.
141              *
142              * \param latencyMs on success is set to the latency in milliseconds of the
143              *        next frame written/read by the server thread to/from the track buffer
144              *        from the device source/sink.
145              * \param fromTrack on success is set to true if latency was computed directly
146              *        from the track timestamp; otherwise set to false if latency was
147              *        estimated from the server timestamp.
148              *        fromTrack may be nullptr or omitted if not required.
149              *
150              * \returns OK or INVALID_OPERATION on failure.
151              */
152             status_t    getServerLatencyMs(double *latencyMs, bool *fromTrack = nullptr) const {
153                             if (!isServerLatencySupported()) {
154                                 return INVALID_OPERATION;
155                             }
156 
157                             // if no thread lock is acquired, these atomics are not
158                             // synchronized with each other, considered a benign race.
159 
160                             const double serverLatencyMs = mServerLatencyMs.load();
161                             if (serverLatencyMs == 0.) {
162                                 return INVALID_OPERATION;
163                             }
164                             if (fromTrack != nullptr) {
165                                 *fromTrack = mServerLatencyFromTrack.load();
166                             }
167                             *latencyMs = serverLatencyMs;
168                             return OK;
169                         }
170 
171             /** computes the total client latency for PCM Playback or Record tracks
172              * for the next client app access to the device sink/source; i.e. the
173              * server latency plus the buffer latency.
174              *
175              * This may be called without the thread lock, but latencyMs and fromTrack
176              * may be not be synchronized. For example PatchPanel may not obtain the
177              * thread lock before calling.
178              *
179              * \param latencyMs on success is set to the latency in milliseconds of the
180              *        next frame written/read by the client app to/from the track buffer
181              *        from the device sink/source.
182              * \param fromTrack on success is set to true if latency was computed directly
183              *        from the track timestamp; otherwise set to false if latency was
184              *        estimated from the server timestamp.
185              *        fromTrack may be nullptr or omitted if not required.
186              *
187              * \returns OK or INVALID_OPERATION on failure.
188              */
189             status_t    getTrackLatencyMs(double *latencyMs, bool *fromTrack = nullptr) const {
190                             double serverLatencyMs;
191                             status_t status = getServerLatencyMs(&serverLatencyMs, fromTrack);
192                             if (status == OK) {
193                                 *latencyMs = serverLatencyMs + bufferLatencyMs();
194                             }
195                             return status;
196                         }
197 
198            // TODO: Consider making this external.
199            struct FrameTime {
200                int64_t frames;
201                int64_t timeNs;
202            };
203 
204            // KernelFrameTime is updated per "mix" period even for non-pcm tracks.
getKernelFrameTime(FrameTime * ft)205            void         getKernelFrameTime(FrameTime *ft) const {
206                            *ft = mKernelFrameTime.load();
207                         }
208 
format()209            audio_format_t format() const { return mFormat; }
id()210            int id() const { return mId; }
211 
getTrackStateAsString()212     const char *getTrackStateAsString() const {
213         if (isTerminated()) {
214             return "TERMINATED";
215         }
216         switch (mState) {
217         case IDLE:
218             return "IDLE";
219         case STOPPING_1: // for Fast and Offload
220             return "STOPPING_1";
221         case STOPPING_2: // for Fast and Offload
222             return "STOPPING_2";
223         case STOPPED:
224             return "STOPPED";
225         case RESUMING:
226             return "RESUMING";
227         case ACTIVE:
228             return "ACTIVE";
229         case PAUSING:
230             return "PAUSING";
231         case PAUSED:
232             return "PAUSED";
233         case FLUSHED:
234             return "FLUSHED";
235         case STARTING_1: // for RecordTrack
236             return "STARTING_1";
237         case STARTING_2: // for RecordTrack
238             return "STARTING_2";
239         default:
240             return "UNKNOWN";
241         }
242     }
243 
244     // Called by the PlaybackThread to indicate that the track is becoming active
245     // and a new interval should start with a given device list.
logBeginInterval(const std::string & devices)246     void logBeginInterval(const std::string& devices) {
247         mTrackMetrics.logBeginInterval(devices);
248     }
249 
250     // Called by the PlaybackThread to indicate the track is no longer active.
logEndInterval()251     void logEndInterval() {
252         mTrackMetrics.logEndInterval();
253     }
254 
255     // Called to tally underrun frames in playback.
tallyUnderrunFrames(size_t)256     virtual void tallyUnderrunFrames(size_t /* frames */) {}
257 
channelMask()258     audio_channel_mask_t channelMask() const { return mChannelMask; }
259 
260     /** @return true if the track has changed (metadata or volume) since
261      *          the last time this function was called,
262      *          true if this function was never called since the track creation,
263      *          false otherwise.
264      *  Thread safe.
265      */
readAndClearHasChanged()266     bool readAndClearHasChanged() { return !mChangeNotified.test_and_set(); }
267 
268     /** Set that a metadata has changed and needs to be notified to backend. Thread safe. */
setMetadataHasChanged()269     void setMetadataHasChanged() { mChangeNotified.clear(); }
270 
271 protected:
272     DISALLOW_COPY_AND_ASSIGN(TrackBase);
273 
releaseCblk()274     void releaseCblk() {
275         if (mCblk != nullptr) {
276             mState.clear();
277             mCblk->~audio_track_cblk_t();   // destroy our shared-structure.
278             if (mClient == 0) {
279                 free(mCblk);
280             }
281             mCblk = nullptr;
282         }
283     }
284 
285     // AudioBufferProvider interface
286     virtual status_t getNextBuffer(AudioBufferProvider::Buffer* buffer) = 0;
287     virtual void releaseBuffer(AudioBufferProvider::Buffer* buffer);
288 
289     // ExtendedAudioBufferProvider interface is only needed for Track,
290     // but putting it in TrackBase avoids the complexity of virtual inheritance
framesReady()291     virtual size_t  framesReady() const { return SIZE_MAX; }
292 
channelCount()293     uint32_t channelCount() const { return mChannelCount; }
294 
frameSize()295     size_t frameSize() const { return mFrameSize; }
296 
sampleRate()297     virtual uint32_t sampleRate() const { return mSampleRate; }
298 
isStopped()299     bool isStopped() const {
300         return (mState == STOPPED || mState == FLUSHED);
301     }
302 
303     // for fast tracks and offloaded tracks only
isStopping()304     bool isStopping() const {
305         return mState == STOPPING_1 || mState == STOPPING_2;
306     }
isStopping_1()307     bool isStopping_1() const {
308         return mState == STOPPING_1;
309     }
isStopping_2()310     bool isStopping_2() const {
311         return mState == STOPPING_2;
312     }
313 
314     // Upper case characters are final states.
315     // Lower case characters are transitory.
getTrackStateAsCodedString()316     const char *getTrackStateAsCodedString() const {
317         if (isTerminated()) {
318             return "T ";
319         }
320         switch (mState) {
321         case IDLE:
322             return "I ";
323         case STOPPING_1: // for Fast and Offload
324             return "s1";
325         case STOPPING_2: // for Fast and Offload
326             return "s2";
327         case STOPPED:
328             return "S ";
329         case RESUMING:
330             return "r ";
331         case ACTIVE:
332             return "A ";
333         case PAUSING:
334             return "p ";
335         case PAUSED:
336             return "P ";
337         case FLUSHED:
338             return "F ";
339         case STARTING_1: // for RecordTrack
340             return "r1";
341         case STARTING_2: // for RecordTrack
342             return "r2";
343         default:
344             return "? ";
345         }
346     }
347 
isOut()348     bool isOut() const { return mIsOut; }
349                                     // true for Track, false for RecordTrack,
350                                     // this could be a track type if needed later
351 
352     const wp<ThreadBase> mThread;
353     /*const*/ sp<Client> mClient;   // see explanation at ~TrackBase() why not const
354     sp<IMemory>         mCblkMemory;
355     audio_track_cblk_t* mCblk;
356     sp<IMemory>         mBufferMemory;  // currently non-0 for fast RecordTrack only
357     void*               mBuffer;    // start of track buffer, typically in shared memory
358                                     // except for OutputTrack when it is in local memory
359     size_t              mBufferSize; // size of mBuffer in bytes
360     // we don't really need a lock for these
361     MirroredVariable<track_state>  mState;
362     const audio_attributes_t mAttr;
363     const uint32_t      mSampleRate;    // initial sample rate only; for tracks which
364                         // support dynamic rates, the current value is in control block
365     const audio_format_t mFormat;
366     const audio_channel_mask_t mChannelMask;
367     const uint32_t      mChannelCount;
368     const size_t        mFrameSize; // AudioFlinger's view of frame size in shared memory,
369                                     // where for AudioTrack (but not AudioRecord),
370                                     // 8-bit PCM samples are stored as 16-bit
371     const size_t        mFrameCount;// size of track buffer given at createTrack() or
372                                     // createRecord(), and then adjusted as needed
373 
374     const audio_session_t mSessionId;
375     uid_t               mUid;
376     Vector < sp<SyncEvent> >mSyncEvents;
377     const bool          mIsOut;
378     sp<ServerProxy>     mServerProxy;
379     const int           mId;
380 #ifdef TEE_SINK
381     NBAIO_Tee           mTee;
382 #endif
383     bool                mTerminated;
384     track_type          mType;      // must be one of TYPE_DEFAULT, TYPE_OUTPUT, TYPE_PATCH ...
385     audio_io_handle_t   mThreadIoHandle; // I/O handle of the thread the track is attached to
386     audio_port_handle_t mPortId; // unique ID for this track used by audio policy
387     bool                mIsInvalid; // non-resettable latch, set by invalidate()
388 
389     // It typically takes 5 threadloop mix iterations for latency to stabilize.
390     // However, this can be 12+ iterations for BT.
391     // To be sure, we wait for latency to dip (it usually increases at the start)
392     // to assess stability and then log to MediaMetrics.
393     // Rapid start / pause calls may cause inaccurate numbers.
394     static inline constexpr int32_t LOG_START_COUNTDOWN = 12;
395     int32_t             mLogStartCountdown = 0; // Mixer period countdown
396     int64_t             mLogStartTimeNs = 0;    // Monotonic time at start()
397     int64_t             mLogStartFrames = 0;    // Timestamp frames at start()
398     double              mLogLatencyMs = 0.;     // Track the last log latency
399 
400     bool                mLogForceVolumeUpdate = true; // force volume update to TrackMetrics.
401 
402     TrackMetrics        mTrackMetrics;
403 
404     bool                mServerLatencySupported = false;
405     std::atomic<bool>   mServerLatencyFromTrack{}; // latency from track or server timestamp.
406     std::atomic<double> mServerLatencyMs{};        // last latency pushed from server thread.
407     std::atomic<FrameTime> mKernelFrameTime{};     // last frame time on kernel side.
408     const pid_t         mCreatorPid;  // can be different from mclient->pid() for instance
409                                       // when created by NuPlayer on behalf of a client
410 
411     // If the last track change was notified to the client with readAndClearHasChanged
412     std::atomic_flag    mChangeNotified = ATOMIC_FLAG_INIT;
413 };
414 
415 // PatchProxyBufferProvider interface is implemented by PatchTrack and PatchRecord.
416 // it provides buffer access methods that map those of a ClientProxy (see AudioTrackShared.h)
417 class PatchProxyBufferProvider
418 {
419 public:
420 
~PatchProxyBufferProvider()421     virtual ~PatchProxyBufferProvider() {}
422 
423     virtual bool        producesBufferOnDemand() const = 0;
424     virtual status_t    obtainBuffer(Proxy::Buffer* buffer,
425                                      const struct timespec *requested = NULL) = 0;
426     virtual void        releaseBuffer(Proxy::Buffer* buffer) = 0;
427 };
428 
429 class PatchTrackBase : public PatchProxyBufferProvider
430 {
431 public:
432     using Timeout = std::optional<std::chrono::nanoseconds>;
433                         PatchTrackBase(sp<ClientProxy> proxy, const ThreadBase& thread,
434                                        const Timeout& timeout);
435             void        setPeerTimeout(std::chrono::nanoseconds timeout);
436             template <typename T>
setPeerProxy(const sp<T> & proxy,bool holdReference)437             void        setPeerProxy(const sp<T> &proxy, bool holdReference) {
438                             mPeerReferenceHold = holdReference ? proxy : nullptr;
439                             mPeerProxy = proxy.get();
440                         }
clearPeerProxy()441             void        clearPeerProxy() {
442                             mPeerReferenceHold.clear();
443                             mPeerProxy = nullptr;
444                         }
445 
producesBufferOnDemand()446             bool        producesBufferOnDemand() const override { return false; }
447 
448 protected:
449     const sp<ClientProxy>       mProxy;
450     sp<RefBase>                 mPeerReferenceHold;   // keeps mPeerProxy alive during access.
451     PatchProxyBufferProvider*   mPeerProxy = nullptr;
452     struct timespec             mPeerTimeout{};
453 
454 };
455