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 */
81struct effect_descriptor_s;
82
83struct 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                        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() */
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                           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
252struct 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                        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 */
418typedef struct audio_policy_module {
419    struct hw_module_t common;
420} audio_policy_module_t;
421
422struct 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
442static 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
449static 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