Android Hardware Abstraction Layer
audio_effect.h
Go to the documentation of this file.
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.h>
30 
31 
32 __BEGIN_DECLS
33 
34 
35 /////////////////////////////////////////////////
36 // Common Definitions
37 /////////////////////////////////////////////////
38 
39 //
40 //--- Effect descriptor structure effect_descriptor_t
41 //
42 
43 // Unique effect ID (can be generated from the following site:
44 // http://www.itu.int/ITU-T/asn1/uuid.html)
45 // This format is used for both "type" and "uuid" fields of the effect descriptor structure.
46 // - When used for effect type and the engine is implementing and effect corresponding to a standard
47 // OpenSL ES interface, this ID must be the one defined in OpenSLES_IID.h for that interface.
48 // - When used as uuid, it should be a unique UUID for this particular implementation.
49 typedef struct effect_uuid_s {
50  uint32_t timeLow;
51  uint16_t timeMid;
52  uint16_t timeHiAndVersion;
53  uint16_t clockSeq;
54  uint8_t node[6];
56 
57 // Maximum length of character strings in structures defines by this API.
58 #define EFFECT_STRING_LEN_MAX 64
59 
60 // NULL UUID definition (matches SL_IID_NULL_)
61 #define EFFECT_UUID_INITIALIZER { 0xec7178ec, 0xe5e1, 0x4432, 0xa3f4, \
62  { 0x46, 0x57, 0xe6, 0x79, 0x52, 0x10 } }
63 static const effect_uuid_t EFFECT_UUID_NULL_ = EFFECT_UUID_INITIALIZER;
64 static const effect_uuid_t * const EFFECT_UUID_NULL = &EFFECT_UUID_NULL_;
65 static const char * const EFFECT_UUID_NULL_STR = "ec7178ec-e5e1-4432-a3f4-4657e6795210";
66 
67 
68 // The effect descriptor contains necessary information to facilitate the enumeration of the effect
69 // engines present in a library.
70 typedef struct effect_descriptor_s {
71  effect_uuid_t type; // UUID of to the OpenSL ES interface implemented by this effect
72  effect_uuid_t uuid; // UUID for this particular implementation
73  uint32_t apiVersion; // Version of the effect control API implemented
74  uint32_t flags; // effect engine capabilities/requirements flags (see below)
75  uint16_t cpuLoad; // CPU load indication (see below)
76  uint16_t memoryUsage; // Data Memory usage (see below)
77  char name[EFFECT_STRING_LEN_MAX]; // human readable effect name
78  char implementor[EFFECT_STRING_LEN_MAX]; // human readable effect implementor name
80 
81 // CPU load and memory usage indication: each effect implementation must provide an indication of
82 // its CPU and memory usage for the audio effect framework to limit the number of effects
83 // instantiated at a given time on a given platform.
84 // The CPU load is expressed in 0.1 MIPS units as estimated on an ARM9E core (ARMv5TE) with 0 WS.
85 // The memory usage is expressed in KB and includes only dynamically allocated memory
86 
87 // Definitions for flags field of effect descriptor.
88 // +---------------------------+-----------+-----------------------------------
89 // | description | bits | values
90 // +---------------------------+-----------+-----------------------------------
91 // | connection mode | 0..2 | 0 insert: after track process
92 // | | | 1 auxiliary: connect to track auxiliary
93 // | | | output and use send level
94 // | | | 2 replace: replaces track process function;
95 // | | | must implement SRC, volume and mono to stereo.
96 // | | | 3 pre processing: applied below audio HAL on input
97 // | | | 4 post processing: applied below audio HAL on output
98 // | | | 5 - 7 reserved
99 // +---------------------------+-----------+-----------------------------------
100 // | insertion preference | 3..5 | 0 none
101 // | | | 1 first of the chain
102 // | | | 2 last of the chain
103 // | | | 3 exclusive (only effect in the insert chain)
104 // | | | 4..7 reserved
105 // +---------------------------+-----------+-----------------------------------
106 // | Volume management | 6..8 | 0 none
107 // | | | 1 implements volume control
108 // | | | 2 requires volume indication
109 // | | | 4 reserved
110 // +---------------------------+-----------+-----------------------------------
111 // | Device indication | 9..11 | 0 none
112 // | | | 1 requires device updates
113 // | | | 2, 4 reserved
114 // +---------------------------+-----------+-----------------------------------
115 // | Sample input mode | 12..13 | 1 direct: process() function or EFFECT_CMD_SET_CONFIG
116 // | | | command must specify a buffer descriptor
117 // | | | 2 provider: process() function uses the
118 // | | | bufferProvider indicated by the
119 // | | | EFFECT_CMD_SET_CONFIG command to request input.
120 // | | | buffers.
121 // | | | 3 both: both input modes are supported
122 // +---------------------------+-----------+-----------------------------------
123 // | Sample output mode | 14..15 | 1 direct: process() function or EFFECT_CMD_SET_CONFIG
124 // | | | command must specify a buffer descriptor
125 // | | | 2 provider: process() function uses the
126 // | | | bufferProvider indicated by the
127 // | | | EFFECT_CMD_SET_CONFIG command to request output
128 // | | | buffers.
129 // | | | 3 both: both output modes are supported
130 // +---------------------------+-----------+-----------------------------------
131 // | Hardware acceleration | 16..17 | 0 No hardware acceleration
132 // | | | 1 non tunneled hw acceleration: the process() function
133 // | | | reads the samples, send them to HW accelerated
134 // | | | effect processor, reads back the processed samples
135 // | | | and returns them to the output buffer.
136 // | | | 2 tunneled hw acceleration: the process() function is
137 // | | | transparent. The effect interface is only used to
138 // | | | control the effect engine. This mode is relevant for
139 // | | | global effects actually applied by the audio
140 // | | | hardware on the output stream.
141 // +---------------------------+-----------+-----------------------------------
142 // | Audio Mode indication | 18..19 | 0 none
143 // | | | 1 requires audio mode updates
144 // | | | 2..3 reserved
145 // +---------------------------+-----------+-----------------------------------
146 // | Audio source indication | 20..21 | 0 none
147 // | | | 1 requires audio source updates
148 // | | | 2..3 reserved
149 // +---------------------------+-----------+-----------------------------------
150 // | Effect offload supported | 22 | 0 The effect cannot be offloaded to an audio DSP
151 // | | | 1 The effect can be offloaded to an audio DSP
152 // +---------------------------+-----------+-----------------------------------
153 
154 // Insert mode
155 #define EFFECT_FLAG_TYPE_SHIFT 0
156 #define EFFECT_FLAG_TYPE_SIZE 3
157 #define EFFECT_FLAG_TYPE_MASK (((1 << EFFECT_FLAG_TYPE_SIZE) -1) \
158  << EFFECT_FLAG_TYPE_SHIFT)
159 #define EFFECT_FLAG_TYPE_INSERT (0 << EFFECT_FLAG_TYPE_SHIFT)
160 #define EFFECT_FLAG_TYPE_AUXILIARY (1 << EFFECT_FLAG_TYPE_SHIFT)
161 #define EFFECT_FLAG_TYPE_REPLACE (2 << EFFECT_FLAG_TYPE_SHIFT)
162 #define EFFECT_FLAG_TYPE_PRE_PROC (3 << EFFECT_FLAG_TYPE_SHIFT)
163 #define EFFECT_FLAG_TYPE_POST_PROC (4 << EFFECT_FLAG_TYPE_SHIFT)
164 
165 // Insert preference
166 #define EFFECT_FLAG_INSERT_SHIFT (EFFECT_FLAG_TYPE_SHIFT + EFFECT_FLAG_TYPE_SIZE)
167 #define EFFECT_FLAG_INSERT_SIZE 3
168 #define EFFECT_FLAG_INSERT_MASK (((1 << EFFECT_FLAG_INSERT_SIZE) -1) \
169  << EFFECT_FLAG_INSERT_SHIFT)
170 #define EFFECT_FLAG_INSERT_ANY (0 << EFFECT_FLAG_INSERT_SHIFT)
171 #define EFFECT_FLAG_INSERT_FIRST (1 << EFFECT_FLAG_INSERT_SHIFT)
172 #define EFFECT_FLAG_INSERT_LAST (2 << EFFECT_FLAG_INSERT_SHIFT)
173 #define EFFECT_FLAG_INSERT_EXCLUSIVE (3 << EFFECT_FLAG_INSERT_SHIFT)
174 
175 
176 // Volume control
177 #define EFFECT_FLAG_VOLUME_SHIFT (EFFECT_FLAG_INSERT_SHIFT + EFFECT_FLAG_INSERT_SIZE)
178 #define EFFECT_FLAG_VOLUME_SIZE 3
179 #define EFFECT_FLAG_VOLUME_MASK (((1 << EFFECT_FLAG_VOLUME_SIZE) -1) \
180  << EFFECT_FLAG_VOLUME_SHIFT)
181 #define EFFECT_FLAG_VOLUME_CTRL (1 << EFFECT_FLAG_VOLUME_SHIFT)
182 #define EFFECT_FLAG_VOLUME_IND (2 << EFFECT_FLAG_VOLUME_SHIFT)
183 #define EFFECT_FLAG_VOLUME_NONE (0 << EFFECT_FLAG_VOLUME_SHIFT)
184 
185 // Device indication
186 #define EFFECT_FLAG_DEVICE_SHIFT (EFFECT_FLAG_VOLUME_SHIFT + EFFECT_FLAG_VOLUME_SIZE)
187 #define EFFECT_FLAG_DEVICE_SIZE 3
188 #define EFFECT_FLAG_DEVICE_MASK (((1 << EFFECT_FLAG_DEVICE_SIZE) -1) \
189  << EFFECT_FLAG_DEVICE_SHIFT)
190 #define EFFECT_FLAG_DEVICE_IND (1 << EFFECT_FLAG_DEVICE_SHIFT)
191 #define EFFECT_FLAG_DEVICE_NONE (0 << EFFECT_FLAG_DEVICE_SHIFT)
192 
193 // Sample input modes
194 #define EFFECT_FLAG_INPUT_SHIFT (EFFECT_FLAG_DEVICE_SHIFT + EFFECT_FLAG_DEVICE_SIZE)
195 #define EFFECT_FLAG_INPUT_SIZE 2
196 #define EFFECT_FLAG_INPUT_MASK (((1 << EFFECT_FLAG_INPUT_SIZE) -1) \
197  << EFFECT_FLAG_INPUT_SHIFT)
198 #define EFFECT_FLAG_INPUT_DIRECT (1 << EFFECT_FLAG_INPUT_SHIFT)
199 #define EFFECT_FLAG_INPUT_PROVIDER (2 << EFFECT_FLAG_INPUT_SHIFT)
200 #define EFFECT_FLAG_INPUT_BOTH (3 << EFFECT_FLAG_INPUT_SHIFT)
201 
202 // Sample output modes
203 #define EFFECT_FLAG_OUTPUT_SHIFT (EFFECT_FLAG_INPUT_SHIFT + EFFECT_FLAG_INPUT_SIZE)
204 #define EFFECT_FLAG_OUTPUT_SIZE 2
205 #define EFFECT_FLAG_OUTPUT_MASK (((1 << EFFECT_FLAG_OUTPUT_SIZE) -1) \
206  << EFFECT_FLAG_OUTPUT_SHIFT)
207 #define EFFECT_FLAG_OUTPUT_DIRECT (1 << EFFECT_FLAG_OUTPUT_SHIFT)
208 #define EFFECT_FLAG_OUTPUT_PROVIDER (2 << EFFECT_FLAG_OUTPUT_SHIFT)
209 #define EFFECT_FLAG_OUTPUT_BOTH (3 << EFFECT_FLAG_OUTPUT_SHIFT)
210 
211 // Hardware acceleration mode
212 #define EFFECT_FLAG_HW_ACC_SHIFT (EFFECT_FLAG_OUTPUT_SHIFT + EFFECT_FLAG_OUTPUT_SIZE)
213 #define EFFECT_FLAG_HW_ACC_SIZE 2
214 #define EFFECT_FLAG_HW_ACC_MASK (((1 << EFFECT_FLAG_HW_ACC_SIZE) -1) \
215  << EFFECT_FLAG_HW_ACC_SHIFT)
216 #define EFFECT_FLAG_HW_ACC_SIMPLE (1 << EFFECT_FLAG_HW_ACC_SHIFT)
217 #define EFFECT_FLAG_HW_ACC_TUNNEL (2 << EFFECT_FLAG_HW_ACC_SHIFT)
218 
219 // Audio mode indication
220 #define EFFECT_FLAG_AUDIO_MODE_SHIFT (EFFECT_FLAG_HW_ACC_SHIFT + EFFECT_FLAG_HW_ACC_SIZE)
221 #define EFFECT_FLAG_AUDIO_MODE_SIZE 2
222 #define EFFECT_FLAG_AUDIO_MODE_MASK (((1 << EFFECT_FLAG_AUDIO_MODE_SIZE) -1) \
223  << EFFECT_FLAG_AUDIO_MODE_SHIFT)
224 #define EFFECT_FLAG_AUDIO_MODE_IND (1 << EFFECT_FLAG_AUDIO_MODE_SHIFT)
225 #define EFFECT_FLAG_AUDIO_MODE_NONE (0 << EFFECT_FLAG_AUDIO_MODE_SHIFT)
226 
227 // Audio source indication
228 #define EFFECT_FLAG_AUDIO_SOURCE_SHIFT (EFFECT_FLAG_AUDIO_MODE_SHIFT + EFFECT_FLAG_AUDIO_MODE_SIZE)
229 #define EFFECT_FLAG_AUDIO_SOURCE_SIZE 2
230 #define EFFECT_FLAG_AUDIO_SOURCE_MASK (((1 << EFFECT_FLAG_AUDIO_SOURCE_SIZE) -1) \
231  << EFFECT_FLAG_AUDIO_SOURCE_SHIFT)
232 #define EFFECT_FLAG_AUDIO_SOURCE_IND (1 << EFFECT_FLAG_AUDIO_SOURCE_SHIFT)
233 #define EFFECT_FLAG_AUDIO_SOURCE_NONE (0 << EFFECT_FLAG_AUDIO_SOURCE_SHIFT)
234 
235 // Effect offload indication
236 #define EFFECT_FLAG_OFFLOAD_SHIFT (EFFECT_FLAG_AUDIO_SOURCE_SHIFT + \
237  EFFECT_FLAG_AUDIO_SOURCE_SIZE)
238 #define EFFECT_FLAG_OFFLOAD_SIZE 1
239 #define EFFECT_FLAG_OFFLOAD_MASK (((1 << EFFECT_FLAG_OFFLOAD_SIZE) -1) \
240  << EFFECT_FLAG_OFFLOAD_SHIFT)
241 #define EFFECT_FLAG_OFFLOAD_SUPPORTED (1 << EFFECT_FLAG_OFFLOAD_SHIFT)
242 
243 #define EFFECT_MAKE_API_VERSION(M, m) (((M)<<16) | ((m) & 0xFFFF))
244 #define EFFECT_API_VERSION_MAJOR(v) ((v)>>16)
245 #define EFFECT_API_VERSION_MINOR(v) ((m) & 0xFFFF)
246 
247 
248 
249 /////////////////////////////////////////////////
250 // Effect control interface
251 /////////////////////////////////////////////////
252 
253 // Effect control interface version 2.0
254 #define EFFECT_CONTROL_API_VERSION EFFECT_MAKE_API_VERSION(2,0)
255 
256 // Effect control interface structure: effect_interface_s
257 // The effect control interface is exposed by each effect engine implementation. It consists of
258 // a set of functions controlling the configuration, activation and process of the engine.
259 // The functions are grouped in a structure of type effect_interface_s.
260 //
261 // Effect control interface handle: effect_handle_t
262 // The effect_handle_t serves two purposes regarding the implementation of the effect engine:
263 // - 1 it is the address of a pointer to an effect_interface_s structure where the functions
264 // of the effect control API for a particular effect are located.
265 // - 2 it is the address of the context of a particular effect instance.
266 // A typical implementation in the effect library would define a structure as follows:
267 // struct effect_module_s {
268 // const struct effect_interface_s *itfe;
269 // effect_config_t config;
270 // effect_context_t context;
271 // }
272 // The implementation of EffectCreate() function would then allocate a structure of this
273 // type and return its address as effect_handle_t
275 
276 
277 // Forward definition of type audio_buffer_t
279 
280 
281 
282 
283 
284 
285 // Effect control interface definition
287  ////////////////////////////////////////////////////////////////////////////////
288  //
289  // Function: process
290  //
291  // Description: Effect process function. Takes input samples as specified
292  // (count and location) in input buffer descriptor and output processed
293  // samples as specified in output buffer descriptor. If the buffer descriptor
294  // is not specified the function must use either the buffer or the
295  // buffer provider function installed by the EFFECT_CMD_SET_CONFIG command.
296  // The effect framework will call the process() function after the EFFECT_CMD_ENABLE
297  // command is received and until the EFFECT_CMD_DISABLE is received. When the engine
298  // receives the EFFECT_CMD_DISABLE command it should turn off the effect gracefully
299  // and when done indicate that it is OK to stop calling the process() function by
300  // returning the -ENODATA status.
301  //
302  // NOTE: the process() function implementation should be "real-time safe" that is
303  // it should not perform blocking calls: malloc/free, sleep, read/write/open/close,
304  // pthread_cond_wait/pthread_mutex_lock...
305  //
306  // Input:
307  // self: handle to the effect interface this function
308  // is called on.
309  // inBuffer: buffer descriptor indicating where to read samples to process.
310  // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG command.
311  //
312  // outBuffer: buffer descriptor indicating where to write processed samples.
313  // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG command.
314  //
315  // Output:
316  // returned value: 0 successful operation
317  // -ENODATA the engine has finished the disable phase and the framework
318  // can stop calling process()
319  // -EINVAL invalid interface handle or
320  // invalid input/output buffer description
321  ////////////////////////////////////////////////////////////////////////////////
322  int32_t (*process)(effect_handle_t self,
323  audio_buffer_t *inBuffer,
324  audio_buffer_t *outBuffer);
325  ////////////////////////////////////////////////////////////////////////////////
326  //
327  // Function: command
328  //
329  // Description: Send a command and receive a response to/from effect engine.
330  //
331  // Input:
332  // self: handle to the effect interface this function
333  // is called on.
334  // cmdCode: command code: the command can be a standardized command defined in
335  // effect_command_e (see below) or a proprietary command.
336  // cmdSize: size of command in bytes
337  // pCmdData: pointer to command data
338  // pReplyData: pointer to reply data
339  //
340  // Input/Output:
341  // replySize: maximum size of reply data as input
342  // actual size of reply data as output
343  //
344  // Output:
345  // returned value: 0 successful operation
346  // -EINVAL invalid interface handle or
347  // invalid command/reply size or format according to command code
348  // The return code should be restricted to indicate problems related to the this
349  // API specification. Status related to the execution of a particular command should be
350  // indicated as part of the reply field.
351  //
352  // *pReplyData updated with command response
353  //
354  ////////////////////////////////////////////////////////////////////////////////
355  int32_t (*command)(effect_handle_t self,
356  uint32_t cmdCode,
357  uint32_t cmdSize,
358  void *pCmdData,
359  uint32_t *replySize,
360  void *pReplyData);
361  ////////////////////////////////////////////////////////////////////////////////
362  //
363  // Function: get_descriptor
364  //
365  // Description: Returns the effect descriptor
366  //
367  // Input:
368  // self: handle to the effect interface this function
369  // is called on.
370  //
371  // Input/Output:
372  // pDescriptor: address where to return the effect descriptor.
373  //
374  // Output:
375  // returned value: 0 successful operation.
376  // -EINVAL invalid interface handle or invalid pDescriptor
377  // *pDescriptor: updated with the effect descriptor.
378  //
379  ////////////////////////////////////////////////////////////////////////////////
380  int32_t (*get_descriptor)(effect_handle_t self,
381  effect_descriptor_t *pDescriptor);
382  ////////////////////////////////////////////////////////////////////////////////
383  //
384  // Function: process_reverse
385  //
386  // Description: Process reverse stream function. This function is used to pass
387  // a reference stream to the effect engine. If the engine does not need a reference
388  // stream, this function pointer can be set to NULL.
389  // This function would typically implemented by an Echo Canceler.
390  //
391  // Input:
392  // self: handle to the effect interface this function
393  // is called on.
394  // inBuffer: buffer descriptor indicating where to read samples to process.
395  // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG_REVERSE command.
396  //
397  // outBuffer: buffer descriptor indicating where to write processed samples.
398  // If NULL, use the configuration passed by EFFECT_CMD_SET_CONFIG_REVERSE command.
399  // If the buffer and buffer provider in the configuration received by
400  // EFFECT_CMD_SET_CONFIG_REVERSE are also NULL, do not return modified reverse
401  // stream data
402  //
403  // Output:
404  // returned value: 0 successful operation
405  // -ENODATA the engine has finished the disable phase and the framework
406  // can stop calling process_reverse()
407  // -EINVAL invalid interface handle or
408  // invalid input/output buffer description
409  ////////////////////////////////////////////////////////////////////////////////
410  int32_t (*process_reverse)(effect_handle_t self,
411  audio_buffer_t *inBuffer,
412  audio_buffer_t *outBuffer);
413 };
414 
415 
416 //
417 //--- Standardized command codes for command() function
418 //
420  EFFECT_CMD_INIT, // initialize effect engine
421  EFFECT_CMD_SET_CONFIG, // configure effect engine (see effect_config_t)
422  EFFECT_CMD_RESET, // reset effect engine
423  EFFECT_CMD_ENABLE, // enable effect process
424  EFFECT_CMD_DISABLE, // disable effect process
425  EFFECT_CMD_SET_PARAM, // set parameter immediately (see effect_param_t)
426  EFFECT_CMD_SET_PARAM_DEFERRED, // set parameter deferred
427  EFFECT_CMD_SET_PARAM_COMMIT, // commit previous set parameter deferred
428  EFFECT_CMD_GET_PARAM, // get parameter
429  EFFECT_CMD_SET_DEVICE, // set audio device (see audio.h, audio_devices_t)
430  EFFECT_CMD_SET_VOLUME, // set volume
431  EFFECT_CMD_SET_AUDIO_MODE, // set the audio mode (normal, ring, ...)
432  EFFECT_CMD_SET_CONFIG_REVERSE, // configure effect engine reverse stream(see effect_config_t)
433  EFFECT_CMD_SET_INPUT_DEVICE, // set capture device (see audio.h, audio_devices_t)
434  EFFECT_CMD_GET_CONFIG, // read effect engine configuration
435  EFFECT_CMD_GET_CONFIG_REVERSE, // read configure effect engine reverse stream configuration
436  EFFECT_CMD_GET_FEATURE_SUPPORTED_CONFIGS,// get all supported configurations for a feature.
437  EFFECT_CMD_GET_FEATURE_CONFIG, // get current feature configuration
438  EFFECT_CMD_SET_FEATURE_CONFIG, // set current feature configuration
439  EFFECT_CMD_SET_AUDIO_SOURCE, // set the audio source (see audio.h, audio_source_t)
440  EFFECT_CMD_OFFLOAD, // set if effect thread is an offload one,
441  // send the ioHandle of the effect thread
442  EFFECT_CMD_FIRST_PROPRIETARY = 0x10000 // first proprietary command code
443 };
444 
445 //==================================================================================================
446 // command: EFFECT_CMD_INIT
447 //--------------------------------------------------------------------------------------------------
448 // description:
449 // Initialize effect engine: All configurations return to default
450 //--------------------------------------------------------------------------------------------------
451 // command format:
452 // size: 0
453 // data: N/A
454 //--------------------------------------------------------------------------------------------------
455 // reply format:
456 // size: sizeof(int)
457 // data: status
458 //==================================================================================================
459 // command: EFFECT_CMD_SET_CONFIG
460 //--------------------------------------------------------------------------------------------------
461 // description:
462 // Apply new audio parameters configurations for input and output buffers
463 //--------------------------------------------------------------------------------------------------
464 // command format:
465 // size: sizeof(effect_config_t)
466 // data: effect_config_t
467 //--------------------------------------------------------------------------------------------------
468 // reply format:
469 // size: sizeof(int)
470 // data: status
471 //==================================================================================================
472 // command: EFFECT_CMD_RESET
473 //--------------------------------------------------------------------------------------------------
474 // description:
475 // Reset the effect engine. Keep configuration but resets state and buffer content
476 //--------------------------------------------------------------------------------------------------
477 // command format:
478 // size: 0
479 // data: N/A
480 //--------------------------------------------------------------------------------------------------
481 // reply format:
482 // size: 0
483 // data: N/A
484 //==================================================================================================
485 // command: EFFECT_CMD_ENABLE
486 //--------------------------------------------------------------------------------------------------
487 // description:
488 // Enable the process. Called by the framework before the first call to process()
489 //--------------------------------------------------------------------------------------------------
490 // command format:
491 // size: 0
492 // data: N/A
493 //--------------------------------------------------------------------------------------------------
494 // reply format:
495 // size: sizeof(int)
496 // data: status
497 //==================================================================================================
498 // command: EFFECT_CMD_DISABLE
499 //--------------------------------------------------------------------------------------------------
500 // description:
501 // Disable the process. Called by the framework after the last call to process()
502 //--------------------------------------------------------------------------------------------------
503 // command format:
504 // size: 0
505 // data: N/A
506 //--------------------------------------------------------------------------------------------------
507 // reply format:
508 // size: sizeof(int)
509 // data: status
510 //==================================================================================================
511 // command: EFFECT_CMD_SET_PARAM
512 //--------------------------------------------------------------------------------------------------
513 // description:
514 // Set a parameter and apply it immediately
515 //--------------------------------------------------------------------------------------------------
516 // command format:
517 // size: sizeof(effect_param_t) + size of param and value
518 // data: effect_param_t + param + value. See effect_param_t definition below for value offset
519 //--------------------------------------------------------------------------------------------------
520 // reply format:
521 // size: sizeof(int)
522 // data: status
523 //==================================================================================================
524 // command: EFFECT_CMD_SET_PARAM_DEFERRED
525 //--------------------------------------------------------------------------------------------------
526 // description:
527 // Set a parameter but apply it only when receiving EFFECT_CMD_SET_PARAM_COMMIT command
528 //--------------------------------------------------------------------------------------------------
529 // command format:
530 // size: sizeof(effect_param_t) + size of param and value
531 // data: effect_param_t + param + value. See effect_param_t definition below for value offset
532 //--------------------------------------------------------------------------------------------------
533 // reply format:
534 // size: 0
535 // data: N/A
536 //==================================================================================================
537 // command: EFFECT_CMD_SET_PARAM_COMMIT
538 //--------------------------------------------------------------------------------------------------
539 // description:
540 // Apply all previously received EFFECT_CMD_SET_PARAM_DEFERRED commands
541 //--------------------------------------------------------------------------------------------------
542 // command format:
543 // size: 0
544 // data: N/A
545 //--------------------------------------------------------------------------------------------------
546 // reply format:
547 // size: sizeof(int)
548 // data: status
549 //==================================================================================================
550 // command: EFFECT_CMD_GET_PARAM
551 //--------------------------------------------------------------------------------------------------
552 // description:
553 // Get a parameter value
554 //--------------------------------------------------------------------------------------------------
555 // command format:
556 // size: sizeof(effect_param_t) + size of param
557 // data: effect_param_t + param
558 //--------------------------------------------------------------------------------------------------
559 // reply format:
560 // size: sizeof(effect_param_t) + size of param and value
561 // data: effect_param_t + param + value. See effect_param_t definition below for value offset
562 //==================================================================================================
563 // command: EFFECT_CMD_SET_DEVICE
564 //--------------------------------------------------------------------------------------------------
565 // description:
566 // Set the rendering device the audio output path is connected to. See audio.h, audio_devices_t
567 // for device values.
568 // The effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to receive this
569 // command when the device changes
570 //--------------------------------------------------------------------------------------------------
571 // command format:
572 // size: sizeof(uint32_t)
573 // data: uint32_t
574 //--------------------------------------------------------------------------------------------------
575 // reply format:
576 // size: 0
577 // data: N/A
578 //==================================================================================================
579 // command: EFFECT_CMD_SET_VOLUME
580 //--------------------------------------------------------------------------------------------------
581 // description:
582 // Set and get volume. Used by audio framework to delegate volume control to effect engine.
583 // The effect implementation must set EFFECT_FLAG_VOLUME_IND or EFFECT_FLAG_VOLUME_CTRL flag in
584 // its descriptor to receive this command before every call to process() function
585 // If EFFECT_FLAG_VOLUME_CTRL flag is set in the effect descriptor, the effect engine must return
586 // the volume that should be applied before the effect is processed. The overall volume (the volume
587 // actually applied by the effect engine multiplied by the returned value) should match the value
588 // indicated in the command.
589 //--------------------------------------------------------------------------------------------------
590 // command format:
591 // size: n * sizeof(uint32_t)
592 // data: volume for each channel defined in effect_config_t for output buffer expressed in
593 // 8.24 fixed point format
594 //--------------------------------------------------------------------------------------------------
595 // reply format:
596 // size: n * sizeof(uint32_t) / 0
597 // data: - if EFFECT_FLAG_VOLUME_CTRL is set in effect descriptor:
598 // volume for each channel defined in effect_config_t for output buffer expressed in
599 // 8.24 fixed point format
600 // - if EFFECT_FLAG_VOLUME_CTRL is not set in effect descriptor:
601 // N/A
602 // It is legal to receive a null pointer as pReplyData in which case the effect framework has
603 // delegated volume control to another effect
604 //==================================================================================================
605 // command: EFFECT_CMD_SET_AUDIO_MODE
606 //--------------------------------------------------------------------------------------------------
607 // description:
608 // Set the audio mode. The effect implementation must set EFFECT_FLAG_AUDIO_MODE_IND flag in its
609 // descriptor to receive this command when the audio mode changes.
610 //--------------------------------------------------------------------------------------------------
611 // command format:
612 // size: sizeof(uint32_t)
613 // data: audio_mode_t
614 //--------------------------------------------------------------------------------------------------
615 // reply format:
616 // size: 0
617 // data: N/A
618 //==================================================================================================
619 // command: EFFECT_CMD_SET_CONFIG_REVERSE
620 //--------------------------------------------------------------------------------------------------
621 // description:
622 // Apply new audio parameters configurations for input and output buffers of reverse stream.
623 // An example of reverse stream is the echo reference supplied to an Acoustic Echo Canceler.
624 //--------------------------------------------------------------------------------------------------
625 // command format:
626 // size: sizeof(effect_config_t)
627 // data: effect_config_t
628 //--------------------------------------------------------------------------------------------------
629 // reply format:
630 // size: sizeof(int)
631 // data: status
632 //==================================================================================================
633 // command: EFFECT_CMD_SET_INPUT_DEVICE
634 //--------------------------------------------------------------------------------------------------
635 // description:
636 // Set the capture device the audio input path is connected to. See audio.h, audio_devices_t
637 // for device values.
638 // The effect implementation must set EFFECT_FLAG_DEVICE_IND flag in its descriptor to receive this
639 // command when the device changes
640 //--------------------------------------------------------------------------------------------------
641 // command format:
642 // size: sizeof(uint32_t)
643 // data: uint32_t
644 //--------------------------------------------------------------------------------------------------
645 // reply format:
646 // size: 0
647 // data: N/A
648 //==================================================================================================
649 // command: EFFECT_CMD_GET_CONFIG
650 //--------------------------------------------------------------------------------------------------
651 // description:
652 // Read audio parameters configurations for input and output buffers
653 //--------------------------------------------------------------------------------------------------
654 // command format:
655 // size: 0
656 // data: N/A
657 //--------------------------------------------------------------------------------------------------
658 // reply format:
659 // size: sizeof(effect_config_t)
660 // data: effect_config_t
661 //==================================================================================================
662 // command: EFFECT_CMD_GET_CONFIG_REVERSE
663 //--------------------------------------------------------------------------------------------------
664 // description:
665 // Read audio parameters configurations for input and output buffers of reverse stream
666 //--------------------------------------------------------------------------------------------------
667 // command format:
668 // size: 0
669 // data: N/A
670 //--------------------------------------------------------------------------------------------------
671 // reply format:
672 // size: sizeof(effect_config_t)
673 // data: effect_config_t
674 //==================================================================================================
675 // command: EFFECT_CMD_GET_FEATURE_SUPPORTED_CONFIGS
676 //--------------------------------------------------------------------------------------------------
677 // description:
678 // Queries for supported configurations for a particular feature (e.g. get the supported
679 // combinations of main and auxiliary channels for a noise suppressor).
680 // The command parameter is the feature identifier (See effect_feature_e for a list of defined
681 // features) followed by the maximum number of configuration descriptor to return.
682 // The reply is composed of:
683 // - status (uint32_t):
684 // - 0 if feature is supported
685 // - -ENOSYS if the feature is not supported,
686 // - -ENOMEM if the feature is supported but the total number of supported configurations
687 // exceeds the maximum number indicated by the caller.
688 // - total number of supported configurations (uint32_t)
689 // - an array of configuration descriptors.
690 // The actual number of descriptors returned must not exceed the maximum number indicated by
691 // the caller.
692 //--------------------------------------------------------------------------------------------------
693 // command format:
694 // size: 2 x sizeof(uint32_t)
695 // data: effect_feature_e + maximum number of configurations to return
696 //--------------------------------------------------------------------------------------------------
697 // reply format:
698 // size: 2 x sizeof(uint32_t) + n x sizeof (<config descriptor>)
699 // data: status + total number of configurations supported + array of n config descriptors
700 //==================================================================================================
701 // command: EFFECT_CMD_GET_FEATURE_CONFIG
702 //--------------------------------------------------------------------------------------------------
703 // description:
704 // Retrieves current configuration for a given feature.
705 // The reply status is:
706 // - 0 if feature is supported
707 // - -ENOSYS if the feature is not supported,
708 //--------------------------------------------------------------------------------------------------
709 // command format:
710 // size: sizeof(uint32_t)
711 // data: effect_feature_e
712 //--------------------------------------------------------------------------------------------------
713 // reply format:
714 // size: sizeof(uint32_t) + sizeof (<config descriptor>)
715 // data: status + config descriptor
716 //==================================================================================================
717 // command: EFFECT_CMD_SET_FEATURE_CONFIG
718 //--------------------------------------------------------------------------------------------------
719 // description:
720 // Sets current configuration for a given feature.
721 // The reply status is:
722 // - 0 if feature is supported
723 // - -ENOSYS if the feature is not supported,
724 // - -EINVAL if the configuration is invalid
725 //--------------------------------------------------------------------------------------------------
726 // command format:
727 // size: sizeof(uint32_t) + sizeof (<config descriptor>)
728 // data: effect_feature_e + config descriptor
729 //--------------------------------------------------------------------------------------------------
730 // reply format:
731 // size: sizeof(uint32_t)
732 // data: status
733 //==================================================================================================
734 // command: EFFECT_CMD_SET_AUDIO_SOURCE
735 //--------------------------------------------------------------------------------------------------
736 // description:
737 // Set the audio source the capture path is configured for (Camcorder, voice recognition...).
738 // See audio.h, audio_source_t for values.
739 //--------------------------------------------------------------------------------------------------
740 // command format:
741 // size: sizeof(uint32_t)
742 // data: uint32_t
743 //--------------------------------------------------------------------------------------------------
744 // reply format:
745 // size: 0
746 // data: N/A
747 //==================================================================================================
748 // command: EFFECT_CMD_OFFLOAD
749 //--------------------------------------------------------------------------------------------------
750 // description:
751 // 1.indicate if the playback thread the effect is attached to is offloaded or not
752 // 2.update the io handle of the playback thread the effect is attached to
753 //--------------------------------------------------------------------------------------------------
754 // command format:
755 // size: sizeof(effect_offload_param_t)
756 // data: effect_offload_param_t
757 //--------------------------------------------------------------------------------------------------
758 // reply format:
759 // size: sizeof(uint32_t)
760 // data: uint32_t
761 //--------------------------------------------------------------------------------------------------
762 // command: EFFECT_CMD_FIRST_PROPRIETARY
763 //--------------------------------------------------------------------------------------------------
764 // description:
765 // All proprietary effect commands must use command codes above this value. The size and format of
766 // command and response fields is free in this case
767 //==================================================================================================
768 
769 
770 // Audio buffer descriptor used by process(), bufferProvider() functions and buffer_config_t
771 // structure. Multi-channel audio is always interleaved. The channel order is from LSB to MSB with
772 // regard to the channel mask definition in audio.h, audio_channel_mask_t e.g :
773 // Stereo: left, right
774 // 5 point 1: front left, front right, front center, low frequency, back left, back right
775 // The buffer size is expressed in frame count, a frame being composed of samples for all
776 // channels at a given time. Frame size for unspecified format (AUDIO_FORMAT_OTHER) is 8 bit by
777 // definition
779  size_t frameCount; // number of frames in buffer
780  union {
781  void* raw; // raw pointer to start of buffer
782  int32_t* s32; // pointer to signed 32 bit data at start of buffer
783  int16_t* s16; // pointer to signed 16 bit data at start of buffer
784  uint8_t* u8; // pointer to unsigned 8 bit data at start of buffer
785  };
786 };
787 
788 // The buffer_provider_s structure contains functions that can be used
789 // by the effect engine process() function to query and release input
790 // or output audio buffer.
791 // The getBuffer() function is called to retrieve a buffer where data
792 // should read from or written to by process() function.
793 // The releaseBuffer() function MUST be called when the buffer retrieved
794 // with getBuffer() is not needed anymore.
795 // The process function should use the buffer provider mechanism to retrieve
796 // input or output buffer if the inBuffer or outBuffer passed as argument is NULL
797 // and the buffer configuration (buffer_config_t) given by the EFFECT_CMD_SET_CONFIG
798 // command did not specify an audio buffer.
799 
800 typedef int32_t (* buffer_function_t)(void *cookie, audio_buffer_t *buffer);
801 
802 typedef struct buffer_provider_s {
803  buffer_function_t getBuffer; // retrieve next buffer
804  buffer_function_t releaseBuffer; // release used buffer
805  void *cookie; // for use by client of buffer provider functions
807 
808 
809 // The buffer_config_s structure specifies the input or output audio format
810 // to be used by the effect engine. It is part of the effect_config_t
811 // structure that defines both input and output buffer configurations and is
812 // passed by the EFFECT_CMD_SET_CONFIG or EFFECT_CMD_SET_CONFIG_REVERSE command.
813 typedef struct buffer_config_s {
814  audio_buffer_t buffer; // buffer for use by process() function if not passed explicitly
815  uint32_t samplingRate; // sampling rate
816  uint32_t channels; // channel mask (see audio_channel_mask_t in audio.h)
817  buffer_provider_t bufferProvider; // buffer provider
818  uint8_t format; // Audio format (see audio_format_t in audio.h)
819  uint8_t accessMode; // read/write or accumulate in buffer (effect_buffer_access_e)
820  uint16_t mask; // indicates which of the above fields is valid
822 
823 // Values for "accessMode" field of buffer_config_t:
824 // overwrite, read only, accumulate (read/modify/write)
829 
830 };
831 
832 // feature identifiers for EFFECT_CMD_GET_FEATURE_SUPPORTED_CONFIGS command
834  EFFECT_FEATURE_AUX_CHANNELS, // supports auxiliary channels (e.g. dual mic noise suppressor)
836 };
837 
838 // EFFECT_FEATURE_AUX_CHANNELS feature configuration descriptor. Describe a combination
839 // of main and auxiliary channels supported
840 typedef struct channel_config_s {
841  audio_channel_mask_t main_channels; // channel mask for main channels
842  audio_channel_mask_t aux_channels; // channel mask for auxiliary channels
844 
845 
846 // Values for bit field "mask" in buffer_config_t. If a bit is set, the corresponding field
847 // in buffer_config_t must be taken into account when executing the EFFECT_CMD_SET_CONFIG command
848 #define EFFECT_CONFIG_BUFFER 0x0001 // buffer field must be taken into account
849 #define EFFECT_CONFIG_SMP_RATE 0x0002 // samplingRate field must be taken into account
850 #define EFFECT_CONFIG_CHANNELS 0x0004 // channels field must be taken into account
851 #define EFFECT_CONFIG_FORMAT 0x0008 // format field must be taken into account
852 #define EFFECT_CONFIG_ACC_MODE 0x0010 // accessMode field must be taken into account
853 #define EFFECT_CONFIG_PROVIDER 0x0020 // bufferProvider field must be taken into account
854 #define EFFECT_CONFIG_ALL (EFFECT_CONFIG_BUFFER | EFFECT_CONFIG_SMP_RATE | \
855  EFFECT_CONFIG_CHANNELS | EFFECT_CONFIG_FORMAT | \
856  EFFECT_CONFIG_ACC_MODE | EFFECT_CONFIG_PROVIDER)
857 
858 
859 // effect_config_s structure describes the format of the pCmdData argument of EFFECT_CMD_SET_CONFIG
860 // command to configure audio parameters and buffers for effect engine input and output.
861 typedef struct effect_config_s {
865 
866 
867 // effect_param_s structure describes the format of the pCmdData argument of EFFECT_CMD_SET_PARAM
868 // command and pCmdData and pReplyData of EFFECT_CMD_GET_PARAM command.
869 // psize and vsize represent the actual size of parameter and value.
870 //
871 // NOTE: the start of value field inside the data field is always on a 32 bit boundary:
872 //
873 // +-----------+
874 // | status | sizeof(int)
875 // +-----------+
876 // | psize | sizeof(int)
877 // +-----------+
878 // | vsize | sizeof(int)
879 // +-----------+
880 // | | | |
881 // ~ parameter ~ > psize |
882 // | | | > ((psize - 1)/sizeof(int) + 1) * sizeof(int)
883 // +-----------+ |
884 // | padding | |
885 // +-----------+
886 // | | |
887 // ~ value ~ > vsize
888 // | | |
889 // +-----------+
890 
891 typedef struct effect_param_s {
892  int32_t status; // Transaction status (unused for command, used for reply)
893  uint32_t psize; // Parameter size
894  uint32_t vsize; // Value size
895  char data[]; // Start of Parameter + Value data
897 
898 // structure used by EFFECT_CMD_OFFLOAD command
899 typedef struct effect_offload_param_s {
900  bool isOffload; // true if the playback thread the effect is attached to is offloaded
901  int ioHandle; // io handle of the playback thread the effect is attached to
903 
904 
905 /////////////////////////////////////////////////
906 // Effect library interface
907 /////////////////////////////////////////////////
908 
909 // Effect library interface version 3.0
910 // Note that EffectsFactory.c only checks the major version component, so changes to the minor
911 // number can only be used for fully backwards compatible changes
912 #define EFFECT_LIBRARY_API_VERSION EFFECT_MAKE_API_VERSION(3,0)
913 
914 #define AUDIO_EFFECT_LIBRARY_TAG ((('A') << 24) | (('E') << 16) | (('L') << 8) | ('T'))
915 
916 // Every effect library must have a data structure named AUDIO_EFFECT_LIBRARY_INFO_SYM
917 // and the fields of this data structure must begin with audio_effect_library_t
918 
919 typedef struct audio_effect_library_s {
920  // tag must be initialized to AUDIO_EFFECT_LIBRARY_TAG
921  uint32_t tag;
922  // Version of the effect library API : 0xMMMMmmmm MMMM: Major, mmmm: minor
923  uint32_t version;
924  // Name of this library
925  const char *name;
926  // Author/owner/implementor of the library
927  const char *implementor;
928 
929  ////////////////////////////////////////////////////////////////////////////////
930  //
931  // Function: create_effect
932  //
933  // Description: Creates an effect engine of the specified implementation uuid and
934  // returns an effect control interface on this engine. The function will allocate the
935  // resources for an instance of the requested effect engine and return
936  // a handle on the effect control interface.
937  //
938  // Input:
939  // uuid: pointer to the effect uuid.
940  // sessionId: audio session to which this effect instance will be attached. All effects
941  // created with the same session ID are connected in series and process the same signal
942  // stream. Knowing that two effects are part of the same effect chain can help the
943  // library implement some kind of optimizations.
944  // ioId: identifies the output or input stream this effect is directed to at audio HAL.
945  // For future use especially with tunneled HW accelerated effects
946  //
947  // Input/Output:
948  // pHandle: address where to return the effect interface handle.
949  //
950  // Output:
951  // returned value: 0 successful operation.
952  // -ENODEV library failed to initialize
953  // -EINVAL invalid pEffectUuid or pHandle
954  // -ENOENT no effect with this uuid found
955  // *pHandle: updated with the effect interface handle.
956  //
957  ////////////////////////////////////////////////////////////////////////////////
958  int32_t (*create_effect)(const effect_uuid_t *uuid,
959  int32_t sessionId,
960  int32_t ioId,
961  effect_handle_t *pHandle);
962 
963  ////////////////////////////////////////////////////////////////////////////////
964  //
965  // Function: release_effect
966  //
967  // Description: Releases the effect engine whose handle is given as argument.
968  // All resources allocated to this particular instance of the effect are
969  // released.
970  //
971  // Input:
972  // handle: handle on the effect interface to be released.
973  //
974  // Output:
975  // returned value: 0 successful operation.
976  // -ENODEV library failed to initialize
977  // -EINVAL invalid interface handle
978  //
979  ////////////////////////////////////////////////////////////////////////////////
980  int32_t (*release_effect)(effect_handle_t handle);
981 
982  ////////////////////////////////////////////////////////////////////////////////
983  //
984  // Function: get_descriptor
985  //
986  // Description: Returns the descriptor of the effect engine which implementation UUID is
987  // given as argument.
988  //
989  // Input/Output:
990  // uuid: pointer to the effect uuid.
991  // pDescriptor: address where to return the effect descriptor.
992  //
993  // Output:
994  // returned value: 0 successful operation.
995  // -ENODEV library failed to initialize
996  // -EINVAL invalid pDescriptor or uuid
997  // *pDescriptor: updated with the effect descriptor.
998  //
999  ////////////////////////////////////////////////////////////////////////////////
1000  int32_t (*get_descriptor)(const effect_uuid_t *uuid,
1001  effect_descriptor_t *pDescriptor);
1003 
1004 // Name of the hal_module_info
1005 #define AUDIO_EFFECT_LIBRARY_INFO_SYM AELI
1006 
1007 // Name of the hal_module_info as a string
1008 #define AUDIO_EFFECT_LIBRARY_INFO_SYM_AS_STR "AELI"
1009 
1010 __END_DECLS
1011 
1012 #endif // ANDROID_AUDIO_EFFECT_H