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 const audio_offload_info_t *offloadInfo);
138
139 /* indicates to the audio policy manager that the output starts being used
140 * by corresponding stream. */
141 int (*start_output)(struct audio_policy *pol,
142 audio_io_handle_t output,
143 audio_stream_type_t stream,
144 audio_session_t session);
145
146 /* indicates to the audio policy manager that the output stops being used
147 * by corresponding stream. */
148 int (*stop_output)(struct audio_policy *pol,
149 audio_io_handle_t output,
150 audio_stream_type_t stream,
151 audio_session_t session);
152
153 /* releases the output. */
154 void (*release_output)(struct audio_policy *pol, audio_io_handle_t output);
155
156 /* request an input appropriate for record from the supplied device with
157 * supplied parameters. */
158 audio_io_handle_t (*get_input)(struct audio_policy *pol, audio_source_t inputSource,
159 uint32_t samplingRate,
160 audio_format_t format,
161 audio_channel_mask_t channelMask,
162 audio_in_acoustics_t acoustics);
163
164 /* indicates to the audio policy manager that the input starts being used */
165 int (*start_input)(struct audio_policy *pol, audio_io_handle_t input);
166
167 /* indicates to the audio policy manager that the input stops being used. */
168 int (*stop_input)(struct audio_policy *pol, audio_io_handle_t input);
169
170 /* releases the input. */
171 void (*release_input)(struct audio_policy *pol, audio_io_handle_t input);
172
173 /*
174 * volume control functions
175 */
176
177 /* initialises stream volume conversion parameters by specifying volume
178 * index range. The index range for each stream is defined by AudioService. */
179 void (*init_stream_volume)(struct audio_policy *pol,
180 audio_stream_type_t stream,
181 int index_min,
182 int index_max);
183
184 /* sets the new stream volume at a level corresponding to the supplied
185 * index. The index is within the range specified by init_stream_volume() */
186 int (*set_stream_volume_index)(struct audio_policy *pol,
187 audio_stream_type_t stream,
188 int index);
189
190 /* retrieve current volume index for the specified stream */
191 int (*get_stream_volume_index)(const struct audio_policy *pol,
192 audio_stream_type_t stream,
193 int *index);
194
195 /* sets the new stream volume at a level corresponding to the supplied
196 * index for the specified device.
197 * The index is within the range specified by init_stream_volume() */
198 int (*set_stream_volume_index_for_device)(struct audio_policy *pol,
199 audio_stream_type_t stream,
200 int index,
201 audio_devices_t device);
202
203 /* retrieve current volume index for the specified stream for the specified device */
204 int (*get_stream_volume_index_for_device)(const struct audio_policy *pol,
205 audio_stream_type_t stream,
206 int *index,
207 audio_devices_t device);
208
209 /* return the strategy corresponding to a given stream type */
210 uint32_t (*get_strategy_for_stream)(const struct audio_policy *pol,
211 audio_stream_type_t stream);
212
213 /* return the enabled output devices for the given stream type */
214 audio_devices_t (*get_devices_for_stream)(const struct audio_policy *pol,
215 audio_stream_type_t stream);
216
217 /* Audio effect management */
218 audio_io_handle_t (*get_output_for_effect)(struct audio_policy *pol,
219 const struct effect_descriptor_s *desc);
220
221 int (*register_effect)(struct audio_policy *pol,
222 const struct effect_descriptor_s *desc,
223 audio_io_handle_t output,
224 uint32_t strategy,
225 audio_session_t session,
226 int id);
227
228 int (*unregister_effect)(struct audio_policy *pol, int id);
229
230 int (*set_effect_enabled)(struct audio_policy *pol, int id, bool enabled);
231
232 bool (*is_stream_active)(const struct audio_policy *pol,
233 audio_stream_type_t stream,
234 uint32_t in_past_ms);
235
236 bool (*is_stream_active_remotely)(const struct audio_policy *pol,
237 audio_stream_type_t stream,
238 uint32_t in_past_ms);
239
240 bool (*is_source_active)(const struct audio_policy *pol,
241 audio_source_t source);
242
243 /* dump state */
244 int (*dump)(const struct audio_policy *pol, int fd);
245
246 /* check if offload is possible for given sample rate, bitrate, duration, ... */
247 bool (*is_offload_supported)(const struct audio_policy *pol,
248 const audio_offload_info_t *info);
249 };
250
251
252 struct audio_policy_service_ops {
253 /*
254 * Audio output Control functions
255 */
256
257 /* Opens an audio output with the requested parameters.
258 *
259 * The parameter values can indicate to use the default values in case the
260 * audio policy manager has no specific requirements for the output being
261 * opened.
262 *
263 * When the function returns, the parameter values reflect the actual
264 * values used by the audio hardware output stream.
265 *
266 * The audio policy manager can check if the proposed parameters are
267 * suitable or not and act accordingly.
268 */
269 audio_io_handle_t (*open_output)(void *service,
270 audio_devices_t *pDevices,
271 uint32_t *pSamplingRate,
272 audio_format_t *pFormat,
273 audio_channel_mask_t *pChannelMask,
274 uint32_t *pLatencyMs,
275 audio_output_flags_t flags);
276
277 /* creates a special output that is duplicated to the two outputs passed as
278 * arguments. The duplication is performed by
279 * a special mixer thread in the AudioFlinger.
280 */
281 audio_io_handle_t (*open_duplicate_output)(void *service,
282 audio_io_handle_t output1,
283 audio_io_handle_t output2);
284
285 /* closes the output stream */
286 int (*close_output)(void *service, audio_io_handle_t output);
287
288 /* suspends the output.
289 *
290 * When an output is suspended, the corresponding audio hardware output
291 * stream is placed in standby and the AudioTracks attached to the mixer
292 * thread are still processed but the output mix is discarded.
293 */
294 int (*suspend_output)(void *service, audio_io_handle_t output);
295
296 /* restores a suspended output. */
297 int (*restore_output)(void *service, audio_io_handle_t output);
298
299 /* */
300 /* Audio input Control functions */
301 /* */
302
303 /* opens an audio input
304 * deprecated - new implementations should use open_input_on_module,
305 * and the acoustics parameter is ignored
306 */
307 audio_io_handle_t (*open_input)(void *service,
308 audio_devices_t *pDevices,
309 uint32_t *pSamplingRate,
310 audio_format_t *pFormat,
311 audio_channel_mask_t *pChannelMask,
312 audio_in_acoustics_t acoustics);
313
314 /* closes an audio input */
315 int (*close_input)(void *service, audio_io_handle_t input);
316
317 /* */
318 /* misc control functions */
319 /* */
320
321 /* set a stream volume for a particular output.
322 *
323 * For the same user setting, a given stream type can have different
324 * volumes for each output (destination device) it is attached to.
325 */
326 int (*set_stream_volume)(void *service,
327 audio_stream_type_t stream,
328 float volume,
329 audio_io_handle_t output,
330 int delay_ms);
331
332 /* invalidate a stream type, causing a reroute to an unspecified new output */
333 int (*invalidate_stream)(void *service,
334 audio_stream_type_t stream);
335
336 /* function enabling to send proprietary informations directly from audio
337 * policy manager to audio hardware interface. */
338 void (*set_parameters)(void *service,
339 audio_io_handle_t io_handle,
340 const char *kv_pairs,
341 int delay_ms);
342
343 /* function enabling to receive proprietary informations directly from
344 * audio hardware interface to audio policy manager.
345 *
346 * Returns a pointer to a heap allocated string. The caller is responsible
347 * for freeing the memory for it using free().
348 */
349
350 char * (*get_parameters)(void *service, audio_io_handle_t io_handle,
351 const char *keys);
352
353 /* request the playback of a tone on the specified stream.
354 * used for instance to replace notification sounds when playing over a
355 * telephony device during a phone call.
356 */
357 int (*start_tone)(void *service,
358 audio_policy_tone_t tone,
359 audio_stream_type_t stream);
360
361 int (*stop_tone)(void *service);
362
363 /* set down link audio volume. */
364 int (*set_voice_volume)(void *service,
365 float volume,
366 int delay_ms);
367
368 /* move effect to the specified output */
369 int (*move_effects)(void *service,
370 audio_session_t session,
371 audio_io_handle_t src_output,
372 audio_io_handle_t dst_output);
373
374 /* loads an audio hw module.
375 *
376 * The module name passed is the base name of the HW module library, e.g "primary" or "a2dp".
377 * The function returns a handle on the module that will be used to specify a particular
378 * module when calling open_output_on_module() or open_input_on_module()
379 */
380 audio_module_handle_t (*load_hw_module)(void *service,
381 const char *name);
382
383 /* Opens an audio output on a particular HW module.
384 *
385 * Same as open_output() but specifying a specific HW module on which the output must be opened.
386 */
387 audio_io_handle_t (*open_output_on_module)(void *service,
388 audio_module_handle_t module,
389 audio_devices_t *pDevices,
390 uint32_t *pSamplingRate,
391 audio_format_t *pFormat,
392 audio_channel_mask_t *pChannelMask,
393 uint32_t *pLatencyMs,
394 audio_output_flags_t flags,
395 const audio_offload_info_t *offloadInfo);
396
397 /* Opens an audio input on a particular HW module.
398 *
399 * Same as open_input() but specifying a specific HW module on which the input must be opened.
400 * Also removed deprecated acoustics parameter
401 */
402 audio_io_handle_t (*open_input_on_module)(void *service,
403 audio_module_handle_t module,
404 audio_devices_t *pDevices,
405 uint32_t *pSamplingRate,
406 audio_format_t *pFormat,
407 audio_channel_mask_t *pChannelMask);
408
409 };
410
411 /**********************************************************************/
412
413 /**
414 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
415 * and the fields of this data structure must begin with hw_module_t
416 * followed by module specific information.
417 */
418 typedef struct audio_policy_module {
419 struct hw_module_t common;
420 } audio_policy_module_t;
421
422 struct audio_policy_device {
423 /**
424 * Common methods of the audio policy device. This *must* be the first member of
425 * audio_policy_device as users of this structure will cast a hw_device_t to
426 * audio_policy_device pointer in contexts where it's known the hw_device_t references an
427 * audio_policy_device.
428 */
429 struct hw_device_t common;
430
431 int (*create_audio_policy)(const struct audio_policy_device *device,
432 struct audio_policy_service_ops *aps_ops,
433 void *service,
434 struct audio_policy **ap);
435
436 int (*destroy_audio_policy)(const struct audio_policy_device *device,
437 struct audio_policy *ap);
438 };
439
440 /** convenience API for opening and closing a supported device */
441
audio_policy_dev_open(const hw_module_t * module,struct audio_policy_device ** device)442 static inline int audio_policy_dev_open(const hw_module_t* module,
443 struct audio_policy_device** device)
444 {
445 return module->methods->open(module, AUDIO_POLICY_INTERFACE,
446 (hw_device_t**)device);
447 }
448
audio_policy_dev_close(struct audio_policy_device * device)449 static inline int audio_policy_dev_close(struct audio_policy_device* device)
450 {
451 return device->common.close(&device->common);
452 }
453
454
455 __END_DECLS
456
457 #endif // ANDROID_AUDIO_POLICY_INTERFACE_H
458