Kevin Rocard | c6ec948 | 2018-01-24 06:04:27 +0000 | [diff] [blame] | 1 | /* |
| 2 | * Copyright (C) 2011 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 | |
| 18 | #ifndef ANDROID_AUDIO_EFFECT_H |
| 19 | #define ANDROID_AUDIO_EFFECT_H |
| 20 | |
| 21 | #include <errno.h> |
| 22 | #include <stdint.h> |
| 23 | #include <strings.h> |
| 24 | #include <sys/cdefs.h> |
| 25 | #include <sys/types.h> |
| 26 | |
| 27 | #include <cutils/bitops.h> |
| 28 | |
| 29 | #include <system/audio_effect.h> |
| 30 | |
| 31 | |
| 32 | __BEGIN_DECLS |
| 33 | |
| 34 | |
| 35 | ///////////////////////////////////////////////// |
| 36 | // Common Definitions |
| 37 | ///////////////////////////////////////////////// |
| 38 | |
| 39 | #define EFFECT_MAKE_API_VERSION(M, m) (((M)<<16) | ((m) & 0xFFFF)) |
| 40 | #define EFFECT_API_VERSION_MAJOR(v) ((v)>>16) |
| 41 | #define EFFECT_API_VERSION_MINOR(v) ((m) & 0xFFFF) |
| 42 | |
| 43 | |
| 44 | ///////////////////////////////////////////////// |
| 45 | // Effect control interface |
| 46 | ///////////////////////////////////////////////// |
| 47 | |
| 48 | // Effect control interface version 2.0 |
| 49 | #define EFFECT_CONTROL_API_VERSION EFFECT_MAKE_API_VERSION(2,0) |
| 50 | |
| 51 | // Effect control interface structure: effect_interface_s |
| 52 | // The effect control interface is exposed by each effect engine implementation. It consists of |
| 53 | // a set of functions controlling the configuration, activation and process of the engine. |
| 54 | // The functions are grouped in a structure of type effect_interface_s. |
| 55 | // |
| 56 | // Effect control interface handle: effect_handle_t |
| 57 | // The effect_handle_t serves two purposes regarding the implementation of the effect engine: |
| 58 | // - 1 it is the address of a pointer to an effect_interface_s structure where the functions |
| 59 | // of the effect control API for a particular effect are located. |
| 60 | // - 2 it is the address of the context of a particular effect instance. |
| 61 | // A typical implementation in the effect library would define a structure as follows: |
| 62 | // struct effect_module_s { |
| 63 | // const struct effect_interface_s *itfe; |
| 64 | // effect_config_t config; |
| 65 | // effect_context_t context; |
| 66 | // } |
| 67 | // The implementation of EffectCreate() function would then allocate a structure of this |
| 68 | // type and return its address as effect_handle_t |
| 69 | typedef struct effect_interface_s **effect_handle_t; |
| 70 | |
| 71 | // Effect control interface definition |
| 72 | struct effect_interface_s { |
| 73 | //////////////////////////////////////////////////////////////////////////////// |
| 74 | // |
| 75 | // Function: process |
| 76 | // |
| 77 | // Description: Effect process function. Takes input samples as specified |
| 78 | // (count and location) in input buffer descriptor and output processed |
| 79 | // samples as specified in output buffer descriptor. If the buffer descriptor |
| 80 | // is not specified the function must use either the buffer or the |
| 81 | // buffer provider function installed by the EFFECT_CMD_SET_CONFIG command. |
| 82 | // The effect framework will call the process() function after the EFFECT_CMD_ENABLE |
| 83 | // command is received and until the EFFECT_CMD_DISABLE is received. When the engine |
| 84 | // receives the EFFECT_CMD_DISABLE command it should turn off the effect gracefully |
| 85 | // and when done indicate that it is OK to stop calling the process() function by |
| 86 | // returning the -ENODATA status. |
| 87 | // |
| 88 | // NOTE: the process() function implementation should be "real-time safe" that is |
| 89 | // it should not perform blocking calls: malloc/free, sleep, read/write/open/close, |
| 90 | // pthread_cond_wait/pthread_mutex_lock... |
| 91 | // |
| 92 | // Input: |
| 93 | // self: handle to the effect interface this function |
| 94 | // is called on. |
| 95 | // inBuffer: buffer descriptor indicating where to read samples to process. |
| 96 | // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG command. |
| 97 | // |
| 98 | // outBuffer: buffer descriptor indicating where to write processed samples. |
| 99 | // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG command. |
| 100 | // |
| 101 | // Output: |
| 102 | // returned value: 0 successful operation |
| 103 | // -ENODATA the engine has finished the disable phase and the framework |
| 104 | // can stop calling process() |
| 105 | // -EINVAL invalid interface handle or |
| 106 | // invalid input/output buffer description |
| 107 | //////////////////////////////////////////////////////////////////////////////// |
| 108 | int32_t (*process)(effect_handle_t self, |
| 109 | audio_buffer_t *inBuffer, |
| 110 | audio_buffer_t *outBuffer); |
| 111 | //////////////////////////////////////////////////////////////////////////////// |
| 112 | // |
| 113 | // Function: command |
| 114 | // |
| 115 | // Description: Send a command and receive a response to/from effect engine. |
| 116 | // |
| 117 | // Input: |
| 118 | // self: handle to the effect interface this function |
| 119 | // is called on. |
| 120 | // cmdCode: command code: the command can be a standardized command defined in |
| 121 | // effect_command_e (see below) or a proprietary command. |
| 122 | // cmdSize: size of command in bytes |
| 123 | // pCmdData: pointer to command data |
| 124 | // pReplyData: pointer to reply data |
| 125 | // |
| 126 | // Input/Output: |
| 127 | // replySize: maximum size of reply data as input |
| 128 | // actual size of reply data as output |
| 129 | // |
| 130 | // Output: |
| 131 | // returned value: 0 successful operation |
| 132 | // -EINVAL invalid interface handle or |
| 133 | // invalid command/reply size or format according to |
| 134 | // command code |
| 135 | // The return code should be restricted to indicate problems related to this API |
| 136 | // specification. Status related to the execution of a particular command should be |
| 137 | // indicated as part of the reply field. |
| 138 | // |
| 139 | // *pReplyData updated with command response |
| 140 | // |
| 141 | //////////////////////////////////////////////////////////////////////////////// |
| 142 | int32_t (*command)(effect_handle_t self, |
| 143 | uint32_t cmdCode, |
| 144 | uint32_t cmdSize, |
| 145 | void *pCmdData, |
| 146 | uint32_t *replySize, |
| 147 | void *pReplyData); |
| 148 | //////////////////////////////////////////////////////////////////////////////// |
| 149 | // |
| 150 | // Function: get_descriptor |
| 151 | // |
| 152 | // Description: Returns the effect descriptor |
| 153 | // |
| 154 | // Input: |
| 155 | // self: handle to the effect interface this function |
| 156 | // is called on. |
| 157 | // |
| 158 | // Input/Output: |
| 159 | // pDescriptor: address where to return the effect descriptor. |
| 160 | // |
| 161 | // Output: |
| 162 | // returned value: 0 successful operation. |
| 163 | // -EINVAL invalid interface handle or invalid pDescriptor |
| 164 | // *pDescriptor: updated with the effect descriptor. |
| 165 | // |
| 166 | //////////////////////////////////////////////////////////////////////////////// |
| 167 | int32_t (*get_descriptor)(effect_handle_t self, |
| 168 | effect_descriptor_t *pDescriptor); |
| 169 | //////////////////////////////////////////////////////////////////////////////// |
| 170 | // |
| 171 | // Function: process_reverse |
| 172 | // |
| 173 | // Description: Process reverse stream function. This function is used to pass |
| 174 | // a reference stream to the effect engine. If the engine does not need a reference |
| 175 | // stream, this function pointer can be set to NULL. |
| 176 | // This function would typically implemented by an Echo Canceler. |
| 177 | // |
| 178 | // Input: |
| 179 | // self: handle to the effect interface this function |
| 180 | // is called on. |
| 181 | // inBuffer: buffer descriptor indicating where to read samples to process. |
| 182 | // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG_REVERSE command. |
| 183 | // |
| 184 | // outBuffer: buffer descriptor indicating where to write processed samples. |
| 185 | // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG_REVERSE command. |
| 186 | // If the buffer and buffer provider in the configuration received by |
| 187 | // EFFECT_CMD_SET_CONFIG_REVERSE are also NULL, do not return modified reverse |
| 188 | // stream data |
| 189 | // |
| 190 | // Output: |
| 191 | // returned value: 0 successful operation |
| 192 | // -ENODATA the engine has finished the disable phase and the framework |
| 193 | // can stop calling process_reverse() |
| 194 | // -EINVAL invalid interface handle or |
| 195 | // invalid input/output buffer description |
| 196 | //////////////////////////////////////////////////////////////////////////////// |
| 197 | int32_t (*process_reverse)(effect_handle_t self, |
| 198 | audio_buffer_t *inBuffer, |
| 199 | audio_buffer_t *outBuffer); |
| 200 | }; |
| 201 | |
| 202 | ///////////////////////////////////////////////// |
| 203 | // Effect library interface |
| 204 | ///////////////////////////////////////////////// |
| 205 | |
| 206 | // Effect library interface version 3.0 |
| 207 | // Note that EffectsFactory.c only checks the major version component, so changes to the minor |
| 208 | // number can only be used for fully backwards compatible changes |
| 209 | #define EFFECT_LIBRARY_API_VERSION EFFECT_MAKE_API_VERSION(3,0) |
Eric Laurent | 472c7ed | 2019-11-13 13:01:15 -0800 | [diff] [blame] | 210 | #define EFFECT_LIBRARY_API_VERSION_3_0 EFFECT_MAKE_API_VERSION(3,0) |
| 211 | #define EFFECT_LIBRARY_API_VERSION_3_1 EFFECT_MAKE_API_VERSION(3,1) |
Kevin Rocard | c6ec948 | 2018-01-24 06:04:27 +0000 | [diff] [blame] | 212 | |
| 213 | #define AUDIO_EFFECT_LIBRARY_TAG ((('A') << 24) | (('E') << 16) | (('L') << 8) | ('T')) |
| 214 | |
| 215 | // Every effect library must have a data structure named AUDIO_EFFECT_LIBRARY_INFO_SYM |
| 216 | // and the fields of this data structure must begin with audio_effect_library_t |
| 217 | |
| 218 | typedef struct audio_effect_library_s { |
| 219 | // tag must be initialized to AUDIO_EFFECT_LIBRARY_TAG |
| 220 | uint32_t tag; |
| 221 | // Version of the effect library API : 0xMMMMmmmm MMMM: Major, mmmm: minor |
| 222 | uint32_t version; |
| 223 | // Name of this library |
| 224 | const char *name; |
| 225 | // Author/owner/implementor of the library |
| 226 | const char *implementor; |
| 227 | |
| 228 | //////////////////////////////////////////////////////////////////////////////// |
| 229 | // |
| 230 | // Function: create_effect |
| 231 | // |
| 232 | // Description: Creates an effect engine of the specified implementation uuid and |
| 233 | // returns an effect control interface on this engine. The function will allocate the |
| 234 | // resources for an instance of the requested effect engine and return |
| 235 | // a handle on the effect control interface. |
| 236 | // |
| 237 | // Input: |
| 238 | // uuid: pointer to the effect uuid. |
| 239 | // sessionId: audio session to which this effect instance will be attached. |
| 240 | // All effects created with the same session ID are connected in series and process |
| 241 | // the same signal stream. Knowing that two effects are part of the same effect |
| 242 | // chain can help the library implement some kind of optimizations. |
| 243 | // ioId: identifies the output or input stream this effect is directed to in |
| 244 | // audio HAL. |
| 245 | // For future use especially with tunneled HW accelerated effects |
| 246 | // |
| 247 | // Input/Output: |
| 248 | // pHandle: address where to return the effect interface handle. |
| 249 | // |
| 250 | // Output: |
| 251 | // returned value: 0 successful operation. |
| 252 | // -ENODEV library failed to initialize |
| 253 | // -EINVAL invalid pEffectUuid or pHandle |
| 254 | // -ENOENT no effect with this uuid found |
| 255 | // *pHandle: updated with the effect interface handle. |
| 256 | // |
| 257 | //////////////////////////////////////////////////////////////////////////////// |
| 258 | int32_t (*create_effect)(const effect_uuid_t *uuid, |
| 259 | int32_t sessionId, |
| 260 | int32_t ioId, |
| 261 | effect_handle_t *pHandle); |
| 262 | |
| 263 | //////////////////////////////////////////////////////////////////////////////// |
| 264 | // |
| 265 | // Function: release_effect |
| 266 | // |
| 267 | // Description: Releases the effect engine whose handle is given as argument. |
| 268 | // All resources allocated to this particular instance of the effect are |
| 269 | // released. |
| 270 | // |
| 271 | // Input: |
| 272 | // handle: handle on the effect interface to be released. |
| 273 | // |
| 274 | // Output: |
| 275 | // returned value: 0 successful operation. |
| 276 | // -ENODEV library failed to initialize |
| 277 | // -EINVAL invalid interface handle |
| 278 | // |
| 279 | //////////////////////////////////////////////////////////////////////////////// |
| 280 | int32_t (*release_effect)(effect_handle_t handle); |
| 281 | |
| 282 | //////////////////////////////////////////////////////////////////////////////// |
| 283 | // |
| 284 | // Function: get_descriptor |
| 285 | // |
| 286 | // Description: Returns the descriptor of the effect engine which implementation UUID is |
| 287 | // given as argument. |
| 288 | // |
| 289 | // Input/Output: |
| 290 | // uuid: pointer to the effect uuid. |
| 291 | // pDescriptor: address where to return the effect descriptor. |
| 292 | // |
| 293 | // Output: |
| 294 | // returned value: 0 successful operation. |
| 295 | // -ENODEV library failed to initialize |
| 296 | // -EINVAL invalid pDescriptor or uuid |
| 297 | // *pDescriptor: updated with the effect descriptor. |
| 298 | // |
| 299 | //////////////////////////////////////////////////////////////////////////////// |
| 300 | int32_t (*get_descriptor)(const effect_uuid_t *uuid, |
| 301 | effect_descriptor_t *pDescriptor); |
Eric Laurent | 472c7ed | 2019-11-13 13:01:15 -0800 | [diff] [blame] | 302 | |
| 303 | //////////////////////////////////////////////////////////////////////////////// |
| 304 | // |
| 305 | // Function: create_effect_3_1 |
| 306 | // |
| 307 | // Description: Creates an effect engine of the specified implementation uuid and |
| 308 | // returns an effect control interface on this engine. The function will allocate the |
| 309 | // resources for an instance of the requested effect engine and return |
| 310 | // a handle on the effect control interface. |
| 311 | // |
| 312 | // Input: |
| 313 | // uuid: pointer to the effect uuid. |
| 314 | // sessionId: audio session to which this effect instance will be attached. |
| 315 | // All effects created with the same session ID are connected in series and process |
| 316 | // the same signal stream. Knowing that two effects are part of the same effect |
| 317 | // chain can help the library implement some kind of optimizations. |
| 318 | // ioId: identifies the output or input stream this effect is directed to in |
| 319 | // audio HAL. |
| 320 | // For future use especially with tunneled HW accelerated effects |
| 321 | // deviceId: identifies the sink or source device this effect is directed to in |
| 322 | // audio HAL. Must be specified if sessionId is AUDIO_SESSION_DEVICE and is |
| 323 | // ignored otherwise. |
| 324 | // deviceId is the audio_port_handle_t used for the device when the audio |
| 325 | // patch is created at the audio HAL. |
| 326 | // |
| 327 | // Input/Output: |
| 328 | // pHandle: address where to return the effect interface handle. |
| 329 | // |
| 330 | // Output: |
| 331 | // returned value: 0 successful operation. |
| 332 | // -ENODEV library failed to initialize |
| 333 | // -EINVAL invalid pEffectUuid or pHandle |
| 334 | // -ENOENT no effect with this uuid found |
| 335 | // *pHandle: updated with the effect interface handle. |
| 336 | // |
| 337 | //////////////////////////////////////////////////////////////////////////////// |
| 338 | int32_t (*create_effect_3_1)(const effect_uuid_t *uuid, |
| 339 | int32_t sessionId, |
| 340 | int32_t ioId, |
| 341 | int32_t deviceId, |
| 342 | effect_handle_t *pHandle); |
| 343 | |
Kevin Rocard | c6ec948 | 2018-01-24 06:04:27 +0000 | [diff] [blame] | 344 | } audio_effect_library_t; |
| 345 | |
| 346 | // Name of the hal_module_info |
| 347 | #define AUDIO_EFFECT_LIBRARY_INFO_SYM AELI |
| 348 | |
| 349 | // Name of the hal_module_info as a string |
| 350 | #define AUDIO_EFFECT_LIBRARY_INFO_SYM_AS_STR "AELI" |
| 351 | |
| 352 | __END_DECLS |
| 353 | |
| 354 | #endif // ANDROID_AUDIO_EFFECT_H |