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/* audio hw module handle used by load_hw_module(), open_output_on_module()
252 * and open_input_on_module() */
253typedef int audio_module_handle_t;
254
255struct audio_policy_service_ops {
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     */
384    audio_module_handle_t (*load_hw_module)(void *service,
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 */
422typedef struct audio_policy_module {
423    struct hw_module_t common;
424} audio_policy_module_t;
425
426struct audio_policy_device {
427    struct hw_device_t common;
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
440static 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
447static 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
456