Android Hardware Abstraction Layer
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 /* audio hw module handle used by load_hw_module(), open_output_on_module()
252  * and open_input_on_module() */
254 
256  /*
257  * Audio output Control functions
258  */
259 
260  /* Opens an audio output with the requested parameters.
261  *
262  * The parameter values can indicate to use the default values in case the
263  * audio policy manager has no specific requirements for the output being
264  * opened.
265  *
266  * When the function returns, the parameter values reflect the actual
267  * values used by the audio hardware output stream.
268  *
269  * The audio policy manager can check if the proposed parameters are
270  * suitable or not and act accordingly.
271  */
272  audio_io_handle_t (*open_output)(void *service,
273  audio_devices_t *pDevices,
274  uint32_t *pSamplingRate,
275  audio_format_t *pFormat,
276  audio_channel_mask_t *pChannelMask,
277  uint32_t *pLatencyMs,
278  audio_output_flags_t flags);
279 
280  /* creates a special output that is duplicated to the two outputs passed as
281  * arguments. The duplication is performed by
282  * a special mixer thread in the AudioFlinger.
283  */
284  audio_io_handle_t (*open_duplicate_output)(void *service,
285  audio_io_handle_t output1,
286  audio_io_handle_t output2);
287 
288  /* closes the output stream */
289  int (*close_output)(void *service, audio_io_handle_t output);
290 
291  /* suspends the output.
292  *
293  * When an output is suspended, the corresponding audio hardware output
294  * stream is placed in standby and the AudioTracks attached to the mixer
295  * thread are still processed but the output mix is discarded.
296  */
297  int (*suspend_output)(void *service, audio_io_handle_t output);
298 
299  /* restores a suspended output. */
300  int (*restore_output)(void *service, audio_io_handle_t output);
301 
302  /* */
303  /* Audio input Control functions */
304  /* */
305 
306  /* opens an audio input
307  * deprecated - new implementations should use open_input_on_module,
308  * and the acoustics parameter is ignored
309  */
310  audio_io_handle_t (*open_input)(void *service,
311  audio_devices_t *pDevices,
312  uint32_t *pSamplingRate,
313  audio_format_t *pFormat,
314  audio_channel_mask_t *pChannelMask,
315  audio_in_acoustics_t acoustics);
316 
317  /* closes an audio input */
318  int (*close_input)(void *service, audio_io_handle_t input);
319 
320  /* */
321  /* misc control functions */
322  /* */
323 
324  /* set a stream volume for a particular output.
325  *
326  * For the same user setting, a given stream type can have different
327  * volumes for each output (destination device) it is attached to.
328  */
329  int (*set_stream_volume)(void *service,
330  audio_stream_type_t stream,
331  float volume,
332  audio_io_handle_t output,
333  int delay_ms);
334 
335  /* reroute a given stream type to the specified output */
336  int (*set_stream_output)(void *service,
337  audio_stream_type_t stream,
338  audio_io_handle_t output);
339 
340  /* function enabling to send proprietary informations directly from audio
341  * policy manager to audio hardware interface. */
342  void (*set_parameters)(void *service,
343  audio_io_handle_t io_handle,
344  const char *kv_pairs,
345  int delay_ms);
346 
347  /* function enabling to receive proprietary informations directly from
348  * audio hardware interface to audio policy manager.
349  *
350  * Returns a pointer to a heap allocated string. The caller is responsible
351  * for freeing the memory for it using free().
352  */
353 
354  char * (*get_parameters)(void *service, audio_io_handle_t io_handle,
355  const char *keys);
356 
357  /* request the playback of a tone on the specified stream.
358  * used for instance to replace notification sounds when playing over a
359  * telephony device during a phone call.
360  */
361  int (*start_tone)(void *service,
362  audio_policy_tone_t tone,
363  audio_stream_type_t stream);
364 
365  int (*stop_tone)(void *service);
366 
367  /* set down link audio volume. */
368  int (*set_voice_volume)(void *service,
369  float volume,
370  int delay_ms);
371 
372  /* move effect to the specified output */
373  int (*move_effects)(void *service,
374  int session,
375  audio_io_handle_t src_output,
376  audio_io_handle_t dst_output);
377 
378  /* loads an audio hw module.
379  *
380  * The module name passed is the base name of the HW module library, e.g "primary" or "a2dp".
381  * The function returns a handle on the module that will be used to specify a particular
382  * module when calling open_output_on_module() or open_input_on_module()
383  */
385  const char *name);
386 
387  /* Opens an audio output on a particular HW module.
388  *
389  * Same as open_output() but specifying a specific HW module on which the output must be opened.
390  */
391  audio_io_handle_t (*open_output_on_module)(void *service,
392  audio_module_handle_t module,
393  audio_devices_t *pDevices,
394  uint32_t *pSamplingRate,
395  audio_format_t *pFormat,
396  audio_channel_mask_t *pChannelMask,
397  uint32_t *pLatencyMs,
398  audio_output_flags_t flags,
399  const audio_offload_info_t *offloadInfo);
400 
401  /* Opens an audio input on a particular HW module.
402  *
403  * Same as open_input() but specifying a specific HW module on which the input must be opened.
404  * Also removed deprecated acoustics parameter
405  */
406  audio_io_handle_t (*open_input_on_module)(void *service,
407  audio_module_handle_t module,
408  audio_devices_t *pDevices,
409  uint32_t *pSamplingRate,
410  audio_format_t *pFormat,
411  audio_channel_mask_t *pChannelMask);
412 
413 };
414 
415 /**********************************************************************/
416 
417 /**
418  * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
419  * and the fields of this data structure must begin with hw_module_t
420  * followed by module specific information.
421  */
422 typedef struct audio_policy_module {
425 
428 
429  int (*create_audio_policy)(const struct audio_policy_device *device,
430  struct audio_policy_service_ops *aps_ops,
431  void *service,
432  struct audio_policy **ap);
433 
434  int (*destroy_audio_policy)(const struct audio_policy_device *device,
435  struct audio_policy *ap);
436 };
437 
438 /** convenience API for opening and closing a supported device */
439 
440 static inline int audio_policy_dev_open(const hw_module_t* module,
441  struct audio_policy_device** device)
442 {
443  return module->methods->open(module, AUDIO_POLICY_INTERFACE,
444  (hw_device_t**)device);
445 }
446 
447 static inline int audio_policy_dev_close(struct audio_policy_device* device)
448 {
449  return device->common.close(&device->common);
450 }
451 
452 
453 __END_DECLS
454 
455 #endif // ANDROID_AUDIO_POLICY_INTERFACE_H