audio: Specify frame counter behavior for streams
Specifies how HAL needs to handle the frame counter
for input and output streams on standby and flush.
Also add whitespaces before "Optional method" spec
for better readability.
Bug: 161253754
Test: in progress
Change-Id: I357739a2382f9425da74fcddbe7ab720be1f0e18
diff --git a/audio/7.0/IDevice.hal b/audio/7.0/IDevice.hal
index e423f29..85c789a 100644
--- a/audio/7.0/IDevice.hal
+++ b/audio/7.0/IDevice.hal
@@ -245,6 +245,7 @@
/**
* Gets the HW synchronization source of the device. Calling this method is
* equivalent to getting AUDIO_PARAMETER_HW_AV_SYNC on the legacy HAL.
+ *
* Optional method
*
* @return retval operation completion status: OK or NOT_SUPPORTED.
@@ -255,6 +256,7 @@
/**
* Sets whether the screen is on. Calling this method is equivalent to
* setting AUDIO_PARAMETER_KEY_SCREEN_STATE on the legacy HAL.
+ *
* Optional method
*
* @param turnedOn whether the screen is turned on.
diff --git a/audio/7.0/IStream.hal b/audio/7.0/IStream.hal
index 393e38f..e4987c2 100644
--- a/audio/7.0/IStream.hal
+++ b/audio/7.0/IStream.hal
@@ -110,6 +110,7 @@
/**
* Return the set of devices which this stream is connected to.
+ *
* Optional method
*
* @return retval operation completion status: OK or NOT_SUPPORTED.
@@ -133,6 +134,7 @@
/**
* Sets the HW synchronization source. Calling this method is equivalent to
* setting AUDIO_PARAMETER_STREAM_HW_AV_SYNC on the legacy HAL.
+ *
* Optional method
*
* @param hwAvSync HW synchronization source
diff --git a/audio/7.0/IStreamIn.hal b/audio/7.0/IStreamIn.hal
index bf9ae52..be4bda4 100644
--- a/audio/7.0/IStreamIn.hal
+++ b/audio/7.0/IStreamIn.hal
@@ -24,6 +24,7 @@
* Returns the source descriptor of the input stream. Calling this method is
* equivalent to getting AUDIO_PARAMETER_STREAM_INPUT_SOURCE on the legacy
* HAL.
+ *
* Optional method
*
* @return retval operation completion status.
@@ -33,6 +34,7 @@
/**
* Set the input gain for the audio driver.
+ *
* Optional method
*
* @param gain 1.0f is unity, 0.0f is zero.
@@ -42,6 +44,7 @@
/**
* Called when the metadata of the stream's sink has been changed.
+ *
* Optional method
*
* @param sinkMetadata Description of the audio that is suggested by the clients.
@@ -148,7 +151,8 @@
/**
* Return a recent count of the number of audio frames received and the
- * clock time associated with that frame count.
+ * clock time associated with that frame count. The count must not reset to
+ * zero when a PCM input enters standby.
*
* @return retval INVALID_STATE if the device is not ready/available,
* NOT_SUPPORTED if the command is not supported,
diff --git a/audio/7.0/IStreamOut.hal b/audio/7.0/IStreamOut.hal
index 4daab26..359dce4 100644
--- a/audio/7.0/IStreamOut.hal
+++ b/audio/7.0/IStreamOut.hal
@@ -35,6 +35,7 @@
* 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.
@@ -46,6 +47,7 @@
/**
* Called when the metadata of the stream's source has been changed.
+ *
* Optional method
*
* @param sourceMetadata Description of the audio that is played by the clients.
@@ -130,6 +132,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.
@@ -141,6 +144,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.
@@ -253,8 +257,11 @@
drain(AudioDrain type) generates (Result retval);
/**
- * Notifies to the audio driver to flush the queued data. Stream must
- * already be paused before calling 'flush'.
+ * Notifies to the audio driver to flush (that is, drop) the queued
+ * data. Stream must already be paused before calling 'flush'. For
+ * compressed and offload streams the frame count returned by
+ * 'getPresentationPosition' must reset after flush.
+ *
* Optional method
*
* Implementation of this function is mandatory for offloaded playback.
@@ -266,12 +273,14 @@
/**
* Return a recent count of the number of audio frames presented to an
* external observer. This excludes frames which have been written but are
- * still in the pipeline. The count is not reset to zero when output enters
- * standby. Also returns the value of CLOCK_MONOTONIC as of this
+ * still in the pipeline. The count must not reset to zero when a PCM output
+ * enters standby. For compressed and offload streams it is recommended that
+ * HAL resets the frame count.
+ *
+ * This method also returns the value of CLOCK_MONOTONIC as of this
* presentation count. The returned count is expected to be 'recent', but
* does not need to be the most recent possible value. However, the
* associated time must correspond to whatever count is returned.
- *
* Example: assume that N+M frames have been presented, where M is a 'small'
* number. Then it is permissible to return N instead of N+M, and the
* timestamp must correspond to N rather than N+M. The terms 'recent' and
@@ -289,6 +298,7 @@
/**
* Selects a presentation for decoding from a next generation media stream
* (as defined per ETSI TS 103 190-2) and a program within the presentation.
+ *
* Optional method
*
* @param presentationId selected audio presentation.