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