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>
diff --git a/audio/4.0/IDevice.hal b/audio/4.0/IDevice.hal
index e3f36f6..23cf9fb 100644
--- a/audio/4.0/IDevice.hal
+++ b/audio/4.0/IDevice.hal
@@ -200,14 +200,17 @@
/**
* 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.
* @return hwAvSync HW synchronization source
*/
- getHwAvSync() generates (AudioHwSync hwAvSync);
+ getHwAvSync() generates (Result retval, AudioHwSync hwAvSync);
/**
* 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.
* @return retval operation completion status.
@@ -219,11 +222,19 @@
* The framework does not interpret the parameters, they are passed
* in an opaque manner between a vendor application and HAL.
*
- * @param keys parameter keys.
+ * Multiple parameters can be retrieved at the same time.
+ * The implementation should return as many requested parameters
+ * as possible, even if one or more is not supported
+ *
+ * @param context provides more information about the request
+ * @param keys keys of the requested parameters
* @return retval operation completion status.
+ * OK must be returned if keys is empty.
+ * NOT_SUPPORTED must be returned if at least one key is unknown.
* @return parameters parameter key value pairs.
+ * Must contain the value of all requested keys if retval == OK
*/
- getParameters(vec<string> keys)
+ getParameters(vec<ParameterValue> context, vec<string> keys)
generates (Result retval, vec<ParameterValue> parameters);
/**
@@ -231,16 +242,28 @@
* The framework does not interpret the parameters, they are passed
* in an opaque manner between a vendor application and HAL.
*
+ * Multiple parameters can be set at the same time though this is
+ * discouraged as it make failure analysis harder.
+ *
+ * If possible, a failed setParameters should not impact the platform state.
+ *
+ * @param context provides more information about the request
* @param parameters parameter key value pairs.
* @return retval operation completion status.
+ * All parameters must be successfully set for OK to be returned
*/
- setParameters(vec<ParameterValue> parameters) generates (Result retval);
+ setParameters(vec<ParameterValue> context, vec<ParameterValue> parameters)
+ generates (Result retval);
/**
- * Dumps information about the stream into the provided file descriptor.
+ * Dumps information about the device into the provided file descriptor.
* This is used for the dumpsys facility.
+ * The implementation should not block as the caller might have time
+ * constraint on the dump.
+ * A back to back dump of all HAL Device and Stream should take under 100ms.
*
* @param fd dump file descriptor.
+ * @return retval operation completion status: OK or NOT_SUPPORTED.
*/
- debugDump(handle fd);
+ debugDump(handle fd) generates (Result retval);
};
diff --git a/audio/4.0/IPrimaryDevice.hal b/audio/4.0/IPrimaryDevice.hal
index 60330fb..4eafdbb 100644
--- a/audio/4.0/IPrimaryDevice.hal
+++ b/audio/4.0/IPrimaryDevice.hal
@@ -52,6 +52,7 @@
* Sets whether BT SCO Noise Reduction and Echo Cancellation are enabled.
* Calling this method is equivalent to setting AUDIO_PARAMETER_KEY_BT_NREC
* on the legacy HAL.
+ * Optional method
*
* @param enabled whether BT SCO NR + EC are enabled.
* @return retval operation completion status.
@@ -70,6 +71,7 @@
/**
* Sets whether BT SCO Wideband mode is enabled. Calling this method is
* equivalent to setting AUDIO_PARAMETER_KEY_BT_SCO_WB on the legacy HAL.
+ * Optional method
*
* @param enabled whether BT Wideband is enabled.
* @return retval operation completion status.
@@ -115,6 +117,7 @@
* Sets whether Hearing Aid Compatibility - Telecoil (HAC-T) mode is
* enabled. Calling this method is equivalent to setting
* AUDIO_PARAMETER_KEY_HAC on the legacy HAL.
+ * Optional method
*
* @param enabled whether HAC mode is enabled.
* @return retval operation completion status.
diff --git a/audio/4.0/IStream.hal b/audio/4.0/IStream.hal
index 162e0fd..62b8d03 100644
--- a/audio/4.0/IStream.hal
+++ b/audio/4.0/IStream.hal
@@ -53,17 +53,30 @@
getSampleRate() generates (uint32_t sampleRateHz);
/**
- * Return supported sampling rates of the stream. Calling this method is
- * equivalent to getting AUDIO_PARAMETER_STREAM_SUP_SAMPLING_RATES on the
- * legacy HAL.
+ * Return supported native sampling rates of the stream for a given format.
+ * A supported native sample rate is a sample rate that can be efficiently
+ * played by the hardware (typically without sample-rate conversions).
*
+ * This function is only called for dynamic profile. If called for
+ * non-dynamic profile is should return NOT_SUPPORTED or the same list
+ * as in audio_policy_configuration.xml.
+ *
+ * Calling this method is equivalent to getting
+ * AUDIO_PARAMETER_STREAM_SUP_SAMPLING_RATES on the legacy HAL.
+ *
+ *
+ * @param format audio format for which the sample rates are supported.
+ * @return retval operation completion status.
+ * Must be OK if the format is supported.
* @return sampleRateHz supported sample rates.
*/
- getSupportedSampleRates() generates (vec<uint32_t> sampleRates);
+ getSupportedSampleRates(AudioFormat format)
+ generates (Result retval, vec<uint32_t> sampleRates);
/**
* Sets the sampling rate of the stream. Calling this method is equivalent
* to setting AUDIO_PARAMETER_STREAM_SAMPLING_RATE on the legacy HAL.
+ * Optional method. If implemented, only called on a stopped stream.
*
* @param sampleRateHz sample rate in Hz.
* @return retval operation completion status.
@@ -82,13 +95,18 @@
* equivalent to getting AUDIO_PARAMETER_STREAM_SUP_CHANNELS on the legacy
* HAL.
*
+ * @param format audio format for which the channel masks are supported.
+ * @return retval operation completion status.
+ * Must be OK if the format is supported.
* @return masks supported audio masks.
*/
- getSupportedChannelMasks() generates (vec<AudioChannelMask> masks);
+ getSupportedChannelMasks(AudioFormat format)
+ generates (Result retval, vec<AudioChannelMask> masks);
/**
* Sets the channel mask of the stream. Calling this method is equivalent to
* setting AUDIO_PARAMETER_STREAM_CHANNELS on the legacy HAL.
+ * Optional method
*
* @param format audio format.
* @return retval operation completion status.
@@ -114,6 +132,7 @@
/**
* Sets the audio format of the stream. Calling this method is equivalent to
* setting AUDIO_PARAMETER_STREAM_FORMAT on the legacy HAL.
+ * Optional method
*
* @param format audio format.
* @return retval operation completion status.
@@ -159,10 +178,12 @@
/**
* Return the set of device(s) which this stream is connected to.
+ * Optional method
*
+ * @return retval operation completion status: OK or NOT_SUPPORTED.
* @return device set of device(s) which this stream is connected to.
*/
- getDevice() generates (AudioDevice device);
+ getDevice() generates (Result retval, AudioDevice device);
/**
* Connects the stream to the device.
@@ -192,6 +213,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
* @return retval operation completion status.
@@ -203,11 +225,19 @@
* The framework does not interpret the parameters, they are passed
* in an opaque manner between a vendor application and HAL.
*
- * @param keys parameter keys.
+ * Multiple parameters can be retrieved at the same time.
+ * The implementation should return as many requested parameters
+ * as possible, even if one or more is not supported
+ *
+ * @param context provides more information about the request
+ * @param keys keys of the requested parameters
* @return retval operation completion status.
+ * OK must be returned if keys is empty.
+ * NOT_SUPPORTED must be returned if at least one key is unknown.
* @return parameters parameter key value pairs.
+ * Must contain the value of all requested keys if retval == OK
*/
- getParameters(vec<string> keys)
+ getParameters(vec<ParameterValue> context, vec<string> keys)
generates (Result retval, vec<ParameterValue> parameters);
/**
@@ -215,18 +245,30 @@
* The framework does not interpret the parameters, they are passed
* in an opaque manner between a vendor application and HAL.
*
+ * Multiple parameters can be set at the same time though this is
+ * discouraged as it make failure analysis harder.
+ *
+ * If possible, a failed setParameters should not impact the platform state.
+ *
+ * @param context provides more information about the request
* @param parameters parameter key value pairs.
* @return retval operation completion status.
+ * All parameters must be successfully set for OK to be returned
*/
- setParameters(vec<ParameterValue> parameters) generates (Result retval);
+ setParameters(vec<ParameterValue> context, vec<ParameterValue> parameters)
+ generates (Result retval);
/**
* Dumps information about the stream into the provided file descriptor.
* This is used for the dumpsys facility.
+ * The implementation should not block as the caller might have time
+ * constraint on the dump.
+ * A back to back dump of all HAL Device and Stream should take under 100ms.
*
* @param fd dump file descriptor.
+ * @return retval operation completion status: OK or NOT_SUPPORTED.
*/
- debugDump(handle fd);
+ debugDump(handle fd) generates (Result retval);
/**
* Called by the framework to start a stream operating in mmap mode.
diff --git a/audio/4.0/IStreamIn.hal b/audio/4.0/IStreamIn.hal
index 306aeb1..ea2826e 100644
--- a/audio/4.0/IStreamIn.hal
+++ b/audio/4.0/IStreamIn.hal
@@ -26,6 +26,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.
* @return source audio source.
@@ -34,6 +35,7 @@
/**
* Set the input gain for the audio driver.
+ * Optional method
*
* @param gain 1.0f is unity, 0.0f is zero.
* @result retval operation completion status.
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.
diff --git a/audio/common/4.0/types.hal b/audio/common/4.0/types.hal
index d0e99fc..eaff69d 100644
--- a/audio/common/4.0/types.hal
+++ b/audio/common/4.0/types.hal
@@ -83,7 +83,7 @@
*/
/**
- * Audio stream type describing the intented use case of a stream.
+ * Audio stream type describing the intended use case of a stream.
*/
@export(name="audio_stream_type_t", value_prefix="AUDIO_STREAM_")
enum AudioStreamType : int32_t {
diff --git a/audio/effect/4.0/IEffectsFactory.hal b/audio/effect/4.0/IEffectsFactory.hal
index 0e1c0d2..84efb74 100644
--- a/audio/effect/4.0/IEffectsFactory.hal
+++ b/audio/effect/4.0/IEffectsFactory.hal
@@ -59,8 +59,12 @@
/**
* Dumps information about effects into the provided file descriptor.
* This is used for the dumpsys facility.
+ * The implementation should not block as the caller might have time
+ * constraint on the dump.
+ * A back to back dump of all HAL Device and Stream should take under 100ms.
*
* @param fd dump file descriptor.
+ * @return retval operation completion status: OK or NOT_SUPPORTED.
*/
- debugDump(handle fd);
+ debugDump(handle fd) generates (Result retval);
};