Non-blocking audio I/O interface, WIP
Yet another abstraction similar to AudioTrack::Buffer and AudioBufferProvider,
but with support for streaming, non-blocking, and eventually PTS.
This is intended to be used as follows:
- primary HAL output stream implements a Sink
- primary HAL input stream implements a Source
- Pipe implements a Sink
- PipeReader implements a Source or TimedSource (not shown yet),
which supports "read at PTS"
- fast AudioTrack on server side will implement a Source using cblk
- normal AudioTrack on server side will not be changed initially
- fast AudioRecord on server side will implement a Sink using cblk
- normal AudioRecord on server side will not be changed initially
- fast mixer thread will read from Sources and write to a Sink,
or (unlikely) implement a Source and multiple Sinks
- Visualization and PCM logger will read from Source or TimedSource
- A2DP normal mixer will be connected directly to its output stream
and there will be a kind of OutputTrack for duplication that will
read from a Sink with non-blocking write fed by the fast mixer.
Patch set 3 changes:
- Add more implementations of NBAIO interfaces:
added SourceAudioBufferProvider, MonoPipe, MonoPipeReader.
- Added Format_sampleRate and Format_channelCount.
- Extract out the roundUp() method.
- Respond to most comments from previous code review.
- The new classes are untested.
Patch set 4 changes:
- Fix bugs in MonoPipe::write() and MonoPipeReader::read()
- Fix bug initializing mFrameBitShift too early
- renamed roundUp() to roundup()
- Fix Android.mk
- Add LOG_TAG an LOG_NDEBUG, use ALOG_ASSERT and utils/Log.h instead of assert
- Fix build warnings
- Move constructor and destructor bodies from .h to .cpp
- Line length 100
- Following naming conventions for #include double-include protector macros
- Include what you use
- More NBAIO logging
- MonoPipe write can be blocking
Patch set 5 changes:
- Address code review comments
- Use a static library so unused implementations don't take memory
- Comment out libsndfile dependency
- Remove debugging LOGV and LOG_NDEBUG
Patch set 6 changes (would be 6 at old location, actually 2 at new location):
- Address code review comments on patchset 5
- For MonoPipe, allow the full pipe to be used, no need to omit one slot
- Don't do atomic releasing stores unless needed
Still to do:
- I'm not happy with the Pipe class names
- Update build/ for new static library?
Change-Id: Ie6c61f05ce06b676b033be448a8ef9025a2ffcfd
diff --git a/services/audioflinger/NBAIO.h b/services/audioflinger/NBAIO.h
new file mode 100644
index 0000000..b5ae0f1
--- /dev/null
+++ b/services/audioflinger/NBAIO.h
@@ -0,0 +1,293 @@
+/*
+ * Copyright (C) 2012 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef ANDROID_AUDIO_NBAIO_H
+#define ANDROID_AUDIO_NBAIO_H
+
+// Non-blocking audio I/O interface
+//
+// This header file has the abstract interfaces only. Concrete implementation classes are declared
+// elsewhere. Implementations _should_ be non-blocking for all methods, especially read() and
+// write(), but this is not enforced. In general, implementations do not need to be multi-thread
+// safe, and any exceptions are noted in the particular implementation.
+
+#include <limits.h>
+#include <stdlib.h>
+#include <utils/RefBase.h>
+
+namespace android {
+
+// In addition to the usual status_t
+enum {
+ NEGOTIATE = 0x80000010, // Must (re-)negotiate format. For negotiate() only, the offeree
+ // doesn't accept offers, and proposes counter-offers
+ OVERRUN = 0x80000011, // availableToRead(), read(), or readVia() detected lost input due
+ // to overrun; an event is counted and the caller should re-try
+ UNDERRUN = 0x80000012, // availableToWrite(), write(), or writeVia() detected a gap in
+ // output due to underrun (not being called often enough, or with
+ // enough data); an event is counted and the caller should re-try
+};
+
+// Negotiation of format is based on the data provider and data sink, or the data consumer and
+// data source, exchanging prioritized arrays of offers and counter-offers until a single offer is
+// mutually agreed upon. Each offer is an NBAIO_Format. For simplicity and performance,
+// NBAIO_Format is an enum that ties together the most important combinations of the various
+// attributes, rather than a struct with separate fields for format, sample rate, channel count,
+// interleave, packing, alignment, etc. The reason is that NBAIO_Format tries to abstract out only
+// the combinations that are actually needed within AudioFligner. If the list of combinations grows
+// too large, then this decision should be re-visited.
+enum NBAIO_Format {
+ Format_Invalid,
+ Format_SR44_1_C2_I16, // 44.1 kHz PCM stereo interleaved 16-bit signed
+ Format_SR48_C2_I16, // 48 kHz PCM stereo interleaved 16-bit signed
+ Format_SR44_1_C1_I16, // 44.1 kHz PCM mono interleaved 16-bit signed
+ Format_SR48_C1_I16, // 48 kHz PCM mono interleaved 16-bit signed
+};
+
+// Return the frame size of an NBAIO_Format in bytes
+size_t Format_frameSize(NBAIO_Format format);
+
+// Return the frame size of an NBAIO_Format as a bit shift
+size_t Format_frameBitShift(NBAIO_Format format);
+
+// Convert a sample rate in Hz and channel count to an NBAIO_Format
+NBAIO_Format Format_from_SR_C(unsigned sampleRate, unsigned channelCount);
+
+// Return the sample rate in Hz of an NBAIO_Format
+unsigned Format_sampleRate(NBAIO_Format format);
+
+// Return the channel count of an NBAIO_Format
+unsigned Format_channelCount(NBAIO_Format format);
+
+// Callbacks used by NBAIO_Sink::writeVia() and NBAIO_Source::readVia() below.
+typedef ssize_t (*writeVia_t)(void *user, void *buffer, size_t count);
+typedef ssize_t (*readVia_t)(void *user, const void *buffer, size_t count);
+
+// Abstract class (interface) representing a data port.
+class NBAIO_Port : public RefBase {
+
+public:
+
+ // negotiate() must called first. The purpose of negotiate() is to check compatibility of
+ // formats, not to automatically adapt if they are incompatible. It's the responsibility of
+ // whoever sets up the graph connections to make sure formats are compatible, and this method
+ // just verifies that. The edges are "dumb" and don't attempt to adapt to bad connections.
+ // How it works: offerer proposes an array of formats, in descending order of preference from
+ // offers[0] to offers[numOffers - 1]. If offeree accepts one of these formats, it returns
+ // the index of that offer. Otherwise, offeree sets numCounterOffers to the number of
+ // counter-offers (up to a maximumum of the entry value of numCounterOffers), fills in the
+ // provided array counterOffers[] with its counter-offers, in descending order of preference
+ // from counterOffers[0] to counterOffers[numCounterOffers - 1], and returns NEGOTIATE.
+ // Note that since the offerer allocates space for counter-offers, but only the offeree knows
+ // how many counter-offers it has, there may be insufficient space for all counter-offers.
+ // In that case, the offeree sets numCounterOffers to the requested number of counter-offers
+ // (which is greater than the entry value of numCounterOffers), fills in as many of the most
+ // important counterOffers as will fit, and returns NEGOTIATE. As this implies a re-allocation,
+ // it should be used as a last resort. It is preferable for the offerer to simply allocate a
+ // larger space to begin with, and/or for the offeree to tolerate a smaller space than desired.
+ // Alternatively, the offerer can pass NULL for offers and counterOffers, and zero for
+ // numOffers. This indicates that it has not allocated space for any counter-offers yet.
+ // In this case, the offerree should set numCounterOffers appropriately and return NEGOTIATE.
+ // Then the offerer will allocate the correct amount of memory and retry.
+ // Format_Invalid is not allowed as either an offer or counter-offer.
+ // Returns:
+ // >= 0 Offer accepted.
+ // NEGOTIATE No offer accepted, and counter-offer(s) optionally made. See above for details.
+ virtual ssize_t negotiate(const NBAIO_Format offers[], size_t numOffers,
+ NBAIO_Format counterOffers[], size_t& numCounterOffers);
+
+ // Return the current negotiated format, or Format_Invalid if negotiation has not been done,
+ // or if re-negotiation is required.
+ virtual NBAIO_Format format() const { return mNegotiated ? mFormat : Format_Invalid; }
+
+protected:
+ NBAIO_Port(NBAIO_Format format) : mNegotiated(false), mFormat(format),
+ mBitShift(Format_frameBitShift(format)) { }
+ virtual ~NBAIO_Port() { }
+
+ // Implementations are free to ignore these if they don't need them
+
+ bool mNegotiated; // mNegotiated implies (mFormat != Format_Invalid)
+ NBAIO_Format mFormat; // (mFormat != Format_Invalid) does not imply mNegotiated
+ size_t mBitShift; // assign in parallel with any assignment to mFormat
+};
+
+// Abstract class (interface) representing a non-blocking data sink, for use by a data provider.
+class NBAIO_Sink : public NBAIO_Port {
+
+public:
+
+ // For the next two APIs:
+ // 32 bits rolls over after 27 hours at 44.1 kHz; if that concerns you then poll periodically.
+
+ // Return the number of frames written successfully since construction.
+ virtual size_t framesWritten() const { return mFramesWritten; }
+
+ // Number of frames lost due to underrun since construction.
+ virtual size_t framesUnderrun() const { return 0; }
+
+ // Number of underruns since construction, where a set of contiguous lost frames is one event.
+ virtual size_t underruns() const { return 0; }
+
+ // Estimate of number of frames that could be written successfully now without blocking.
+ // When a write() is actually attempted, the implementation is permitted to return a smaller or
+ // larger transfer count, however it will make a good faith effort to give an accurate estimate.
+ // Errors:
+ // NEGOTIATE (Re-)negotiation is needed.
+ // UNDERRUN write() has not been called frequently enough, or with enough frames to keep up.
+ // An underrun event is counted, and the caller should re-try this operation.
+ // WOULD_BLOCK Determining how many frames can be written without blocking would itself block.
+ virtual ssize_t availableToWrite() const { return SSIZE_MAX; }
+
+ // Transfer data to sink from single input buffer. Implies a copy.
+ // Inputs:
+ // buffer Non-NULL buffer owned by provider.
+ // count Maximum number of frames to transfer.
+ // Return value:
+ // > 0 Number of frames successfully transferred prior to first error.
+ // = 0 Count was zero.
+ // < 0 status_t error occurred prior to the first frame transfer.
+ // Errors:
+ // NEGOTIATE (Re-)negotiation is needed.
+ // WOULD_BLOCK No frames can be transferred without blocking.
+ // UNDERRUN write() has not been called frequently enough, or with enough frames to keep up.
+ // An underrun event is counted, and the caller should re-try this operation.
+ virtual ssize_t write(const void *buffer, size_t count) = 0;
+
+ // Transfer data to sink using a series of callbacks. More suitable for zero-fill, synthesis,
+ // and non-contiguous transfers (e.g. circular buffer or writev).
+ // Inputs:
+ // via Callback function that the sink will call as many times as needed to consume data.
+ // total Estimate of the number of frames the provider has available. This is an estimate,
+ // and it can provide a different number of frames during the series of callbacks.
+ // user Arbitrary void * reserved for data provider.
+ // block Number of frames per block, that is a suggested value for 'count' in each callback.
+ // Zero means no preference. This parameter is a hint only, and may be ignored.
+ // Return value:
+ // > 0 Total number of frames successfully transferred prior to first error.
+ // = 0 Count was zero.
+ // < 0 status_t error occurred prior to the first frame transfer.
+ // Errors:
+ // NEGOTIATE (Re-)negotiation is needed.
+ // WOULD_BLOCK No frames can be transferred without blocking.
+ // UNDERRUN write() has not been called frequently enough, or with enough frames to keep up.
+ // An underrun event is counted, and the caller should re-try this operation.
+ //
+ // The 'via' callback is called by the data sink as follows:
+ // Inputs:
+ // user Arbitrary void * reserved for data provider.
+ // buffer Non-NULL buffer owned by sink that callback should fill in with data,
+ // up to a maximum of 'count' frames.
+ // count Maximum number of frames to transfer during this callback.
+ // Return value:
+ // > 0 Number of frames successfully transferred during this callback prior to first error.
+ // = 0 Count was zero.
+ // < 0 status_t error occurred prior to the first frame transfer during this callback.
+ virtual ssize_t writeVia(writeVia_t via, size_t total, void *user, size_t block = 0);
+
+protected:
+ NBAIO_Sink(NBAIO_Format format = Format_Invalid) : NBAIO_Port(format), mFramesWritten(0) { }
+ virtual ~NBAIO_Sink() { }
+
+ // Implementations are free to ignore these if they don't need them
+ size_t mFramesWritten;
+};
+
+// Abstract class (interface) representing a non-blocking data source, for use by a data consumer.
+class NBAIO_Source : public NBAIO_Port {
+
+public:
+
+ // For the next two APIs:
+ // 32 bits rolls over after 27 hours at 44.1 kHz; if that concerns you then poll periodically.
+
+ // Number of frames read successfully since construction.
+ virtual size_t framesRead() const { return mFramesRead; }
+
+ // Number of frames lost due to overrun since construction.
+ // Not const because implementations may need to do I/O.
+ virtual size_t framesOverrun() /*const*/ { return 0; }
+
+ // Number of overruns since construction, where a set of contiguous lost frames is one event.
+ // Not const because implementations may need to do I/O.
+ virtual size_t overruns() /*const*/ { return 0; }
+
+ // Estimate of number of frames that could be read successfully now.
+ // When a read() is actually attempted, the implementation is permitted to return a smaller or
+ // larger transfer count, however it will make a good faith effort to give an accurate estimate.
+ // Errors:
+ // NEGOTIATE (Re-)negotiation is needed.
+ // OVERRUN One or more frames were lost due to overrun, try again to read more recent data.
+ // WOULD_BLOCK Determining how many frames can be read without blocking would itself block.
+ virtual ssize_t availableToRead() { return SSIZE_MAX; }
+
+ // Transfer data from source into single destination buffer. Implies a copy.
+ // Inputs:
+ // buffer Non-NULL destination buffer owned by consumer.
+ // count Maximum number of frames to transfer.
+ // Return value:
+ // > 0 Number of frames successfully transferred prior to first error.
+ // = 0 Count was zero.
+ // < 0 status_t error occurred prior to the first frame transfer.
+ // Errors:
+ // NEGOTIATE (Re-)negotiation is needed.
+ // WOULD_BLOCK No frames can be transferred without blocking.
+ // OVERRUN read() has not been called frequently enough, or with enough frames to keep up.
+ // One or more frames were lost due to overrun, try again to read more recent data.
+ virtual ssize_t read(void *buffer, size_t count) = 0;
+
+ // Transfer data from source using a series of callbacks. More suitable for zero-fill,
+ // synthesis, and non-contiguous transfers (e.g. circular buffer or readv).
+ // Inputs:
+ // via Callback function that the source will call as many times as needed to provide data.
+ // total Estimate of the number of frames the consumer desires. This is an estimate,
+ // and it can consume a different number of frames during the series of callbacks.
+ // user Arbitrary void * reserved for data consumer.
+ // block Number of frames per block, that is a suggested value for 'count' in each callback.
+ // Zero means no preference. This parameter is a hint only, and may be ignored.
+ // Return value:
+ // > 0 Total number of frames successfully transferred prior to first error.
+ // = 0 Count was zero.
+ // < 0 status_t error occurred prior to the first frame transfer.
+ // Errors:
+ // NEGOTIATE (Re-)negotiation is needed.
+ // WOULD_BLOCK No frames can be transferred without blocking.
+ // OVERRUN read() has not been called frequently enough, or with enough frames to keep up.
+ // One or more frames were lost due to overrun, try again to read more recent data.
+ //
+ // The 'via' callback is called by the data source as follows:
+ // Inputs:
+ // user Arbitrary void * reserved for data consumer.
+ // dest Non-NULL buffer owned by source that callback should consume data from,
+ // up to a maximum of 'count' frames.
+ // count Maximum number of frames to transfer during this callback.
+ // Return value:
+ // > 0 Number of frames successfully transferred during this callback prior to first error.
+ // = 0 Count was zero.
+ // < 0 status_t error occurred prior to the first frame transfer during this callback.
+ virtual ssize_t readVia(readVia_t via, size_t total, void *user, size_t block = 0);
+
+protected:
+ NBAIO_Source(NBAIO_Format format = Format_Invalid) : NBAIO_Port(format), mFramesRead(0) { }
+ virtual ~NBAIO_Source() { }
+
+ // Implementations are free to ignore these if they don't need them
+ size_t mFramesRead;
+};
+
+} // namespace android
+
+#endif // ANDROID_AUDIO_NBAIO_H