Add comments
Change-Id: Ifbf3a46a4183c8abc0feee1c588953ab10303cc1
diff --git a/include/media/AudioTrack.h b/include/media/AudioTrack.h
index 6727601..58e0deb 100644
--- a/include/media/AudioTrack.h
+++ b/include/media/AudioTrack.h
@@ -75,8 +75,10 @@
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
+ // (currently ignored, but will make the primary field in future)
size_t size; // input/output in bytes == frameCount * frameSize
+ // on output is the number of bytes actually filled
// FIXME this is redundant with respect to frameCount,
// and TRANSFER_OBTAIN mode is broken for 8-bit data
// since we don't define the frame format
diff --git a/include/media/IAudioFlinger.h b/include/media/IAudioFlinger.h
index f8a9f2b..0aa5870 100644
--- a/include/media/IAudioFlinger.h
+++ b/include/media/IAudioFlinger.h
@@ -125,7 +125,9 @@
virtual String8 getParameters(audio_io_handle_t ioHandle, const String8& keys)
const = 0;
- // register a current process for audio output change notifications
+ // Register an object to receive audio input/output change and track notifications.
+ // For a given calling pid, AudioFlinger disregards any registrations after the first.
+ // Thus the IAudioFlingerClient must be a singleton per process.
virtual void registerClient(const sp<IAudioFlingerClient>& client) = 0;
// retrieve the audio recording buffer size
diff --git a/include/media/nbaio/NBLog.h b/include/media/nbaio/NBLog.h
index 107ba66..6d59ea7 100644
--- a/include/media/nbaio/NBLog.h
+++ b/include/media/nbaio/NBLog.h
@@ -90,6 +90,8 @@
virtual ~Timeline();
#endif
+ // Input parameter 'size' is the desired size of the timeline in byte units.
+ // Returns the size rounded up to a power-of-2, plus the constant size overhead for indices.
static size_t sharedSize(size_t size);
#if 0
@@ -110,8 +112,12 @@
class Writer : public RefBase {
public:
Writer(); // dummy nop implementation without shared memory
+
+ // Input parameter 'size' is the desired size of the timeline in byte units.
+ // The size of the shared memory must be at least Timeline::sharedSize(size).
Writer(size_t size, void *shared);
Writer(size_t size, const sp<IMemory>& iMemory);
+
virtual ~Writer() { }
virtual void log(const char *string);
@@ -165,8 +171,12 @@
class Reader : public RefBase {
public:
+
+ // Input parameter 'size' is the desired size of the timeline in byte units.
+ // The size of the shared memory must be at least Timeline::sharedSize(size).
Reader(size_t size, const void *shared);
Reader(size_t size, const sp<IMemory>& iMemory);
+
virtual ~Reader() { }
void dump(int fd, size_t indent = 0);
diff --git a/media/libmedia/AudioSystem.cpp b/media/libmedia/AudioSystem.cpp
index 22d6763..7ceffd3 100644
--- a/media/libmedia/AudioSystem.cpp
+++ b/media/libmedia/AudioSystem.cpp
@@ -537,6 +537,8 @@
return gAudioPolicyService;
}
+// ---------------------------------------------------------------------------
+
status_t AudioSystem::setDeviceConnectionState(audio_devices_t device,
audio_policy_dev_state_t state,
const char *device_address)
diff --git a/media/libmedia/AudioTrack.cpp b/media/libmedia/AudioTrack.cpp
index 33c4462..3f4cbc2 100644
--- a/media/libmedia/AudioTrack.cpp
+++ b/media/libmedia/AudioTrack.cpp
@@ -585,6 +585,7 @@
status_t AudioTrack::setMarkerPosition(uint32_t marker)
{
+ // The only purpose of setting marker position is to get a callback
if (mCbf == NULL) {
return INVALID_OPERATION;
}
@@ -610,6 +611,7 @@
status_t AudioTrack::setPositionUpdatePeriod(uint32_t updatePeriod)
{
+ // The only purpose of setting position update period is to get a callback
if (mCbf == NULL) {
return INVALID_OPERATION;
}
@@ -1220,6 +1222,11 @@
nsecs_t AudioTrack::processAudioBuffer(const sp<AudioTrackThread>& thread)
{
+ // Currently the AudioTrack thread is not created if there are no callbacks.
+ // Would it ever make sense to run the thread, even without callbacks?
+ // If so, then replace this by checks at each use for mCbf != NULL.
+ LOG_ALWAYS_FATAL_IF(mCblk == NULL);
+
mLock.lock();
if (mAwaitBoost) {
mAwaitBoost = false;
diff --git a/media/libmediaplayerservice/MidiFile.cpp b/media/libmediaplayerservice/MidiFile.cpp
index 8db5b9b..270b872 100644
--- a/media/libmediaplayerservice/MidiFile.cpp
+++ b/media/libmediaplayerservice/MidiFile.cpp
@@ -422,7 +422,7 @@
status_t MidiFile::createOutputTrack() {
if (mAudioSink->open(pLibConfig->sampleRate, pLibConfig->numChannels,
- CHANNEL_MASK_USE_CHANNEL_ORDER, AUDIO_FORMAT_PCM_16_BIT, 2) != NO_ERROR) {
+ CHANNEL_MASK_USE_CHANNEL_ORDER, AUDIO_FORMAT_PCM_16_BIT, 2 /*bufferCount*/) != NO_ERROR) {
ALOGE("mAudioSink open failed");
return ERROR_OPEN_FAILED;
}
diff --git a/services/audioflinger/StateQueue.h b/services/audioflinger/StateQueue.h
index e33b3c6..9cde642 100644
--- a/services/audioflinger/StateQueue.h
+++ b/services/audioflinger/StateQueue.h
@@ -31,8 +31,14 @@
// and this may result in an audible artifact
// needs read-only access to a recent stable state,
// but not necessarily the most current one
+// only allocate and free memory when configuration changes
+// avoid conventional logging, as this is a form of I/O and could block
+// defer computation to other threads when feasible; for example
+// cycle times are collected by fast mixer thread but the floating-point
+// statistical calculations on these cycle times are computed by normal mixer
+// these requirements also apply to callouts such as AudioBufferProvider and VolumeProvider
// Normal mixer thread:
-// periodic with typical period ~40 ms
+// periodic with typical period ~20 ms
// SCHED_OTHER scheduling policy and nice priority == urgent audio
// ok to block, but prefer to avoid as much as possible
// needs read/write access to state
diff --git a/services/audioflinger/Threads.h b/services/audioflinger/Threads.h
index 7de6872..e15d98a 100644
--- a/services/audioflinger/Threads.h
+++ b/services/audioflinger/Threads.h
@@ -429,6 +429,8 @@
virtual status_t setSyncEvent(const sp<SyncEvent>& event);
virtual bool isValidSyncEvent(const sp<SyncEvent>& event) const;
+
+ // called with AudioFlinger lock held
void invalidateTracks(audio_stream_type_t streamType);