Update comments
We no longer put the filename at start of file.
Change-Id: Ic435b159a23105681e3d4a6cb1ac097bc853302e
diff --git a/include/media/AudioSystem.h b/include/media/AudioSystem.h
index da99620..1916ac5 100644
--- a/include/media/AudioSystem.h
+++ b/include/media/AudioSystem.h
@@ -131,7 +131,7 @@
NUM_CONFIG_EVENTS
};
- // audio output descritor used to cache output configurations in client process to avoid frequent calls
+ // audio output descriptor used to cache output configurations in client process to avoid frequent calls
// through IAudioFlinger
class OutputDescriptor {
public:
diff --git a/include/media/AudioTrack.h b/include/media/AudioTrack.h
index 11db81b..0f2c323 100644
--- a/include/media/AudioTrack.h
+++ b/include/media/AudioTrack.h
@@ -58,8 +58,8 @@
EVENT_BUFFER_END = 5 // Playback head is at the end of the buffer.
};
- /* Create Buffer on the stack and pass it to obtainBuffer()
- * and releaseBuffer().
+ /* Client should declare Buffer on the stack and pass address to obtainBuffer()
+ * and releaseBuffer(). See also callback_t for EVENT_MORE_DATA.
*/
class Buffer
@@ -68,12 +68,16 @@
enum {
MUTE = 0x00000001
};
- uint32_t flags;
+ uint32_t flags; // 0 or MUTE
audio_format_t format; // but AUDIO_FORMAT_PCM_8_BIT -> AUDIO_FORMAT_PCM_16_BIT
// accessed directly by WebKit ANP callback
int channelCount; // will be removed in the future, do not use
- size_t frameCount;
- size_t size;
+
+ size_t frameCount; // number of sample frames corresponding to size;
+ // on input it is the number of frames desired,
+ // on output is the number of frames actually filled
+
+ size_t size; // input/output in byte units
union {
void* raw;
short* i16; // signed 16-bit
@@ -84,15 +88,15 @@
/* As a convenience, if a callback is supplied, a handler thread
* is automatically created with the appropriate priority. This thread
- * invokes the callback when a new buffer becomes available or an underrun condition occurs.
+ * invokes the callback when a new buffer becomes available or various conditions occur.
* Parameters:
*
* event: type of event notified (see enum AudioTrack::event_type).
* user: Pointer to context for use by the callback receiver.
* info: Pointer to optional parameter according to event type:
* - EVENT_MORE_DATA: pointer to AudioTrack::Buffer struct. The callback must not write
- * more bytes than indicated by 'size' field and update 'size' if less bytes are
- * written.
+ * more bytes than indicated by 'size' field and update 'size' if fewer bytes are
+ * written.
* - EVENT_UNDERRUN: unused.
* - EVENT_LOOP_END: pointer to an int indicating the number of loops remaining.
* - EVENT_MARKER: pointer to an uint32_t containing the marker position in frames.
@@ -225,7 +229,7 @@
*/
uint32_t latency() const;
- /* getters, see constructor */
+ /* getters, see constructors and set() */
audio_stream_type_t streamType() const;
audio_format_t format() const;
@@ -401,13 +405,19 @@
status_t attachAuxEffect(int effectId);
/* Obtains a buffer of "frameCount" frames. The buffer must be
- * filled entirely. If the track is stopped, obtainBuffer() returns
+ * filled entirely, and then released with releaseBuffer().
+ * If the track is stopped, obtainBuffer() returns
* STOPPED instead of NO_ERROR as long as there are buffers available,
* at which point NO_MORE_BUFFERS is returned.
* Buffers will be returned until the pool (buffercount())
* is exhausted, at which point obtainBuffer() will either block
* or return WOULD_BLOCK depending on the value of the "blocking"
* parameter.
+ *
+ * Interpretation of waitCount:
+ * +n limits wait time to n * WAIT_PERIOD_MS,
+ * -1 causes an (almost) infinite wait time,
+ * 0 non-blocking.
*/
enum {
@@ -416,12 +426,19 @@
};
status_t obtainBuffer(Buffer* audioBuffer, int32_t waitCount);
+
+ /* Release a filled buffer of "frameCount" frames for AudioFlinger to process. */
void releaseBuffer(Buffer* audioBuffer);
/* As a convenience we provide a write() interface to the audio buffer.
- * This is implemented on top of lockBuffer/unlockBuffer. For best
- * performance use callbacks. Return actual number of bytes written.
- *
+ * This is implemented on top of obtainBuffer/releaseBuffer. For best
+ * performance use callbacks. Returns actual number of bytes written >= 0,
+ * or one of the following negative status codes:
+ * INVALID_OPERATION AudioTrack is configured for shared buffer mode
+ * BAD_VALUE size is invalid
+ * STOPPED AudioTrack was stopped during the write
+ * NO_MORE_BUFFERS when obtainBuffer() returns same
+ * or any other error code returned by IAudioTrack::start() or restoreTrack_l().
*/
ssize_t write(const void* buffer, size_t size);
@@ -448,6 +465,7 @@
AudioTrack& mReceiver;
};
+ // body of AudioTrackThread::threadLoop()
bool processAudioBuffer(const sp<AudioTrackThread>& thread);
status_t createTrack_l(audio_stream_type_t streamType,
uint32_t sampleRate,
@@ -484,7 +502,7 @@
bool mActive; // protected by mLock
- callback_t mCbf;
+ callback_t mCbf; // callback handler for events, or NULL
void* mUserData;
uint32_t mNotificationFramesReq; // requested number of frames between each notification callback
uint32_t mNotificationFramesAct; // actual number of frames between each notification callback
diff --git a/include/media/EffectsFactoryApi.h b/include/media/EffectsFactoryApi.h
index df83995..65c26f4 100644
--- a/include/media/EffectsFactoryApi.h
+++ b/include/media/EffectsFactoryApi.h
@@ -87,7 +87,7 @@
// Description: Creates an effect engine of the specified type and returns an
// effect control interface on this engine. The function will allocate the
// resources for an instance of the requested effect engine and return
-// a handler on the effect control interface.
+// a handle on the effect control interface.
//
// Input:
// pEffectUuid: pointer to the effect uuid.
@@ -115,17 +115,17 @@
//
// Function: EffectRelease
//
-// Description: Releases the effect engine whose handler is given as argument.
+// Description: Releases the effect engine whose handle is given as argument.
// All resources allocated to this particular instance of the effect are
// released.
//
// Input:
-// handle: handler on the effect interface to be released.
+// handle: handle on the effect interface to be released.
//
// Output:
// returned value: 0 successful operation.
// -ENODEV factory failed to initialize
-// -EINVAL invalid interface handler
+// -EINVAL invalid interface handle
//
////////////////////////////////////////////////////////////////////////////////
int EffectRelease(effect_handle_t handle);
diff --git a/include/media/IAudioTrack.h b/include/media/IAudioTrack.h
index b346722..e4772a1 100644
--- a/include/media/IAudioTrack.h
+++ b/include/media/IAudioTrack.h
@@ -46,12 +46,12 @@
/* Stop a track. If set, the callback will cease being called and
* obtainBuffer will return an error. Buffers that are already released
- * will be processed, unless flush() is called.
+ * will continue to be processed, unless/until flush() is called.
*/
virtual void stop() = 0;
- /* Flush a stopped track. All pending buffers are discarded.
- * This function has no effect if the track is not stopped.
+ /* Flush a stopped or paused track. All pending/released buffers are discarded.
+ * This function has no effect if the track is not stopped or paused.
*/
virtual void flush() = 0;
@@ -62,7 +62,7 @@
/* Pause a track. If set, the callback will cease being called and
* obtainBuffer will return an error. Buffers that are already released
- * will be processed, unless flush() is called.
+ * will continue to be processed, unless/until flush() is called.
*/
virtual void pause() = 0;
diff --git a/include/media/MemoryLeakTrackUtil.h b/include/media/MemoryLeakTrackUtil.h
index 290b748..ac0f6b2 100644
--- a/include/media/MemoryLeakTrackUtil.h
+++ b/include/media/MemoryLeakTrackUtil.h
@@ -19,7 +19,7 @@
namespace android {
/*
- * Dump the memory adddress of the calling process to the given fd.
+ * Dump the memory address of the calling process to the given fd.
*/
extern void dumpMemoryAddresses(int fd);
diff --git a/include/private/media/AudioTrackShared.h b/include/private/media/AudioTrackShared.h
index 23226c0..af2db93 100644
--- a/include/private/media/AudioTrackShared.h
+++ b/include/private/media/AudioTrackShared.h
@@ -62,16 +62,23 @@
// are in the same line of data cache.
Mutex lock; // sizeof(int)
Condition cv; // sizeof(int)
+
+ // next 4 are offsets within "buffers"
volatile uint32_t user;
volatile uint32_t server;
uint32_t userBase;
uint32_t serverBase;
+
+ // if there is a shared buffer, "buffers" is the value of pointer() for the shared
+ // buffer, otherwise "buffers" points immediately after the control block
void* buffers;
uint32_t frameCount;
+
// Cache line boundary
+
uint32_t loopStart;
- uint32_t loopEnd;
- int loopCount;
+ uint32_t loopEnd; // read-only for server, read/write for client
+ int loopCount; // read/write for client
// Channel volumes are fixed point U4.12, so 0x1000 means 1.0.
// Left channel is in [0:15], right channel is in [16:31].
@@ -82,29 +89,39 @@
public:
uint32_t sampleRate;
+
// NOTE: audio_track_cblk_t::frameSize is not equal to AudioTrack::frameSize() for
// 8 bit PCM data: in this case, mCblk->frameSize is based on a sample size of
// 16 bit because data is converted to 16 bit before being stored in buffer
+ // read-only for client, server writes once at initialization and is then read-only
uint8_t frameSize; // would normally be size_t, but 8 bits is plenty
+
+ // never used
uint8_t pad1;
+
+ // used by client only
uint16_t bufferTimeoutMs; // Maximum cumulated timeout before restarting audioflinger
- uint16_t waitTimeMs; // Cumulated wait time
+ uint16_t waitTimeMs; // Cumulated wait time, used by client only
private:
+ // client write-only, server read-only
uint16_t mSendLevel; // Fixed point U4.12 so 0x1000 means 1.0
public:
volatile int32_t flags;
// Cache line boundary (32 bytes)
+ // Since the control block is always located in shared memory, this constructor
+ // is only used for placement new(). It is never used for regular new() or stack.
audio_track_cblk_t();
- uint32_t stepUser(uint32_t frameCount);
- bool stepServer(uint32_t frameCount);
+ uint32_t stepUser(uint32_t frameCount); // called by client only, where
+ // client includes regular AudioTrack and AudioFlinger::PlaybackThread::OutputTrack
+ bool stepServer(uint32_t frameCount); // called by server only
void* buffer(uint32_t offset) const;
uint32_t framesAvailable();
uint32_t framesAvailable_l();
- uint32_t framesReady();
+ uint32_t framesReady(); // called by server only
bool tryLock();
// No barriers on the following operations, so the ordering of loads/stores