2 * Copyright (C) 2011 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
18 #ifndef ANDROID_AUDIO_HAL_INTERFACE_H
19 #define ANDROID_AUDIO_HAL_INTERFACE_H
23 #include <sys/cdefs.h>
24 #include <sys/types.h>
26 #include <cutils/bitops.h>
28 #include <hardware/hardware.h>
29 #include <system/audio.h>
30 #include <hardware/audio_effect.h>
35 * The id of this module
37 #define AUDIO_HARDWARE_MODULE_ID "audio"
40 * Name of the audio devices to open
42 #define AUDIO_HARDWARE_INTERFACE "audio_hw_if"
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.
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
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.
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
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
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"
71 /**************************************/
74 * standard audio parameters that the HAL may need to handle
78 * audio device parameters
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"
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"
93 /* A2DP sink address set by framework */
94 #define AUDIO_PARAMETER_A2DP_SINK_ADDRESS "a2dp_sink_address"
97 #define AUDIO_PARAMETER_KEY_SCREEN_STATE "screen_state"
100 * audio stream parameters
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
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"
121 /**************************************/
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
;
130 typedef struct audio_config audio_config_t
;
132 /* common audio stream parameters and operations */
133 struct audio_stream
{
136 * Return the sampling rate in Hz - eg. 44100.
138 uint32_t (*get_sample_rate
)(const struct audio_stream
*stream
);
140 /* currently unused - use set_parameters with key
141 * AUDIO_PARAMETER_STREAM_SAMPLING_RATE
143 int (*set_sample_rate
)(struct audio_stream
*stream
, uint32_t rate
);
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.
149 size_t (*get_buffer_size
)(const struct audio_stream
*stream
);
152 * Return the channel mask -
153 * e.g. AUDIO_CHANNEL_OUT_STEREO or AUDIO_CHANNEL_IN_STEREO
155 audio_channel_mask_t (*get_channels
)(const struct audio_stream
*stream
);
158 * Return the audio format - e.g. AUDIO_FORMAT_PCM_16_BIT
160 audio_format_t (*get_format
)(const struct audio_stream
*stream
);
162 /* currently unused - use set_parameters with key
163 * AUDIO_PARAMETER_STREAM_FORMAT
165 int (*set_format
)(struct audio_stream
*stream
, audio_format_t format
);
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.
172 int (*standby
)(struct audio_stream
*stream
);
174 /** dump the state of the audio input/output device */
175 int (*dump
)(const struct audio_stream
*stream
, int fd
);
177 /** Return the set of device(s) which this stream is connected to */
178 audio_devices_t (*get_device
)(const struct audio_stream
*stream
);
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.
186 int (*set_device
)(struct audio_stream
*stream
, audio_devices_t device
);
189 * set/get audio stream parameters. The function accepts a list of
190 * parameter key value pairs in the form: key1=value1;key2=value2;...
192 * Some keys are reserved for standard parameters (See AudioParameter class)
194 * If the implementation does not accept a parameter change while
195 * the output is active but the parameter is acceptable otherwise, it must
198 * The audio flinger will put the stream in standby and then change the
201 int (*set_parameters
)(struct audio_stream
*stream
, const char *kv_pairs
);
204 * Returns a pointer to a heap allocated string. The caller is responsible
205 * for freeing the memory for it using free().
207 char * (*get_parameters
)(const struct audio_stream
*stream
,
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
);
214 typedef struct audio_stream audio_stream_t
;
217 * audio_stream_out is the abstraction interface for the audio output hardware.
219 * It provides information about various properties of the audio output
223 struct audio_stream_out
{
224 struct audio_stream common
;
227 * Return the audio hardware driver estimated latency in milliseconds.
229 uint32_t (*get_latency
)(const struct audio_stream_out
*stream
);
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.
238 int (*set_volume
)(struct audio_stream_out
*stream
, float left
, float right
);
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.
246 ssize_t (*write
)(struct audio_stream_out
*stream
, const void* buffer
,
249 /* return the number of audio frames written by the audio dsp to DAC since
250 * the output has exited standby
252 int (*get_render_position
)(const struct audio_stream_out
*stream
,
253 uint32_t *dsp_frames
);
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.
259 int (*get_next_write_timestamp
)(const struct audio_stream_out
*stream
,
263 typedef struct audio_stream_out audio_stream_out_t
;
265 struct audio_stream_in
{
266 struct audio_stream common
;
268 /** set the input gain for the audio driver. This method is for
270 int (*set_gain
)(struct audio_stream_in
*stream
, float gain
);
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.
276 ssize_t (*read
)(struct audio_stream_in
*stream
, void* buffer
,
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.
287 * Unit: the number of input audio frames
289 uint32_t (*get_input_frames_lost
)(struct audio_stream_in
*stream
);
291 typedef struct audio_stream_in audio_stream_in_t
;
294 * return the frame size (number of bytes per sample).
296 static inline size_t audio_stream_frame_size(const struct audio_stream
*s
)
300 switch (s
->get_format(s
)) {
301 case AUDIO_FORMAT_PCM_16_BIT
:
302 chan_samp_sz
= sizeof(int16_t);
304 case AUDIO_FORMAT_PCM_8_BIT
:
306 chan_samp_sz
= sizeof(int8_t);
310 return popcount(s
->get_channels(s
)) * chan_samp_sz
;
314 /**********************************************************************/
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.
321 struct audio_module
{
322 struct hw_module_t common
;
325 struct audio_hw_device
{
326 struct hw_device_t common
;
329 * used by audio flinger to enumerate what devices are supported by
330 * each audio_hw_device implementation.
332 * Return value is a bitmask of 1 or more values of audio_devices_t
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.
340 uint32_t (*get_supported_devices
)(const struct audio_hw_device
*dev
);
343 * check to see if the audio hardware interface has been initialized.
344 * returns 0 on success, -ENODEV on failure.
346 int (*init_check
)(const struct audio_hw_device
*dev
);
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
);
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.
356 int (*set_master_volume
)(struct audio_hw_device
*dev
, float volume
);
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.
365 int (*get_master_volume
)(struct audio_hw_device
*dev
, float *volume
);
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.
372 int (*set_mode
)(struct audio_hw_device
*dev
, audio_mode_t mode
);
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
);
378 /* set/get global audio parameters */
379 int (*set_parameters
)(struct audio_hw_device
*dev
, const char *kv_pairs
);
382 * Returns a pointer to a heap allocated string. The caller is responsible
383 * for freeing the memory for it using free().
385 char * (*get_parameters
)(const struct audio_hw_device
*dev
,
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.
392 size_t (*get_input_buffer_size
)(const struct audio_hw_device
*dev
,
393 const struct audio_config
*config
);
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
);
403 void (*close_output_stream
)(struct audio_hw_device
*dev
,
404 struct audio_stream_out
* stream_out
);
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
);
413 void (*close_input_stream
)(struct audio_hw_device
*dev
,
414 struct audio_stream_in
*stream_in
);
416 /** This method dumps the state of the audio hardware */
417 int (*dump
)(const struct audio_hw_device
*dev
, int fd
);
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.
423 int (*set_master_mute
)(struct audio_hw_device
*dev
, bool mute
);
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.
432 int (*get_master_mute
)(struct audio_hw_device
*dev
, bool *mute
);
434 typedef struct audio_hw_device audio_hw_device_t
;
436 /** convenience API for opening and closing a supported device */
438 static inline int audio_hw_device_open(const struct hw_module_t
* module
,
439 struct audio_hw_device
** device
)
441 return module
->methods
->open(module
, AUDIO_HARDWARE_INTERFACE
,
442 (struct hw_device_t
**)device
);
445 static inline int audio_hw_device_close(struct audio_hw_device
* device
)
447 return device
->common
.close(&device
->common
);
453 #endif // ANDROID_AUDIO_INTERFACE_H