From 0632ae6cd125153936020e70c80aa0f4a763b075 Mon Sep 17 00:00:00 2001 From: Shunkai Yao Date: Wed, 28 Sep 2022 17:37:50 +0000 Subject: [PATCH] AIDL effect: Add effect AIDL definition Bug: 238913361 Test: atest VtsHalAudioEffectTargetTest; atest VtsHalAudioEffectFactoryTargetTest Merged-In: I8cc902df0a396d0703839b8933318a26aab2e38d Change-Id: I8cc902df0a396d0703839b8933318a26aab2e38d --- audio/aidl/Android.bp | 8 ++ .../hardware/audio/effect/Capability.aidl | 43 +++++++ .../hardware/audio/effect/CommandId.aidl | 50 +++++++++ .../hardware/audio/effect/Descriptor.aidl | 2 + .../hardware/audio/effect/Equalizer.aidl | 46 ++++++++ .../android/hardware/audio/effect/Flags.aidl | 37 ++++++ .../hardware/audio/effect/IEffect.aidl | 18 ++- .../hardware/audio/effect/Parameter.aidl | 62 +++++++++++ .../android/hardware/audio/effect/State.aidl | 40 +++++++ .../hardware/audio/effect/Capability.aidl | 46 ++++++++ .../hardware/audio/effect/CommandId.aidl | 70 ++++++++++++ .../hardware/audio/effect/Descriptor.aidl | 16 ++- .../hardware/audio/effect/Equalizer.aidl | 47 ++++++++ .../android/hardware/audio/effect/Flags.aidl | 26 +++++ .../hardware/audio/effect/IEffect.aidl | 105 +++++++++++++++++- .../hardware/audio/effect/Parameter.aidl | 87 +++++++++++++++ .../android/hardware/audio/effect/State.aidl | 86 ++++++++++++++ .../android/hardware/audio/effect/state.gv | 36 ++++++ 18 files changed, 815 insertions(+), 10 deletions(-) create mode 100644 audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Capability.aidl create mode 100644 audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/CommandId.aidl create mode 100644 audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Equalizer.aidl create mode 100644 audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Flags.aidl create mode 100644 audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Parameter.aidl create mode 100644 audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/State.aidl create mode 100644 audio/aidl/android/hardware/audio/effect/Capability.aidl create mode 100644 audio/aidl/android/hardware/audio/effect/CommandId.aidl create mode 100644 audio/aidl/android/hardware/audio/effect/Equalizer.aidl create mode 100644 audio/aidl/android/hardware/audio/effect/Flags.aidl create mode 100644 audio/aidl/android/hardware/audio/effect/Parameter.aidl create mode 100644 audio/aidl/android/hardware/audio/effect/State.aidl create mode 100644 audio/aidl/android/hardware/audio/effect/state.gv diff --git a/audio/aidl/Android.bp b/audio/aidl/Android.bp index d6e6f50ae9..4f9af12779 100644 --- a/audio/aidl/Android.bp +++ b/audio/aidl/Android.bp @@ -147,11 +147,19 @@ aidl_interface { name: "android.hardware.audio.effect", vendor_available: true, srcs: [ + "android/hardware/audio/effect/Capability.aidl", + "android/hardware/audio/effect/CommandId.aidl", "android/hardware/audio/effect/Descriptor.aidl", + "android/hardware/audio/effect/Equalizer.aidl", + "android/hardware/audio/effect/Flags.aidl", "android/hardware/audio/effect/IEffect.aidl", "android/hardware/audio/effect/IFactory.aidl", + "android/hardware/audio/effect/Parameter.aidl", + "android/hardware/audio/effect/State.aidl", ], imports: [ + "android.hardware.common-V2", + "android.hardware.common.fmq-V1", "android.hardware.audio.common-V1", "android.media.audio.common.types-V2", ], diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Capability.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Capability.aidl new file mode 100644 index 0000000000..11acf5e9ed --- /dev/null +++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Capability.aidl @@ -0,0 +1,43 @@ +/* + * 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 +union Capability { + android.hardware.audio.effect.Capability.VendorEffectCapability vendor; + android.hardware.audio.effect.Equalizer.Capability equalizer; + @VintfStability + parcelable VendorEffectCapability { + ParcelableHolder extension; + } +} diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/CommandId.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/CommandId.aidl new file mode 100644 index 0000000000..79299eeef5 --- /dev/null +++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/CommandId.aidl @@ -0,0 +1,50 @@ +/* + * 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; +@Backing(type="int") @VintfStability +enum CommandId { + START = 0, + STOP = 1, + RESET = 2, + VENDOR_COMMAND_0 = 256, + VENDOR_COMMAND_1 = 257, + VENDOR_COMMAND_2 = 258, + VENDOR_COMMAND_3 = 259, + VENDOR_COMMAND_4 = 260, + VENDOR_COMMAND_5 = 261, + VENDOR_COMMAND_6 = 262, + VENDOR_COMMAND_7 = 263, + VENDOR_COMMAND_8 = 264, + VENDOR_COMMAND_9 = 265, +} diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Descriptor.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Descriptor.aidl index 94cacd9da6..1c86cf3f3a 100644 --- a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Descriptor.aidl +++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Descriptor.aidl @@ -35,6 +35,7 @@ package android.hardware.audio.effect; @VintfStability parcelable Descriptor { android.hardware.audio.effect.Descriptor.Common common; + android.hardware.audio.effect.Capability capability; const String EFFECT_TYPE_UUID_ENV_REVERB = "c2e5d5f0-94bd-4763-9cac-4e234d06839e"; const String EFFECT_TYPE_UUID_PRESET_REVERB = "47382d60-ddd8-11db-bf3a-0002a5d5c51b"; const String EFFECT_TYPE_UUID_EQUALIZER = "0bed4300-ddd6-11db-8f34-0002a5d5c51b"; @@ -56,5 +57,6 @@ parcelable Descriptor { @VintfStability parcelable Common { android.hardware.audio.effect.Descriptor.Identity id; + android.hardware.audio.effect.Flags flags; } } diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Equalizer.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Equalizer.aidl new file mode 100644 index 0000000000..31732d3663 --- /dev/null +++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Equalizer.aidl @@ -0,0 +1,46 @@ +/* + * 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 +union Equalizer { + android.hardware.audio.effect.Equalizer.VendorExtension vendor; + @VintfStability + parcelable Capability { + ParcelableHolder extension; + } + @VintfStability + parcelable VendorExtension { + ParcelableHolder extension; + } +} diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Flags.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Flags.aidl new file mode 100644 index 0000000000..af774e8d7d --- /dev/null +++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Flags.aidl @@ -0,0 +1,37 @@ +/* + * 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 +parcelable Flags { +} 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 index 7f868ad36d..e5c96f5164 100644 --- 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 @@ -34,7 +34,23 @@ package android.hardware.audio.effect; @VintfStability interface IEffect { - void open(); + android.hardware.audio.effect.IEffect.OpenEffectReturn open(in android.hardware.audio.effect.Parameter.Common common, in android.hardware.audio.effect.Parameter.Specific specific); void close(); android.hardware.audio.effect.Descriptor getDescriptor(); + void command(in android.hardware.audio.effect.CommandId commandId); + android.hardware.audio.effect.State getState(); + void setParameter(in android.hardware.audio.effect.Parameter param); + android.hardware.audio.effect.Parameter getParameter(in android.hardware.audio.effect.Parameter.Id paramId); + @FixedSize @VintfStability + parcelable Status { + int status; + int fmqByteConsumed; + int fmqByteProduced; + } + @VintfStability + parcelable OpenEffectReturn { + android.hardware.common.fmq.MQDescriptor statusMQ; + android.hardware.common.fmq.MQDescriptor inputDataMQ; + android.hardware.common.fmq.MQDescriptor outputDataMQ; + } } diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Parameter.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Parameter.aidl new file mode 100644 index 0000000000..16bd3bbd33 --- /dev/null +++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Parameter.aidl @@ -0,0 +1,62 @@ +/* + * 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 +union Parameter { + android.hardware.audio.effect.Parameter.Common common; + android.hardware.audio.effect.Parameter.VendorEffectParameter vendorEffect; + android.hardware.audio.effect.Parameter.Specific specific; + @VintfStability + union Id { + int commonTag; + int vendorTag; + android.hardware.audio.effect.Parameter.Specific.Tag specificTag; + } + @VintfStability + parcelable Common { + int session; + int ioHandle; + android.media.audio.common.AudioDeviceDescription device; + android.media.audio.common.AudioConfig input; + android.media.audio.common.AudioConfig output; + } + @VintfStability + parcelable VendorEffectParameter { + ParcelableHolder extension; + } + @VintfStability + union Specific { + android.hardware.audio.effect.Equalizer equalizer; + } +} diff --git a/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/State.aidl b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/State.aidl new file mode 100644 index 0000000000..3176b0103a --- /dev/null +++ b/audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/State.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; +@Backing(type="byte") @VintfStability +enum State { + INIT = 0, + IDLE = 1, + PROCESSING = 2, +} diff --git a/audio/aidl/android/hardware/audio/effect/Capability.aidl b/audio/aidl/android/hardware/audio/effect/Capability.aidl new file mode 100644 index 0000000000..e792f8652e --- /dev/null +++ b/audio/aidl/android/hardware/audio/effect/Capability.aidl @@ -0,0 +1,46 @@ +/* + * 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.Equalizer; + +/** + * Effect capability definitions. + * This data structure is used as part of effect Descriptor to identify effect capabilities which + * not meant to change at runtime. + */ +@VintfStability +union Capability { + /** + * Vendor defined effect capability. + * This extension can be used when vendor have a new effect implementated and need + * capability definition for this new type of effect. + * If vendor want to extend existing effect capabilities, it is recommended to expose though + * the ParcelableHolder in each effect capability definition. For example: + * Equalizer.Capability.extension. + */ + @VintfStability + parcelable VendorEffectCapability { + ParcelableHolder extension; + } + VendorEffectCapability vendor; + + /** + * Equalizer capability definition. + */ + Equalizer.Capability equalizer; +} diff --git a/audio/aidl/android/hardware/audio/effect/CommandId.aidl b/audio/aidl/android/hardware/audio/effect/CommandId.aidl new file mode 100644 index 0000000000..208c1637b4 --- /dev/null +++ b/audio/aidl/android/hardware/audio/effect/CommandId.aidl @@ -0,0 +1,70 @@ +/* + * 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; + +/** + * Defines all commands supported by the effect instance. + * + * There are three groups of commands: + * 1. Common part which MUST be supported by all effects. + * 2. Commands MUST be supported by a specific type of effect. + * 3. Extension commands for vendor. + */ +@VintfStability +@Backing(type="int") +enum CommandId { + /// MUST be supported by all effects + /** + * Start effect engine processing. + * An effect instance must start processing data and transfer to PROCESSING state if it is in + * IDLE state and have all necessary information. Otherwise it must: + * 1. Throw a EX_ILLEGAL_STATE exception if effect is not in IDLE state, or + * 2. Throw a EX_TRANSACTION_FAILED for all other errors. + * + * Depending on parameters set to the effect instance, effect may do process or reverse + * process after START command. + */ + START = 0, + /** + * Stop effect engine processing with all resource kept. + * The currently processed audio data will be discarded if the effect engine is in PROCESSING + * state. + * Effect instance must do nothing and return ok when it receive STOP command in IDLE state. + */ + STOP = 1, + /** + * Keep all parameter settings but reset the buffer content, stop engine processing, and transit + * instance state to IDLE if its in PROCESSING state. + * Effect instance must be able to handle RESET command at IDLE and PROCESSING states. + */ + RESET = 2, + + /// MUST be supported by a specific type of effect. + // Commands must supported by Equalizer. + + /// Extension commands for vendor. + VENDOR_COMMAND_0 = 0x100, + VENDOR_COMMAND_1, + VENDOR_COMMAND_2, + VENDOR_COMMAND_3, + VENDOR_COMMAND_4, + VENDOR_COMMAND_5, + VENDOR_COMMAND_6, + VENDOR_COMMAND_7, + VENDOR_COMMAND_8, + VENDOR_COMMAND_9, +} diff --git a/audio/aidl/android/hardware/audio/effect/Descriptor.aidl b/audio/aidl/android/hardware/audio/effect/Descriptor.aidl index 51b31c2371..aca9bbe326 100644 --- a/audio/aidl/android/hardware/audio/effect/Descriptor.aidl +++ b/audio/aidl/android/hardware/audio/effect/Descriptor.aidl @@ -16,12 +16,13 @@ package android.hardware.audio.effect; +import android.hardware.audio.effect.Capability; +import android.hardware.audio.effect.Flags; import android.media.audio.common.AudioUuid; /** - * Effect descriptor contains all information (capabilities, attributes, and ownership) for an - * effect implemented in the Audio Effect HAL. Framework uses this information to decide when and - * how to apply the effect. + * Descriptor contains all information (capabilities, attributes, etc) for an effect implementation. + * The client uses this information to decide when and how to apply an effect implementation. */ @VintfStability parcelable Descriptor { @@ -77,6 +78,15 @@ parcelable Descriptor { * Identity of effect implementation. */ Identity id; + /** + * Effect engine defined capabilities/requirements flags. + */ + Flags flags; } Common common; + + /** + * Effect implementation capability. + */ + Capability capability; } diff --git a/audio/aidl/android/hardware/audio/effect/Equalizer.aidl b/audio/aidl/android/hardware/audio/effect/Equalizer.aidl new file mode 100644 index 0000000000..309874d183 --- /dev/null +++ b/audio/aidl/android/hardware/audio/effect/Equalizer.aidl @@ -0,0 +1,47 @@ +/* + * 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.media.audio.common.AudioProfile; + +/** + * Equalizer specific definitions. + */ +@VintfStability +union Equalizer { + /** + * Defines Equalizer implementation capabilities, it MUST be supported by all equalizer + * implementations. + * + * Equalizer.Capability definition is used by android.hardware.audio.effect.Capability. + */ + @VintfStability + parcelable Capability { + /** + * Equalizer capability extension, vendor can use this extension in case existing capability + * definition not enough. + */ + ParcelableHolder extension; + } + + // Vendor Equalizer implementation definition for additional parameters. + @VintfStability + parcelable VendorExtension { + ParcelableHolder extension; + } + VendorExtension vendor; +} diff --git a/audio/aidl/android/hardware/audio/effect/Flags.aidl b/audio/aidl/android/hardware/audio/effect/Flags.aidl new file mode 100644 index 0000000000..8add975752 --- /dev/null +++ b/audio/aidl/android/hardware/audio/effect/Flags.aidl @@ -0,0 +1,26 @@ +/* + * 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; + +/** + * The common part of available capability/configuration for effects. For effect type specific + * capability, see @c android.hardware.audio.effect.Capability. + */ +@VintfStability +parcelable Flags { + // TODO: add Effect engine defined capabilities/requirements flags. +} diff --git a/audio/aidl/android/hardware/audio/effect/IEffect.aidl b/audio/aidl/android/hardware/audio/effect/IEffect.aidl index d7a9501569..9ab8b02249 100644 --- a/audio/aidl/android/hardware/audio/effect/IEffect.aidl +++ b/audio/aidl/android/hardware/audio/effect/IEffect.aidl @@ -16,24 +16,68 @@ package android.hardware.audio.effect; +import android.hardware.audio.effect.CommandId; import android.hardware.audio.effect.Descriptor; +import android.hardware.audio.effect.Parameter; +import android.hardware.audio.effect.State; +import android.hardware.common.fmq.MQDescriptor; +import android.hardware.common.fmq.SynchronizedReadWrite; /** * Effect interfaces definitions to configure and control the effect instance. */ @VintfStability interface IEffect { + @VintfStability + @FixedSize + parcelable Status { + /** + * One of Binder STATUS_* statuses: + * - STATUS_OK: the command has completed successfully; + * - STATUS_BAD_VALUE: invalid value in the 'Command' structure; + * - STATUS_INVALID_OPERATION: the mix port is not connected + * to any producer or consumer, thus + * positions can not be reported; + * - STATUS_NOT_ENOUGH_DATA: a read or write error has + * occurred for the 'audio.fmq' queue; + * + */ + int status; + /** + * The amount of bytes consumed by the effect instance. + */ + int fmqByteConsumed; + /** + * The amount of bytes produced by the effect instance. + */ + int fmqByteProduced; + } + + // Return data structure of IEffect.open() interface. + @VintfStability + parcelable OpenEffectReturn { + // Message queue for effect processing status. + MQDescriptor statusMQ; + // Message queue for input data buffer. + MQDescriptor inputDataMQ; + // Message queue for output data buffer. + MQDescriptor outputDataMQ; + } + /** - * 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. + * Open an effect instance, effect must not start processing data before receive + * CommandId::START command. All necessary information should be allocated and instance must + * transfer to State::IDLE state after open() call has been handled successfully. After open, + * the effect instance must be able to handle all IEffect interface calls. * + * @param common Parameters which MUST pass from client at open time. + * + * @throws EX_ILLEGAL_ARGUMENT if the effect instance receive unsupported command. * @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 should not throw an error. */ - void open(); + OpenEffectReturn open(in Parameter.Common common, in Parameter.Specific specific); /** * Called by the client to close the effect instance, processing thread should be destroyed and @@ -45,7 +89,7 @@ interface IEffect { * * Effect instance close interface should always succeed unless: * 1. The effect instance is not in a proper state to be closed, for example it's still in - * processing state. + * State::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. @@ -62,4 +106,53 @@ interface IEffect { * @return Descriptor The @c Descriptor of this effect instance. */ Descriptor getDescriptor(); + + /** + * Send a command (defined in enum CommandId) to the effect instance, instance state can be + * changed as result of command handling. + * + * Must be available for the effect instance after it has been open(). + * + * @param commandId ID of the command send to the effect instance. + * + * @throws EX_ILLEGAL_STATE if the effect instance is not in a proper state to handle the + * command. + * @throws EX_ILLEGAL_ARGUMENT if the effect instance receive unsupported command. + */ + void command(in CommandId commandId); + + /** + * Get current state of the effect instance. + * + * Must be available for the effect instance at anytime and should always succeed. + * + * @return Current effect instance state. + */ + State getState(); + + /** + * Set a parameter to the effect instance. + * + * Must be available for the effect instance after open(). + * + * @param param Parameter data to set to the effect instance. + * + * @throws EX_ILLEGAL_ARGUMENT if the effect instance receive unsupported parameter. + */ + void setParameter(in Parameter param); + + /** + * Get a parameter from the effect instance with parameter ID. + * + * This interface must return the current parameter of the effect instance, if no parameter + * has been set by client yet, the default value must be returned. + * + * Must be available for the effect instance after open(). + * + * @param paramId The tag enum of parameter to get. + * @return Parameter The parameter to get from the effect instance. + * + * @throws EX_ILLEGAL_ARGUMENT if the effect instance receive unsupported parameter tag. + */ + Parameter getParameter(in Parameter.Id paramId); } diff --git a/audio/aidl/android/hardware/audio/effect/Parameter.aidl b/audio/aidl/android/hardware/audio/effect/Parameter.aidl new file mode 100644 index 0000000000..2951660b6e --- /dev/null +++ b/audio/aidl/android/hardware/audio/effect/Parameter.aidl @@ -0,0 +1,87 @@ +/* + * 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.Equalizer; +import android.media.audio.common.AudioConfig; +import android.media.audio.common.AudioDeviceDescription; +/** + * Defines all parameters supported by the effect instance. + * + * There are three groups of parameters: + * 1. Common parameters are essential parameters, MUST pass to effects at open() interface. + * 2. Parameters defined for a specific effect type. + * 3. Extension parameters for vendor. + * + * For all supported parameter, implementation MUST support both set and get. + */ +@VintfStability +union Parameter { + /** + * Client can pass in Parameter.Id with the corresponding tag value in IEffect.getParameter() + * call to get android.hardware.audio.effect.Parameter. + * + * As an example, if a client want to get audio.hardware.audio.effect.Specific.Equalizer, the + * value of Id should be audio.hardware.audio.effect.Parameter.Specific.equalizer. + */ + @VintfStability + union Id { + // Common parameter tag. + int commonTag; + // Vendor defined parameter tag. + int vendorTag; + // Specific effect parameter tag. + Specific.Tag specificTag; + } + + /** + * Common parameters MUST be supported by all effect implementations. + */ + @VintfStability + parcelable Common { + // Type of Audio device. + int session; + // I/O Handle. + int ioHandle; + // Type of Audio device. + AudioDeviceDescription device; + // Input config. + AudioConfig input; + // Output config. + AudioConfig output; + } + Common common; + + /** + * Parameters for vendor extension effect implementation usage. + */ + @VintfStability + parcelable VendorEffectParameter { + ParcelableHolder extension; + } + VendorEffectParameter vendorEffect; + + /** + * Parameters MUST be supported by a Specific type of effect. + */ + @VintfStability + union Specific { + Equalizer equalizer; + // TODO: add other effect definitions here + } + Specific specific; +} diff --git a/audio/aidl/android/hardware/audio/effect/State.aidl b/audio/aidl/android/hardware/audio/effect/State.aidl new file mode 100644 index 0000000000..85a4afc085 --- /dev/null +++ b/audio/aidl/android/hardware/audio/effect/State.aidl @@ -0,0 +1,86 @@ +/* + * 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; + +/** + * Possible states of an effect instance. + * A typical effect instance will be in INIT state when it is created with IFactory.createEffect() + * interface, transfer to IDLE after open(), and to PROCESSING after + * IEffect.command(Command.Id.START) command. When an effect instance receive STOP or RESET command, + * it should transfer to IDLE state after handle the command successfully. Effect instance should + * consume minimal resource and transfer to INIT state after it was close(). + * + * Refer to State.gv for detailed state diagram. + */ +@VintfStability +@Backing(type="byte") +enum State { + + /** + * An effect instance is in INIT state by default after it was created with + * IFactory.createEffect(). When an effect instance is in INIT state, it should have instance + * context initialized, and ready to handle IEffect.setParameter(), IEffect.open() as well as + * all getter interfaces. + * + * In INIT state, effect instance must: + * 1. Not handle any IEffect.command() and return EX_ILLEGAL_STATE with any Command.Id. + * 2. Be able to handle all parameter setting with IEffect.setParameter(). + * 3. Be able to handle all getter interface calls like IEffect.getParameter() and + * IEffect.getState(). + * 4. Be able to handle IEffect.open() successfully after configuration. + * + * Client is expected to do necessary configuration with IEffect.setParameter(), get all + * resource ready with IEffect.open(), and make sure effect instance transfer to IDLE state + * before sending commands with IEffect.command() interface. Effect instance must transfer + * from INIT to IDLE state after handle IEffect.open() call successfully. + */ + INIT, + /** + * An effect instance transfer to IDLE state after it was open successfully with IEffect.open() + * in INIT state, or after it was stop/reset with Command.Id.STOP/RESET in PROCESSING state. + * + * In IDLE state, effect instance must: + * 1. Be able to start effect processing engine with IEffect.command(Command.Id.START) call. + * 2. Be able to handle all parameter setting with IEffect.setParameter(). + * 3. Be able to handle all getter interface calls like IEffect.getParameter() and + * IEffect.getState(). + * + * The following state transfer can happen in IDLE state: + * 1. Transfer to PROCESSING if instance receive an START command and start processing data + * successfully. + * 2. Transfer to INIT if instance receive a close() call. + */ + IDLE, + /** + * An effect instance is in PROCESSING state after it receive an START command and start + * processing data successfully. Effect instance will transfer from PROCESSING to IDLE state if + * it receive an STOP or RESET command and handle the command successfully. + * + * When an instance is in PROCESSING state, client should try not to close() it directly, + * instead client should try to stop processing data first with STOP command before close(). In + * the case of a close() call received when instance in PROCESSING state, it should try to stop + * processing and transfer to IDLE first before close(). + * + * In PROCESSING state, effect instance must: + * 1. Return EX_ILLEGAL_STATE if it's not able to handle any parameter settings at runtime. + * 2. Be able to handle STOP and RESET for IEffect.command() interface, and return + * EX_ILLEGAL_STATE for all other commands. + * 3. Must be able to handle all get* interface calls like IEffect.getParameter() and + * IEffect.getState(). + */ + PROCESSING, +} diff --git a/audio/aidl/android/hardware/audio/effect/state.gv b/audio/aidl/android/hardware/audio/effect/state.gv new file mode 100644 index 0000000000..e19e6c7a1d --- /dev/null +++ b/audio/aidl/android/hardware/audio/effect/state.gv @@ -0,0 +1,36 @@ +/* + * 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. + */ + +// To render: "dot -Tpng state.gv -o state.png" +digraph effect_state_machine { + node [shape=point style=filled fillcolor=black width=0.5] I; + node [shape=doublecircle] F; + node [shape=oval width=1]; + node [fillcolor=lightgreen] INIT; + node [fillcolor=lightblue] IDLE; + node [fillcolor=lightyellow] PROCESSING; + + I -> INIT [label="IFactory.createEffect" labelfontcolor="navy"]; + INIT -> F [label="IFactory.destroyEffect"]; + INIT -> IDLE [label="open()" labelfontcolor="lime"]; + IDLE -> PROCESSING [label="command(START"]; + PROCESSING -> IDLE [label="command(STOP)\ncommand(RESET)"]; + IDLE -> INIT [label="close()"]; + + INIT -> INIT [label="getState\ngetDescriptor"]; + IDLE -> IDLE [label="getXXX\nsetParameter\ncommand(RESET)"]; + PROCESSING -> PROCESSING [label="getXXX\nsetParameter"]; +} \ No newline at end of file