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