audio_policy.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_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 */
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. */
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  int 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  int 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() */
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() */
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 */
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  int 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 
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  int 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 {
421 
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  */
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 
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 
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
bool(* is_stream_active_remotely)(const struct audio_policy *pol, audio_stream_type_t stream, uint32_t in_past_ms)
Definition: audio_policy.h:236
audio_module_handle_t(* load_hw_module)(void *service, const char *name)
Definition: audio_policy.h:380
bool(* is_stream_active)(const struct audio_policy *pol, audio_stream_type_t stream, uint32_t in_past_ms)
Definition: audio_policy.h:232
int(* open)(const struct hw_module_t *module, const char *id, struct hw_device_t **device)
Definition: hardware.h:158
int(* destroy_audio_policy)(const struct audio_policy_device *device, struct audio_policy *ap)
Definition: audio_policy.h:436
int(* stop_input)(struct audio_policy *pol, audio_io_handle_t input)
Definition: audio_policy.h:168
int(* start_output)(struct audio_policy *pol, audio_io_handle_t output, audio_stream_type_t stream, int session)
Definition: audio_policy.h:141
int(* get_stream_volume_index)(const struct audio_policy *pol, audio_stream_type_t stream, int *index)
Definition: audio_policy.h:191
int(* create_audio_policy)(const struct audio_policy_device *device, struct audio_policy_service_ops *aps_ops, void *service, struct audio_policy **ap)
Definition: audio_policy.h:431
audio_policy_forced_cfg_t(* get_force_use)(const struct audio_policy *pol, audio_policy_force_use_t usage)
Definition: audio_policy.h:114
void(* set_can_mute_enforced_audible)(struct audio_policy *pol, bool can_mute)
Definition: audio_policy.h:119
int(* start_tone)(void *service, audio_policy_tone_t tone, audio_stream_type_t stream)
Definition: audio_policy.h:357
int(* close)(struct hw_device_t *device)
Definition: hardware.h:200
int(* dump)(const struct audio_policy *pol, int fd)
Definition: audio_policy.h:244
void(* set_force_use)(struct audio_policy *pol, audio_policy_force_use_t usage, audio_policy_forced_cfg_t config)
Definition: audio_policy.h:109
int(* set_stream_volume_index)(struct audio_policy *pol, audio_stream_type_t stream, int index)
Definition: audio_policy.h:186
int(* init_check)(const struct audio_policy *pol)
Definition: audio_policy.h:123
int(* close_output)(void *service, audio_io_handle_t output)
Definition: audio_policy.h:286
bool(* is_source_active)(const struct audio_policy *pol, audio_source_t source)
Definition: audio_policy.h:240
uint32_t(* get_strategy_for_stream)(const struct audio_policy *pol, audio_stream_type_t stream)
Definition: audio_policy.h:210
int(* register_effect)(struct audio_policy *pol, const struct effect_descriptor_s *desc, audio_io_handle_t output, uint32_t strategy, int session, int id)
Definition: audio_policy.h:221
void(* set_phone_state)(struct audio_policy *pol, audio_mode_t state)
Definition: audio_policy.h:102
int(* set_stream_volume)(void *service, audio_stream_type_t stream, float volume, audio_io_handle_t output, int delay_ms)
Definition: audio_policy.h:326
int(* get_stream_volume_index_for_device)(const struct audio_policy *pol, audio_stream_type_t stream, int *index, audio_devices_t device)
Definition: audio_policy.h:204
int(* stop_tone)(void *service)
Definition: audio_policy.h:361
int(* set_effect_enabled)(struct audio_policy *pol, int id, bool enabled)
Definition: audio_policy.h:230
int(* unregister_effect)(struct audio_policy *pol, int id)
Definition: audio_policy.h:228
audio_io_handle_t(* open_duplicate_output)(void *service, audio_io_handle_t output1, audio_io_handle_t output2)
Definition: audio_policy.h:281
int(* suspend_output)(void *service, audio_io_handle_t output)
Definition: audio_policy.h:294
audio_io_handle_t(* open_output)(void *service, audio_devices_t *pDevices, uint32_t *pSamplingRate, audio_format_t *pFormat, audio_channel_mask_t *pChannelMask, uint32_t *pLatencyMs, audio_output_flags_t flags)
Definition: audio_policy.h:269
audio_io_handle_t(* open_input)(void *service, audio_devices_t *pDevices, uint32_t *pSamplingRate, audio_format_t *pFormat, audio_channel_mask_t *pChannelMask, audio_in_acoustics_t acoustics)
Definition: audio_policy.h:307
audio_devices_t(* get_devices_for_stream)(const struct audio_policy *pol, audio_stream_type_t stream)
Definition: audio_policy.h:214
void(* set_ringer_mode)(struct audio_policy *pol, uint32_t mode, uint32_t mask)
Definition: audio_policy.h:105
int(* start_input)(struct audio_policy *pol, audio_io_handle_t input)
Definition: audio_policy.h:165
audio_io_handle_t(* open_output_on_module)(void *service, audio_module_handle_t module, audio_devices_t *pDevices, uint32_t *pSamplingRate, audio_format_t *pFormat, audio_channel_mask_t *pChannelMask, uint32_t *pLatencyMs, audio_output_flags_t flags, const audio_offload_info_t *offloadInfo)
Definition: audio_policy.h:387
bool(* is_offload_supported)(const struct audio_policy *pol, const audio_offload_info_t *info)
Definition: audio_policy.h:247
audio_io_handle_t(* open_input_on_module)(void *service, audio_module_handle_t module, audio_devices_t *pDevices, uint32_t *pSamplingRate, audio_format_t *pFormat, audio_channel_mask_t *pChannelMask)
Definition: audio_policy.h:402
struct hw_device_t common
Definition: audio_policy.h:429
void(* set_parameters)(void *service, audio_io_handle_t io_handle, const char *kv_pairs, int delay_ms)
Definition: audio_policy.h:338
struct audio_policy_module audio_policy_module_t
struct hw_module_methods_t * methods
Definition: hardware.h:142
audio_policy_dev_state_t(* get_device_connection_state)(const struct audio_policy *pol, audio_devices_t device, const char *device_address)
Definition: audio_policy.h:95
void(* release_output)(struct audio_policy *pol, audio_io_handle_t output)
Definition: audio_policy.h:154
int(* close_input)(void *service, audio_io_handle_t input)
Definition: audio_policy.h:315
struct hw_module_t common
Definition: audio_policy.h:419
#define AUDIO_POLICY_INTERFACE
Definition: audio_policy.h:40
void(* init_stream_volume)(struct audio_policy *pol, audio_stream_type_t stream, int index_min, int index_max)
Definition: audio_policy.h:179
int(* restore_output)(void *service, audio_io_handle_t output)
Definition: audio_policy.h:297
int(* invalidate_stream)(void *service, audio_stream_type_t stream)
Definition: audio_policy.h:333
int(* set_device_connection_state)(struct audio_policy *pol, audio_devices_t device, audio_policy_dev_state_t state, const char *device_address)
Definition: audio_policy.h:89
void(* release_input)(struct audio_policy *pol, audio_io_handle_t input)
Definition: audio_policy.h:171
audio_io_handle_t(* get_input)(struct audio_policy *pol, audio_source_t inputSource, uint32_t samplingRate, audio_format_t format, audio_channel_mask_t channelMask, audio_in_acoustics_t acoustics)
Definition: audio_policy.h:158
audio_io_handle_t(* get_output_for_effect)(struct audio_policy *pol, const struct effect_descriptor_s *desc)
Definition: audio_policy.h:218
int(* set_voice_volume)(void *service, float volume, int delay_ms)
Definition: audio_policy.h:364
int(* stop_output)(struct audio_policy *pol, audio_io_handle_t output, audio_stream_type_t stream, int session)
Definition: audio_policy.h:148
int(* move_effects)(void *service, int session, audio_io_handle_t src_output, audio_io_handle_t dst_output)
Definition: audio_policy.h:369
int(* set_stream_volume_index_for_device)(struct audio_policy *pol, audio_stream_type_t stream, int index, audio_devices_t device)
Definition: audio_policy.h:198
audio_io_handle_t(* get_output)(struct audio_policy *pol, audio_stream_type_t stream, uint32_t samplingRate, audio_format_t format, audio_channel_mask_t channelMask, audio_output_flags_t flags, const audio_offload_info_t *offloadInfo)
Definition: audio_policy.h:131