android/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 <hardware/hardware.h>
  27 #include <system/audio.h>
  28 #include <hardware/audio_effect.h>
  29
  30 __BEGIN_DECLS
  31
  32 /**
  33  * The id of this module
  34  */
  35 #define AUDIO_HARDWARE_MODULE_ID "audio"
  36
  37 /**
  38  * Name of the audio devices to open
  39  */
  40 #define AUDIO_HARDWARE_INTERFACE "audio_hw_if"
  41
  42
  43 /* Use version 0.1 to be compatible with first generation of audio hw module with version_major
  44  * hardcoded to 1. No audio module API change.
  45  */
  46 #define AUDIO_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1)
  47 #define AUDIO_MODULE_API_VERSION_CURRENT AUDIO_MODULE_API_VERSION_0_1
  48
  49 /* First generation of audio devices had version hardcoded to 0. all devices with versions < 1.0
  50  * will be considered of first generation API.
  51  */
  52 #define AUDIO_DEVICE_API_VERSION_0_0 HARDWARE_DEVICE_API_VERSION(0, 0)
  53 #define AUDIO_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0)
  54 #define AUDIO_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0)
  55 #define AUDIO_DEVICE_API_VERSION_3_0 HARDWARE_DEVICE_API_VERSION(3, 0)
  56 #define AUDIO_DEVICE_API_VERSION_CURRENT AUDIO_DEVICE_API_VERSION_3_0
  57 /* Minimal audio HAL version supported by the audio framework */
  58 #define AUDIO_DEVICE_API_VERSION_MIN AUDIO_DEVICE_API_VERSION_2_0
  59
  60 /**
  61  * List of known audio HAL modules. This is the base name of the audio HAL
  62  * library composed of the "audio." prefix, one of the base names below and
  63  * a suffix specific to the device.
  64  * e.g: audio.primary.goldfish.so or audio.a2dp.default.so
  65  */
  66
  67 #define AUDIO_HARDWARE_MODULE_ID_PRIMARY "primary"
  68 #define AUDIO_HARDWARE_MODULE_ID_A2DP "a2dp"
  69 #define AUDIO_HARDWARE_MODULE_ID_USB "usb"
  70 #define AUDIO_HARDWARE_MODULE_ID_REMOTE_SUBMIX "r_submix"
  71 #define AUDIO_HARDWARE_MODULE_ID_CODEC_OFFLOAD "codec_offload"
  72
  73 /**************************************/
  74
  75 /**
  76  *  standard audio parameters that the HAL may need to handle
  77  */
  78
  79 /**
  80  *  audio device parameters
  81  */
  82
  83 /* BT SCO Noise Reduction + Echo Cancellation parameters */
  84 #define AUDIO_PARAMETER_KEY_BT_NREC "bt_headset_nrec"
  85 #define AUDIO_PARAMETER_VALUE_ON "on"
  86 #define AUDIO_PARAMETER_VALUE_OFF "off"
  87
  88 /* TTY mode selection */
  89 #define AUDIO_PARAMETER_KEY_TTY_MODE "tty_mode"
  90 #define AUDIO_PARAMETER_VALUE_TTY_OFF "tty_off"
  91 #define AUDIO_PARAMETER_VALUE_TTY_VCO "tty_vco"
  92 #define AUDIO_PARAMETER_VALUE_TTY_HCO "tty_hco"
  93 #define AUDIO_PARAMETER_VALUE_TTY_FULL "tty_full"
  94
  95 /* Hearing Aid Compatibility - Telecoil (HAC-T) mode on/off
  96    Strings must be in sync with CallFeaturesSetting.java */
  97 #define AUDIO_PARAMETER_KEY_HAC "HACSetting"
  98 #define AUDIO_PARAMETER_VALUE_HAC_ON "ON"
  99 #define AUDIO_PARAMETER_VALUE_HAC_OFF "OFF"
 100
 101 /* A2DP sink address set by framework */
 102 #define AUDIO_PARAMETER_A2DP_SINK_ADDRESS "a2dp_sink_address"
 103
 104 /* A2DP source address set by framework */
 105 #define AUDIO_PARAMETER_A2DP_SOURCE_ADDRESS "a2dp_source_address"
 106
 107 /* Screen state */
 108 #define AUDIO_PARAMETER_KEY_SCREEN_STATE "screen_state"
 109
 110 /* Bluetooth SCO wideband */
 111 #define AUDIO_PARAMETER_KEY_BT_SCO_WB "bt_wbs"
 112
 113
 114 /**
 115  *  audio stream parameters
 116  */
 117
 118 #define AUDIO_PARAMETER_STREAM_ROUTING "routing"             /* audio_devices_t */
 119 #define AUDIO_PARAMETER_STREAM_FORMAT "format"               /* audio_format_t */
 120 #define AUDIO_PARAMETER_STREAM_CHANNELS "channels"           /* audio_channel_mask_t */
 121 #define AUDIO_PARAMETER_STREAM_FRAME_COUNT "frame_count"     /* size_t */
 122 #define AUDIO_PARAMETER_STREAM_INPUT_SOURCE "input_source"   /* audio_source_t */
 123 #define AUDIO_PARAMETER_STREAM_SAMPLING_RATE "sampling_rate" /* uint32_t */
 124
 125 #define AUDIO_PARAMETER_DEVICE_DISCONNECT "disconnect"      /* audio_devices_t */
 126
 127 /* Query supported formats. The response is a '|' separated list of strings from
 128  * audio_format_t enum e.g: "sup_formats=AUDIO_FORMAT_PCM_16_BIT" */
 129 #define AUDIO_PARAMETER_STREAM_SUP_FORMATS "sup_formats"
 130 /* Query supported channel masks. The response is a '|' separated list of strings from
 131  * audio_channel_mask_t enum e.g: "sup_channels=AUDIO_CHANNEL_OUT_STEREO|AUDIO_CHANNEL_OUT_MONO" */
 132 #define AUDIO_PARAMETER_STREAM_SUP_CHANNELS "sup_channels"
 133 /* Query supported sampling rates. The response is a '|' separated list of integer values e.g:
 134  * "sup_sampling_rates=44100|48000" */
 135 #define AUDIO_PARAMETER_STREAM_SUP_SAMPLING_RATES "sup_sampling_rates"
 136
 137 /* Get the HW synchronization source used for an output stream.
 138  * Return a valid source (positive integer) or AUDIO_HW_SYNC_INVALID if an error occurs
 139  * or no HW sync source is used. */
 140 #define AUDIO_PARAMETER_STREAM_HW_AV_SYNC "hw_av_sync"
 141
 142 /**
 143  * audio codec parameters
 144  */
 145
 146 #define AUDIO_OFFLOAD_CODEC_PARAMS "music_offload_codec_param"
 147 #define AUDIO_OFFLOAD_CODEC_BIT_PER_SAMPLE "music_offload_bit_per_sample"
 148 #define AUDIO_OFFLOAD_CODEC_BIT_RATE "music_offload_bit_rate"
 149 #define AUDIO_OFFLOAD_CODEC_AVG_BIT_RATE "music_offload_avg_bit_rate"
 150 #define AUDIO_OFFLOAD_CODEC_ID "music_offload_codec_id"
 151 #define AUDIO_OFFLOAD_CODEC_BLOCK_ALIGN "music_offload_block_align"
 152 #define AUDIO_OFFLOAD_CODEC_SAMPLE_RATE "music_offload_sample_rate"
 153 #define AUDIO_OFFLOAD_CODEC_ENCODE_OPTION "music_offload_encode_option"
 154 #define AUDIO_OFFLOAD_CODEC_NUM_CHANNEL  "music_offload_num_channels"
 155 #define AUDIO_OFFLOAD_CODEC_DOWN_SAMPLING  "music_offload_down_sampling"
 156 #define AUDIO_OFFLOAD_CODEC_DELAY_SAMPLES  "delay_samples"
 157 #define AUDIO_OFFLOAD_CODEC_PADDING_SAMPLES  "padding_samples"
 158
 159 /**************************************/
 160
 161 /* common audio stream parameters and operations */
 162 struct audio_stream {
 163
 164     /**
 165      * Return the sampling rate in Hz - eg. 44100.
 166      */
 167     uint32_t (*get_sample_rate)(const struct audio_stream *stream);
 168
 169     /* currently unused - use set_parameters with key
 170      *    AUDIO_PARAMETER_STREAM_SAMPLING_RATE
 171      */
 172     int (*set_sample_rate)(struct audio_stream *stream, uint32_t rate);
 173
 174     /**
 175      * Return size of input/output buffer in bytes for this stream - eg. 4800.
 176      * It should be a multiple of the frame size.  See also get_input_buffer_size.
 177      */
 178     size_t (*get_buffer_size)(const struct audio_stream *stream);
 179
 180     /**
 181      * Return the channel mask -
 182      *  e.g. AUDIO_CHANNEL_OUT_STEREO or AUDIO_CHANNEL_IN_STEREO
 183      */
 184     audio_channel_mask_t (*get_channels)(const struct audio_stream *stream);
 185
 186     /**
 187      * Return the audio format - e.g. AUDIO_FORMAT_PCM_16_BIT
 188      */
 189     audio_format_t (*get_format)(const struct audio_stream *stream);
 190
 191     /* currently unused - use set_parameters with key
 192      *     AUDIO_PARAMETER_STREAM_FORMAT
 193      */
 194     int (*set_format)(struct audio_stream *stream, audio_format_t format);
 195
 196     /**
 197      * Put the audio hardware input/output into standby mode.
 198      * Driver should exit from standby mode at the next I/O operation.
 199      * Returns 0 on success and <0 on failure.
 200      */
 201     int (*standby)(struct audio_stream *stream);
 202
 203     /** dump the state of the audio input/output device */
 204     int (*dump)(const struct audio_stream *stream, int fd);
 205
 206     /** Return the set of device(s) which this stream is connected to */
 207     audio_devices_t (*get_device)(const struct audio_stream *stream);
 208
 209     /**
 210      * Currently unused - set_device() corresponds to set_parameters() with key
 211      * AUDIO_PARAMETER_STREAM_ROUTING for both input and output.
 212      * AUDIO_PARAMETER_STREAM_INPUT_SOURCE is an additional information used by
 213      * input streams only.
 214      */
 215     int (*set_device)(struct audio_stream *stream, audio_devices_t device);
 216
 217     /**
 218      * set/get audio stream parameters. The function accepts a list of
 219      * parameter key value pairs in the form: key1=value1;key2=value2;...
 220      *
 221      * Some keys are reserved for standard parameters (See AudioParameter class)
 222      *
 223      * If the implementation does not accept a parameter change while
 224      * the output is active but the parameter is acceptable otherwise, it must
 225      * return -ENOSYS.
 226      *
 227      * The audio flinger will put the stream in standby and then change the
 228      * parameter value.
 229      */
 230     int (*set_parameters)(struct audio_stream *stream, const char *kv_pairs);
 231
 232     /*
 233      * Returns a pointer to a heap allocated string. The caller is responsible
 234      * for freeing the memory for it using free().
 235      */
 236     char * (*get_parameters)(const struct audio_stream *stream,
 237                              const char *keys);
 238     int (*add_audio_effect)(const struct audio_stream *stream,
 239                              effect_handle_t effect);
 240     int (*remove_audio_effect)(const struct audio_stream *stream,
 241                              effect_handle_t effect);
 242 };
 243 typedef struct audio_stream audio_stream_t;
 244
 245 /* type of asynchronous write callback events. Mutually exclusive */
 246 typedef enum {
 247     STREAM_CBK_EVENT_WRITE_READY, /* non blocking write completed */
 248     STREAM_CBK_EVENT_DRAIN_READY  /* drain completed */
 249 } stream_callback_event_t;
 250
 251 typedef int (*stream_callback_t)(stream_callback_event_t event, void *param, void *cookie);
 252
 253 /* type of drain requested to audio_stream_out->drain(). Mutually exclusive */
 254 typedef enum {
 255     AUDIO_DRAIN_ALL,            /* drain() returns when all data has been played */
 256     AUDIO_DRAIN_EARLY_NOTIFY    /* drain() returns a short time before all data
 257                                    from the current track has been played to
 258                                    give time for gapless track switch */
 259 } audio_drain_type_t;
 260
 261 /**
 262  * audio_stream_out is the abstraction interface for the audio output hardware.
 263  *
 264  * It provides information about various properties of the audio output
 265  * hardware driver.
 266  */
 267
 268 struct audio_stream_out {
 269     /**
 270      * Common methods of the audio stream out.  This *must* be the first member of audio_stream_out
 271      * as users of this structure will cast a audio_stream to audio_stream_out pointer in contexts
 272      * where it's known the audio_stream references an audio_stream_out.
 273      */
 274     struct audio_stream common;
 275
 276     /**
 277      * Return the audio hardware driver estimated latency in milliseconds.
 278      */
 279     uint32_t (*get_latency)(const struct audio_stream_out *stream);
 280
 281     /**
 282      * Use this method in situations where audio mixing is done in the
 283      * hardware. This method serves as a direct interface with hardware,
 284      * allowing you to directly set the volume as apposed to via the framework.
 285      * This method might produce multiple PCM outputs or hardware accelerated
 286      * codecs, such as MP3 or AAC.
 287      */
 288     int (*set_volume)(struct audio_stream_out *stream, float left, float right);
 289
 290     /**
 291      * Write audio buffer to driver. Returns number of bytes written, or a
 292      * negative status_t. If at least one frame was written successfully prior to the error,
 293      * it is suggested that the driver return that successful (short) byte count
 294      * and then return an error in the subsequent call.
 295      *
 296      * If set_callback() has previously been called to enable non-blocking mode
 297      * the write() is not allowed to block. It must write only the number of
 298      * bytes that currently fit in the driver/hardware buffer and then return
 299      * this byte count. If this is less than the requested write size the
 300      * callback function must be called when more space is available in the
 301      * driver/hardware buffer.
 302      */
 303     ssize_t (*write)(struct audio_stream_out *stream, const void* buffer,
 304                      size_t bytes);
 305
 306     /* return the number of audio frames written by the audio dsp to DAC since
 307      * the output has exited standby
 308      */
 309     int (*get_render_position)(const struct audio_stream_out *stream,
 310                                uint32_t *dsp_frames);
 311
 312     /**
 313      * get the local time at which the next write to the audio driver will be presented.
 314      * The units are microseconds, where the epoch is decided by the local audio HAL.
 315      */
 316     int (*get_next_write_timestamp)(const struct audio_stream_out *stream,
 317                                     int64_t *timestamp);
 318
 319     /**
 320      * set the callback function for notifying completion of non-blocking
 321      * write and drain.
 322      * Calling this function implies that all future write() and drain()
 323      * must be non-blocking and use the callback to signal completion.
 324      */
 325     int (*set_callback)(struct audio_stream_out *stream,
 326             stream_callback_t callback, void *cookie);
 327
 328     /**
 329      * Notifies to the audio driver to stop playback however the queued buffers are
 330      * retained by the hardware. Useful for implementing pause/resume. Empty implementation
 331      * if not supported however should be implemented for hardware with non-trivial
 332      * latency. In the pause state audio hardware could still be using power. User may
 333      * consider calling suspend after a timeout.
 334      *
 335      * Implementation of this function is mandatory for offloaded playback.
 336      */
 337     int (*pause)(struct audio_stream_out* stream);
 338
 339     /**
 340      * Notifies to the audio driver to resume playback following a pause.
 341      * Returns error if called without matching pause.
 342      *
 343      * Implementation of this function is mandatory for offloaded playback.
 344      */
 345     int (*resume)(struct audio_stream_out* stream);
 346
 347     /**
 348      * Requests notification when data buffered by the driver/hardware has
 349      * been played. If set_callback() has previously been called to enable
 350      * non-blocking mode, the drain() must not block, instead it should return
 351      * quickly and completion of the drain is notified through the callback.
 352      * If set_callback() has not been called, the drain() must block until
 353      * completion.
 354      * If type==AUDIO_DRAIN_ALL, the drain completes when all previously written
 355      * data has been played.
 356      * If type==AUDIO_DRAIN_EARLY_NOTIFY, the drain completes shortly before all
 357      * data for the current track has played to allow time for the framework
 358      * to perform a gapless track switch.
 359      *
 360      * Drain must return immediately on stop() and flush() call
 361      *
 362      * Implementation of this function is mandatory for offloaded playback.
 363      */
 364     int (*drain)(struct audio_stream_out* stream, audio_drain_type_t type );
 365
 366     /**
 367      * Notifies to the audio driver to flush the queued data. Stream must already
 368      * be paused before calling flush().
 369      *
 370      * Implementation of this function is mandatory for offloaded playback.
 371      */
 372    int (*flush)(struct audio_stream_out* stream);
 373
 374     /**
 375      * Return a recent count of the number of audio frames presented to an external observer.
 376      * This excludes frames which have been written but are still in the pipeline.
 377      * The count is not reset to zero when output enters standby.
 378      * Also returns the value of CLOCK_MONOTONIC as of this presentation count.
 379      * The returned count is expected to be 'recent',
 380      * but does not need to be the most recent possible value.
 381      * However, the associated time should correspond to whatever count is returned.
 382      * Example:  assume that N+M frames have been presented, where M is a 'small' number.
 383      * Then it is permissible to return N instead of N+M,
 384      * and the timestamp should correspond to N rather than N+M.
 385      * The terms 'recent' and 'small' are not defined.
 386      * They reflect the quality of the implementation.
 387      *
 388      * 3.0 and higher only.
 389      */
 390     int (*get_presentation_position)(const struct audio_stream_out *stream,
 391                                uint64_t *frames, struct timespec *timestamp);
 392
 393 };
 394 typedef struct audio_stream_out audio_stream_out_t;
 395
 396 struct audio_stream_in {
 397     /**
 398      * Common methods of the audio stream in.  This *must* be the first member of audio_stream_in
 399      * as users of this structure will cast a audio_stream to audio_stream_in pointer in contexts
 400      * where it's known the audio_stream references an audio_stream_in.
 401      */
 402     struct audio_stream common;
 403
 404     /** set the input gain for the audio driver. This method is for
 405      *  for future use */
 406     int (*set_gain)(struct audio_stream_in *stream, float gain);
 407
 408     /** Read audio buffer in from audio driver. Returns number of bytes read, or a
 409      *  negative status_t. If at least one frame was read prior to the error,
 410      *  read should return that byte count and then return an error in the subsequent call.
 411      */
 412     ssize_t (*read)(struct audio_stream_in *stream, void* buffer,
 413                     size_t bytes);
 414
 415     /**
 416      * Return the amount of input frames lost in the audio driver since the
 417      * last call of this function.
 418      * Audio driver is expected to reset the value to 0 and restart counting
 419      * upon returning the current value by this function call.
 420      * Such loss typically occurs when the user space process is blocked
 421      * longer than the capacity of audio driver buffers.
 422      *
 423      * Unit: the number of input audio frames
 424      */
 425     uint32_t (*get_input_frames_lost)(struct audio_stream_in *stream);
 426 };
 427 typedef struct audio_stream_in audio_stream_in_t;
 428
 429 /**
 430  * return the frame size (number of bytes per sample).
 431  *
 432  * Deprecated: use audio_stream_out_frame_size() or audio_stream_in_frame_size() instead.
 433  */
 434 __attribute__((__deprecated__))
 435 static inline size_t audio_stream_frame_size(const struct audio_stream *s)
 436 {
 437     size_t chan_samp_sz;
 438     audio_format_t format = s->get_format(s);
 439
 440     if (audio_is_linear_pcm(format)) {
 441         chan_samp_sz = audio_bytes_per_sample(format);
 442         return popcount(s->get_channels(s)) * chan_samp_sz;
 443     }
 444
 445     return sizeof(int8_t);
 446 }
 447
 448 /**
 449  * return the frame size (number of bytes per sample) of an output stream.
 450  */
 451 static inline size_t audio_stream_out_frame_size(const struct audio_stream_out *s)
 452 {
 453     size_t chan_samp_sz;
 454     audio_format_t format = s->common.get_format(&s->common);
 455
 456     if (audio_is_linear_pcm(format)) {
 457         chan_samp_sz = audio_bytes_per_sample(format);
 458         return audio_channel_count_from_out_mask(s->common.get_channels(&s->common)) * chan_samp_sz;
 459     }
 460
 461     return sizeof(int8_t);
 462 }
 463
 464 /**
 465  * return the frame size (number of bytes per sample) of an input stream.
 466  */
 467 static inline size_t audio_stream_in_frame_size(const struct audio_stream_in *s)
 468 {
 469     size_t chan_samp_sz;
 470     audio_format_t format = s->common.get_format(&s->common);
 471
 472     if (audio_is_linear_pcm(format)) {
 473         chan_samp_sz = audio_bytes_per_sample(format);
 474         return audio_channel_count_from_in_mask(s->common.get_channels(&s->common)) * chan_samp_sz;
 475     }
 476
 477     return sizeof(int8_t);
 478 }
 479
 480 /**********************************************************************/
 481
 482 /**
 483  * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
 484  * and the fields of this data structure must begin with hw_module_t
 485  * followed by module specific information.
 486  */
 487 struct audio_module {
 488     struct hw_module_t common;
 489 };
 490
 491 struct audio_hw_device {
 492     /**
 493      * Common methods of the audio device.  This *must* be the first member of audio_hw_device
 494      * as users of this structure will cast a hw_device_t to audio_hw_device pointer in contexts
 495      * where it's known the hw_device_t references an audio_hw_device.
 496      */
 497     struct hw_device_t common;
 498
 499     /**
 500      * used by audio flinger to enumerate what devices are supported by
 501      * each audio_hw_device implementation.
 502      *
 503      * Return value is a bitmask of 1 or more values of audio_devices_t
 504      *
 505      * NOTE: audio HAL implementations starting with
 506      * AUDIO_DEVICE_API_VERSION_2_0 do not implement this function.
 507      * All supported devices should be listed in audio_policy.conf
 508      * file and the audio policy manager must choose the appropriate
 509      * audio module based on information in this file.
 510      */
 511     uint32_t (*get_supported_devices)(const struct audio_hw_device *dev);
 512
 513     /**
 514      * check to see if the audio hardware interface has been initialized.
 515      * returns 0 on success, -ENODEV on failure.
 516      */
 517     int (*init_check)(const struct audio_hw_device *dev);
 518
 519     /** set the audio volume of a voice call. Range is between 0.0 and 1.0 */
 520     int (*set_voice_volume)(struct audio_hw_device *dev, float volume);
 521
 522     /**
 523      * set the audio volume for all audio activities other than voice call.
 524      * Range between 0.0 and 1.0. If any value other than 0 is returned,
 525      * the software mixer will emulate this capability.
 526      */
 527     int (*set_master_volume)(struct audio_hw_device *dev, float volume);
 528
 529     /**
 530      * Get the current master volume value for the HAL, if the HAL supports
 531      * master volume control.  AudioFlinger will query this value from the
 532      * primary audio HAL when the service starts and use the value for setting
 533      * the initial master volume across all HALs.  HALs which do not support
 534      * this method may leave it set to NULL.
 535      */
 536     int (*get_master_volume)(struct audio_hw_device *dev, float *volume);
 537
 538     /**
 539      * set_mode is called when the audio mode changes. AUDIO_MODE_NORMAL mode
 540      * is for standard audio playback, AUDIO_MODE_RINGTONE when a ringtone is
 541      * playing, and AUDIO_MODE_IN_CALL when a call is in progress.
 542      */
 543     int (*set_mode)(struct audio_hw_device *dev, audio_mode_t mode);
 544
 545     /* mic mute */
 546     int (*set_mic_mute)(struct audio_hw_device *dev, bool state);
 547     int (*get_mic_mute)(const struct audio_hw_device *dev, bool *state);
 548
 549     /* set/get global audio parameters */
 550     int (*set_parameters)(struct audio_hw_device *dev, const char *kv_pairs);
 551
 552     /*
 553      * Returns a pointer to a heap allocated string. The caller is responsible
 554      * for freeing the memory for it using free().
 555      */
 556     char * (*get_parameters)(const struct audio_hw_device *dev,
 557                              const char *keys);
 558
 559     /* Returns audio input buffer size according to parameters passed or
 560      * 0 if one of the parameters is not supported.
 561      * See also get_buffer_size which is for a particular stream.
 562      */
 563     size_t (*get_input_buffer_size)(const struct audio_hw_device *dev,
 564                                     const struct audio_config *config);
 565
 566     /** This method creates and opens the audio hardware output stream.
 567      * The "address" parameter qualifies the "devices" audio device type if needed.
 568      * The format format depends on the device type:
 569      * - Bluetooth devices use the MAC address of the device in the form "00:11:22:AA:BB:CC"
 570      * - USB devices use the ALSA card and device numbers in the form  "card=X;device=Y"
 571      * - Other devices may use a number or any other string.
 572      */
 573
 574     int (*open_output_stream)(struct audio_hw_device *dev,
 575                               audio_io_handle_t handle,
 576                               audio_devices_t devices,
 577                               audio_output_flags_t flags,
 578                               struct audio_config *config,
 579                               struct audio_stream_out **stream_out,
 580                               const char *address);
 581
 582     void (*close_output_stream)(struct audio_hw_device *dev,
 583                                 struct audio_stream_out* stream_out);
 584
 585     /** This method creates and opens the audio hardware input stream */
 586     int (*open_input_stream)(struct audio_hw_device *dev,
 587                              audio_io_handle_t handle,
 588                              audio_devices_t devices,
 589                              struct audio_config *config,
 590                              struct audio_stream_in **stream_in,
 591                              audio_input_flags_t flags,
 592                              const char *address,
 593                              audio_source_t source);
 594
 595     void (*close_input_stream)(struct audio_hw_device *dev,
 596                                struct audio_stream_in *stream_in);
 597
 598     /** This method dumps the state of the audio hardware */
 599     int (*dump)(const struct audio_hw_device *dev, int fd);
 600
 601     /**
 602      * set the audio mute status for all audio activities.  If any value other
 603      * than 0 is returned, the software mixer will emulate this capability.
 604      */
 605     int (*set_master_mute)(struct audio_hw_device *dev, bool mute);
 606
 607     /**
 608      * Get the current master mute status for the HAL, if the HAL supports
 609      * master mute control.  AudioFlinger will query this value from the primary
 610      * audio HAL when the service starts and use the value for setting the
 611      * initial master mute across all HALs.  HALs which do not support this
 612      * method may leave it set to NULL.
 613      */
 614     int (*get_master_mute)(struct audio_hw_device *dev, bool *mute);
 615
 616     /**
 617      * Routing control
 618      */
 619
 620     /* Creates an audio patch between several source and sink ports.
 621      * The handle is allocated by the HAL and should be unique for this
 622      * audio HAL module. */
 623     int (*create_audio_patch)(struct audio_hw_device *dev,
 624                                unsigned int num_sources,
 625                                const struct audio_port_config *sources,
 626                                unsigned int num_sinks,
 627                                const struct audio_port_config *sinks,
 628                                audio_patch_handle_t *handle);
 629
 630     /* Release an audio patch */
 631     int (*release_audio_patch)(struct audio_hw_device *dev,
 632                                audio_patch_handle_t handle);
 633
 634     /* Fills the list of supported attributes for a given audio port.
 635      * As input, "port" contains the information (type, role, address etc...)
 636      * needed by the HAL to identify the port.
 637      * As output, "port" contains possible attributes (sampling rates, formats,
 638      * channel masks, gain controllers...) for this port.
 639      */
 640     int (*get_audio_port)(struct audio_hw_device *dev,
 641                           struct audio_port *port);
 642
 643     /* Set audio port configuration */
 644     int (*set_audio_port_config)(struct audio_hw_device *dev,
 645                          const struct audio_port_config *config);
 646
 647 };
 648 typedef struct audio_hw_device audio_hw_device_t;
 649
 650 /** convenience API for opening and closing a supported device */
 651
 652 static inline int audio_hw_device_open(const struct hw_module_t* module,
 653                                        struct audio_hw_device** device)
 654 {
 655     return module->methods->open(module, AUDIO_HARDWARE_INTERFACE,
 656                                  (struct hw_device_t**)device);
 657 }
 658
 659 static inline int audio_hw_device_close(struct audio_hw_device* device)
 660 {
 661     return device->common.close(&device->common);
 662 }
 663
 664
 665 __END_DECLS
 666
 667 #endif  // ANDROID_AUDIO_INTERFACE_H