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