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