1/*
2 * Copyright (C) 2016 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
17package android.hardware.audio.effect@2.0;
18
19import android.hardware.audio.common@2.0;
20
21enum 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_")
113enum 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 */
202struct 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    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 */
225struct 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_")
232enum 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_")
242enum 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    ALL = BUFFER | SMP_RATE | CHANNELS | FORMAT | ACC_MODE
249};
250
251/**
252 * The buffer config structure specifies the input or output audio format
253 * to be used by the effect engine.
254 */
255struct EffectBufferConfig {
256    AudioBuffer buffer;
257    uint32_t samplingRateHz;
258    AudioChannelMask channels;
259    AudioFormat format;
260    EffectBufferAccess accessMode;
261    EffectConfigParameters mask;
262};
263
264struct EffectConfig {
265    EffectBufferConfig inputCfg;
266    EffectBufferConfig outputCfg;
267};
268
269@export(name="effect_feature_e", value_prefix="EFFECT_FEATURE_")
270enum EffectFeature : int32_t {
271    AUX_CHANNELS, // supports auxiliary channels
272                  // (e.g. dual mic noise suppressor)
273    CNT
274};
275
276struct EffectAuxChannelsConfig {
277    AudioChannelMask mainChannels;  // channel mask for main channels
278    AudioChannelMask auxChannels;   // channel mask for auxiliary channels
279};
280
281struct 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 */
292enum 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