Implement audio effects HAL delegating to legacy HAL
Changes made to the .hal definition:
- added missing generated Result for methods implemented via legacy
"command" function;
- fixed Aux Channels feature definition;
- added "size" parameter for reply data in cases where the wrapper
needs to allocate a reply buffer;
- added method for generic support of feature configs;
- added new Result type;
- use arrays instead of strings in effect descriptor to ease
conversion from / to legacy HAL;
- added missing method to the Preset Reverb interface;
- fixed names of the Visualizer enums to avoid clashes with defines
from the legacy HAL file.
The implementation isn't hooked up to the server yet. Need to implement
devices and streams first.
Bug: 30222631
Change-Id: I75bb42f19ac3303759e918b6d6a91646b1555f8c
Test: make
diff --git a/audio/effect/2.0/IEffect.hal b/audio/effect/2.0/IEffect.hal
index f1cc795..615a460 100644
--- a/audio/effect/2.0/IEffect.hal
+++ b/audio/effect/2.0/IEffect.hal
@@ -48,9 +48,11 @@
/*
* Reset the effect engine. Keep configuration but resets state and buffer
* content.
+ *
+ * @return retval operation completion status.
*/
@callflow(next={"*"})
- reset();
+ reset() generates (Result retval);
/*
* Enable processing.
@@ -74,9 +76,10 @@
* descriptor to receive this command when the device changes.
*
* @param device output device specification.
+ * @return retval operation completion status.
*/
@callflow(next={"*"})
- setDevice(AudioDevice device);
+ setDevice(AudioDevice device) generates (Result retval);
/*
* Set and get volume. Used by audio framework to delegate volume control to
@@ -94,9 +97,11 @@
* @return result updated volume values. It is OK to receive an empty vector
* as a result in which case the effect framework has
* delegated volume control to another effect.
+ * @return retval operation completion status.
*/
@callflow(next={"*"})
- setAndGetVolume(vec<int32_t> volumes) generates (vec<int32_t> result);
+ setAndGetVolume(vec<uint32_t> volumes)
+ generates (Result retval, vec<uint32_t> result);
/*
* Set the audio mode. The effect implementation must set
@@ -104,9 +109,10 @@
* when the audio mode changes.
*
* @param mode desired audio mode.
+ * @return retval operation completion status.
*/
@callflow(next={"*"})
- setAudioMode(AudioMode mode);
+ setAudioMode(AudioMode mode) generates (Result retval);
/*
* Apply new audio parameters configurations for input and output buffers of
@@ -130,58 +136,63 @@
* receive this command when the device changes.
*
* @param device input device specification.
+ * @return retval operation completion status.
*/
@callflow(next={"*"})
- setInputDevice(AudioDevice device);
+ setInputDevice(AudioDevice device) generates (Result retval);
/*
* Read audio parameters configurations for input and output buffers.
*
+ * @return retval operation completion status.
* @return config configuration descriptor.
*/
@callflow(next={"*"})
- getConfig() generates (EffectConfig config);
+ getConfig() generates (Result retval, EffectConfig config);
/*
* Read audio parameters configurations for input and output buffers of
* reverse stream.
*
+ * @return retval operation completion status.
* @return config configuration descriptor.
*/
@callflow(next={"*"})
- getConfigReverse() generates (EffectConfig config);
+ getConfigReverse() generates (Result retval, EffectConfig config);
/*
- * Queries for supported configurations for a particular feature (e.g. get
- * the supported combinations of main and auxiliary channels for a noise
- * suppressor). The command parameter is a list of the feature identifiers.
+ * Queries for supported combinations of main and auxiliary channels
+ * (e.g. for a multi-microphone noise suppressor).
*
+ * @param maxConfigs maximum number of the combinations to return.
* @return retval absence of the feature support is indicated using
- * NOT_SUPPORTED code.
+ * NOT_SUPPORTED code. RESULT_TOO_BIG is returned if
+ * the number of supported combinations exceeds 'maxConfigs'.
* @return result list of configuration descriptors.
*/
@callflow(next={"*"})
- getFeatureSupportedConfigs(vec<EffectFeature> features)
- generates (Result retval, vec<EffectFeatureConfig> result);
+ getSupportedAuxChannelsConfigs(uint32_t maxConfigs)
+ generates (Result retval, vec<EffectAuxChannelsConfig> result);
/*
- * Retrieves current configuration for a given feature.
+ * Retrieves the current configuration of main and auxiliary channels.
*
* @return retval absence of the feature support is indicated using
* NOT_SUPPORTED code.
* @return result configuration descriptor.
*/
@callflow(next={"*"})
- getFeatureConfig(EffectFeature feature)
- generates (Result retval, EffectFeatureConfig result);
+ getAuxChannelsConfig()
+ generates (Result retval, EffectAuxChannelsConfig result);
/*
- * Sets current configuration for a given feature.
+ * Sets the current configuration of main and auxiliary channels.
*
- * @return retval operation completion status.
+ * @return retval operation completion status; absence of the feature
+ * support is indicated using NOT_SUPPORTED code.
*/
@callflow(next={"*"})
- setFeatureConfig(EffectFeatureConfig featureConfig)
+ setAuxChannelsConfig(EffectAuxChannelsConfig config)
generates (Result retval);
/*
@@ -189,9 +200,10 @@
* recognition...).
*
* @param source source descriptor.
+ * @return retval operation completion status.
*/
@callflow(next={"*"})
- setAudioSource(AudioSource source);
+ setAudioSource(AudioSource source) generates (Result retval);
/*
* This command indicates if the playback thread the effect is attached to
@@ -207,10 +219,11 @@
/*
* Returns the effect descriptor.
*
+ * @return retval operation completion status.
* @return descriptor effect descriptor.
*/
@callflow(next={"*"})
- getDescriptor() generates (EffectDescriptor descriptor);
+ getDescriptor() generates (Result retval, EffectDescriptor descriptor);
/*
* Effect process function. Takes input samples as specified (count and
@@ -223,13 +236,18 @@
* off the effect gracefully and when done indicate that it is OK to stop
* calling the 'process' function by returning the INVALID_STATE status.
*
+ * Output audio buffer must contain no more frames than the input audio
+ * buffer. Since the effect may transform input channels into a different
+ * amount of channels, the caller provides the output frame size.
+ *
* @param inBuffer input audio buffer.
+ * @param outFrameSize output frame size in bytes.
* @return retval operation completion status.
* @return outBuffer output audio buffer.
*/
// TODO(mnaganov): replace with FMQ version.
@callflow(next={"*"})
- process(AudioBuffer inBuffer)
+ process(AudioBuffer inBuffer, uint32_t outFrameSize)
generates (Result retval, AudioBuffer outBuffer);
/*
@@ -238,13 +256,18 @@
* reference stream, this function MUST return NOT_SUPPORTED. For example,
* this function would typically implemented by an Echo Canceler.
*
+ * Output audio buffer must contain no more frames than the input audio
+ * buffer. Since the effect may transform input channels into a different
+ * amount of channels, the caller provides the output frame size.
+ *
* @param inBuffer input audio buffer.
+ * @param outFrameSize output frame size in bytes.
* @return retval operation completion status.
* @return outBuffer output audio buffer.
*/
// TODO(mnaganov): replace with FMQ version.
@callflow(next={"*"})
- processReverse(AudioBuffer inBuffer)
+ processReverse(AudioBuffer inBuffer, uint32_t outFrameSize)
generates (Result retval, AudioBuffer outBuffer);
/*
@@ -261,10 +284,11 @@
*
* @param commandId the ID of the command.
* @param data command data.
+ * @param resultMaxSize maximum size in bytes of the result; can be 0.
* @return status command completion status.
* @return result result data.
*/
- command(uint32_t commandId, vec<uint8_t> data)
+ command(uint32_t commandId, vec<uint8_t> data, uint32_t resultMaxSize)
generates (int32_t status, vec<uint8_t> result);
/*
@@ -302,10 +326,84 @@
* implemented in software.
*
* @param parameter identifying data of the parameter.
+ * @param valueMaxSize maximum size in bytes of the value.
* @return retval operation completion status.
* @return result the value of the parameter.
*/
@callflow(next={"*"})
- getParameter(vec<uint8_t> parameter)
+ getParameter(vec<uint8_t> parameter, uint32_t valueMaxSize)
generates (Result retval, vec<uint8_t> value);
+
+ /*
+ * Get supported configs for a vendor-specific feature. The configs returned
+ * are not interpreted by Android Framework and are passed as-is between the
+ * application and the effect.
+ *
+ * The effect must use INVALID_ARGUMENTS return code if the feature ID is
+ * unknown. If the effect does not support getting vendor-specific feature
+ * configs, it must return NOT_SUPPORTED. If the feature is supported but
+ * the total number of supported configurations exceeds the maximum number
+ * indicated by the caller, the method must return RESULT_TOO_BIG.
+ *
+ * Use this method only if the effect is provided by a third party, and
+ * there is no interface defined for it. This method only works for effects
+ * implemented in software.
+ *
+ * @param featureId feature identifier.
+ * @param maxConfigs maximum number of configs to return.
+ * @param configSize size of each config in bytes.
+ * @return retval operation completion status.
+ * @return configsCount number of configs returned.
+ * @return configsData data for all the configs returned.
+ */
+ @callflow(next={"*"})
+ getSupportedConfigsForFeature(
+ uint32_t featureId,
+ uint32_t maxConfigs,
+ uint32_t configSize) generates (
+ Result retval,
+ uint32_t configsCount,
+ vec<uint8_t> configsData);
+
+ /*
+ * Get the current config for a vendor-specific feature. The config returned
+ * is not interpreted by Android Framework and is passed as-is between the
+ * application and the effect.
+ *
+ * The effect must use INVALID_ARGUMENTS return code if the feature ID is
+ * unknown. If the effect does not support getting vendor-specific
+ * feature configs, it must return NOT_SUPPORTED.
+ *
+ * Use this method only if the effect is provided by a third party, and
+ * there is no interface defined for it. This method only works for effects
+ * implemented in software.
+ *
+ * @param featureId feature identifier.
+ * @param configSize size of the config in bytes.
+ * @return retval operation completion status.
+ * @return configData config data.
+ */
+ @callflow(next={"*"})
+ getCurrentConfigForFeature(uint32_t featureId, uint32_t configSize)
+ generates (Result retval, vec<uint8_t> configData);
+
+ /*
+ * Set the current config for a vendor-specific feature. The config data
+ * is not interpreted by Android Framework and is passed as-is between the
+ * application and the effect.
+ *
+ * The effect must use INVALID_ARGUMENTS return code if the feature ID is
+ * unknown. If the effect does not support getting vendor-specific
+ * feature configs, it must return NOT_SUPPORTED.
+ *
+ * Use this method only if the effect is provided by a third party, and
+ * there is no interface defined for it. This method only works for effects
+ * implemented in software.
+ *
+ * @param featureId feature identifier.
+ * @param configData config data.
+ * @return retval operation completion status.
+ */
+ setCurrentConfigForFeature(uint32_t featureId, vec<uint8_t> configData)
+ generates (Result retval);
};