Home | History | Annotate | Download | only in hardware
      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     /* 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() */
    253 typedef int audio_module_handle_t;
    254 
    255 struct 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  */
    422 typedef struct audio_policy_module {
    423     struct hw_module_t common;
    424 } audio_policy_module_t;
    425 
    426 struct 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 
    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
    456