1010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten/*
2010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten * Copyright (C) 2012 The Android Open Source Project
3010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten *
4010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten * Licensed under the Apache License, Version 2.0 (the "License");
5010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten * you may not use this file except in compliance with the License.
6010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten * You may obtain a copy of the License at
7010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten *
8010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten *      http://www.apache.org/licenses/LICENSE-2.0
9010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten *
10010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten * Unless required by applicable law or agreed to in writing, software
11010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten * distributed under the License is distributed on an "AS IS" BASIS,
12010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten * See the License for the specific language governing permissions and
14010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten * limitations under the License.
15010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten */
16010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
17010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten#ifndef ANDROID_AUDIO_MONO_PIPE_H
18010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten#define ANDROID_AUDIO_MONO_PIPE_H
19010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
20010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten#include <time.h>
212c3b2da3049627264b7c6b449a1622f002210f03John Grossman#include <utils/LinearTransform.h>
22010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten#include "NBAIO.h"
23010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
24010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastennamespace android {
25010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
26010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// MonoPipe is similar to Pipe except:
27010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten//  - supports only a single reader, called MonoPipeReader
28010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten//  - write() cannot overrun; instead it will return a short actual count if insufficient space
29010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten//  - write() can optionally block if the pipe is full
30010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Like Pipe, it is not multi-thread safe for either writer or reader
31010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// but writer and reader can be different threads.
32010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenclass MonoPipe : public NBAIO_Sink {
33010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
34010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    friend class MonoPipeReader;
35010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
36010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenpublic:
37820ba70df8ba595ae9055dfd34fdbfa32f70f14dGlenn Kasten    // reqFrames will be rounded up to a power of 2, and all slots are available. Must be >= 2.
38010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Note: whatever shares this object with another thread needs to do so in an SMP-safe way (like
39010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // creating it the object before creating the other thread, or storing the object with a
40010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // release_store). Otherwise the other thread could see a partially-constructed object.
41820ba70df8ba595ae9055dfd34fdbfa32f70f14dGlenn Kasten    MonoPipe(size_t reqFrames, NBAIO_Format format, bool writeCanBlock = false);
42010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual ~MonoPipe();
43010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
44010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // NBAIO_Port interface
45010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
46010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //virtual ssize_t negotiate(const NBAIO_Format offers[], size_t numOffers,
47010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //                          NBAIO_Format counterOffers[], size_t& numCounterOffers);
48010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //virtual NBAIO_Format format() const;
49010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
50010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // NBAIO_Sink interface
51010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
52010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //virtual size_t framesWritten() const;
53010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //virtual size_t framesUnderrun() const;
54010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //virtual size_t underruns() const;
55010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
56010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual ssize_t availableToWrite() const;
57010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual ssize_t write(const void *buffer, size_t count);
58010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //virtual ssize_t writeVia(writeVia_t via, size_t total, void *user, size_t block);
59010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
602c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // MonoPipe's implementation of getNextWriteTimestamp works in conjunction
612c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // with MonoPipeReader.  Every time a MonoPipeReader reads from the pipe, it
622c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // receives a "readPTS" indicating the point in time for which the reader
632c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // would like to read data.  This "last read PTS" is offset by the amt of
642c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // data the reader is currently mixing and then cached cached along with the
652c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // updated read pointer.  This cached value is the local time for which the
662c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // reader is going to request data next time it reads data (assuming we are
672c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // in steady state and operating with no underflows).  Writers to the
682c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // MonoPipe who would like to know when their next write operation will hit
692c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // the speakers can call getNextWriteTimestamp which will return the value
702c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // of the last read PTS plus the duration of the amt of data waiting to be
712c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // read in the MonoPipe.
722c3b2da3049627264b7c6b449a1622f002210f03John Grossman    virtual status_t getNextWriteTimestamp(int64_t *timestamp);
732c3b2da3049627264b7c6b449a1622f002210f03John Grossman
74e737cda649acbfa43fc1b74612a83f2fac9aa449Eric Laurent            // average number of frames present in the pipe under normal conditions.
75e737cda649acbfa43fc1b74612a83f2fac9aa449Eric Laurent            // See throttling mechanism in MonoPipe::write()
7628ed2f93324988767b5658eba7c1fa781a275183Glenn Kasten            size_t  getAvgFrames() const { return mSetpoint; }
7728ed2f93324988767b5658eba7c1fa781a275183Glenn Kasten            void    setAvgFrames(size_t setpoint);
7828ed2f93324988767b5658eba7c1fa781a275183Glenn Kasten            size_t  maxFrames() const { return mMaxFrames; }
79e737cda649acbfa43fc1b74612a83f2fac9aa449Eric Laurent
80003d9f71937070791418bf7efc1f7fe1e4c6b821Glenn Kasten            // Set the shutdown state for the write side of a pipe.
81003d9f71937070791418bf7efc1f7fe1e4c6b821Glenn Kasten            // This may be called by an unrelated thread.  When shutdown state is 'true',
82003d9f71937070791418bf7efc1f7fe1e4c6b821Glenn Kasten            // a write that would otherwise block instead returns a short transfer count.
83003d9f71937070791418bf7efc1f7fe1e4c6b821Glenn Kasten            // There is no guarantee how long it will take for the shutdown to be recognized,
84003d9f71937070791418bf7efc1f7fe1e4c6b821Glenn Kasten            // but it will not be an unbounded amount of time.
85003d9f71937070791418bf7efc1f7fe1e4c6b821Glenn Kasten            // The state can be restored to normal by calling shutdown(false).
86003d9f71937070791418bf7efc1f7fe1e4c6b821Glenn Kasten            void    shutdown(bool newState = true);
87003d9f71937070791418bf7efc1f7fe1e4c6b821Glenn Kasten
88003d9f71937070791418bf7efc1f7fe1e4c6b821Glenn Kasten            // Return true if the write side of a pipe is currently shutdown.
89003d9f71937070791418bf7efc1f7fe1e4c6b821Glenn Kasten            bool    isShutdown();
90003d9f71937070791418bf7efc1f7fe1e4c6b821Glenn Kasten
91010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenprivate:
922c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // A pair of methods and a helper variable which allows the reader and the
932c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // writer to update and observe the values of mFront and mNextRdPTS in an
942c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // atomic lock-less fashion.
952c3b2da3049627264b7c6b449a1622f002210f03John Grossman    //
962c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // :: Important ::
972c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // Two assumptions must be true in order for this lock-less approach to
982c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // function properly on all systems.  First, there may only be one updater
992c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // thread in the system.  Second, the updater thread must be running at a
1002c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // strictly higher priority than the observer threads.  Currently, both of
1012c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // these assumptions are true.  The only updater is always a single
1022c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // FastMixer thread (which runs with SCHED_FIFO/RT priority while the only
1032c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // observer is always an AudioFlinger::PlaybackThread running with
1042c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // traditional (non-RT) audio priority.
1052c3b2da3049627264b7c6b449a1622f002210f03John Grossman    void updateFrontAndNRPTS(int32_t newFront, int64_t newNextRdPTS);
1062c3b2da3049627264b7c6b449a1622f002210f03John Grossman    void observeFrontAndNRPTS(int32_t *outFront, int64_t *outNextRdPTS);
1072c3b2da3049627264b7c6b449a1622f002210f03John Grossman    volatile int32_t mUpdateSeq;
1082c3b2da3049627264b7c6b449a1622f002210f03John Grossman
109820ba70df8ba595ae9055dfd34fdbfa32f70f14dGlenn Kasten    const size_t    mReqFrames;     // as requested in constructor, unrounded
110010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    const size_t    mMaxFrames;     // always a power of 2
111010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    void * const    mBuffer;
112010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // mFront and mRear will never be separated by more than mMaxFrames.
113010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // 32-bit overflow is possible if the pipe is active for a long time, but if that happens it's
114010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // safe because we "&" with (mMaxFrames-1) at end of computations to calculate a buffer index.
1152c3b2da3049627264b7c6b449a1622f002210f03John Grossman    volatile int32_t mFront;        // written by the reader with updateFrontAndNRPTS, observed by
1162c3b2da3049627264b7c6b449a1622f002210f03John Grossman                                    // the writer with observeFrontAndNRPTS
117010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    volatile int32_t mRear;         // written by writer with android_atomic_release_store,
118010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten                                    // read by reader with android_atomic_acquire_load
1192c3b2da3049627264b7c6b449a1622f002210f03John Grossman    volatile int64_t mNextRdPTS;    // written by the reader with updateFrontAndNRPTS, observed by
1202c3b2da3049627264b7c6b449a1622f002210f03John Grossman                                    // the writer with observeFrontAndNRPTS
12128ed2f93324988767b5658eba7c1fa781a275183Glenn Kasten    bool            mWriteTsValid;  // whether mWriteTs is valid
12228ed2f93324988767b5658eba7c1fa781a275183Glenn Kasten    struct timespec mWriteTs;       // time that the previous write() completed
12328ed2f93324988767b5658eba7c1fa781a275183Glenn Kasten    size_t          mSetpoint;      // target value for pipe fill depth
124010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    const bool      mWriteCanBlock; // whether write() should block if the pipe is full
1252c3b2da3049627264b7c6b449a1622f002210f03John Grossman
1262c3b2da3049627264b7c6b449a1622f002210f03John Grossman    int64_t offsetTimestampByAudioFrames(int64_t ts, size_t audFrames);
1272c3b2da3049627264b7c6b449a1622f002210f03John Grossman    LinearTransform mSamplesToLocalTime;
128003d9f71937070791418bf7efc1f7fe1e4c6b821Glenn Kasten
129003d9f71937070791418bf7efc1f7fe1e4c6b821Glenn Kasten    bool            mIsShutdown;    // whether shutdown(true) was called, no barriers are needed
130010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten};
131010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
132010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten}   // namespace android
133010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
134010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten#endif  // ANDROID_AUDIO_MONO_PIPE_H
135