blob: 56896b9fd5f5ab36e12b533af5f13574f550679c [file] [log] [blame]
Glenn Kasten01066232012-02-27 11:50:44 -08001/*
2 * Copyright (C) 2012 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_NBAIO_H
18#define ANDROID_AUDIO_NBAIO_H
19
20// Non-blocking audio I/O interface
21//
22// This header file has the abstract interfaces only. Concrete implementation classes are declared
23// elsewhere. Implementations _should_ be non-blocking for all methods, especially read() and
24// write(), but this is not enforced. In general, implementations do not need to be multi-thread
25// safe, and any exceptions are noted in the particular implementation.
26
27#include <limits.h>
28#include <stdlib.h>
John Grossman2c3b2da2012-08-02 17:08:54 -070029#include <utils/Errors.h>
Glenn Kasten01066232012-02-27 11:50:44 -080030#include <utils/RefBase.h>
Glenn Kasten767094d2013-08-23 13:51:43 -070031#include <media/AudioTimestamp.h>
Glenn Kasten01066232012-02-27 11:50:44 -080032
33namespace android {
34
35// In addition to the usual status_t
36enum {
37 NEGOTIATE = 0x80000010, // Must (re-)negotiate format. For negotiate() only, the offeree
38 // doesn't accept offers, and proposes counter-offers
39 OVERRUN = 0x80000011, // availableToRead(), read(), or readVia() detected lost input due
40 // to overrun; an event is counted and the caller should re-try
41 UNDERRUN = 0x80000012, // availableToWrite(), write(), or writeVia() detected a gap in
42 // output due to underrun (not being called often enough, or with
43 // enough data); an event is counted and the caller should re-try
44};
45
46// Negotiation of format is based on the data provider and data sink, or the data consumer and
47// data source, exchanging prioritized arrays of offers and counter-offers until a single offer is
48// mutually agreed upon. Each offer is an NBAIO_Format. For simplicity and performance,
Glenn Kastenb64497e2012-10-01 09:47:30 -070049// NBAIO_Format is a typedef that ties together the most important combinations of the various
Glenn Kasten01066232012-02-27 11:50:44 -080050// attributes, rather than a struct with separate fields for format, sample rate, channel count,
51// interleave, packing, alignment, etc. The reason is that NBAIO_Format tries to abstract out only
Glenn Kastenb64497e2012-10-01 09:47:30 -070052// the combinations that are actually needed within AudioFlinger. If the list of combinations grows
Glenn Kasten01066232012-02-27 11:50:44 -080053// too large, then this decision should be re-visited.
Glenn Kastenb64497e2012-10-01 09:47:30 -070054// Sample rate and channel count are explicit, PCM interleaved 16-bit is assumed.
Glenn Kastenc4b8b322014-01-31 09:39:01 -080055struct NBAIO_Format {
56//private:
57 unsigned mPacked;
58};
Glenn Kasten51d53cd2014-01-31 09:38:33 -080059
60extern const NBAIO_Format Format_Invalid;
Glenn Kasten01066232012-02-27 11:50:44 -080061
62// Return the frame size of an NBAIO_Format in bytes
Glenn Kasten72e54af2014-01-31 09:37:35 -080063size_t Format_frameSize(const NBAIO_Format& format);
Glenn Kasten01066232012-02-27 11:50:44 -080064
65// Return the frame size of an NBAIO_Format as a bit shift
Glenn Kasten4d7b3f82014-01-31 10:38:16 -080066// or -1 if frame size is not a power of 2
67int Format_frameBitShift(const NBAIO_Format& format);
Glenn Kasten01066232012-02-27 11:50:44 -080068
69// Convert a sample rate in Hz and channel count to an NBAIO_Format
Glenn Kasten1ec712f2014-01-31 09:47:15 -080070// FIXME The sample format is hard-coded to AUDIO_FORMAT_PCM_16_BIT
Glenn Kasten01066232012-02-27 11:50:44 -080071NBAIO_Format Format_from_SR_C(unsigned sampleRate, unsigned channelCount);
72
73// Return the sample rate in Hz of an NBAIO_Format
Glenn Kasten72e54af2014-01-31 09:37:35 -080074unsigned Format_sampleRate(const NBAIO_Format& format);
Glenn Kasten01066232012-02-27 11:50:44 -080075
76// Return the channel count of an NBAIO_Format
Glenn Kasten72e54af2014-01-31 09:37:35 -080077unsigned Format_channelCount(const NBAIO_Format& format);
Glenn Kasten01066232012-02-27 11:50:44 -080078
79// Callbacks used by NBAIO_Sink::writeVia() and NBAIO_Source::readVia() below.
80typedef ssize_t (*writeVia_t)(void *user, void *buffer, size_t count);
John Grossman2c3b2da2012-08-02 17:08:54 -070081typedef ssize_t (*readVia_t)(void *user, const void *buffer,
82 size_t count, int64_t readPTS);
Glenn Kasten01066232012-02-27 11:50:44 -080083
Glenn Kastencc1e0e82014-01-31 09:48:42 -080084// Check whether an NBAIO_Format is valid
85bool Format_isValid(const NBAIO_Format& format);
86
87// Compare two NBAIO_Format values
88bool Format_isEqual(const NBAIO_Format& format1, const NBAIO_Format& format2);
89
Glenn Kasten01066232012-02-27 11:50:44 -080090// Abstract class (interface) representing a data port.
91class NBAIO_Port : public RefBase {
92
93public:
94
95 // negotiate() must called first. The purpose of negotiate() is to check compatibility of
96 // formats, not to automatically adapt if they are incompatible. It's the responsibility of
97 // whoever sets up the graph connections to make sure formats are compatible, and this method
98 // just verifies that. The edges are "dumb" and don't attempt to adapt to bad connections.
99 // How it works: offerer proposes an array of formats, in descending order of preference from
100 // offers[0] to offers[numOffers - 1]. If offeree accepts one of these formats, it returns
101 // the index of that offer. Otherwise, offeree sets numCounterOffers to the number of
102 // counter-offers (up to a maximumum of the entry value of numCounterOffers), fills in the
103 // provided array counterOffers[] with its counter-offers, in descending order of preference
104 // from counterOffers[0] to counterOffers[numCounterOffers - 1], and returns NEGOTIATE.
105 // Note that since the offerer allocates space for counter-offers, but only the offeree knows
106 // how many counter-offers it has, there may be insufficient space for all counter-offers.
107 // In that case, the offeree sets numCounterOffers to the requested number of counter-offers
108 // (which is greater than the entry value of numCounterOffers), fills in as many of the most
109 // important counterOffers as will fit, and returns NEGOTIATE. As this implies a re-allocation,
110 // it should be used as a last resort. It is preferable for the offerer to simply allocate a
111 // larger space to begin with, and/or for the offeree to tolerate a smaller space than desired.
112 // Alternatively, the offerer can pass NULL for offers and counterOffers, and zero for
113 // numOffers. This indicates that it has not allocated space for any counter-offers yet.
114 // In this case, the offerree should set numCounterOffers appropriately and return NEGOTIATE.
115 // Then the offerer will allocate the correct amount of memory and retry.
116 // Format_Invalid is not allowed as either an offer or counter-offer.
117 // Returns:
118 // >= 0 Offer accepted.
119 // NEGOTIATE No offer accepted, and counter-offer(s) optionally made. See above for details.
120 virtual ssize_t negotiate(const NBAIO_Format offers[], size_t numOffers,
121 NBAIO_Format counterOffers[], size_t& numCounterOffers);
122
123 // Return the current negotiated format, or Format_Invalid if negotiation has not been done,
124 // or if re-negotiation is required.
125 virtual NBAIO_Format format() const { return mNegotiated ? mFormat : Format_Invalid; }
126
127protected:
Glenn Kasten72e54af2014-01-31 09:37:35 -0800128 NBAIO_Port(const NBAIO_Format& format) : mNegotiated(false), mFormat(format),
129 mBitShift(Format_frameBitShift(format)) { }
Glenn Kasten01066232012-02-27 11:50:44 -0800130 virtual ~NBAIO_Port() { }
131
132 // Implementations are free to ignore these if they don't need them
133
134 bool mNegotiated; // mNegotiated implies (mFormat != Format_Invalid)
135 NBAIO_Format mFormat; // (mFormat != Format_Invalid) does not imply mNegotiated
136 size_t mBitShift; // assign in parallel with any assignment to mFormat
137};
138
139// Abstract class (interface) representing a non-blocking data sink, for use by a data provider.
140class NBAIO_Sink : public NBAIO_Port {
141
142public:
143
144 // For the next two APIs:
145 // 32 bits rolls over after 27 hours at 44.1 kHz; if that concerns you then poll periodically.
146
147 // Return the number of frames written successfully since construction.
148 virtual size_t framesWritten() const { return mFramesWritten; }
149
150 // Number of frames lost due to underrun since construction.
151 virtual size_t framesUnderrun() const { return 0; }
152
153 // Number of underruns since construction, where a set of contiguous lost frames is one event.
154 virtual size_t underruns() const { return 0; }
155
156 // Estimate of number of frames that could be written successfully now without blocking.
157 // When a write() is actually attempted, the implementation is permitted to return a smaller or
158 // larger transfer count, however it will make a good faith effort to give an accurate estimate.
159 // Errors:
160 // NEGOTIATE (Re-)negotiation is needed.
161 // UNDERRUN write() has not been called frequently enough, or with enough frames to keep up.
162 // An underrun event is counted, and the caller should re-try this operation.
163 // WOULD_BLOCK Determining how many frames can be written without blocking would itself block.
164 virtual ssize_t availableToWrite() const { return SSIZE_MAX; }
165
166 // Transfer data to sink from single input buffer. Implies a copy.
167 // Inputs:
168 // buffer Non-NULL buffer owned by provider.
169 // count Maximum number of frames to transfer.
170 // Return value:
171 // > 0 Number of frames successfully transferred prior to first error.
172 // = 0 Count was zero.
173 // < 0 status_t error occurred prior to the first frame transfer.
174 // Errors:
175 // NEGOTIATE (Re-)negotiation is needed.
176 // WOULD_BLOCK No frames can be transferred without blocking.
177 // UNDERRUN write() has not been called frequently enough, or with enough frames to keep up.
178 // An underrun event is counted, and the caller should re-try this operation.
179 virtual ssize_t write(const void *buffer, size_t count) = 0;
180
181 // Transfer data to sink using a series of callbacks. More suitable for zero-fill, synthesis,
182 // and non-contiguous transfers (e.g. circular buffer or writev).
183 // Inputs:
184 // via Callback function that the sink will call as many times as needed to consume data.
185 // total Estimate of the number of frames the provider has available. This is an estimate,
186 // and it can provide a different number of frames during the series of callbacks.
187 // user Arbitrary void * reserved for data provider.
188 // block Number of frames per block, that is a suggested value for 'count' in each callback.
189 // Zero means no preference. This parameter is a hint only, and may be ignored.
190 // Return value:
191 // > 0 Total number of frames successfully transferred prior to first error.
192 // = 0 Count was zero.
193 // < 0 status_t error occurred prior to the first frame transfer.
194 // Errors:
195 // NEGOTIATE (Re-)negotiation is needed.
196 // WOULD_BLOCK No frames can be transferred without blocking.
197 // UNDERRUN write() has not been called frequently enough, or with enough frames to keep up.
198 // An underrun event is counted, and the caller should re-try this operation.
199 //
200 // The 'via' callback is called by the data sink as follows:
201 // Inputs:
202 // user Arbitrary void * reserved for data provider.
203 // buffer Non-NULL buffer owned by sink that callback should fill in with data,
204 // up to a maximum of 'count' frames.
205 // count Maximum number of frames to transfer during this callback.
206 // Return value:
207 // > 0 Number of frames successfully transferred during this callback prior to first error.
208 // = 0 Count was zero.
209 // < 0 status_t error occurred prior to the first frame transfer during this callback.
210 virtual ssize_t writeVia(writeVia_t via, size_t total, void *user, size_t block = 0);
211
John Grossman2c3b2da2012-08-02 17:08:54 -0700212 // Get the time (on the LocalTime timeline) at which the first frame of audio of the next write
213 // operation to this sink will be eventually rendered by the HAL.
214 // Inputs:
215 // ts A pointer pointing to the int64_t which will hold the result.
216 // Return value:
217 // OK Everything went well, *ts holds the time at which the first audio frame of the next
218 // write operation will be rendered, or AudioBufferProvider::kInvalidPTS if this sink
219 // does not know the answer for some reason. Sinks which eventually lead to a HAL
220 // which implements get_next_write_timestamp may return Invalid temporarily if the DMA
221 // output of the audio driver has not started yet. Sinks which lead to a HAL which
222 // does not implement get_next_write_timestamp, or which don't lead to a HAL at all,
223 // will always return kInvalidPTS.
224 // <other> Something unexpected happened internally. Check the logs and start debugging.
225 virtual status_t getNextWriteTimestamp(int64_t *ts) { return INVALID_OPERATION; }
226
Glenn Kasten767094d2013-08-23 13:51:43 -0700227 // Returns NO_ERROR if a timestamp is available. The timestamp includes the total number
228 // of frames presented to an external observer, together with the value of CLOCK_MONOTONIC
229 // as of this presentation count.
230 virtual status_t getTimestamp(AudioTimestamp& timestamp) { return INVALID_OPERATION; }
231
Glenn Kasten01066232012-02-27 11:50:44 -0800232protected:
Glenn Kasten72e54af2014-01-31 09:37:35 -0800233 NBAIO_Sink(const NBAIO_Format& format = Format_Invalid) : NBAIO_Port(format), mFramesWritten(0) { }
Glenn Kasten01066232012-02-27 11:50:44 -0800234 virtual ~NBAIO_Sink() { }
235
236 // Implementations are free to ignore these if they don't need them
237 size_t mFramesWritten;
238};
239
240// Abstract class (interface) representing a non-blocking data source, for use by a data consumer.
241class NBAIO_Source : public NBAIO_Port {
242
243public:
244
245 // For the next two APIs:
246 // 32 bits rolls over after 27 hours at 44.1 kHz; if that concerns you then poll periodically.
247
248 // Number of frames read successfully since construction.
249 virtual size_t framesRead() const { return mFramesRead; }
250
251 // Number of frames lost due to overrun since construction.
252 // Not const because implementations may need to do I/O.
253 virtual size_t framesOverrun() /*const*/ { return 0; }
254
255 // Number of overruns since construction, where a set of contiguous lost frames is one event.
256 // Not const because implementations may need to do I/O.
257 virtual size_t overruns() /*const*/ { return 0; }
258
259 // Estimate of number of frames that could be read successfully now.
260 // When a read() is actually attempted, the implementation is permitted to return a smaller or
261 // larger transfer count, however it will make a good faith effort to give an accurate estimate.
262 // Errors:
263 // NEGOTIATE (Re-)negotiation is needed.
264 // OVERRUN One or more frames were lost due to overrun, try again to read more recent data.
265 // WOULD_BLOCK Determining how many frames can be read without blocking would itself block.
266 virtual ssize_t availableToRead() { return SSIZE_MAX; }
267
268 // Transfer data from source into single destination buffer. Implies a copy.
269 // Inputs:
270 // buffer Non-NULL destination buffer owned by consumer.
271 // count Maximum number of frames to transfer.
John Grossman2c3b2da2012-08-02 17:08:54 -0700272 // readPTS The presentation time (on the LocalTime timeline) for which data
273 // is being requested, or kInvalidPTS if not known.
Glenn Kasten01066232012-02-27 11:50:44 -0800274 // Return value:
275 // > 0 Number of frames successfully transferred prior to first error.
276 // = 0 Count was zero.
277 // < 0 status_t error occurred prior to the first frame transfer.
278 // Errors:
279 // NEGOTIATE (Re-)negotiation is needed.
280 // WOULD_BLOCK No frames can be transferred without blocking.
281 // OVERRUN read() has not been called frequently enough, or with enough frames to keep up.
282 // One or more frames were lost due to overrun, try again to read more recent data.
John Grossman2c3b2da2012-08-02 17:08:54 -0700283 virtual ssize_t read(void *buffer, size_t count, int64_t readPTS) = 0;
Glenn Kasten01066232012-02-27 11:50:44 -0800284
285 // Transfer data from source using a series of callbacks. More suitable for zero-fill,
286 // synthesis, and non-contiguous transfers (e.g. circular buffer or readv).
287 // Inputs:
288 // via Callback function that the source will call as many times as needed to provide data.
289 // total Estimate of the number of frames the consumer desires. This is an estimate,
290 // and it can consume a different number of frames during the series of callbacks.
291 // user Arbitrary void * reserved for data consumer.
John Grossman2c3b2da2012-08-02 17:08:54 -0700292 // readPTS The presentation time (on the LocalTime timeline) for which data
293 // is being requested, or kInvalidPTS if not known.
Glenn Kasten01066232012-02-27 11:50:44 -0800294 // block Number of frames per block, that is a suggested value for 'count' in each callback.
295 // Zero means no preference. This parameter is a hint only, and may be ignored.
296 // Return value:
297 // > 0 Total number of frames successfully transferred prior to first error.
298 // = 0 Count was zero.
299 // < 0 status_t error occurred prior to the first frame transfer.
300 // Errors:
301 // NEGOTIATE (Re-)negotiation is needed.
302 // WOULD_BLOCK No frames can be transferred without blocking.
303 // OVERRUN read() has not been called frequently enough, or with enough frames to keep up.
304 // One or more frames were lost due to overrun, try again to read more recent data.
305 //
306 // The 'via' callback is called by the data source as follows:
307 // Inputs:
308 // user Arbitrary void * reserved for data consumer.
309 // dest Non-NULL buffer owned by source that callback should consume data from,
310 // up to a maximum of 'count' frames.
311 // count Maximum number of frames to transfer during this callback.
312 // Return value:
313 // > 0 Number of frames successfully transferred during this callback prior to first error.
314 // = 0 Count was zero.
315 // < 0 status_t error occurred prior to the first frame transfer during this callback.
John Grossman2c3b2da2012-08-02 17:08:54 -0700316 virtual ssize_t readVia(readVia_t via, size_t total, void *user,
317 int64_t readPTS, size_t block = 0);
Glenn Kasten01066232012-02-27 11:50:44 -0800318
Glenn Kasten894d6be2013-08-26 10:29:28 -0700319 // Invoked asynchronously by corresponding sink when a new timestamp is available.
320 // Default implementation ignores the timestamp.
321 virtual void onTimestamp(const AudioTimestamp& timestamp) { }
322
Glenn Kasten01066232012-02-27 11:50:44 -0800323protected:
Glenn Kasten72e54af2014-01-31 09:37:35 -0800324 NBAIO_Source(const NBAIO_Format& format = Format_Invalid) : NBAIO_Port(format), mFramesRead(0) { }
Glenn Kasten01066232012-02-27 11:50:44 -0800325 virtual ~NBAIO_Source() { }
326
327 // Implementations are free to ignore these if they don't need them
328 size_t mFramesRead;
329};
330
331} // namespace android
332
333#endif // ANDROID_AUDIO_NBAIO_H