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_NBAIO_H
18010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten#define ANDROID_AUDIO_NBAIO_H
19010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
20010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Non-blocking audio I/O interface
21010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten//
22010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// This header file has the abstract interfaces only.  Concrete implementation classes are declared
23010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// elsewhere.  Implementations _should_ be non-blocking for all methods, especially read() and
24010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// write(), but this is not enforced.  In general, implementations do not need to be multi-thread
25010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// safe, and any exceptions are noted in the particular implementation.
26010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
27010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten#include <limits.h>
28010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten#include <stdlib.h>
292c3b2da3049627264b7c6b449a1622f002210f03John Grossman#include <utils/Errors.h>
30010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten#include <utils/RefBase.h>
31010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
32010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastennamespace android {
33010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
34010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// In addition to the usual status_t
35010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenenum {
36010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    NEGOTIATE    = 0x80000010,  // Must (re-)negotiate format.  For negotiate() only, the offeree
37010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten                                // doesn't accept offers, and proposes counter-offers
38010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    OVERRUN      = 0x80000011,  // availableToRead(), read(), or readVia() detected lost input due
39010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten                                // to overrun; an event is counted and the caller should re-try
40010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    UNDERRUN     = 0x80000012,  // availableToWrite(), write(), or writeVia() detected a gap in
41010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten                                // output due to underrun (not being called often enough, or with
42010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten                                // enough data); an event is counted and the caller should re-try
43010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten};
44010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
45010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Negotiation of format is based on the data provider and data sink, or the data consumer and
46010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// data source, exchanging prioritized arrays of offers and counter-offers until a single offer is
47010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// mutually agreed upon.  Each offer is an NBAIO_Format.  For simplicity and performance,
48010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// NBAIO_Format is an enum that ties together the most important combinations of the various
49010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// attributes, rather than a struct with separate fields for format, sample rate, channel count,
50010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// interleave, packing, alignment, etc.  The reason is that NBAIO_Format tries to abstract out only
51010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// the combinations that are actually needed within AudioFligner.  If the list of combinations grows
52010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// too large, then this decision should be re-visited.
53010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenenum NBAIO_Format {
54010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    Format_Invalid,
55010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    Format_SR44_1_C2_I16,   // 44.1 kHz PCM stereo interleaved 16-bit signed
56010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    Format_SR48_C2_I16,     // 48 kHz PCM stereo interleaved 16-bit signed
57010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    Format_SR44_1_C1_I16,   // 44.1 kHz PCM mono interleaved 16-bit signed
58010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    Format_SR48_C1_I16,     // 48 kHz PCM mono interleaved 16-bit signed
59010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten};
60010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
61010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Return the frame size of an NBAIO_Format in bytes
62010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastensize_t Format_frameSize(NBAIO_Format format);
63010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
64010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Return the frame size of an NBAIO_Format as a bit shift
65010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastensize_t Format_frameBitShift(NBAIO_Format format);
66010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
67010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Convert a sample rate in Hz and channel count to an NBAIO_Format
68010662326b9c43c703725f933e95e0897f8a6bddGlenn KastenNBAIO_Format Format_from_SR_C(unsigned sampleRate, unsigned channelCount);
69010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
70010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Return the sample rate in Hz of an NBAIO_Format
71010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenunsigned Format_sampleRate(NBAIO_Format format);
72010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
73010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Return the channel count of an NBAIO_Format
74010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenunsigned Format_channelCount(NBAIO_Format format);
75010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
76010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Callbacks used by NBAIO_Sink::writeVia() and NBAIO_Source::readVia() below.
77010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastentypedef ssize_t (*writeVia_t)(void *user, void *buffer, size_t count);
782c3b2da3049627264b7c6b449a1622f002210f03John Grossmantypedef ssize_t (*readVia_t)(void *user, const void *buffer,
792c3b2da3049627264b7c6b449a1622f002210f03John Grossman                             size_t count, int64_t readPTS);
80010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
81010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Abstract class (interface) representing a data port.
82010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenclass NBAIO_Port : public RefBase {
83010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
84010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenpublic:
85010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
86010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // negotiate() must called first.  The purpose of negotiate() is to check compatibility of
87010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // formats, not to automatically adapt if they are incompatible.  It's the responsibility of
88010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // whoever sets up the graph connections to make sure formats are compatible, and this method
89010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // just verifies that.  The edges are "dumb" and don't attempt to adapt to bad connections.
90010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // How it works: offerer proposes an array of formats, in descending order of preference from
91010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // offers[0] to offers[numOffers - 1].  If offeree accepts one of these formats, it returns
92010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // the index of that offer.  Otherwise, offeree sets numCounterOffers to the number of
93010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // counter-offers (up to a maximumum of the entry value of numCounterOffers), fills in the
94010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // provided array counterOffers[] with its counter-offers, in descending order of preference
95010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // from counterOffers[0] to counterOffers[numCounterOffers - 1], and returns NEGOTIATE.
96010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Note that since the offerer allocates space for counter-offers, but only the offeree knows
97010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // how many counter-offers it has, there may be insufficient space for all counter-offers.
98010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // In that case, the offeree sets numCounterOffers to the requested number of counter-offers
99010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // (which is greater than the entry value of numCounterOffers), fills in as many of the most
100010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // important counterOffers as will fit, and returns NEGOTIATE.  As this implies a re-allocation,
101010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // it should be used as a last resort.  It is preferable for the offerer to simply allocate a
102010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // larger space to begin with, and/or for the offeree to tolerate a smaller space than desired.
103010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Alternatively, the offerer can pass NULL for offers and counterOffers, and zero for
104010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // numOffers. This indicates that it has not allocated space for any counter-offers yet.
105010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // In this case, the offerree should set numCounterOffers appropriately and return NEGOTIATE.
106010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Then the offerer will allocate the correct amount of memory and retry.
107010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Format_Invalid is not allowed as either an offer or counter-offer.
108010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Returns:
109010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  >= 0        Offer accepted.
110010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  NEGOTIATE   No offer accepted, and counter-offer(s) optionally made. See above for details.
111010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual ssize_t negotiate(const NBAIO_Format offers[], size_t numOffers,
112010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten                              NBAIO_Format counterOffers[], size_t& numCounterOffers);
113010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
114010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Return the current negotiated format, or Format_Invalid if negotiation has not been done,
115010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // or if re-negotiation is required.
116010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual NBAIO_Format format() const { return mNegotiated ? mFormat : Format_Invalid; }
117010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
118010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenprotected:
119010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    NBAIO_Port(NBAIO_Format format) : mNegotiated(false), mFormat(format),
120010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten                                      mBitShift(Format_frameBitShift(format)) { }
121010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual ~NBAIO_Port() { }
122010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
123010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Implementations are free to ignore these if they don't need them
124010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
125010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    bool            mNegotiated;    // mNegotiated implies (mFormat != Format_Invalid)
126010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    NBAIO_Format    mFormat;        // (mFormat != Format_Invalid) does not imply mNegotiated
127010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    size_t          mBitShift;      // assign in parallel with any assignment to mFormat
128010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten};
129010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
130010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Abstract class (interface) representing a non-blocking data sink, for use by a data provider.
131010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenclass NBAIO_Sink : public NBAIO_Port {
132010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
133010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenpublic:
134010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
135010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // For the next two APIs:
136010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // 32 bits rolls over after 27 hours at 44.1 kHz; if that concerns you then poll periodically.
137010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
138010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Return the number of frames written successfully since construction.
139010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual size_t framesWritten() const { return mFramesWritten; }
140010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
141010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Number of frames lost due to underrun since construction.
142010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual size_t framesUnderrun() const { return 0; }
143010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
144010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Number of underruns since construction, where a set of contiguous lost frames is one event.
145010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual size_t underruns() const { return 0; }
146010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
147010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Estimate of number of frames that could be written successfully now without blocking.
148010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // When a write() is actually attempted, the implementation is permitted to return a smaller or
149010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // larger transfer count, however it will make a good faith effort to give an accurate estimate.
150010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Errors:
151010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  NEGOTIATE   (Re-)negotiation is needed.
152010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  UNDERRUN    write() has not been called frequently enough, or with enough frames to keep up.
153010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //              An underrun event is counted, and the caller should re-try this operation.
154010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  WOULD_BLOCK Determining how many frames can be written without blocking would itself block.
155010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual ssize_t availableToWrite() const { return SSIZE_MAX; }
156010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
157010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Transfer data to sink from single input buffer.  Implies a copy.
158010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Inputs:
159010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  buffer  Non-NULL buffer owned by provider.
160010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  count   Maximum number of frames to transfer.
161010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Return value:
162010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  > 0     Number of frames successfully transferred prior to first error.
163010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  = 0     Count was zero.
164010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  < 0     status_t error occurred prior to the first frame transfer.
165010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Errors:
166010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  NEGOTIATE   (Re-)negotiation is needed.
167010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  WOULD_BLOCK No frames can be transferred without blocking.
168010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  UNDERRUN    write() has not been called frequently enough, or with enough frames to keep up.
169010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //              An underrun event is counted, and the caller should re-try this operation.
170010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual ssize_t write(const void *buffer, size_t count) = 0;
171010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
172010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Transfer data to sink using a series of callbacks.  More suitable for zero-fill, synthesis,
173010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // and non-contiguous transfers (e.g. circular buffer or writev).
174010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Inputs:
175010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  via     Callback function that the sink will call as many times as needed to consume data.
176010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  total   Estimate of the number of frames the provider has available.  This is an estimate,
177010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //          and it can provide a different number of frames during the series of callbacks.
178010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  user    Arbitrary void * reserved for data provider.
179010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  block   Number of frames per block, that is a suggested value for 'count' in each callback.
180010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //          Zero means no preference.  This parameter is a hint only, and may be ignored.
181010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Return value:
182010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  > 0     Total number of frames successfully transferred prior to first error.
183010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  = 0     Count was zero.
184010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  < 0     status_t error occurred prior to the first frame transfer.
185010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Errors:
186010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  NEGOTIATE   (Re-)negotiation is needed.
187010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  WOULD_BLOCK No frames can be transferred without blocking.
188010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  UNDERRUN    write() has not been called frequently enough, or with enough frames to keep up.
189010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //              An underrun event is counted, and the caller should re-try this operation.
190010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //
191010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // The 'via' callback is called by the data sink as follows:
192010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Inputs:
193010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  user    Arbitrary void * reserved for data provider.
194010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  buffer  Non-NULL buffer owned by sink that callback should fill in with data,
195010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //          up to a maximum of 'count' frames.
196010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  count   Maximum number of frames to transfer during this callback.
197010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Return value:
198010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  > 0     Number of frames successfully transferred during this callback prior to first error.
199010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  = 0     Count was zero.
200010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  < 0     status_t error occurred prior to the first frame transfer during this callback.
201010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual ssize_t writeVia(writeVia_t via, size_t total, void *user, size_t block = 0);
202010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
2032c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // Get the time (on the LocalTime timeline) at which the first frame of audio of the next write
2042c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // operation to this sink will be eventually rendered by the HAL.
2052c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // Inputs:
2062c3b2da3049627264b7c6b449a1622f002210f03John Grossman    //  ts      A pointer pointing to the int64_t which will hold the result.
2072c3b2da3049627264b7c6b449a1622f002210f03John Grossman    // Return value:
2082c3b2da3049627264b7c6b449a1622f002210f03John Grossman    //  OK      Everything went well, *ts holds the time at which the first audio frame of the next
2092c3b2da3049627264b7c6b449a1622f002210f03John Grossman    //          write operation will be rendered, or AudioBufferProvider::kInvalidPTS if this sink
2102c3b2da3049627264b7c6b449a1622f002210f03John Grossman    //          does not know the answer for some reason.  Sinks which eventually lead to a HAL
2112c3b2da3049627264b7c6b449a1622f002210f03John Grossman    //          which implements get_next_write_timestamp may return Invalid temporarily if the DMA
2122c3b2da3049627264b7c6b449a1622f002210f03John Grossman    //          output of the audio driver has not started yet.  Sinks which lead to a HAL which
2132c3b2da3049627264b7c6b449a1622f002210f03John Grossman    //          does not implement get_next_write_timestamp, or which don't lead to a HAL at all,
2142c3b2da3049627264b7c6b449a1622f002210f03John Grossman    //          will always return kInvalidPTS.
2152c3b2da3049627264b7c6b449a1622f002210f03John Grossman    //  <other> Something unexpected happened internally.  Check the logs and start debugging.
2162c3b2da3049627264b7c6b449a1622f002210f03John Grossman    virtual status_t getNextWriteTimestamp(int64_t *ts) { return INVALID_OPERATION; }
2172c3b2da3049627264b7c6b449a1622f002210f03John Grossman
218010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenprotected:
219010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    NBAIO_Sink(NBAIO_Format format = Format_Invalid) : NBAIO_Port(format), mFramesWritten(0) { }
220010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual ~NBAIO_Sink() { }
221010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
222010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Implementations are free to ignore these if they don't need them
223010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    size_t  mFramesWritten;
224010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten};
225010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
226010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Abstract class (interface) representing a non-blocking data source, for use by a data consumer.
227010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenclass NBAIO_Source : public NBAIO_Port {
228010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
229010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenpublic:
230010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
231010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // For the next two APIs:
232010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // 32 bits rolls over after 27 hours at 44.1 kHz; if that concerns you then poll periodically.
233010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
234010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Number of frames read successfully since construction.
235010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual size_t framesRead() const { return mFramesRead; }
236010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
237010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Number of frames lost due to overrun since construction.
238010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Not const because implementations may need to do I/O.
239010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual size_t framesOverrun() /*const*/ { return 0; }
240010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
241010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Number of overruns since construction, where a set of contiguous lost frames is one event.
242010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Not const because implementations may need to do I/O.
243010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual size_t overruns() /*const*/ { return 0; }
244010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
245010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Estimate of number of frames that could be read successfully now.
246010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // When a read() is actually attempted, the implementation is permitted to return a smaller or
247010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // larger transfer count, however it will make a good faith effort to give an accurate estimate.
248010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Errors:
249010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  NEGOTIATE   (Re-)negotiation is needed.
250010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  OVERRUN     One or more frames were lost due to overrun, try again to read more recent data.
251010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  WOULD_BLOCK Determining how many frames can be read without blocking would itself block.
252010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual ssize_t availableToRead() { return SSIZE_MAX; }
253010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
254010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Transfer data from source into single destination buffer.  Implies a copy.
255010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Inputs:
256010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  buffer  Non-NULL destination buffer owned by consumer.
257010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  count   Maximum number of frames to transfer.
2582c3b2da3049627264b7c6b449a1622f002210f03John Grossman    //  readPTS The presentation time (on the LocalTime timeline) for which data
2592c3b2da3049627264b7c6b449a1622f002210f03John Grossman    //          is being requested, or kInvalidPTS if not known.
260010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Return value:
261010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  > 0     Number of frames successfully transferred prior to first error.
262010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  = 0     Count was zero.
263010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  < 0     status_t error occurred prior to the first frame transfer.
264010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Errors:
265010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  NEGOTIATE   (Re-)negotiation is needed.
266010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  WOULD_BLOCK No frames can be transferred without blocking.
267010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  OVERRUN     read() has not been called frequently enough, or with enough frames to keep up.
268010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //              One or more frames were lost due to overrun, try again to read more recent data.
2692c3b2da3049627264b7c6b449a1622f002210f03John Grossman    virtual ssize_t read(void *buffer, size_t count, int64_t readPTS) = 0;
270010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
271010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Transfer data from source using a series of callbacks.  More suitable for zero-fill,
272010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // synthesis, and non-contiguous transfers (e.g. circular buffer or readv).
273010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Inputs:
274010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  via     Callback function that the source will call as many times as needed to provide data.
275010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  total   Estimate of the number of frames the consumer desires.  This is an estimate,
276010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //          and it can consume a different number of frames during the series of callbacks.
277010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  user    Arbitrary void * reserved for data consumer.
2782c3b2da3049627264b7c6b449a1622f002210f03John Grossman    //  readPTS The presentation time (on the LocalTime timeline) for which data
2792c3b2da3049627264b7c6b449a1622f002210f03John Grossman    //          is being requested, or kInvalidPTS if not known.
280010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  block   Number of frames per block, that is a suggested value for 'count' in each callback.
281010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //          Zero means no preference.  This parameter is a hint only, and may be ignored.
282010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Return value:
283010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  > 0     Total number of frames successfully transferred prior to first error.
284010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  = 0     Count was zero.
285010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  < 0     status_t error occurred prior to the first frame transfer.
286010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Errors:
287010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  NEGOTIATE   (Re-)negotiation is needed.
288010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  WOULD_BLOCK No frames can be transferred without blocking.
289010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  OVERRUN     read() has not been called frequently enough, or with enough frames to keep up.
290010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //              One or more frames were lost due to overrun, try again to read more recent data.
291010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //
292010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // The 'via' callback is called by the data source as follows:
293010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Inputs:
294010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  user    Arbitrary void * reserved for data consumer.
295010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  dest    Non-NULL buffer owned by source that callback should consume data from,
296010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //          up to a maximum of 'count' frames.
297010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  count   Maximum number of frames to transfer during this callback.
298010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Return value:
299010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  > 0     Number of frames successfully transferred during this callback prior to first error.
300010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  = 0     Count was zero.
301010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    //  < 0     status_t error occurred prior to the first frame transfer during this callback.
3022c3b2da3049627264b7c6b449a1622f002210f03John Grossman    virtual ssize_t readVia(readVia_t via, size_t total, void *user,
3032c3b2da3049627264b7c6b449a1622f002210f03John Grossman                            int64_t readPTS, size_t block = 0);
304010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
305010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenprotected:
306010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    NBAIO_Source(NBAIO_Format format = Format_Invalid) : NBAIO_Port(format), mFramesRead(0) { }
307010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    virtual ~NBAIO_Source() { }
308010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
309010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    // Implementations are free to ignore these if they don't need them
310010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten    size_t  mFramesRead;
311010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten};
312010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
313010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten}   // namespace android
314010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten
315010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten#endif  // ANDROID_AUDIO_NBAIO_H
316