Commit | Line | Data |
---|---|---|
1e494cf4 JB |
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_POLICY_INTERFACE_H | |
19 | #define ANDROID_AUDIO_POLICY_INTERFACE_H | |
20 | ||
21 | #include <stdint.h> | |
22 | #include <sys/cdefs.h> | |
23 | #include <sys/types.h> | |
24 | ||
25 | #include <hardware/hardware.h> | |
26 | ||
27 | #include <system/audio.h> | |
28 | #include <system/audio_policy.h> | |
29 | ||
30 | __BEGIN_DECLS | |
31 | ||
32 | /** | |
33 | * The id of this module | |
34 | */ | |
35 | #define AUDIO_POLICY_HARDWARE_MODULE_ID "audio_policy" | |
36 | ||
37 | /** | |
38 | * Name of the audio devices to open | |
39 | */ | |
40 | #define AUDIO_POLICY_INTERFACE "policy" | |
41 | ||
42 | /* ---------------------------------------------------------------------------- */ | |
43 | ||
44 | /* | |
45 | * The audio_policy and audio_policy_service_ops structs define the | |
46 | * communication interfaces between the platform specific audio policy manager | |
47 | * and Android generic audio policy manager. | |
48 | * The platform specific audio policy manager must implement methods of the | |
49 | * audio_policy struct. | |
50 | * This implementation makes use of the audio_policy_service_ops to control | |
51 | * the activity and configuration of audio input and output streams. | |
52 | * | |
53 | * The platform specific audio policy manager is in charge of the audio | |
54 | * routing and volume control policies for a given platform. | |
55 | * The main roles of this module are: | |
56 | * - keep track of current system state (removable device connections, phone | |
57 | * state, user requests...). | |
58 | * System state changes and user actions are notified to audio policy | |
59 | * manager with methods of the audio_policy. | |
60 | * | |
61 | * - process get_output() queries received when AudioTrack objects are | |
62 | * created: Those queries return a handler on an output that has been | |
63 | * selected, configured and opened by the audio policy manager and that | |
64 | * must be used by the AudioTrack when registering to the AudioFlinger | |
65 | * with the createTrack() method. | |
66 | * When the AudioTrack object is released, a release_output() query | |
67 | * is received and the audio policy manager can decide to close or | |
68 | * reconfigure the output depending on other streams using this output and | |
69 | * current system state. | |
70 | * | |
71 | * - similarly process get_input() and release_input() queries received from | |
72 | * AudioRecord objects and configure audio inputs. | |
73 | * - process volume control requests: the stream volume is converted from | |
74 | * an index value (received from UI) to a float value applicable to each | |
75 | * output as a function of platform specific settings and current output | |
76 | * route (destination device). It also make sure that streams are not | |
77 | * muted if not allowed (e.g. camera shutter sound in some countries). | |
78 | */ | |
79 | ||
80 | /* XXX: this should be defined OUTSIDE of frameworks/base */ | |
81 | struct effect_descriptor_s; | |
82 | ||
83 | struct audio_policy { | |
84 | /* | |
85 | * configuration functions | |
86 | */ | |
87 | ||
88 | /* indicate a change in device connection status */ | |
89 | int (*set_device_connection_state)(struct audio_policy *pol, | |
90 | audio_devices_t device, | |
91 | audio_policy_dev_state_t state, | |
92 | const char *device_address); | |
93 | ||
94 | /* retrieve a device connection status */ | |
95 | audio_policy_dev_state_t (*get_device_connection_state)( | |
96 | const struct audio_policy *pol, | |
97 | audio_devices_t device, | |
98 | const char *device_address); | |
99 | ||
100 | /* indicate a change in phone state. Valid phones states are defined | |
101 | * by audio_mode_t */ | |
102 | void (*set_phone_state)(struct audio_policy *pol, audio_mode_t state); | |
103 | ||
104 | /* deprecated, never called (was "indicate a change in ringer mode") */ | |
105 | void (*set_ringer_mode)(struct audio_policy *pol, uint32_t mode, | |
106 | uint32_t mask); | |
107 | ||
108 | /* force using a specific device category for the specified usage */ | |
109 | void (*set_force_use)(struct audio_policy *pol, | |
110 | audio_policy_force_use_t usage, | |
111 | audio_policy_forced_cfg_t config); | |
112 | ||
113 | /* retrieve current device category forced for a given usage */ | |
114 | audio_policy_forced_cfg_t (*get_force_use)(const struct audio_policy *pol, | |
115 | audio_policy_force_use_t usage); | |
116 | ||
117 | /* if can_mute is true, then audio streams that are marked ENFORCED_AUDIBLE | |
118 | * can still be muted. */ | |
119 | void (*set_can_mute_enforced_audible)(struct audio_policy *pol, | |
120 | bool can_mute); | |
121 | ||
122 | /* check proper initialization */ | |
123 | int (*init_check)(const struct audio_policy *pol); | |
124 | ||
125 | /* | |
126 | * Audio routing query functions | |
127 | */ | |
128 | ||
129 | /* request an output appropriate for playback of the supplied stream type and | |
130 | * parameters */ | |
131 | audio_io_handle_t (*get_output)(struct audio_policy *pol, | |
132 | audio_stream_type_t stream, | |
133 | uint32_t samplingRate, | |
134 | audio_format_t format, | |
135 | audio_channel_mask_t channelMask, | |
136 | audio_output_flags_t flags); | |
137 | ||
138 | /* indicates to the audio policy manager that the output starts being used | |
139 | * by corresponding stream. */ | |
140 | int (*start_output)(struct audio_policy *pol, | |
141 | audio_io_handle_t output, | |
142 | audio_stream_type_t stream, | |
143 | int session); | |
144 | ||
145 | /* indicates to the audio policy manager that the output stops being used | |
146 | * by corresponding stream. */ | |
147 | int (*stop_output)(struct audio_policy *pol, | |
148 | audio_io_handle_t output, | |
149 | audio_stream_type_t stream, | |
150 | int session); | |
151 | ||
152 | /* releases the output. */ | |
153 | void (*release_output)(struct audio_policy *pol, audio_io_handle_t output); | |
154 | ||
155 | /* request an input appropriate for record from the supplied device with | |
156 | * supplied parameters. */ | |
157 | audio_io_handle_t (*get_input)(struct audio_policy *pol, audio_source_t inputSource, | |
158 | uint32_t samplingRate, | |
159 | audio_format_t format, | |
160 | audio_channel_mask_t channelMask, | |
161 | audio_in_acoustics_t acoustics); | |
162 | ||
163 | /* indicates to the audio policy manager that the input starts being used */ | |
164 | int (*start_input)(struct audio_policy *pol, audio_io_handle_t input); | |
165 | ||
166 | /* indicates to the audio policy manager that the input stops being used. */ | |
167 | int (*stop_input)(struct audio_policy *pol, audio_io_handle_t input); | |
168 | ||
169 | /* releases the input. */ | |
170 | void (*release_input)(struct audio_policy *pol, audio_io_handle_t input); | |
171 | ||
172 | /* | |
173 | * volume control functions | |
174 | */ | |
175 | ||
176 | /* initialises stream volume conversion parameters by specifying volume | |
177 | * index range. The index range for each stream is defined by AudioService. */ | |
178 | void (*init_stream_volume)(struct audio_policy *pol, | |
179 | audio_stream_type_t stream, | |
180 | int index_min, | |
181 | int index_max); | |
182 | ||
183 | /* sets the new stream volume at a level corresponding to the supplied | |
184 | * index. The index is within the range specified by init_stream_volume() */ | |
185 | int (*set_stream_volume_index)(struct audio_policy *pol, | |
186 | audio_stream_type_t stream, | |
187 | int index); | |
188 | ||
189 | /* retrieve current volume index for the specified stream */ | |
190 | int (*get_stream_volume_index)(const struct audio_policy *pol, | |
191 | audio_stream_type_t stream, | |
192 | int *index); | |
193 | ||
194 | /* sets the new stream volume at a level corresponding to the supplied | |
195 | * index for the specified device. | |
196 | * The index is within the range specified by init_stream_volume() */ | |
197 | int (*set_stream_volume_index_for_device)(struct audio_policy *pol, | |
198 | audio_stream_type_t stream, | |
199 | int index, | |
200 | audio_devices_t device); | |
201 | ||
202 | /* retrieve current volume index for the specified stream for the specified device */ | |
203 | int (*get_stream_volume_index_for_device)(const struct audio_policy *pol, | |
204 | audio_stream_type_t stream, | |
205 | int *index, | |
206 | audio_devices_t device); | |
207 | ||
208 | /* return the strategy corresponding to a given stream type */ | |
209 | uint32_t (*get_strategy_for_stream)(const struct audio_policy *pol, | |
210 | audio_stream_type_t stream); | |
211 | ||
212 | /* return the enabled output devices for the given stream type */ | |
213 | audio_devices_t (*get_devices_for_stream)(const struct audio_policy *pol, | |
214 | audio_stream_type_t stream); | |
215 | ||
216 | /* Audio effect management */ | |
217 | audio_io_handle_t (*get_output_for_effect)(struct audio_policy *pol, | |
218 | const struct effect_descriptor_s *desc); | |
219 | ||
220 | int (*register_effect)(struct audio_policy *pol, | |
221 | const struct effect_descriptor_s *desc, | |
222 | audio_io_handle_t output, | |
223 | uint32_t strategy, | |
224 | int session, | |
225 | int id); | |
226 | ||
227 | int (*unregister_effect)(struct audio_policy *pol, int id); | |
228 | ||
229 | int (*set_effect_enabled)(struct audio_policy *pol, int id, bool enabled); | |
230 | ||
231 | bool (*is_stream_active)(const struct audio_policy *pol, | |
232 | audio_stream_type_t stream, | |
233 | uint32_t in_past_ms); | |
234 | ||
235 | bool (*is_source_active)(const struct audio_policy *pol, | |
236 | audio_source_t source); | |
237 | ||
238 | /* dump state */ | |
239 | int (*dump)(const struct audio_policy *pol, int fd); | |
240 | }; | |
241 | ||
242 | /* audio hw module handle used by load_hw_module(), open_output_on_module() | |
243 | * and open_input_on_module() */ | |
244 | typedef int audio_module_handle_t; | |
245 | ||
246 | struct audio_policy_service_ops { | |
247 | /* | |
248 | * Audio output Control functions | |
249 | */ | |
250 | ||
251 | /* Opens an audio output with the requested parameters. | |
252 | * | |
253 | * The parameter values can indicate to use the default values in case the | |
254 | * audio policy manager has no specific requirements for the output being | |
255 | * opened. | |
256 | * | |
257 | * When the function returns, the parameter values reflect the actual | |
258 | * values used by the audio hardware output stream. | |
259 | * | |
260 | * The audio policy manager can check if the proposed parameters are | |
261 | * suitable or not and act accordingly. | |
262 | */ | |
263 | audio_io_handle_t (*open_output)(void *service, | |
264 | audio_devices_t *pDevices, | |
265 | uint32_t *pSamplingRate, | |
266 | audio_format_t *pFormat, | |
267 | audio_channel_mask_t *pChannelMask, | |
268 | uint32_t *pLatencyMs, | |
269 | audio_output_flags_t flags); | |
270 | ||
271 | /* creates a special output that is duplicated to the two outputs passed as | |
272 | * arguments. The duplication is performed by | |
273 | * a special mixer thread in the AudioFlinger. | |
274 | */ | |
275 | audio_io_handle_t (*open_duplicate_output)(void *service, | |
276 | audio_io_handle_t output1, | |
277 | audio_io_handle_t output2); | |
278 | ||
279 | /* closes the output stream */ | |
280 | int (*close_output)(void *service, audio_io_handle_t output); | |
281 | ||
282 | /* suspends the output. | |
283 | * | |
284 | * When an output is suspended, the corresponding audio hardware output | |
285 | * stream is placed in standby and the AudioTracks attached to the mixer | |
286 | * thread are still processed but the output mix is discarded. | |
287 | */ | |
288 | int (*suspend_output)(void *service, audio_io_handle_t output); | |
289 | ||
290 | /* restores a suspended output. */ | |
291 | int (*restore_output)(void *service, audio_io_handle_t output); | |
292 | ||
293 | /* */ | |
294 | /* Audio input Control functions */ | |
295 | /* */ | |
296 | ||
297 | /* opens an audio input | |
298 | * deprecated - new implementations should use open_input_on_module, | |
299 | * and the acoustics parameter is ignored | |
300 | */ | |
301 | audio_io_handle_t (*open_input)(void *service, | |
302 | audio_devices_t *pDevices, | |
303 | uint32_t *pSamplingRate, | |
304 | audio_format_t *pFormat, | |
305 | audio_channel_mask_t *pChannelMask, | |
306 | audio_in_acoustics_t acoustics); | |
307 | ||
308 | /* closes an audio input */ | |
309 | int (*close_input)(void *service, audio_io_handle_t input); | |
310 | ||
311 | /* */ | |
312 | /* misc control functions */ | |
313 | /* */ | |
314 | ||
315 | /* set a stream volume for a particular output. | |
316 | * | |
317 | * For the same user setting, a given stream type can have different | |
318 | * volumes for each output (destination device) it is attached to. | |
319 | */ | |
320 | int (*set_stream_volume)(void *service, | |
321 | audio_stream_type_t stream, | |
322 | float volume, | |
323 | audio_io_handle_t output, | |
324 | int delay_ms); | |
325 | ||
326 | /* reroute a given stream type to the specified output */ | |
327 | int (*set_stream_output)(void *service, | |
328 | audio_stream_type_t stream, | |
329 | audio_io_handle_t output); | |
330 | ||
331 | /* function enabling to send proprietary informations directly from audio | |
332 | * policy manager to audio hardware interface. */ | |
333 | void (*set_parameters)(void *service, | |
334 | audio_io_handle_t io_handle, | |
335 | const char *kv_pairs, | |
336 | int delay_ms); | |
337 | ||
338 | /* function enabling to receive proprietary informations directly from | |
339 | * audio hardware interface to audio policy manager. | |
340 | * | |
341 | * Returns a pointer to a heap allocated string. The caller is responsible | |
342 | * for freeing the memory for it using free(). | |
343 | */ | |
344 | ||
345 | char * (*get_parameters)(void *service, audio_io_handle_t io_handle, | |
346 | const char *keys); | |
347 | ||
348 | /* request the playback of a tone on the specified stream. | |
349 | * used for instance to replace notification sounds when playing over a | |
350 | * telephony device during a phone call. | |
351 | */ | |
352 | int (*start_tone)(void *service, | |
353 | audio_policy_tone_t tone, | |
354 | audio_stream_type_t stream); | |
355 | ||
356 | int (*stop_tone)(void *service); | |
357 | ||
358 | /* set down link audio volume. */ | |
359 | int (*set_voice_volume)(void *service, | |
360 | float volume, | |
361 | int delay_ms); | |
362 | ||
363 | /* move effect to the specified output */ | |
364 | int (*move_effects)(void *service, | |
365 | int session, | |
366 | audio_io_handle_t src_output, | |
367 | audio_io_handle_t dst_output); | |
368 | ||
369 | /* loads an audio hw module. | |
370 | * | |
371 | * The module name passed is the base name of the HW module library, e.g "primary" or "a2dp". | |
372 | * The function returns a handle on the module that will be used to specify a particular | |
373 | * module when calling open_output_on_module() or open_input_on_module() | |
374 | */ | |
375 | audio_module_handle_t (*load_hw_module)(void *service, | |
376 | const char *name); | |
377 | ||
378 | /* Opens an audio output on a particular HW module. | |
379 | * | |
380 | * Same as open_output() but specifying a specific HW module on which the output must be opened. | |
381 | */ | |
382 | audio_io_handle_t (*open_output_on_module)(void *service, | |
383 | audio_module_handle_t module, | |
384 | audio_devices_t *pDevices, | |
385 | uint32_t *pSamplingRate, | |
386 | audio_format_t *pFormat, | |
387 | audio_channel_mask_t *pChannelMask, | |
388 | uint32_t *pLatencyMs, | |
389 | audio_output_flags_t flags); | |
390 | ||
391 | /* Opens an audio input on a particular HW module. | |
392 | * | |
393 | * Same as open_input() but specifying a specific HW module on which the input must be opened. | |
394 | * Also removed deprecated acoustics parameter | |
395 | */ | |
396 | audio_io_handle_t (*open_input_on_module)(void *service, | |
397 | audio_module_handle_t module, | |
398 | audio_devices_t *pDevices, | |
399 | uint32_t *pSamplingRate, | |
400 | audio_format_t *pFormat, | |
401 | audio_channel_mask_t *pChannelMask); | |
402 | ||
403 | }; | |
404 | ||
405 | /**********************************************************************/ | |
406 | ||
407 | /** | |
408 | * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM | |
409 | * and the fields of this data structure must begin with hw_module_t | |
410 | * followed by module specific information. | |
411 | */ | |
412 | typedef struct audio_policy_module { | |
413 | struct hw_module_t common; | |
414 | } audio_policy_module_t; | |
415 | ||
416 | struct audio_policy_device { | |
417 | struct hw_device_t common; | |
418 | ||
419 | int (*create_audio_policy)(const struct audio_policy_device *device, | |
420 | struct audio_policy_service_ops *aps_ops, | |
421 | void *service, | |
422 | struct audio_policy **ap); | |
423 | ||
424 | int (*destroy_audio_policy)(const struct audio_policy_device *device, | |
425 | struct audio_policy *ap); | |
426 | }; | |
427 | ||
428 | /** convenience API for opening and closing a supported device */ | |
429 | ||
430 | static inline int audio_policy_dev_open(const hw_module_t* module, | |
431 | struct audio_policy_device** device) | |
432 | { | |
433 | return module->methods->open(module, AUDIO_POLICY_INTERFACE, | |
434 | (hw_device_t**)device); | |
435 | } | |
436 | ||
437 | static inline int audio_policy_dev_close(struct audio_policy_device* device) | |
438 | { | |
439 | return device->common.close(&device->common); | |
440 | } | |
441 | ||
442 | ||
443 | __END_DECLS | |
444 | ||
445 | #endif // ANDROID_AUDIO_POLICY_INTERFACE_H |