7623ed9258
Fixed behavior of IStream|IEffect.close to release the underlying HAL resource synchronously. This is to avoid adding artificial delays in VTS that become totally unpractical in V6. Added clarification about expected client behavior for IStream|IEffect.close w.r.t. audio data transfer. Added IDevice.close method which releases HAL device resource. Updated VTS tests to remove delays in V6. Bug: 114451103 Bug: 141989952 Test: atest VtsHalAudioV6_0TargetTest Change-Id: I439f0f923c091af2ab234d15ca847cfade341f25
421 lines
17 KiB
Text
421 lines
17 KiB
Text
/*
|
|
* Copyright (C) 2019 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@6.0;
|
|
|
|
import android.hardware.audio.common@6.0;
|
|
import IEffectBufferProviderCallback;
|
|
|
|
interface IEffect {
|
|
/**
|
|
* Initialize effect engine--all configurations return to default.
|
|
*
|
|
* @return retval operation completion status.
|
|
*/
|
|
@entry
|
|
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.
|
|
*/
|
|
setConfig(EffectConfig config,
|
|
IEffectBufferProviderCallback inputBufferProvider,
|
|
IEffectBufferProviderCallback outputBufferProvider)
|
|
generates (Result retval);
|
|
|
|
/**
|
|
* Reset the effect engine. Keep configuration but resets state and buffer
|
|
* content.
|
|
*
|
|
* @return retval operation completion status.
|
|
*/
|
|
reset() generates (Result retval);
|
|
|
|
/**
|
|
* Enable processing.
|
|
*
|
|
* @return retval operation completion status.
|
|
*/
|
|
@callflow(next={"prepareForProcessing"})
|
|
enable() generates (Result retval);
|
|
|
|
/**
|
|
* Disable processing.
|
|
*
|
|
* @return retval operation completion status.
|
|
*/
|
|
@callflow(next={"close"})
|
|
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.
|
|
*
|
|
* Note: this method is only supported for effects inserted into
|
|
* the output chain.
|
|
*
|
|
* @param device output device specification.
|
|
* @return retval operation completion status.
|
|
*/
|
|
setDevice(bitfield<AudioDevice> device) generates (Result retval);
|
|
|
|
/**
|
|
* Set and get volume. Used by audio framework to delegate volume control to
|
|
* effect engine. The effect implementation must set EFFECT_FLAG_VOLUME_CTRL
|
|
* flag in its descriptor to receive this command. 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.
|
|
* @return retval operation completion status.
|
|
*/
|
|
setAndGetVolume(vec<uint32_t> volumes)
|
|
generates (Result retval, vec<uint32_t> result);
|
|
|
|
/**
|
|
* Notify the effect of the volume change. The effect implementation must
|
|
* set EFFECT_FLAG_VOLUME_IND flag in its descriptor to receive this
|
|
* command.
|
|
*
|
|
* @param volumes vector containing volume for each channel defined in
|
|
* EffectConfig for output buffer expressed in 8.24 fixed
|
|
* point format.
|
|
* @return retval operation completion status.
|
|
*/
|
|
volumeChangeNotification(vec<uint32_t> volumes)
|
|
generates (Result retval);
|
|
|
|
/**
|
|
* 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.
|
|
* @return retval operation completion status.
|
|
*/
|
|
setAudioMode(AudioMode mode) generates (Result retval);
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
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.
|
|
*
|
|
* Note: this method is only supported for effects inserted into
|
|
* the input chain.
|
|
*
|
|
* @param device input device specification.
|
|
* @return retval operation completion status.
|
|
*/
|
|
setInputDevice(bitfield<AudioDevice> device) generates (Result retval);
|
|
|
|
/**
|
|
* Read audio parameters configurations for input and output buffers.
|
|
*
|
|
* @return retval operation completion status.
|
|
* @return config configuration descriptor.
|
|
*/
|
|
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.
|
|
*/
|
|
getConfigReverse() generates (Result retval, EffectConfig config);
|
|
|
|
/**
|
|
* 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. RESULT_TOO_BIG is returned if
|
|
* the number of supported combinations exceeds 'maxConfigs'.
|
|
* @return result list of configuration descriptors.
|
|
*/
|
|
getSupportedAuxChannelsConfigs(uint32_t maxConfigs)
|
|
generates (Result retval, vec<EffectAuxChannelsConfig> result);
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
getAuxChannelsConfig()
|
|
generates (Result retval, EffectAuxChannelsConfig result);
|
|
|
|
/**
|
|
* Sets the current configuration of main and auxiliary channels.
|
|
*
|
|
* @return retval operation completion status; absence of the feature
|
|
* support is indicated using NOT_SUPPORTED code.
|
|
*/
|
|
setAuxChannelsConfig(EffectAuxChannelsConfig config)
|
|
generates (Result retval);
|
|
|
|
/**
|
|
* Set the audio source the capture path is configured for (Camcorder, voice
|
|
* recognition...).
|
|
*
|
|
* Note: this method is only supported for effects inserted into
|
|
* the input chain.
|
|
*
|
|
* @param source source descriptor.
|
|
* @return retval operation completion status.
|
|
*/
|
|
setAudioSource(AudioSource source) generates (Result retval);
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
offload(EffectOffloadParameter param) generates (Result retval);
|
|
|
|
/**
|
|
* Returns the effect descriptor.
|
|
*
|
|
* @return retval operation completion status.
|
|
* @return descriptor effect descriptor.
|
|
*/
|
|
getDescriptor() generates (Result retval, EffectDescriptor descriptor);
|
|
|
|
/**
|
|
* Set up required transports for passing audio buffers to the effect.
|
|
*
|
|
* The transport consists of shared memory and a message queue for reporting
|
|
* effect processing operation status. The shared memory is set up
|
|
* separately using 'setProcessBuffers' method.
|
|
*
|
|
* Processing is requested by setting 'REQUEST_PROCESS' or
|
|
* 'REQUEST_PROCESS_REVERSE' EventFlags associated with the status message
|
|
* queue. The result of processing may be one of the following:
|
|
* OK if there were no errors during processing;
|
|
* INVALID_ARGUMENTS if audio buffers are invalid;
|
|
* INVALID_STATE if the engine has finished the disable phase;
|
|
* NOT_INITIALIZED if the audio buffers were not set;
|
|
* NOT_SUPPORTED if the requested processing type is not supported by
|
|
* the effect.
|
|
*
|
|
* @return retval OK if both message queues were created successfully.
|
|
* INVALID_STATE if the method was already called.
|
|
* INVALID_ARGUMENTS if there was a problem setting up
|
|
* the queue.
|
|
* @return statusMQ a message queue used for passing status from the effect.
|
|
*/
|
|
@callflow(next={"setProcessBuffers"})
|
|
prepareForProcessing() generates (Result retval, fmq_sync<Result> statusMQ);
|
|
|
|
/**
|
|
* Set up input and output buffers for processing audio data. The effect
|
|
* may modify both the input and the output buffer during the operation.
|
|
* Buffers may be set multiple times during effect lifetime.
|
|
*
|
|
* The input and the output buffer may be reused between different effects,
|
|
* and the input buffer may be used as an output buffer. Buffers are
|
|
* distinguished using 'AudioBuffer.id' field.
|
|
*
|
|
* @param inBuffer input audio buffer.
|
|
* @param outBuffer output audio buffer.
|
|
* @return retval OK if both buffers were mapped successfully.
|
|
* INVALID_ARGUMENTS if there was a problem with mapping
|
|
* any of the buffers.
|
|
*/
|
|
setProcessBuffers(AudioBuffer inBuffer, AudioBuffer outBuffer)
|
|
generates (Result retval);
|
|
|
|
/**
|
|
* 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.
|
|
* @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, uint32_t resultMaxSize)
|
|
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.
|
|
*/
|
|
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.
|
|
* @param valueMaxSize maximum size in bytes of the value.
|
|
* @return retval operation completion status.
|
|
* @return result the value of the 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.
|
|
*/
|
|
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.
|
|
*/
|
|
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);
|
|
|
|
/**
|
|
* Called by the framework to deinitialize the effect and free up
|
|
* all currently allocated resources. It is recommended to close
|
|
* the effect on the client side as soon as it is becomes unused.
|
|
*
|
|
* The client must ensure that this function is not called while
|
|
* audio data is being transferred through the effect's message queues.
|
|
*
|
|
* @return retval OK in case the success.
|
|
* INVALID_STATE if the effect was already closed.
|
|
*/
|
|
@exit
|
|
close() generates (Result retval);
|
|
};
|