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) 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) 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); 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 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 355