1 /* 2 * Copyright (C) 2018 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.hardware.audio.effect@4.0; 18 19 import android.hardware.audio.common@4.0; 20 21 enum Result : int32_t { 22 OK, 23 NOT_INITIALIZED, 24 INVALID_ARGUMENTS, 25 INVALID_STATE, 26 NOT_SUPPORTED, 27 RESULT_TOO_BIG 28 }; 29 30 /** 31 * Effect engine capabilities/requirements flags. 32 * 33 * Definitions for flags field of effect descriptor. 34 * 35 * +----------------+--------+-------------------------------------------------- 36 * | description | bits | values 37 * +----------------+--------+-------------------------------------------------- 38 * | connection | 0..2 | 0 insert: after track process 39 * | mode | | 1 auxiliary: connect to track auxiliary 40 * | | | output and use send level 41 * | | | 2 replace: replaces track process function; 42 * | | | must implement SRC, volume and mono to stereo. 43 * | | | 3 pre processing: applied below audio HAL on in 44 * | | | 4 post processing: applied below audio HAL on out 45 * | | | 5 - 7 reserved 46 * +----------------+--------+-------------------------------------------------- 47 * | insertion | 3..5 | 0 none 48 * | preference | | 1 first of the chain 49 * | | | 2 last of the chain 50 * | | | 3 exclusive (only effect in the insert chain) 51 * | | | 4..7 reserved 52 * +----------------+--------+-------------------------------------------------- 53 * | Volume | 6..8 | 0 none 54 * | management | | 1 implements volume control 55 * | | | 2 requires volume indication 56 * | | | 4 reserved 57 * +----------------+--------+-------------------------------------------------- 58 * | Device | 9..11 | 0 none 59 * | indication | | 1 requires device updates 60 * | | | 2, 4 reserved 61 * +----------------+--------+-------------------------------------------------- 62 * | Sample input | 12..13 | 1 direct: process() function or 63 * | mode | | EFFECT_CMD_SET_CONFIG command must specify 64 * | | | a buffer descriptor 65 * | | | 2 provider: process() function uses the 66 * | | | bufferProvider indicated by the 67 * | | | EFFECT_CMD_SET_CONFIG command to request input. 68 * | | | buffers. 69 * | | | 3 both: both input modes are supported 70 * +----------------+--------+-------------------------------------------------- 71 * | Sample output | 14..15 | 1 direct: process() function or 72 * | mode | | EFFECT_CMD_SET_CONFIG command must specify 73 * | | | a buffer descriptor 74 * | | | 2 provider: process() function uses the 75 * | | | bufferProvider indicated by the 76 * | | | EFFECT_CMD_SET_CONFIG command to request output 77 * | | | buffers. 78 * | | | 3 both: both output modes are supported 79 * +----------------+--------+-------------------------------------------------- 80 * | Hardware | 16..17 | 0 No hardware acceleration 81 * | acceleration | | 1 non tunneled hw acceleration: the process() 82 * | | | function reads the samples, send them to HW 83 * | | | accelerated effect processor, reads back 84 * | | | the processed samples and returns them 85 * | | | to the output buffer. 86 * | | | 2 tunneled hw acceleration: the process() 87 * | | | function is transparent. The effect interface 88 * | | | is only used to control the effect engine. 89 * | | | This mode is relevant for global effects 90 * | | | actually applied by the audio hardware on 91 * | | | the output stream. 92 * +----------------+--------+-------------------------------------------------- 93 * | Audio Mode | 18..19 | 0 none 94 * | indication | | 1 requires audio mode updates 95 * | | | 2..3 reserved 96 * +----------------+--------+-------------------------------------------------- 97 * | Audio source | 20..21 | 0 none 98 * | indication | | 1 requires audio source updates 99 * | | | 2..3 reserved 100 * +----------------+--------+-------------------------------------------------- 101 * | Effect offload | 22 | 0 The effect cannot be offloaded to an audio DSP 102 * | supported | | 1 The effect can be offloaded to an audio DSP 103 * +----------------+--------+-------------------------------------------------- 104 * | Process | 23 | 0 The effect implements a process function. 105 * | function | | 1 The effect does not implement a process 106 * | not | | function: enabling the effect has no impact 107 * | implemented | | on latency or CPU load. 108 * | | | Effect implementations setting this flag do not 109 * | | | have to implement a process function. 110 * +----------------+--------+-------------------------------------------------- 111 */ 112 @export(name="", value_prefix="EFFECT_FLAG_") 113 enum EffectFlags : int32_t { 114 // Insert mode 115 TYPE_SHIFT = 0, 116 TYPE_SIZE = 3, 117 TYPE_MASK = ((1 << TYPE_SIZE) -1) << TYPE_SHIFT, 118 TYPE_INSERT = 0 << TYPE_SHIFT, 119 TYPE_AUXILIARY = 1 << TYPE_SHIFT, 120 TYPE_REPLACE = 2 << TYPE_SHIFT, 121 TYPE_PRE_PROC = 3 << TYPE_SHIFT, 122 TYPE_POST_PROC = 4 << TYPE_SHIFT, 123 124 // Insert preference 125 INSERT_SHIFT = TYPE_SHIFT + TYPE_SIZE, 126 INSERT_SIZE = 3, 127 INSERT_MASK = ((1 << INSERT_SIZE) -1) << INSERT_SHIFT, 128 INSERT_ANY = 0 << INSERT_SHIFT, 129 INSERT_FIRST = 1 << INSERT_SHIFT, 130 INSERT_LAST = 2 << INSERT_SHIFT, 131 INSERT_EXCLUSIVE = 3 << INSERT_SHIFT, 132 133 // Volume control 134 VOLUME_SHIFT = INSERT_SHIFT + INSERT_SIZE, 135 VOLUME_SIZE = 3, 136 VOLUME_MASK = ((1 << VOLUME_SIZE) -1) << VOLUME_SHIFT, 137 VOLUME_CTRL = 1 << VOLUME_SHIFT, 138 VOLUME_IND = 2 << VOLUME_SHIFT, 139 VOLUME_NONE = 0 << VOLUME_SHIFT, 140 141 // Device indication 142 DEVICE_SHIFT = VOLUME_SHIFT + VOLUME_SIZE, 143 DEVICE_SIZE = 3, 144 DEVICE_MASK = ((1 << DEVICE_SIZE) -1) << DEVICE_SHIFT, 145 DEVICE_IND = 1 << DEVICE_SHIFT, 146 DEVICE_NONE = 0 << DEVICE_SHIFT, 147 148 // Sample input modes 149 INPUT_SHIFT = DEVICE_SHIFT + DEVICE_SIZE, 150 INPUT_SIZE = 2, 151 INPUT_MASK = ((1 << INPUT_SIZE) -1) << INPUT_SHIFT, 152 INPUT_DIRECT = 1 << INPUT_SHIFT, 153 INPUT_PROVIDER = 2 << INPUT_SHIFT, 154 INPUT_BOTH = 3 << INPUT_SHIFT, 155 156 // Sample output modes 157 OUTPUT_SHIFT = INPUT_SHIFT + INPUT_SIZE, 158 OUTPUT_SIZE = 2, 159 OUTPUT_MASK = ((1 << OUTPUT_SIZE) -1) << OUTPUT_SHIFT, 160 OUTPUT_DIRECT = 1 << OUTPUT_SHIFT, 161 OUTPUT_PROVIDER = 2 << OUTPUT_SHIFT, 162 OUTPUT_BOTH = 3 << OUTPUT_SHIFT, 163 164 // Hardware acceleration mode 165 HW_ACC_SHIFT = OUTPUT_SHIFT + OUTPUT_SIZE, 166 HW_ACC_SIZE = 2, 167 HW_ACC_MASK = ((1 << HW_ACC_SIZE) -1) << HW_ACC_SHIFT, 168 HW_ACC_SIMPLE = 1 << HW_ACC_SHIFT, 169 HW_ACC_TUNNEL = 2 << HW_ACC_SHIFT, 170 171 // Audio mode indication 172 AUDIO_MODE_SHIFT = HW_ACC_SHIFT + HW_ACC_SIZE, 173 AUDIO_MODE_SIZE = 2, 174 AUDIO_MODE_MASK = ((1 << AUDIO_MODE_SIZE) -1) << AUDIO_MODE_SHIFT, 175 AUDIO_MODE_IND = 1 << AUDIO_MODE_SHIFT, 176 AUDIO_MODE_NONE = 0 << AUDIO_MODE_SHIFT, 177 178 // Audio source indication 179 AUDIO_SOURCE_SHIFT = AUDIO_MODE_SHIFT + AUDIO_MODE_SIZE, 180 AUDIO_SOURCE_SIZE = 2, 181 AUDIO_SOURCE_MASK = ((1 << AUDIO_SOURCE_SIZE) -1) << AUDIO_SOURCE_SHIFT, 182 AUDIO_SOURCE_IND = 1 << AUDIO_SOURCE_SHIFT, 183 AUDIO_SOURCE_NONE = 0 << AUDIO_SOURCE_SHIFT, 184 185 // Effect offload indication 186 OFFLOAD_SHIFT = AUDIO_SOURCE_SHIFT + AUDIO_SOURCE_SIZE, 187 OFFLOAD_SIZE = 1, 188 OFFLOAD_MASK = ((1 << OFFLOAD_SIZE) -1) << OFFLOAD_SHIFT, 189 OFFLOAD_SUPPORTED = 1 << OFFLOAD_SHIFT, 190 191 // Effect has no process indication 192 NO_PROCESS_SHIFT = OFFLOAD_SHIFT + OFFLOAD_SIZE, 193 NO_PROCESS_SIZE = 1, 194 NO_PROCESS_MASK = ((1 << NO_PROCESS_SIZE) -1) << NO_PROCESS_SHIFT, 195 NO_PROCESS = 1 << NO_PROCESS_SHIFT 196 }; 197 198 /** 199 * The effect descriptor contains necessary information to facilitate the 200 * enumeration of the effect engines present in a library. 201 */ 202 struct EffectDescriptor { 203 Uuid type; // UUID of to the OpenSL ES interface implemented 204 // by this effect 205 Uuid uuid; // UUID for this particular implementation 206 bitfield<EffectFlags> flags; // effect engine capabilities/requirements flags 207 uint16_t cpuLoad; // CPU load indication expressed in 0.1 MIPS units 208 // as estimated on an ARM9E core (ARMv5TE) with 0 WS 209 uint16_t memoryUsage; // data memory usage expressed in KB and includes 210 // only dynamically allocated memory 211 uint8_t[64] name; // human readable effect name 212 uint8_t[64] implementor; // human readable effect implementor name 213 }; 214 215 /** 216 * A buffer is a chunk of audio data for processing. Multi-channel audio is 217 * always interleaved. The channel order is from LSB to MSB with regard to the 218 * channel mask definition in audio.h, audio_channel_mask_t, e.g.: 219 * Stereo: L, R; 5.1: FL, FR, FC, LFE, BL, BR. 220 * 221 * The buffer size is expressed in frame count, a frame being composed of 222 * samples for all channels at a given time. Frame size for unspecified format 223 * (AUDIO_FORMAT_OTHER) is 8 bit by definition. 224 */ 225 struct AudioBuffer { 226 uint64_t id; 227 uint32_t frameCount; 228 memory data; 229 }; 230 231 @export(name="effect_buffer_access_e", value_prefix="EFFECT_BUFFER_") 232 enum EffectBufferAccess : int32_t { 233 ACCESS_WRITE, 234 ACCESS_READ, 235 ACCESS_ACCUMULATE 236 }; 237 238 /** 239 * Determines what fields of EffectBufferConfig need to be considered. 240 */ 241 @export(name="", value_prefix="EFFECT_CONFIG_") 242 enum EffectConfigParameters : int32_t { 243 BUFFER = 0x0001, // buffer field 244 SMP_RATE = 0x0002, // samplingRate 245 CHANNELS = 0x0004, // channels 246 FORMAT = 0x0008, // format 247 ACC_MODE = 0x0010, // accessMode 248 // Note that the 2.0 ALL have been moved to an helper function 249 }; 250 251 /** 252 * The buffer config structure specifies the input or output audio format 253 * to be used by the effect engine. 254 */ 255 struct EffectBufferConfig { 256 AudioBuffer buffer; 257 uint32_t samplingRateHz; 258 bitfield<AudioChannelMask> channels; 259 AudioFormat format; 260 EffectBufferAccess accessMode; 261 bitfield<EffectConfigParameters> mask; 262 }; 263 264 struct EffectConfig { 265 EffectBufferConfig inputCfg; 266 EffectBufferConfig outputCfg; 267 }; 268 269 @export(name="effect_feature_e", value_prefix="EFFECT_FEATURE_") 270 enum EffectFeature : int32_t { 271 AUX_CHANNELS, // supports auxiliary channels 272 // (e.g. dual mic noise suppressor) 273 CNT 274 }; 275 276 struct EffectAuxChannelsConfig { 277 bitfield<AudioChannelMask> mainChannels; // channel mask for main channels 278 bitfield<AudioChannelMask> auxChannels; // channel mask for auxiliary channels 279 }; 280 281 struct EffectOffloadParameter { 282 bool isOffload; // true if the playback thread the effect 283 // is attached to is offloaded 284 AudioIoHandle ioHandle; // io handle of the playback thread 285 // the effect is attached to 286 }; 287 288 /** 289 * The message queue flags used to synchronize reads and writes from 290 * the status message queue used by effects. 291 */ 292 enum MessageQueueFlagBits : uint32_t { 293 DONE_PROCESSING = 1 << 0, 294 REQUEST_PROCESS = 1 << 1, 295 REQUEST_PROCESS_REVERSE = 1 << 2, 296 REQUEST_QUIT = 1 << 3, 297 REQUEST_PROCESS_ALL = 298 REQUEST_PROCESS | REQUEST_PROCESS_REVERSE | REQUEST_QUIT 299 }; 300
