From 84efa03de34a6c6933413e63b000ace1da12bee5 Mon Sep 17 00:00:00 2001 From: Shunkai Yao Date: Tue, 23 Aug 2022 17:46:10 +0000 Subject: [PATCH] AIDL effect: Initial IEffect interface definition Bug: 238913361 Test: atest VtsHalAudioEffectTargetTest Merged-In: I0d02fed5d40a108003e735d3619e2fc7c0ef6332 Change-Id: I0d02fed5d40a108003e735d3619e2fc7c0ef6332 --- audio/aidl/Android.bp | 1 + .../hardware/audio/effect/IEffect.aidl | 40 ++++++++++++ .../hardware/audio/effect/IFactory.aidl | 2 + .../hardware/audio/effect/IEffect.aidl | 63 +++++++++++++++++++ .../hardware/audio/effect/IFactory.aidl | 27 ++++++++ 5 files changed, 133 insertions(+) create mode 100644 audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/IEffect.aidl create mode 100644 audio/aidl/android/hardware/audio/effect/IEffect.aidl diff --git a/audio/aidl/Android.bp b/audio/aidl/Android.bp index d4c1e85e91..ad933bc78b 100644 --- a/audio/aidl/Android.bp +++ b/audio/aidl/Android.bp @@ -148,6 +148,7 @@ aidl_interface { vendor_available: true, srcs: [ "android/hardware/audio/effect/Descriptor.aidl", + "android/hardware/audio/effect/IEffect.aidl", "android/hardware/audio/effect/IFactory.aidl", ], imports: [ diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/IEffect.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/IEffect.aidl new file mode 100644 index 0000000000..7f868ad36d --- /dev/null +++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/IEffect.aidl @@ -0,0 +1,40 @@ +/* + * Copyright (C) 2022 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. + */ +/////////////////////////////////////////////////////////////////////////////// +// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE. // +/////////////////////////////////////////////////////////////////////////////// + +// This file is a snapshot of an AIDL file. Do not edit it manually. There are +// two cases: +// 1). this is a frozen version file - do not edit this in any case. +// 2). this is a 'current' file. If you make a backwards compatible change to +// the interface (from the latest frozen version), the build system will +// prompt you to update this file with `m -update-api`. +// +// You must not make a backward incompatible change to any AIDL file built +// with the aidl_interface module type with versions property set. The module +// type is used to build AIDL files in a way that they can be used across +// independently updatable components of the system. If a device is shipped +// with such a backward incompatible change, it has a high risk of breaking +// later when a module using the interface is updated, e.g., Mainline modules. + +package android.hardware.audio.effect; +@VintfStability +interface IEffect { + void open(); + void close(); + android.hardware.audio.effect.Descriptor getDescriptor(); +} diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/IFactory.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/IFactory.aidl index b6c9aab75e..db06475cde 100644 --- a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/IFactory.aidl +++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/IFactory.aidl @@ -35,4 +35,6 @@ package android.hardware.audio.effect; @VintfStability interface IFactory { android.hardware.audio.effect.Descriptor.Identity[] queryEffects(in @nullable android.media.audio.common.AudioUuid type, in @nullable android.media.audio.common.AudioUuid implementation); + android.hardware.audio.effect.IEffect createEffect(in android.media.audio.common.AudioUuid implUuid); + void destroyEffect(in android.hardware.audio.effect.IEffect handle); } diff --git a/audio/aidl/android/hardware/audio/effect/IEffect.aidl b/audio/aidl/android/hardware/audio/effect/IEffect.aidl new file mode 100644 index 0000000000..44e916b7bf --- /dev/null +++ b/audio/aidl/android/hardware/audio/effect/IEffect.aidl @@ -0,0 +1,63 @@ +/* + * Copyright (C) 2022 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; + +import android.hardware.audio.effect.Descriptor; + +/** + * Effect interfaces definitions to configure and control the effect instance. + */ +@VintfStability +interface IEffect { + /** + * Open an effect instance, effect should not start processing data before receive START + * command. All necessary information should be allocated and instance should transfer to IDLE + * state after open() call has been handled successfully. + * After open, the effect instance should be able to handle all IEffect interface calls. + * + * @throws a EX_UNSUPPORTED_OPERATION if device capability/resource is not enough or system + * failure happens. + * @note Open an already-opened effect instance should do nothing and not result in throw error. + */ + void open(); + + /** + * Called by the client to close the effect instance, instance context will be kept after + * close, but processing thread should be destroyed and consume no CPU. It is recommended to + * close the effect on the client side as soon as it becomes unused, it's client responsibility + * to make sure all parameter/buffer is correct if client wants to reopen a closed instance. + * + * Effect instance close interface should always success unless: + * 1. The effect instance is not in a proper state to be closed, for example it's still in + * processing state. + * 2. There is system/hardware related failure when close. + * + * @throws EX_ILLEGAL_STATE if the effect instance is not in a proper state to be closed. + * @throws EX_UNSUPPORTED_OPERATION if the effect instance failed to close for any other reason. + * @note Close an already-closed effect should do nothing and not result in throw error. + */ + void close(); + + /** + * Return the @c Descriptor of this effect instance. + * + * Must be available for the effect instance at anytime and should always succeed. + * + * @return Descriptor The @c Descriptor of this effect instance. + */ + Descriptor getDescriptor(); +} diff --git a/audio/aidl/android/hardware/audio/effect/IFactory.aidl b/audio/aidl/android/hardware/audio/effect/IFactory.aidl index 99c2e6a2f5..4873d3a825 100644 --- a/audio/aidl/android/hardware/audio/effect/IFactory.aidl +++ b/audio/aidl/android/hardware/audio/effect/IFactory.aidl @@ -17,6 +17,7 @@ package android.hardware.audio.effect; import android.hardware.audio.effect.Descriptor; +import android.hardware.audio.effect.IEffect; import android.media.audio.common.AudioUuid; /** @@ -42,4 +43,30 @@ interface IFactory { */ Descriptor.Identity[] queryEffects( in @nullable AudioUuid type, in @nullable AudioUuid implementation); + + /** + * Called by the audio framework to create the effect (identified by the implementation UUID + * parameter). + * + * The effect instance should be able to maintain its own context and parameters after creation. + * + * @param implUuid UUID for the effect implementation which instance will be created based on. + * @return The effect instance handle created. + * @throws EX_ILLEGAL_ARGUMENT if the implUuid is not valid. + * @throws EX_TRANSACTION_FAILED if device capability/resource is not enough to create the + * effect instance. + */ + IEffect createEffect(in AudioUuid implUuid); + + /** + * Called by the framework to destroy the effect and free up all currently allocated resources. + * It is recommended to destroy the effect from the client side as soon as it is becomes unused. + * + * The client must ensure effect instance is closed before destroy. + * + * @param handle The handle of effect instance to be destroyed. + * @throws EX_ILLEGAL_ARGUMENT if the effect handle is not valid. + * @throws EX_ILLEGAL_STATE if the effect instance is not in a proper state to be destroyed. + */ + void destroyEffect(in IEffect handle); }