hardware/audio.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_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