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_HAL_INTERFACE_H 19 #define ANDROID_AUDIO_HAL_INTERFACE_H 20 21 #include <stdint.h> 22 #include <strings.h> 23 #include <sys/cdefs.h> 24 #include <sys/types.h> 25 26 #include <cutils/bitops.h> 27 28 #include <hardware/hardware.h> 29 #include <system/audio.h> 30 #include <hardware/audio_effect.h> 31 32 __BEGIN_DECLS 33 34 /** 35 * The id of this module 36 */ 37 #define AUDIO_HARDWARE_MODULE_ID "audio" 38 39 /** 40 * Name of the audio devices to open 41 */ 42 #define AUDIO_HARDWARE_INTERFACE "audio_hw_if" 43 44 45 /* Use version 0.1 to be compatible with first generation of audio hw module with version_major 46 * hardcoded to 1. No audio module API change. 47 */ 48 #define AUDIO_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1) 49 #define AUDIO_MODULE_API_VERSION_CURRENT AUDIO_MODULE_API_VERSION_0_1 50 51 /* First generation of audio devices had version hardcoded to 0. all devices with versions < 1.0 52 * will be considered of first generation API. 53 */ 54 #define AUDIO_DEVICE_API_VERSION_0_0 HARDWARE_DEVICE_API_VERSION(0, 0) 55 #define AUDIO_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0) 56 #define AUDIO_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0) 57 #define AUDIO_DEVICE_API_VERSION_CURRENT AUDIO_DEVICE_API_VERSION_2_0 58 59 /** 60 * List of known audio HAL modules. This is the base name of the audio HAL 61 * library composed of the "audio." prefix, one of the base names below and 62 * a suffix specific to the device. 63 * e.g: audio.primary.goldfish.so or audio.a2dp.default.so 64 */ 65 66 #define AUDIO_HARDWARE_MODULE_ID_PRIMARY "primary" 67 #define AUDIO_HARDWARE_MODULE_ID_A2DP "a2dp" 68 #define AUDIO_HARDWARE_MODULE_ID_USB "usb" 69 #define AUDIO_HARDWARE_MODULE_ID_REMOTE_SUBMIX "r_submix" 70 71 /**************************************/ 72 73 /** 74 * standard audio parameters that the HAL may need to handle 75 */ 76 77 /** 78 * audio device parameters 79 */ 80 81 /* BT SCO Noise Reduction + Echo Cancellation parameters */ 82 #define AUDIO_PARAMETER_KEY_BT_NREC "bt_headset_nrec" 83 #define AUDIO_PARAMETER_VALUE_ON "on" 84 #define AUDIO_PARAMETER_VALUE_OFF "off" 85 86 /* TTY mode selection */ 87 #define AUDIO_PARAMETER_KEY_TTY_MODE "tty_mode" 88 #define AUDIO_PARAMETER_VALUE_TTY_OFF "tty_off" 89 #define AUDIO_PARAMETER_VALUE_TTY_VCO "tty_vco" 90 #define AUDIO_PARAMETER_VALUE_TTY_HCO "tty_hco" 91 #define AUDIO_PARAMETER_VALUE_TTY_FULL "tty_full" 92 93 /* A2DP sink address set by framework */ 94 #define AUDIO_PARAMETER_A2DP_SINK_ADDRESS "a2dp_sink_address" 95 96 /* Screen state */ 97 #define AUDIO_PARAMETER_KEY_SCREEN_STATE "screen_state" 98 99 /** 100 * audio stream parameters 101 */ 102 103 #define AUDIO_PARAMETER_STREAM_ROUTING "routing" // audio_devices_t 104 #define AUDIO_PARAMETER_STREAM_FORMAT "format" // audio_format_t 105 #define AUDIO_PARAMETER_STREAM_CHANNELS "channels" // audio_channel_mask_t 106 #define AUDIO_PARAMETER_STREAM_FRAME_COUNT "frame_count" // size_t 107 #define AUDIO_PARAMETER_STREAM_INPUT_SOURCE "input_source" // audio_source_t 108 #define AUDIO_PARAMETER_STREAM_SAMPLING_RATE "sampling_rate" // uint32_t 109 110 /* Query supported formats. The response is a '|' separated list of strings from 111 * audio_format_t enum e.g: "sup_formats=AUDIO_FORMAT_PCM_16_BIT" */ 112 #define AUDIO_PARAMETER_STREAM_SUP_FORMATS "sup_formats" 113 /* Query supported channel masks. The response is a '|' separated list of strings from 114 * audio_channel_mask_t enum e.g: "sup_channels=AUDIO_CHANNEL_OUT_STEREO|AUDIO_CHANNEL_OUT_MONO" */ 115 #define AUDIO_PARAMETER_STREAM_SUP_CHANNELS "sup_channels" 116 /* Query supported sampling rates. The response is a '|' separated list of integer values e.g: 117 * "sup_sampling_rates=44100|48000" */ 118 #define AUDIO_PARAMETER_STREAM_SUP_SAMPLING_RATES "sup_sampling_rates" 119 120 121 /**************************************/ 122 123 /* common audio stream configuration parameters */ 124 struct audio_config { 125 uint32_t sample_rate; 126 audio_channel_mask_t channel_mask; 127 audio_format_t format; 128 }; 129 130 typedef struct audio_config audio_config_t; 131 132 /* common audio stream parameters and operations */ 133 struct audio_stream { 134 135 /** 136 * Return the sampling rate in Hz - eg. 44100. 137 */ 138 uint32_t (*get_sample_rate)(const struct audio_stream *stream); 139 140 /* currently unused - use set_parameters with key 141 * AUDIO_PARAMETER_STREAM_SAMPLING_RATE 142 */ 143 int (*set_sample_rate)(struct audio_stream *stream, uint32_t rate); 144 145 /** 146 * Return size of input/output buffer in bytes for this stream - eg. 4800. 147 * It should be a multiple of the frame size. See also get_input_buffer_size. 148 */ 149 size_t (*get_buffer_size)(const struct audio_stream *stream); 150 151 /** 152 * Return the channel mask - 153 * e.g. AUDIO_CHANNEL_OUT_STEREO or AUDIO_CHANNEL_IN_STEREO 154 */ 155 audio_channel_mask_t (*get_channels)(const struct audio_stream *stream); 156 157 /** 158 * Return the audio format - e.g. AUDIO_FORMAT_PCM_16_BIT 159 */ 160 audio_format_t (*get_format)(const struct audio_stream *stream); 161 162 /* currently unused - use set_parameters with key 163 * AUDIO_PARAMETER_STREAM_FORMAT 164 */ 165 int (*set_format)(struct audio_stream *stream, audio_format_t format); 166 167 /** 168 * Put the audio hardware input/output into standby mode. 169 * Driver should exit from standby mode at the next I/O operation. 170 * Returns 0 on success and <0 on failure. 171 */ 172 int (*standby)(struct audio_stream *stream); 173 174 /** dump the state of the audio input/output device */ 175 int (*dump)(const struct audio_stream *stream, int fd); 176 177 /** Return the set of device(s) which this stream is connected to */ 178 audio_devices_t (*get_device)(const struct audio_stream *stream); 179 180 /** 181 * Currently unused - set_device() corresponds to set_parameters() with key 182 * AUDIO_PARAMETER_STREAM_ROUTING for both input and output. 183 * AUDIO_PARAMETER_STREAM_INPUT_SOURCE is an additional information used by 184 * input streams only. 185 */ 186 int (*set_device)(struct audio_stream *stream, audio_devices_t device); 187 188 /** 189 * set/get audio stream parameters. The function accepts a list of 190 * parameter key value pairs in the form: key1=value1;key2=value2;... 191 * 192 * Some keys are reserved for standard parameters (See AudioParameter class) 193 * 194 * If the implementation does not accept a parameter change while 195 * the output is active but the parameter is acceptable otherwise, it must 196 * return -ENOSYS. 197 * 198 * The audio flinger will put the stream in standby and then change the 199 * parameter value. 200 */ 201 int (*set_parameters)(struct audio_stream *stream, const char *kv_pairs); 202 203 /* 204 * Returns a pointer to a heap allocated string. The caller is responsible 205 * for freeing the memory for it using free(). 206 */ 207 char * (*get_parameters)(const struct audio_stream *stream, 208 const char *keys); 209 int (*add_audio_effect)(const struct audio_stream *stream, 210 effect_handle_t effect); 211 int (*remove_audio_effect)(const struct audio_stream *stream, 212 effect_handle_t effect); 213 }; 214 typedef struct audio_stream audio_stream_t; 215 216 /** 217 * audio_stream_out is the abstraction interface for the audio output hardware. 218 * 219 * It provides information about various properties of the audio output 220 * hardware driver. 221 */ 222 223 struct audio_stream_out { 224 struct audio_stream common; 225 226 /** 227 * Return the audio hardware driver estimated latency in milliseconds. 228 */ 229 uint32_t (*get_latency)(const struct audio_stream_out *stream); 230 231 /** 232 * Use this method in situations where audio mixing is done in the 233 * hardware. This method serves as a direct interface with hardware, 234 * allowing you to directly set the volume as apposed to via the framework. 235 * This method might produce multiple PCM outputs or hardware accelerated 236 * codecs, such as MP3 or AAC. 237 */ 238 int (*set_volume)(struct audio_stream_out *stream, float left, float right); 239 240 /** 241 * Write audio buffer to driver. Returns number of bytes written, or a 242 * negative status_t. If at least one frame was written successfully prior to the error, 243 * it is suggested that the driver return that successful (short) byte count 244 * and then return an error in the subsequent call. 245 */ 246 ssize_t (*write)(struct audio_stream_out *stream, const void* buffer, 247 size_t bytes); 248 249 /* return the number of audio frames written by the audio dsp to DAC since 250 * the output has exited standby 251 */ 252 int (*get_render_position)(const struct audio_stream_out *stream, 253 uint32_t *dsp_frames); 254 255 /** 256 * get the local time at which the next write to the audio driver will be presented. 257 * The units are microseconds, where the epoch is decided by the local audio HAL. 258 */ 259 int (*get_next_write_timestamp)(const struct audio_stream_out *stream, 260 int64_t *timestamp); 261 262 }; 263 typedef struct audio_stream_out audio_stream_out_t; 264 265 struct audio_stream_in { 266 struct audio_stream common; 267 268 /** set the input gain for the audio driver. This method is for 269 * for future use */ 270 int (*set_gain)(struct audio_stream_in *stream, float gain); 271 272 /** Read audio buffer in from audio driver. Returns number of bytes read, or a 273 * negative status_t. If at least one frame was read prior to the error, 274 * read should return that byte count and then return an error in the subsequent call. 275 */ 276 ssize_t (*read)(struct audio_stream_in *stream, void* buffer, 277 size_t bytes); 278 279 /** 280 * Return the amount of input frames lost in the audio driver since the 281 * last call of this function. 282 * Audio driver is expected to reset the value to 0 and restart counting 283 * upon returning the current value by this function call. 284 * Such loss typically occurs when the user space process is blocked 285 * longer than the capacity of audio driver buffers. 286 * 287 * Unit: the number of input audio frames 288 */ 289 uint32_t (*get_input_frames_lost)(struct audio_stream_in *stream); 290 }; 291 typedef struct audio_stream_in audio_stream_in_t; 292 293 /** 294 * return the frame size (number of bytes per sample). 295 */ 296 static inline size_t audio_stream_frame_size(const struct audio_stream *s) 297 { 298 size_t chan_samp_sz; 299 300 switch (s->get_format(s)) { 301 case AUDIO_FORMAT_PCM_16_BIT: 302 chan_samp_sz = sizeof(int16_t); 303 break; 304 case AUDIO_FORMAT_PCM_8_BIT: 305 default: 306 chan_samp_sz = sizeof(int8_t); 307 break; 308 } 309 310 return popcount(s->get_channels(s)) * chan_samp_sz; 311 } 312 313 314 /**********************************************************************/ 315 316 /** 317 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM 318 * and the fields of this data structure must begin with hw_module_t 319 * followed by module specific information. 320 */ 321 struct audio_module { 322 struct hw_module_t common; 323 }; 324 325 struct audio_hw_device { 326 struct hw_device_t common; 327 328 /** 329 * used by audio flinger to enumerate what devices are supported by 330 * each audio_hw_device implementation. 331 * 332 * Return value is a bitmask of 1 or more values of audio_devices_t 333 * 334 * NOTE: audio HAL implementations starting with 335 * AUDIO_DEVICE_API_VERSION_2_0 do not implement this function. 336 * All supported devices should be listed in audio_policy.conf 337 * file and the audio policy manager must choose the appropriate 338 * audio module based on information in this file. 339 */ 340 uint32_t (*get_supported_devices)(const struct audio_hw_device *dev); 341 342 /** 343 * check to see if the audio hardware interface has been initialized. 344 * returns 0 on success, -ENODEV on failure. 345 */ 346 int (*init_check)(const struct audio_hw_device *dev); 347 348 /** set the audio volume of a voice call. Range is between 0.0 and 1.0 */ 349 int (*set_voice_volume)(struct audio_hw_device *dev, float volume); 350 351 /** 352 * set the audio volume for all audio activities other than voice call. 353 * Range between 0.0 and 1.0. If any value other than 0 is returned, 354 * the software mixer will emulate this capability. 355 */ 356 int (*set_master_volume)(struct audio_hw_device *dev, float volume); 357 358 /** 359 * Get the current master volume value for the HAL, if the HAL supports 360 * master volume control. AudioFlinger will query this value from the 361 * primary audio HAL when the service starts and use the value for setting 362 * the initial master volume across all HALs. HALs which do not support 363 * this method may leave it set to NULL. 364 */ 365 int (*get_master_volume)(struct audio_hw_device *dev, float *volume); 366 367 /** 368 * set_mode is called when the audio mode changes. AUDIO_MODE_NORMAL mode 369 * is for standard audio playback, AUDIO_MODE_RINGTONE when a ringtone is 370 * playing, and AUDIO_MODE_IN_CALL when a call is in progress. 371 */ 372 int (*set_mode)(struct audio_hw_device *dev, audio_mode_t mode); 373 374 /* mic mute */ 375 int (*set_mic_mute)(struct audio_hw_device *dev, bool state); 376 int (*get_mic_mute)(const struct audio_hw_device *dev, bool *state); 377 378 /* set/get global audio parameters */ 379 int (*set_parameters)(struct audio_hw_device *dev, const char *kv_pairs); 380 381 /* 382 * Returns a pointer to a heap allocated string. The caller is responsible 383 * for freeing the memory for it using free(). 384 */ 385 char * (*get_parameters)(const struct audio_hw_device *dev, 386 const char *keys); 387 388 /* Returns audio input buffer size according to parameters passed or 389 * 0 if one of the parameters is not supported. 390 * See also get_buffer_size which is for a particular stream. 391 */ 392 size_t (*get_input_buffer_size)(const struct audio_hw_device *dev, 393 const struct audio_config *config); 394 395 /** This method creates and opens the audio hardware output stream */ 396 int (*open_output_stream)(struct audio_hw_device *dev, 397 audio_io_handle_t handle, 398 audio_devices_t devices, 399 audio_output_flags_t flags, 400 struct audio_config *config, 401 struct audio_stream_out **stream_out); 402 403 void (*close_output_stream)(struct audio_hw_device *dev, 404 struct audio_stream_out* stream_out); 405 406 /** This method creates and opens the audio hardware input stream */ 407 int (*open_input_stream)(struct audio_hw_device *dev, 408 audio_io_handle_t handle, 409 audio_devices_t devices, 410 struct audio_config *config, 411 struct audio_stream_in **stream_in); 412 413 void (*close_input_stream)(struct audio_hw_device *dev, 414 struct audio_stream_in *stream_in); 415 416 /** This method dumps the state of the audio hardware */ 417 int (*dump)(const struct audio_hw_device *dev, int fd); 418 419 /** 420 * set the audio mute status for all audio activities. If any value other 421 * than 0 is returned, the software mixer will emulate this capability. 422 */ 423 int (*set_master_mute)(struct audio_hw_device *dev, bool mute); 424 425 /** 426 * Get the current master mute status for the HAL, if the HAL supports 427 * master mute control. AudioFlinger will query this value from the primary 428 * audio HAL when the service starts and use the value for setting the 429 * initial master mute across all HALs. HALs which do not support this 430 * method may leave it set to NULL. 431 */ 432 int (*get_master_mute)(struct audio_hw_device *dev, bool *mute); 433 }; 434 typedef struct audio_hw_device audio_hw_device_t; 435 436 /** convenience API for opening and closing a supported device */ 437 438 static inline int audio_hw_device_open(const struct hw_module_t* module, 439 struct audio_hw_device** device) 440 { 441 return module->methods->open(module, AUDIO_HARDWARE_INTERFACE, 442 (struct hw_device_t**)device); 443 } 444 445 static inline int audio_hw_device_close(struct audio_hw_device* device) 446 { 447 return device->common.close(&device->common); 448 } 449 450 451 __END_DECLS 452 453 #endif // ANDROID_AUDIO_INTERFACE_H 454
