Update audio comments

Change-Id: I85d7d2f6381b251db5695202fec75128883a8662

5 files changed, 19 insertions, 7 deletions

diff --git a/include/media/AudioTrack.h b/include/media/AudioTrack.h
index 3504f1f..b82f814 100644
--- a/include/media/AudioTrack.h
+++ b/include/media/AudioTrack.h
@@ -422,6 +422,7 @@ public:
      * After error return:
      *  frameCount  0
      *  size        0
+     *  raw         undefined
      * After successful return:
      *  frameCount  actual number of frames available, <= number requested
      *  size        actual number of bytes available
@@ -510,7 +511,13 @@ protected:
     uint32_t                mFrameCount;
 
     audio_track_cblk_t*     mCblk;                  // re-load after mLock.unlock()
-    void*                   mBuffers;               // starting address of buffers in shared memory
+
+            // Starting address of buffers in shared memory.  If there is a shared buffer, mBuffers
+            // is the value of pointer() for the shared buffer, otherwise mBuffers points
+            // immediately after the control block.  This address is for the mapping within client
+            // address space.  AudioFlinger::TrackBase::mBuffer is for the server address space.
+    void*                   mBuffers;
+
     audio_format_t          mFormat;
     audio_stream_type_t     mStreamType;
     uint8_t                 mChannelCount;
diff --git a/include/private/media/AudioTrackShared.h b/include/private/media/AudioTrackShared.h
index 3063448..bbc5e26 100644
--- a/include/private/media/AudioTrackShared.h
+++ b/include/private/media/AudioTrackShared.h
@@ -54,9 +54,10 @@ struct audio_track_cblk_t
                 uint32_t    serverBase;
 
                 int         mPad1;          // unused, but preserves cache line alignment
+
                 uint32_t    frameCount;
 
-                // Cache line boundary
+                // Cache line boundary (32 bytes)
 
                 uint32_t    loopStart;
                 uint32_t    loopEnd;        // read-only for server, read/write for client
diff --git a/media/libmedia/AudioTrack.cpp b/media/libmedia/AudioTrack.cpp
index 4a4759e..daf6d07 100644
--- a/media/libmedia/AudioTrack.cpp
+++ b/media/libmedia/AudioTrack.cpp
@@ -390,7 +390,7 @@ void AudioTrack::start()
         }
         if (cblk->flags & CBLK_INVALID) {
             audio_track_cblk_t* temp = cblk;
-            status = restoreTrack_l(temp, true);
+            status = restoreTrack_l(temp, true /*fromStart*/);
             cblk = temp;
         }
         cblk->lock.unlock();
@@ -988,7 +988,7 @@ status_t AudioTrack::obtainBuffer(Buffer* audioBuffer, int32_t waitCount)
                             android_atomic_or(CBLK_INVALID, &cblk->flags);
 create_new_track:
                             audio_track_cblk_t* temp = cblk;
-                            result = restoreTrack_l(temp, false);
+                            result = restoreTrack_l(temp, false /*fromStart*/);
                             cblk = temp;
                         }
                         if (result != NO_ERROR) {
@@ -1147,7 +1147,7 @@ status_t TimedAudioTrack::allocateTimedBuffer(size_t size, sp<IMemory>* buffer)
     if (cblk->flags & CBLK_INVALID) {
         cblk->lock.lock();
         audio_track_cblk_t* temp = cblk;
-        result = restoreTrack_l(temp, false);
+        result = restoreTrack_l(temp, false /*fromStart*/);
         cblk = temp;
         cblk->lock.unlock();
 
diff --git a/services/audioflinger/AudioFlinger.h b/services/audioflinger/AudioFlinger.h
index 8cf58b1..54cf239 100644
--- a/services/audioflinger/AudioFlinger.h
+++ b/services/audioflinger/AudioFlinger.h
@@ -861,6 +861,9 @@ private:
 
             sp<IMemory> sharedBuffer() const { return mSharedBuffer; }
 
+            // framesWritten is cumulative, never reset, and is shared all tracks
+            // audioHalFrames is derived from output latency
+            // FIXME parameters not needed, could get them from the thread
             bool presentationComplete(size_t framesWritten, size_t audioHalFrames);
 
         public:
@@ -893,6 +896,7 @@ private:
             bool                mHasVolumeController;
             size_t              mPresentationCompleteFrames; // number of frames written to the
                                             // audio HAL when this track will be fully rendered
+                                            // zero means not monitoring
         private:
             IAudioFlinger::track_flags_t mFlags;
 
@@ -997,7 +1001,7 @@ private:
         };
 
 
-        // playback track
+        // playback track, used by DuplicatingThread
         class OutputTrack : public Track {
         public:
 
diff --git a/services/audioflinger/StateQueue.h b/services/audioflinger/StateQueue.h
index c9b5111..e33b3c6 100644
--- a/services/audioflinger/StateQueue.h
+++ b/services/audioflinger/StateQueue.h
@@ -174,7 +174,7 @@ public:
 #endif
 
 private:
-    static const unsigned kN = 4;       // values != 4 are not supported by this code
+    static const unsigned kN = 4;       // values < 4 are not supported by this code
     T                 mStates[kN];      // written by mutator, read by observer
 
     // "volatile" is meaningless with SMP, but here it indicates that we're using atomic ops