tequilaOS/platform_hardware_interfaces
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

AIDL effect: Add effect AIDL definition am: 0632ae6cd1

Browse source 
Original change: https://android-review.googlesource.com/c/platform/hardware/interfaces/+/2242193

Change-Id: I8ae04c451f965a42efca215985cdd7f1e2154187
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>
This commit is contained in:
Shunkai Yao 2022-10-13 02:53:31 +00:00 committed by Automerger Merge Worker
commit 9eaa089d34
18 changed files with 815 additions and 10 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
audio/aidl/Android.bp
View file

@ -148,11 +148,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",
],

43
audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Capability.aidl Normal file
View file

@ -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 <name>-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;
}
}

50
audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/CommandId.aidl Normal file
View file

@ -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 <name>-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,
}

2
audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Descriptor.aidl
View file

@ -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;
}
}

46
audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Equalizer.aidl Normal file
View file

@ -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 <name>-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;
}
}

37
audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Flags.aidl Normal file
View file

@ -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 <name>-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 {
}

18
audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/IEffect.aidl
View file

@ -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<android.hardware.audio.effect.IEffect.Status,android.hardware.common.fmq.SynchronizedReadWrite> statusMQ;
android.hardware.common.fmq.MQDescriptor<byte,android.hardware.common.fmq.SynchronizedReadWrite> inputDataMQ;
android.hardware.common.fmq.MQDescriptor<byte,android.hardware.common.fmq.SynchronizedReadWrite> outputDataMQ;
}
}

62
audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/Parameter.aidl Normal file
View file

@ -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 <name>-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;
}
}

40
audio/aidl/aidl_api/android.hardware.audio.effect/current/android/hardware/audio/effect/State.aidl Normal file
View file

@ -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 <name>-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,
}

46
audio/aidl/android/hardware/audio/effect/Capability.aidl Normal file
View file

@ -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;
}

70
audio/aidl/android/hardware/audio/effect/CommandId.aidl Normal file
View file

@ -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,
}

16
audio/aidl/android/hardware/audio/effect/Descriptor.aidl
View file

@ -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;
}

47
audio/aidl/android/hardware/audio/effect/Equalizer.aidl Normal file
View file

@ -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;
}

26
audio/aidl/android/hardware/audio/effect/Flags.aidl Normal file
View file

@ -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.
}

105
audio/aidl/android/hardware/audio/effect/IEffect.aidl
View file

@ -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<Status, SynchronizedReadWrite> statusMQ;
// Message queue for input data buffer.
MQDescriptor<byte, SynchronizedReadWrite> inputDataMQ;
// Message queue for output data buffer.
MQDescriptor<byte, SynchronizedReadWrite> 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);
}

87
audio/aidl/android/hardware/audio/effect/Parameter.aidl Normal file
View file

@ -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;
}

86
audio/aidl/android/hardware/audio/effect/State.aidl Normal file
View file

@ -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,
}

36
audio/aidl/android/hardware/audio/effect/state.gv Normal file
View file

@ -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"];
}