Define HAL for audio effects
Created after hardware/audio_effect.h with the following changes:
- names changed to satisfy HAL style guide;
- defined an interface per effect, an interface method
per command, and getter / setter methods for properties;
- retained methods for executing proprietary commands
and accessing proprietary properties, only to be used
for third-party software effects;
- HIDL vector type is used instead of count / array pairs;
- provider callback changed to be used over RPC;
- 'dump' is method is already defined by generated code.
Note that audio data is currently transferred using AudioBuffers,
which is not effective due to memory copy and HwBinder transaction
involved. The transfer method will be changed to FastMessageQueue.
Bug: 30222631
Test: make
Change-Id: Ic8ea5c19688610ebe642c7597d2bcfa3226977e7
diff --git a/audio/effect/2.0/IEffect.hal b/audio/effect/2.0/IEffect.hal
new file mode 100644
index 0000000..f1cc795
--- /dev/null
+++ b/audio/effect/2.0/IEffect.hal
@@ -0,0 +1,311 @@
+/*
+ * Copyright (C) 2016 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package android.hardware.audio.effect@2.0;
+
+import android.hardware.audio.common@2.0;
+import IEffectBufferProviderCallback;
+
+interface IEffect {
+ /*
+ * Initialize effect engine--all configurations return to default.
+ *
+ * @return retval operation completion status.
+ */
+ @entry
+ @callflow(next={"*"})
+ init() generates (Result retval);
+
+ /*
+ * Apply new audio parameters configurations for input and output buffers.
+ * The provider callbacks may be empty, but in this case the buffer
+ * must be provided in the EffectConfig structure.
+ *
+ * @param config configuration descriptor.
+ * @param inputBufferProvider optional buffer provider reference.
+ * @param outputBufferProvider optional buffer provider reference.
+ * @return retval operation completion status.
+ */
+ @callflow(next={"*"})
+ setConfig(EffectConfig config,
+ IEffectBufferProviderCallback inputBufferProvider,
+ IEffectBufferProviderCallback outputBufferProvider)
+ generates (Result retval);
+
+ /*
+ * Reset the effect engine. Keep configuration but resets state and buffer
+ * content.
+ */
+ @callflow(next={"*"})
+ reset();
+
+ /*
+ * Enable processing.
+ *
+ * @return retval operation completion status.
+ */
+ @callflow(next={"process"})
+ enable() generates (Result retval);
+
+ /*
+ * Disable processing.
+ *
+ * @return retval operation completion status.
+ */
+ @exit
+ disable() generates (Result retval);
+
+ /*
+ * Set the rendering device the audio output path is connected to. The
+ * effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its
+ * descriptor to receive this command when the device changes.
+ *
+ * @param device output device specification.
+ */
+ @callflow(next={"*"})
+ setDevice(AudioDevice device);
+
+ /*
+ * Set and get volume. Used by audio framework to delegate volume control to
+ * effect engine. The effect implementation must set EFFECT_FLAG_VOLUME_IND
+ * or EFFECT_FLAG_VOLUME_CTRL flag in its descriptor to receive this command
+ * before every call to 'process' function If EFFECT_FLAG_VOLUME_CTRL flag
+ * is set in the effect descriptor, the effect engine must return the volume
+ * that should be applied before the effect is processed. The overall volume
+ * (the volume actually applied by the effect engine multiplied by the
+ * returned value) should match the value indicated in the command.
+ *
+ * @param volumes vector containing volume for each channel defined in
+ * EffectConfig for output buffer expressed in 8.24 fixed
+ * point format.
+ * @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.
+ */
+ @callflow(next={"*"})
+ setAndGetVolume(vec<int32_t> volumes) generates (vec<int32_t> result);
+
+ /*
+ * Set the audio mode. The effect implementation must set
+ * EFFECT_FLAG_AUDIO_MODE_IND flag in its descriptor to receive this command
+ * when the audio mode changes.
+ *
+ * @param mode desired audio mode.
+ */
+ @callflow(next={"*"})
+ setAudioMode(AudioMode mode);
+
+ /*
+ * Apply new audio parameters configurations for input and output buffers of
+ * reverse stream. An example of reverse stream is the echo reference
+ * supplied to an Acoustic Echo Canceler.
+ *
+ * @param config configuration descriptor.
+ * @param inputBufferProvider optional buffer provider reference.
+ * @param outputBufferProvider optional buffer provider reference.
+ * @return retval operation completion status.
+ */
+ @callflow(next={"*"})
+ setConfigReverse(EffectConfig config,
+ IEffectBufferProviderCallback inputBufferProvider,
+ IEffectBufferProviderCallback outputBufferProvider)
+ generates (Result retval);
+
+ /*
+ * Set the capture device the audio input path is connected to. The effect
+ * implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to
+ * receive this command when the device changes.
+ *
+ * @param device input device specification.
+ */
+ @callflow(next={"*"})
+ setInputDevice(AudioDevice device);
+
+ /*
+ * Read audio parameters configurations for input and output buffers.
+ *
+ * @return config configuration descriptor.
+ */
+ @callflow(next={"*"})
+ getConfig() generates (EffectConfig config);
+
+ /*
+ * Read audio parameters configurations for input and output buffers of
+ * reverse stream.
+ *
+ * @return config configuration descriptor.
+ */
+ @callflow(next={"*"})
+ getConfigReverse() generates (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.
+ *
+ * @return retval absence of the feature support is indicated using
+ * NOT_SUPPORTED code.
+ * @return result list of configuration descriptors.
+ */
+ @callflow(next={"*"})
+ getFeatureSupportedConfigs(vec<EffectFeature> features)
+ generates (Result retval, vec<EffectFeatureConfig> result);
+
+ /*
+ * Retrieves current configuration for a given feature.
+ *
+ * @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);
+
+ /*
+ * Sets current configuration for a given feature.
+ *
+ * @return retval operation completion status.
+ */
+ @callflow(next={"*"})
+ setFeatureConfig(EffectFeatureConfig featureConfig)
+ generates (Result retval);
+
+ /*
+ * Set the audio source the capture path is configured for (Camcorder, voice
+ * recognition...).
+ *
+ * @param source source descriptor.
+ */
+ @callflow(next={"*"})
+ setAudioSource(AudioSource source);
+
+ /*
+ * This command indicates if the playback thread the effect is attached to
+ * is offloaded or not, and updates the I/O handle of the playback thread
+ * the effect is attached to.
+ *
+ * @param param effect offload descriptor.
+ * @return retval operation completion status.
+ */
+ @callflow(next={"*"})
+ offload(EffectOffloadParameter param) generates (Result retval);
+
+ /*
+ * Returns the effect descriptor.
+ *
+ * @return descriptor effect descriptor.
+ */
+ @callflow(next={"*"})
+ getDescriptor() generates (EffectDescriptor descriptor);
+
+ /*
+ * Effect process function. Takes input samples as specified (count and
+ * location) in input buffer and returns processed samples as specified in
+ * output buffer. If the buffer descriptor is empty the function must use
+ * either the buffer or the buffer provider callback installed by the
+ * setConfig command. The effect framework must call the 'process' function
+ * after the 'enable' command is received and until the 'disable' is
+ * received. When the engine receives the 'disable' command it should turn
+ * off the effect gracefully and when done indicate that it is OK to stop
+ * calling the 'process' function by returning the INVALID_STATE status.
+ *
+ * @param inBuffer input audio buffer.
+ * @return retval operation completion status.
+ * @return outBuffer output audio buffer.
+ */
+ // TODO(mnaganov): replace with FMQ version.
+ @callflow(next={"*"})
+ process(AudioBuffer inBuffer)
+ generates (Result retval, AudioBuffer outBuffer);
+
+ /*
+ * Process reverse stream function. This function is used to pass a
+ * reference stream to the effect engine. If the engine does not need a
+ * reference stream, this function MUST return NOT_SUPPORTED. For example,
+ * this function would typically implemented by an Echo Canceler.
+ *
+ * @param inBuffer input audio buffer.
+ * @return retval operation completion status.
+ * @return outBuffer output audio buffer.
+ */
+ // TODO(mnaganov): replace with FMQ version.
+ @callflow(next={"*"})
+ processReverse(AudioBuffer inBuffer)
+ generates (Result retval, AudioBuffer outBuffer);
+
+ /*
+ * Execute a vendor specific command on the effect. The command code
+ * and data, as well as result data are not interpreted by Android
+ * Framework and are passed as-is between the application and the effect.
+ *
+ * The effect must use standard POSIX.1-2001 error codes for the operation
+ * completion status.
+ *
+ * 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 commandId the ID of the command.
+ * @param data command data.
+ * @return status command completion status.
+ * @return result result data.
+ */
+ command(uint32_t commandId, vec<uint8_t> data)
+ generates (int32_t status, vec<uint8_t> result);
+
+ /*
+ * Set a vendor-specific parameter and apply it immediately. The parameter
+ * code and data 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 parameter ID is
+ * unknown or if provided parameter data is invalid. If the effect does not
+ * support setting vendor-specific parameters, 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 parameter identifying data of the parameter.
+ * @param value the value of the parameter.
+ * @return retval operation completion status.
+ */
+ @callflow(next={"*"})
+ setParameter(vec<uint8_t> parameter, vec<uint8_t> value)
+ generates (Result retval);
+
+ /*
+ * Get a vendor-specific parameter value. The parameter code and returned
+ * data 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 parameter ID is
+ * unknown. If the effect does not support setting vendor-specific
+ * parameters, 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 parameter identifying data of the parameter.
+ * @return retval operation completion status.
+ * @return result the value of the parameter.
+ */
+ @callflow(next={"*"})
+ getParameter(vec<uint8_t> parameter)
+ generates (Result retval, vec<uint8_t> value);
+};