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 /* retreive 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, int state);
103
104 /* 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 /* retreive 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 appriate 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 uint32_t format,
135 uint32_t channels,
136 audio_policy_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 appriate for record from the supplied device with
156 * supplied parameters. */
157 audio_io_handle_t (*get_input)(struct audio_policy *pol, int inputSource,
158 uint32_t samplingRate,
159 uint32_t format,
160 uint32_t channels,
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. */
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 */
185 int (*set_stream_volume_index)(struct audio_policy *pol,
186 audio_stream_type_t stream,
187 int index);
188
189 /* retreive 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 /* return the strategy corresponding to a given stream type */
195 uint32_t (*get_strategy_for_stream)(const struct audio_policy *pol,
196 audio_stream_type_t stream);
197
198 /* return the enabled output devices for the given stream type */
199 uint32_t (*get_devices_for_stream)(const struct audio_policy *pol,
200 audio_stream_type_t stream);
201
202 /* Audio effect management */
203 audio_io_handle_t (*get_output_for_effect)(struct audio_policy *pol,
204 struct effect_descriptor_s *desc);
205
206 int (*register_effect)(struct audio_policy *pol,
207 struct effect_descriptor_s *desc,
208 audio_io_handle_t output,
209 uint32_t strategy,
210 int session,
211 int id);
212
213 int (*unregister_effect)(struct audio_policy *pol, int id);
214
215 int (*set_effect_enabled)(struct audio_policy *pol, int id, bool enabled);
216
217 bool (*is_stream_active)(const struct audio_policy *pol,
218 int stream,
219 uint32_t in_past_ms);
220
221 /* dump state */
222 int (*dump)(const struct audio_policy *pol, int fd);
223 };
224
225 struct audio_policy_service_ops {
226 /*
227 * Audio output Control functions
228 */
229
230 /* Opens an audio output with the requested parameters.
231 *
232 * The parameter values can indicate to use the default values in case the
233 * audio policy manager has no specific requirements for the output being
234 * opened.
235 *
236 * When the function returns, the parameter values reflect the actual
237 * values used by the audio hardware output stream.
238 *
239 * The audio policy manager can check if the proposed parameters are
240 * suitable or not and act accordingly.
241 */
242 audio_io_handle_t (*open_output)(void *service,
243 uint32_t *pDevices,
244 uint32_t *pSamplingRate,
245 uint32_t *pFormat,
246 uint32_t *pChannels,
247 uint32_t *pLatencyMs,
248 audio_policy_output_flags_t flags);
249
250 /* creates a special output that is duplicated to the two outputs passed as
251 * arguments. The duplication is performed by
252 * a special mixer thread in the AudioFlinger.
253 */
254 audio_io_handle_t (*open_duplicate_output)(void *service,
255 audio_io_handle_t output1,
256 audio_io_handle_t output2);
257
258 /* closes the output stream */
259 int (*close_output)(void *service, audio_io_handle_t output);
260
261 /* suspends the output.
262 *
263 * When an output is suspended, the corresponding audio hardware output
264 * stream is placed in standby and the AudioTracks attached to the mixer
265 * thread are still processed but the output mix is discarded.
266 */
267 int (*suspend_output)(void *service, audio_io_handle_t output);
268
269 /* restores a suspended output. */
270 int (*restore_output)(void *service, audio_io_handle_t output);
271
272 /* */
273 /* Audio input Control functions */
274 /* */
275
276 /* opens an audio input */
277 audio_io_handle_t (*open_input)(void *service,
278 uint32_t *pDevices,
279 uint32_t *pSamplingRate,
280 uint32_t *pFormat,
281 uint32_t *pChannels,
282 uint32_t acoustics);
283
284 /* closes an audio input */
285 int (*close_input)(void *service, audio_io_handle_t input);
286
287 /* */
288 /* misc control functions */
289 /* */
290
291 /* set a stream volume for a particular output.
292 *
293 * For the same user setting, a given stream type can have different
294 * volumes for each output (destination device) it is attached to.
295 */
296 int (*set_stream_volume)(void *service,
297 audio_stream_type_t stream,
298 float volume,
299 audio_io_handle_t output,
300 int delay_ms);
301
302 /* reroute a given stream type to the specified output */
303 int (*set_stream_output)(void *service,
304 audio_stream_type_t stream,
305 audio_io_handle_t output);
306
307 /* function enabling to send proprietary informations directly from audio
308 * policy manager to audio hardware interface. */
309 void (*set_parameters)(void *service,
310 audio_io_handle_t io_handle,
311 const char *kv_pairs,
312 int delay_ms);
313
314 /* function enabling to receive proprietary informations directly from
315 * audio hardware interface to audio policy manager.
316 *
317 * Returns a pointer to a heap allocated string. The caller is responsible
318 * for freeing the memory for it.
319 */
320
321 char * (*get_parameters)(void *service, audio_io_handle_t io_handle,
322 const char *keys);
323
324 /* request the playback of a tone on the specified stream.
325 * used for instance to replace notification sounds when playing over a
326 * telephony device during a phone call.
327 */
328 int (*start_tone)(void *service,
329 audio_policy_tone_t tone,
330 audio_stream_type_t stream);
331
332 int (*stop_tone)(void *service);
333
334 /* set down link audio volume. */
335 int (*set_voice_volume)(void *service,
336 float volume,
337 int delay_ms);
338
339 /* move effect to the specified output */
340 int (*move_effects)(void *service,
341 int session,
342 audio_io_handle_t src_output,
343 audio_io_handle_t dst_output);
344 };
345
346 /**********************************************************************/
347
348 /**
349 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
350 * and the fields of this data structure must begin with hw_module_t
351 * followed by module specific information.
352 */
353 typedef struct audio_policy_module {
354 struct hw_module_t common;
355 } audio_policy_module_t;
356
357 struct audio_policy_device {
358 struct hw_device_t common;
359
360 int (*create_audio_policy)(const struct audio_policy_device *device,
361 struct audio_policy_service_ops *aps_ops,
362 void *service,
363 struct audio_policy **ap);
364
365 int (*destroy_audio_policy)(const struct audio_policy_device *device,
366 struct audio_policy *ap);
367 };
368
369 /** convenience API for opening and closing a supported device */
370
audio_policy_dev_open(const hw_module_t * module,struct audio_policy_device ** device)371 static inline int audio_policy_dev_open(const hw_module_t* module,
372 struct audio_policy_device** device)
373 {
374 return module->methods->open(module, AUDIO_POLICY_INTERFACE,
375 (hw_device_t**)device);
376 }
377
audio_policy_dev_close(struct audio_policy_device * device)378 static inline int audio_policy_dev_close(struct audio_policy_device* device)
379 {
380 return device->common.close(&device->common);
381 }
382
383
384 __END_DECLS
385
386 #endif // ANDROID_AUDIO_POLICY_INTERFACE_H
387