NBAIO.h revision 2b7b910f4b417ab3930379298f538d0dfc857e88
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> 31767094dd98b01baf21de2ad09c27b3c98776cf73Glenn Kasten#include <media/AudioTimestamp.h> 32f95a3c4122d67273d930c7d83c3df99f136603edGlenn Kasten#include <system/audio.h> 33010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 34010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastennamespace android { 35010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 36010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// In addition to the usual status_t 37010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenenum { 38010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten NEGOTIATE = 0x80000010, // Must (re-)negotiate format. For negotiate() only, the offeree 39010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // doesn't accept offers, and proposes counter-offers 40010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten OVERRUN = 0x80000011, // availableToRead(), read(), or readVia() detected lost input due 41010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // to overrun; an event is counted and the caller should re-try 42010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten UNDERRUN = 0x80000012, // availableToWrite(), write(), or writeVia() detected a gap in 43010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // output due to underrun (not being called often enough, or with 44010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // enough data); an event is counted and the caller should re-try 45010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten}; 46010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 47010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Negotiation of format is based on the data provider and data sink, or the data consumer and 48010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// data source, exchanging prioritized arrays of offers and counter-offers until a single offer is 49010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// mutually agreed upon. Each offer is an NBAIO_Format. For simplicity and performance, 50b64497eb8724c4c372fffdbf3ee30543432953c5Glenn Kasten// NBAIO_Format is a typedef that ties together the most important combinations of the various 51010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// attributes, rather than a struct with separate fields for format, sample rate, channel count, 52010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// interleave, packing, alignment, etc. The reason is that NBAIO_Format tries to abstract out only 53b64497eb8724c4c372fffdbf3ee30543432953c5Glenn Kasten// the combinations that are actually needed within AudioFlinger. If the list of combinations grows 54010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// too large, then this decision should be re-visited. 55b64497eb8724c4c372fffdbf3ee30543432953c5Glenn Kasten// Sample rate and channel count are explicit, PCM interleaved 16-bit is assumed. 56c4b8b32dec91a11a83d0a7ab49747606d16d39a5Glenn Kastenstruct NBAIO_Format { 57c4b8b32dec91a11a83d0a7ab49747606d16d39a5Glenn Kasten//private: 582b7b910f4b417ab3930379298f538d0dfc857e88Glenn Kasten unsigned mSampleRate; 592b7b910f4b417ab3930379298f538d0dfc857e88Glenn Kasten unsigned mChannelCount; 602b7b910f4b417ab3930379298f538d0dfc857e88Glenn Kasten audio_format_t mFormat; 612b7b910f4b417ab3930379298f538d0dfc857e88Glenn Kasten ssize_t mFrameSize; 62c4b8b32dec91a11a83d0a7ab49747606d16d39a5Glenn Kasten}; 6351d53cd993043d9286e12cba884e6ee4d10b5facGlenn Kasten 6451d53cd993043d9286e12cba884e6ee4d10b5facGlenn Kastenextern const NBAIO_Format Format_Invalid; 65010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 66010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Return the frame size of an NBAIO_Format in bytes 6772e54af9fcdc4754914fe2bf8de699523538b315Glenn Kastensize_t Format_frameSize(const NBAIO_Format& format); 68010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 69010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Return the frame size of an NBAIO_Format as a bit shift 704d7b3f876b21997680ae32a340d746ed1cae6ab1Glenn Kasten// or -1 if frame size is not a power of 2 714d7b3f876b21997680ae32a340d746ed1cae6ab1Glenn Kastenint Format_frameBitShift(const NBAIO_Format& format); 72010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 73010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Convert a sample rate in Hz and channel count to an NBAIO_Format 74f95a3c4122d67273d930c7d83c3df99f136603edGlenn Kasten// FIXME Remove the default value of AUDIO_FORMAT_PCM_16_BIT, and rename 75f95a3c4122d67273d930c7d83c3df99f136603edGlenn KastenNBAIO_Format Format_from_SR_C(unsigned sampleRate, unsigned channelCount, 76f95a3c4122d67273d930c7d83c3df99f136603edGlenn Kasten audio_format_t format = AUDIO_FORMAT_PCM_16_BIT); 77010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 78010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Return the sample rate in Hz of an NBAIO_Format 7972e54af9fcdc4754914fe2bf8de699523538b315Glenn Kastenunsigned Format_sampleRate(const NBAIO_Format& format); 80010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 81010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Return the channel count of an NBAIO_Format 8272e54af9fcdc4754914fe2bf8de699523538b315Glenn Kastenunsigned Format_channelCount(const NBAIO_Format& format); 83010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 84010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Callbacks used by NBAIO_Sink::writeVia() and NBAIO_Source::readVia() below. 85010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastentypedef ssize_t (*writeVia_t)(void *user, void *buffer, size_t count); 862c3b2da3049627264b7c6b449a1622f002210f03John Grossmantypedef ssize_t (*readVia_t)(void *user, const void *buffer, 872c3b2da3049627264b7c6b449a1622f002210f03John Grossman size_t count, int64_t readPTS); 88010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 89cc1e0e807ee9a9f163a4685cbd6efd6ae55849cfGlenn Kasten// Check whether an NBAIO_Format is valid 90cc1e0e807ee9a9f163a4685cbd6efd6ae55849cfGlenn Kastenbool Format_isValid(const NBAIO_Format& format); 91cc1e0e807ee9a9f163a4685cbd6efd6ae55849cfGlenn Kasten 92cc1e0e807ee9a9f163a4685cbd6efd6ae55849cfGlenn Kasten// Compare two NBAIO_Format values 93cc1e0e807ee9a9f163a4685cbd6efd6ae55849cfGlenn Kastenbool Format_isEqual(const NBAIO_Format& format1, const NBAIO_Format& format2); 94cc1e0e807ee9a9f163a4685cbd6efd6ae55849cfGlenn Kasten 95010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Abstract class (interface) representing a data port. 96010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenclass NBAIO_Port : public RefBase { 97010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 98010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenpublic: 99010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 100010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // negotiate() must called first. The purpose of negotiate() is to check compatibility of 101010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // formats, not to automatically adapt if they are incompatible. It's the responsibility of 102010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // whoever sets up the graph connections to make sure formats are compatible, and this method 103010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // just verifies that. The edges are "dumb" and don't attempt to adapt to bad connections. 104010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // How it works: offerer proposes an array of formats, in descending order of preference from 105010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // offers[0] to offers[numOffers - 1]. If offeree accepts one of these formats, it returns 106010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // the index of that offer. Otherwise, offeree sets numCounterOffers to the number of 107010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // counter-offers (up to a maximumum of the entry value of numCounterOffers), fills in the 108010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // provided array counterOffers[] with its counter-offers, in descending order of preference 109010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // from counterOffers[0] to counterOffers[numCounterOffers - 1], and returns NEGOTIATE. 110010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Note that since the offerer allocates space for counter-offers, but only the offeree knows 111010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // how many counter-offers it has, there may be insufficient space for all counter-offers. 112010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // In that case, the offeree sets numCounterOffers to the requested number of counter-offers 113010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // (which is greater than the entry value of numCounterOffers), fills in as many of the most 114010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // important counterOffers as will fit, and returns NEGOTIATE. As this implies a re-allocation, 115010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // it should be used as a last resort. It is preferable for the offerer to simply allocate a 116010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // larger space to begin with, and/or for the offeree to tolerate a smaller space than desired. 117010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Alternatively, the offerer can pass NULL for offers and counterOffers, and zero for 118010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // numOffers. This indicates that it has not allocated space for any counter-offers yet. 119010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // In this case, the offerree should set numCounterOffers appropriately and return NEGOTIATE. 120010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Then the offerer will allocate the correct amount of memory and retry. 121010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Format_Invalid is not allowed as either an offer or counter-offer. 122010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Returns: 123010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // >= 0 Offer accepted. 124010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // NEGOTIATE No offer accepted, and counter-offer(s) optionally made. See above for details. 125010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten virtual ssize_t negotiate(const NBAIO_Format offers[], size_t numOffers, 126010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten NBAIO_Format counterOffers[], size_t& numCounterOffers); 127010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 128010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Return the current negotiated format, or Format_Invalid if negotiation has not been done, 129010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // or if re-negotiation is required. 130010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten virtual NBAIO_Format format() const { return mNegotiated ? mFormat : Format_Invalid; } 131010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 132010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenprotected: 13372e54af9fcdc4754914fe2bf8de699523538b315Glenn Kasten NBAIO_Port(const NBAIO_Format& format) : mNegotiated(false), mFormat(format), 134ac3e9db88ddb1f24bc6c8fb744a37dfdeec332bbGlenn Kasten mBitShift(Format_frameBitShift(format)), 135ac3e9db88ddb1f24bc6c8fb744a37dfdeec332bbGlenn Kasten mFrameSize(Format_frameSize(format)) { } 136010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten virtual ~NBAIO_Port() { } 137010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 138010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Implementations are free to ignore these if they don't need them 139010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 140010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten bool mNegotiated; // mNegotiated implies (mFormat != Format_Invalid) 141010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten NBAIO_Format mFormat; // (mFormat != Format_Invalid) does not imply mNegotiated 142010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten size_t mBitShift; // assign in parallel with any assignment to mFormat 143ac3e9db88ddb1f24bc6c8fb744a37dfdeec332bbGlenn Kasten size_t mFrameSize; // assign in parallel with any assignment to mFormat 144010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten}; 145010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 146010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Abstract class (interface) representing a non-blocking data sink, for use by a data provider. 147010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenclass NBAIO_Sink : public NBAIO_Port { 148010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 149010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenpublic: 150010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 151010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // For the next two APIs: 152010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // 32 bits rolls over after 27 hours at 44.1 kHz; if that concerns you then poll periodically. 153010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 154010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Return the number of frames written successfully since construction. 155010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten virtual size_t framesWritten() const { return mFramesWritten; } 156010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 157010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Number of frames lost due to underrun since construction. 158010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten virtual size_t framesUnderrun() const { return 0; } 159010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 160010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Number of underruns since construction, where a set of contiguous lost frames is one event. 161010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten virtual size_t underruns() const { return 0; } 162010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 163010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Estimate of number of frames that could be written successfully now without blocking. 164010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // When a write() is actually attempted, the implementation is permitted to return a smaller or 165010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // larger transfer count, however it will make a good faith effort to give an accurate estimate. 166010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Errors: 167010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // NEGOTIATE (Re-)negotiation is needed. 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 // WOULD_BLOCK Determining how many frames can be written without blocking would itself block. 171010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten virtual ssize_t availableToWrite() const { return SSIZE_MAX; } 172010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 173010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Transfer data to sink from single input buffer. Implies a copy. 174010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Inputs: 175010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // buffer Non-NULL buffer owned by provider. 176010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // count Maximum number of frames to transfer. 177010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Return value: 178010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // > 0 Number of frames successfully transferred prior to first error. 179010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // = 0 Count was zero. 180010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // < 0 status_t error occurred prior to the first frame transfer. 181010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Errors: 182010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // NEGOTIATE (Re-)negotiation is needed. 183010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // WOULD_BLOCK No frames can be transferred without blocking. 184010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // UNDERRUN write() has not been called frequently enough, or with enough frames to keep up. 185010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // An underrun event is counted, and the caller should re-try this operation. 186010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten virtual ssize_t write(const void *buffer, size_t count) = 0; 187010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 188010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Transfer data to sink using a series of callbacks. More suitable for zero-fill, synthesis, 189010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // and non-contiguous transfers (e.g. circular buffer or writev). 190010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Inputs: 191010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // via Callback function that the sink will call as many times as needed to consume data. 192010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // total Estimate of the number of frames the provider has available. This is an estimate, 193010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // and it can provide a different number of frames during the series of callbacks. 194010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // user Arbitrary void * reserved for data provider. 195010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // block Number of frames per block, that is a suggested value for 'count' in each callback. 196010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Zero means no preference. This parameter is a hint only, and may be ignored. 197010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Return value: 198010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // > 0 Total number of frames successfully transferred prior to first error. 199010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // = 0 Count was zero. 200010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // < 0 status_t error occurred prior to the first frame transfer. 201010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Errors: 202010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // NEGOTIATE (Re-)negotiation is needed. 203010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // WOULD_BLOCK No frames can be transferred without blocking. 204010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // UNDERRUN write() has not been called frequently enough, or with enough frames to keep up. 205010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // An underrun event is counted, and the caller should re-try this operation. 206010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // 207010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // The 'via' callback is called by the data sink as follows: 208010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Inputs: 209010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // user Arbitrary void * reserved for data provider. 210010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // buffer Non-NULL buffer owned by sink that callback should fill in with data, 211010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // up to a maximum of 'count' frames. 212010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // count Maximum number of frames to transfer during this callback. 213010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Return value: 214010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // > 0 Number of frames successfully transferred during this callback prior to first error. 215010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // = 0 Count was zero. 216010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // < 0 status_t error occurred prior to the first frame transfer during this callback. 217010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten virtual ssize_t writeVia(writeVia_t via, size_t total, void *user, size_t block = 0); 218010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 2192c3b2da3049627264b7c6b449a1622f002210f03John Grossman // Get the time (on the LocalTime timeline) at which the first frame of audio of the next write 2202c3b2da3049627264b7c6b449a1622f002210f03John Grossman // operation to this sink will be eventually rendered by the HAL. 2212c3b2da3049627264b7c6b449a1622f002210f03John Grossman // Inputs: 2222c3b2da3049627264b7c6b449a1622f002210f03John Grossman // ts A pointer pointing to the int64_t which will hold the result. 2232c3b2da3049627264b7c6b449a1622f002210f03John Grossman // Return value: 2242c3b2da3049627264b7c6b449a1622f002210f03John Grossman // OK Everything went well, *ts holds the time at which the first audio frame of the next 2252c3b2da3049627264b7c6b449a1622f002210f03John Grossman // write operation will be rendered, or AudioBufferProvider::kInvalidPTS if this sink 2262c3b2da3049627264b7c6b449a1622f002210f03John Grossman // does not know the answer for some reason. Sinks which eventually lead to a HAL 2272c3b2da3049627264b7c6b449a1622f002210f03John Grossman // which implements get_next_write_timestamp may return Invalid temporarily if the DMA 2282c3b2da3049627264b7c6b449a1622f002210f03John Grossman // output of the audio driver has not started yet. Sinks which lead to a HAL which 2292c3b2da3049627264b7c6b449a1622f002210f03John Grossman // does not implement get_next_write_timestamp, or which don't lead to a HAL at all, 2302c3b2da3049627264b7c6b449a1622f002210f03John Grossman // will always return kInvalidPTS. 2312c3b2da3049627264b7c6b449a1622f002210f03John Grossman // <other> Something unexpected happened internally. Check the logs and start debugging. 2322c3b2da3049627264b7c6b449a1622f002210f03John Grossman virtual status_t getNextWriteTimestamp(int64_t *ts) { return INVALID_OPERATION; } 233767094dd98b01baf21de2ad09c27b3c98776cf73Glenn Kasten 234767094dd98b01baf21de2ad09c27b3c98776cf73Glenn Kasten // Returns NO_ERROR if a timestamp is available. The timestamp includes the total number 235767094dd98b01baf21de2ad09c27b3c98776cf73Glenn Kasten // of frames presented to an external observer, together with the value of CLOCK_MONOTONIC 236767094dd98b01baf21de2ad09c27b3c98776cf73Glenn Kasten // as of this presentation count. 237767094dd98b01baf21de2ad09c27b3c98776cf73Glenn Kasten virtual status_t getTimestamp(AudioTimestamp& timestamp) { return INVALID_OPERATION; } 2382c3b2da3049627264b7c6b449a1622f002210f03John Grossman 239010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenprotected: 24072e54af9fcdc4754914fe2bf8de699523538b315Glenn Kasten NBAIO_Sink(const NBAIO_Format& format = Format_Invalid) : NBAIO_Port(format), mFramesWritten(0) { } 241010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten virtual ~NBAIO_Sink() { } 242010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 243010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Implementations are free to ignore these if they don't need them 244010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten size_t mFramesWritten; 245010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten}; 246010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 247010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten// Abstract class (interface) representing a non-blocking data source, for use by a data consumer. 248010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenclass NBAIO_Source : public NBAIO_Port { 249010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 250010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenpublic: 251010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 252010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // For the next two APIs: 253010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // 32 bits rolls over after 27 hours at 44.1 kHz; if that concerns you then poll periodically. 254010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 255010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Number of frames read successfully since construction. 256010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten virtual size_t framesRead() const { return mFramesRead; } 257010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 258010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Number of frames lost due to overrun since construction. 259010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Not const because implementations may need to do I/O. 260010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten virtual size_t framesOverrun() /*const*/ { return 0; } 261010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 262010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Number of overruns since construction, where a set of contiguous lost frames is one event. 263010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Not const because implementations may need to do I/O. 264010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten virtual size_t overruns() /*const*/ { return 0; } 265010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 266010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Estimate of number of frames that could be read successfully now. 267010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // When a read() is actually attempted, the implementation is permitted to return a smaller or 268010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // larger transfer count, however it will make a good faith effort to give an accurate estimate. 269010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Errors: 270010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // NEGOTIATE (Re-)negotiation is needed. 271010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // OVERRUN One or more frames were lost due to overrun, try again to read more recent data. 272010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // WOULD_BLOCK Determining how many frames can be read without blocking would itself block. 273010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten virtual ssize_t availableToRead() { return SSIZE_MAX; } 274010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 275010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Transfer data from source into single destination buffer. Implies a copy. 276010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Inputs: 277010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // buffer Non-NULL destination buffer owned by consumer. 278010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // count Maximum number of frames to transfer. 2792c3b2da3049627264b7c6b449a1622f002210f03John Grossman // readPTS The presentation time (on the LocalTime timeline) for which data 2802c3b2da3049627264b7c6b449a1622f002210f03John Grossman // is being requested, or kInvalidPTS if not known. 281010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Return value: 282010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // > 0 Number of frames successfully transferred prior to first error. 283010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // = 0 Count was zero. 284010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // < 0 status_t error occurred prior to the first frame transfer. 285010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Errors: 286010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // NEGOTIATE (Re-)negotiation is needed. 287010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // WOULD_BLOCK No frames can be transferred without blocking. 288010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // OVERRUN read() has not been called frequently enough, or with enough frames to keep up. 289010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // One or more frames were lost due to overrun, try again to read more recent data. 2902c3b2da3049627264b7c6b449a1622f002210f03John Grossman virtual ssize_t read(void *buffer, size_t count, int64_t readPTS) = 0; 291010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 292010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Transfer data from source using a series of callbacks. More suitable for zero-fill, 293010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // synthesis, and non-contiguous transfers (e.g. circular buffer or readv). 294010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Inputs: 295010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // via Callback function that the source will call as many times as needed to provide data. 296010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // total Estimate of the number of frames the consumer desires. This is an estimate, 297010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // and it can consume a different number of frames during the series of callbacks. 298010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // user Arbitrary void * reserved for data consumer. 2992c3b2da3049627264b7c6b449a1622f002210f03John Grossman // readPTS The presentation time (on the LocalTime timeline) for which data 3002c3b2da3049627264b7c6b449a1622f002210f03John Grossman // is being requested, or kInvalidPTS if not known. 301010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // block Number of frames per block, that is a suggested value for 'count' in each callback. 302010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Zero means no preference. This parameter is a hint only, and may be ignored. 303010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Return value: 304010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // > 0 Total number of frames successfully transferred prior to first error. 305010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // = 0 Count was zero. 306010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // < 0 status_t error occurred prior to the first frame transfer. 307010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Errors: 308010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // NEGOTIATE (Re-)negotiation is needed. 309010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // WOULD_BLOCK No frames can be transferred without blocking. 310010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // OVERRUN read() has not been called frequently enough, or with enough frames to keep up. 311010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // One or more frames were lost due to overrun, try again to read more recent data. 312010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // 313010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // The 'via' callback is called by the data source as follows: 314010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Inputs: 315010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // user Arbitrary void * reserved for data consumer. 316010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // dest Non-NULL buffer owned by source that callback should consume data from, 317010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // up to a maximum of 'count' frames. 318010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // count Maximum number of frames to transfer during this callback. 319010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Return value: 320010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // > 0 Number of frames successfully transferred during this callback prior to first error. 321010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // = 0 Count was zero. 322010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // < 0 status_t error occurred prior to the first frame transfer during this callback. 3232c3b2da3049627264b7c6b449a1622f002210f03John Grossman virtual ssize_t readVia(readVia_t via, size_t total, void *user, 3242c3b2da3049627264b7c6b449a1622f002210f03John Grossman int64_t readPTS, size_t block = 0); 325010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 326894d6be4f9b4721c77a01919ecf03b27cec90cc9Glenn Kasten // Invoked asynchronously by corresponding sink when a new timestamp is available. 327894d6be4f9b4721c77a01919ecf03b27cec90cc9Glenn Kasten // Default implementation ignores the timestamp. 328894d6be4f9b4721c77a01919ecf03b27cec90cc9Glenn Kasten virtual void onTimestamp(const AudioTimestamp& timestamp) { } 329894d6be4f9b4721c77a01919ecf03b27cec90cc9Glenn Kasten 330010662326b9c43c703725f933e95e0897f8a6bddGlenn Kastenprotected: 33172e54af9fcdc4754914fe2bf8de699523538b315Glenn Kasten NBAIO_Source(const NBAIO_Format& format = Format_Invalid) : NBAIO_Port(format), mFramesRead(0) { } 332010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten virtual ~NBAIO_Source() { } 333010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 334010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten // Implementations are free to ignore these if they don't need them 335010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten size_t mFramesRead; 336010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten}; 337010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 338010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten} // namespace android 339010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten 340010662326b9c43c703725f933e95e0897f8a6bddGlenn Kasten#endif // ANDROID_AUDIO_NBAIO_H 341