hardware/audio_policy.h

   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
 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 appropriate for record from the supplied device with
 156      * supplied parameters. */
 157     audio_io_handle_t (*get_input)(struct audio_policy *pol, audio_source_t inputSource,
 158                                    uint32_t samplingRate,
 159                                    audio_format_t format,
 160                                    audio_channel_mask_t channelMask,
 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. The index range for each stream is defined by AudioService. */
 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. The index is within the range specified by init_stream_volume() */
 185     int (*set_stream_volume_index)(struct audio_policy *pol,
 186                                    audio_stream_type_t stream,
 187                                    int index);
 188
 189     /* retrieve 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     /* sets the new stream volume at a level corresponding to the supplied
 195      * index for the specified device.
 196      * The index is within the range specified by init_stream_volume() */
 197     int (*set_stream_volume_index_for_device)(struct audio_policy *pol,
 198                                    audio_stream_type_t stream,
 199                                    int index,
 200                                    audio_devices_t device);
 201
 202     /* retrieve current volume index for the specified stream for the specified device */
 203     int (*get_stream_volume_index_for_device)(const struct audio_policy *pol,
 204                                    audio_stream_type_t stream,
 205                                    int *index,
 206                                    audio_devices_t device);
 207
 208     /* return the strategy corresponding to a given stream type */
 209     uint32_t (*get_strategy_for_stream)(const struct audio_policy *pol,
 210                                         audio_stream_type_t stream);
 211
 212     /* return the enabled output devices for the given stream type */
 213     audio_devices_t (*get_devices_for_stream)(const struct audio_policy *pol,
 214                                        audio_stream_type_t stream);
 215
 216     /* Audio effect management */
 217     audio_io_handle_t (*get_output_for_effect)(struct audio_policy *pol,
 218                                             const struct effect_descriptor_s *desc);
 219
 220     int (*register_effect)(struct audio_policy *pol,
 221                            const struct effect_descriptor_s *desc,
 222                            audio_io_handle_t output,
 223                            uint32_t strategy,
 224                            int session,
 225                            int id);
 226
 227     int (*unregister_effect)(struct audio_policy *pol, int id);
 228
 229     int (*set_effect_enabled)(struct audio_policy *pol, int id, bool enabled);
 230
 231     bool (*is_stream_active)(const struct audio_policy *pol,
 232                              audio_stream_type_t stream,
 233                              uint32_t in_past_ms);
 234
 235     bool (*is_source_active)(const struct audio_policy *pol,
 236                              audio_source_t source);
 237
 238     /* dump state */
 239     int (*dump)(const struct audio_policy *pol, int fd);
 240 };
 241
 242 /* audio hw module handle used by load_hw_module(), open_output_on_module()
 243  * and open_input_on_module() */
 244 typedef int audio_module_handle_t;
 245
 246 struct audio_policy_service_ops {
 247     /*
 248      * Audio output Control functions
 249      */
 250
 251     /* Opens an audio output with the requested parameters.
 252      *
 253      * The parameter values can indicate to use the default values in case the
 254      * audio policy manager has no specific requirements for the output being
 255      * opened.
 256      *
 257      * When the function returns, the parameter values reflect the actual
 258      * values used by the audio hardware output stream.
 259      *
 260      * The audio policy manager can check if the proposed parameters are
 261      * suitable or not and act accordingly.
 262      */
 263     audio_io_handle_t (*open_output)(void *service,
 264                                      audio_devices_t *pDevices,
 265                                      uint32_t *pSamplingRate,
 266                                      audio_format_t *pFormat,
 267                                      audio_channel_mask_t *pChannelMask,
 268                                      uint32_t *pLatencyMs,
 269                                      audio_output_flags_t flags);
 270
 271     /* creates a special output that is duplicated to the two outputs passed as
 272      * arguments. The duplication is performed by
 273      * a special mixer thread in the AudioFlinger.
 274      */
 275     audio_io_handle_t (*open_duplicate_output)(void *service,
 276                                                audio_io_handle_t output1,
 277                                                audio_io_handle_t output2);
 278
 279     /* closes the output stream */
 280     int (*close_output)(void *service, audio_io_handle_t output);
 281
 282     /* suspends the output.
 283      *
 284      * When an output is suspended, the corresponding audio hardware output
 285      * stream is placed in standby and the AudioTracks attached to the mixer
 286      * thread are still processed but the output mix is discarded.
 287      */
 288     int (*suspend_output)(void *service, audio_io_handle_t output);
 289
 290     /* restores a suspended output. */
 291     int (*restore_output)(void *service, audio_io_handle_t output);
 292
 293     /* */
 294     /* Audio input Control functions */
 295     /* */
 296
 297     /* opens an audio input
 298      * deprecated - new implementations should use open_input_on_module,
 299      * and the acoustics parameter is ignored
 300      */
 301     audio_io_handle_t (*open_input)(void *service,
 302                                     audio_devices_t *pDevices,
 303                                     uint32_t *pSamplingRate,
 304                                     audio_format_t *pFormat,
 305                                     audio_channel_mask_t *pChannelMask,
 306                                     audio_in_acoustics_t acoustics);
 307
 308     /* closes an audio input */
 309     int (*close_input)(void *service, audio_io_handle_t input);
 310
 311     /* */
 312     /* misc control functions */
 313     /* */
 314
 315     /* set a stream volume for a particular output.
 316      *
 317      * For the same user setting, a given stream type can have different
 318      * volumes for each output (destination device) it is attached to.
 319      */
 320     int (*set_stream_volume)(void *service,
 321                              audio_stream_type_t stream,
 322                              float volume,
 323                              audio_io_handle_t output,
 324                              int delay_ms);
 325
 326     /* reroute a given stream type to the specified output */
 327     int (*set_stream_output)(void *service,
 328                              audio_stream_type_t stream,
 329                              audio_io_handle_t output);
 330
 331     /* function enabling to send proprietary informations directly from audio
 332      * policy manager to audio hardware interface. */
 333     void (*set_parameters)(void *service,
 334                            audio_io_handle_t io_handle,
 335                            const char *kv_pairs,
 336                            int delay_ms);
 337
 338     /* function enabling to receive proprietary informations directly from
 339      * audio hardware interface to audio policy manager.
 340      *
 341      * Returns a pointer to a heap allocated string. The caller is responsible
 342      * for freeing the memory for it using free().
 343      */
 344
 345     char * (*get_parameters)(void *service, audio_io_handle_t io_handle,
 346                              const char *keys);
 347
 348     /* request the playback of a tone on the specified stream.
 349      * used for instance to replace notification sounds when playing over a
 350      * telephony device during a phone call.
 351      */
 352     int (*start_tone)(void *service,
 353                       audio_policy_tone_t tone,
 354                       audio_stream_type_t stream);
 355
 356     int (*stop_tone)(void *service);
 357
 358     /* set down link audio volume. */
 359     int (*set_voice_volume)(void *service,
 360                             float volume,
 361                             int delay_ms);
 362
 363     /* move effect to the specified output */
 364     int (*move_effects)(void *service,
 365                         int session,
 366                         audio_io_handle_t src_output,
 367                         audio_io_handle_t dst_output);
 368
 369     /* loads an audio hw module.
 370      *
 371      * The module name passed is the base name of the HW module library, e.g "primary" or "a2dp".
 372      * The function returns a handle on the module that will be used to specify a particular
 373      * module when calling open_output_on_module() or open_input_on_module()
 374      */
 375     audio_module_handle_t (*load_hw_module)(void *service,
 376                                               const char *name);
 377
 378     /* Opens an audio output on a particular HW module.
 379      *
 380      * Same as open_output() but specifying a specific HW module on which the output must be opened.
 381      */
 382     audio_io_handle_t (*open_output_on_module)(void *service,
 383                                      audio_module_handle_t module,
 384                                      audio_devices_t *pDevices,
 385                                      uint32_t *pSamplingRate,
 386                                      audio_format_t *pFormat,
 387                                      audio_channel_mask_t *pChannelMask,
 388                                      uint32_t *pLatencyMs,
 389                                      audio_output_flags_t flags);
 390
 391     /* Opens an audio input on a particular HW module.
 392      *
 393      * Same as open_input() but specifying a specific HW module on which the input must be opened.
 394      * Also removed deprecated acoustics parameter
 395      */
 396     audio_io_handle_t (*open_input_on_module)(void *service,
 397                                     audio_module_handle_t module,
 398                                     audio_devices_t *pDevices,
 399                                     uint32_t *pSamplingRate,
 400                                     audio_format_t *pFormat,
 401                                     audio_channel_mask_t *pChannelMask);
 402
 403 };
 404
 405 /**********************************************************************/
 406
 407 /**
 408  * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
 409  * and the fields of this data structure must begin with hw_module_t
 410  * followed by module specific information.
 411  */
 412 typedef struct audio_policy_module {
 413     struct hw_module_t common;
 414 } audio_policy_module_t;
 415
 416 struct audio_policy_device {
 417     struct hw_device_t common;
 418
 419     int (*create_audio_policy)(const struct audio_policy_device *device,
 420                                struct audio_policy_service_ops *aps_ops,
 421                                void *service,
 422                                struct audio_policy **ap);
 423
 424     int (*destroy_audio_policy)(const struct audio_policy_device *device,
 425                                 struct audio_policy *ap);
 426 };
 427
 428 /** convenience API for opening and closing a supported device */
 429
 430 static inline int audio_policy_dev_open(const hw_module_t* module,
 431                                     struct audio_policy_device** device)
 432 {
 433     return module->methods->open(module, AUDIO_POLICY_INTERFACE,
 434                                  (hw_device_t**)device);
 435 }
 436
 437 static inline int audio_policy_dev_close(struct audio_policy_device* device)
 438 {
 439     return device->common.close(&device->common);
 440 }
 441
 442
 443 __END_DECLS
 444
 445 #endif  // ANDROID_AUDIO_POLICY_INTERFACE_H