commit 74980b56eb6a86d670b88f96c0ff925b4432b4dc
author Kevin Rocard <krocard@google.com> Sat Jan 20 22:12:57 2018 -0800
committer Kevin Rocard <krocard@google.com> Wed Jan 31 23:09:23 2018 -0800
tree a163b9b319e26f3dee438a05db56df42b0d4d663
parent a4e6d8b1ded6392c9c14b876c7401b457d0c19c4

Audio V4: Fix documentation and useable/untestable bugs

Add missing documentation, especially for failure cases
and methods that are optional.
Add missing operation status for testability.
Add format for getSupported* methods as they could not
be implemented in 2.0 for multi-format stream (HDMI).

Test: compile
Bug: 38184704
Change-Id: I14ee5e02ef70a82df6de732f88b065810e9b032f
Signed-off-by: Kevin Rocard <krocard@google.com>

audio/4.0/IStreamOut.hal

diff --git a/audio/4.0/IStreamOut.hal b/audio/4.0/IStreamOut.hal
index 22b91f0..02f1697 100644
--- a/audio/4.0/IStreamOut.hal
+++ b/audio/4.0/IStreamOut.hal
@@ -36,10 +36,12 @@
      * allowing to directly set the volume as apposed to via the framework.
      * This method might produce multiple PCM outputs or hardware accelerated
      * codecs, such as MP3 or AAC.
+     * Optional method
      *
      * @param left left channel attenuation, 1.0f is unity, 0.0f is zero.
      * @param right right channel attenuation, 1.0f is unity, 0.0f is zero.
      * @return retval operation completion status.
+     *        If a volume is outside [0,1], return INVALID_ARGUMENTS
      */
     setVolume(float left, float right) generates (Result retval);
 
@@ -115,6 +117,7 @@
     /**
      * Return the number of audio frames written by the audio DSP to DAC since
      * the output has exited standby.
+     * Optional method
      *
      * @return retval operation completion status.
      * @return dspFrames number of audio frames written.
@@ -125,6 +128,7 @@
      * Get the local time at which the next write to the audio driver will be
      * presented. The units are microseconds, where the epoch is decided by the
      * local audio HAL.
+     * Optional method
      *
      * @return retval operation completion status.
      * @return timestampUs time of the next write.
@@ -152,6 +156,9 @@
      * Warning: failure to call this method results in callback implementation
      * on the client side being held until the HAL server termination.
      *
+     * If no callback was previously set, the method should be a no-op
+     * and return OK.
+     *
      * @return retval operation completion status: OK or NOT_SUPPORTED.
      */
     clearCallback() generates (Result retval);
@@ -223,6 +230,7 @@
     /**
      * Notifies to the audio driver to flush the queued data. Stream must
      * already be paused before calling 'flush'.
+     * Optional method
      *
      * Implementation of this function is mandatory for offloaded playback.
      *
@@ -244,6 +252,8 @@
      * timestamp must correspond to N rather than N+M. The terms 'recent' and
      * 'small' are not defined. They reflect the quality of the implementation.
      *
+     * Optional method
+     *
      * @return retval operation completion status.
      * @return frames count of presented audio frames.
      * @return timeStamp associated clock time.