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
