blob: ef7d3427c0b78d2b63f3b912f6ef40350ab993d1 [file] [log] [blame]
Dima Zavinf1504db2011-03-11 11:20:49 -08001/*
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>
Dima Zavinaa211722011-05-11 14:15:53 -070029#include <system/audio.h>
Eric Laurentf3008aa2011-06-17 16:53:12 -070030#include <hardware/audio_effect.h>
Dima Zavinf1504db2011-03-11 11:20:49 -080031
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
Eric Laurent55786bc2012-04-10 16:56:32 -070044
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_CURRENT AUDIO_DEVICE_API_VERSION_1_0
57
Eric Laurent431fc782012-04-03 12:07:02 -070058/**
59 * List of known audio HAL modules. This is the base name of the audio HAL
60 * library composed of the "audio." prefix, one of the base names below and
61 * a suffix specific to the device.
62 * e.g: audio.primary.goldfish.so or audio.a2dp.default.so
63 */
64
65#define AUDIO_HARDWARE_MODULE_ID_PRIMARY "primary"
66#define AUDIO_HARDWARE_MODULE_ID_A2DP "a2dp"
67#define AUDIO_HARDWARE_MODULE_ID_USB "usb"
68
Dima Zavinf1504db2011-03-11 11:20:49 -080069/**************************************/
70
Eric Laurent70e81102011-08-07 10:05:40 -070071/**
72 * standard audio parameters that the HAL may need to handle
73 */
74
75/**
76 * audio device parameters
77 */
78
Eric Laurented9928c2011-08-02 17:12:00 -070079/* BT SCO Noise Reduction + Echo Cancellation parameters */
80#define AUDIO_PARAMETER_KEY_BT_NREC "bt_headset_nrec"
81#define AUDIO_PARAMETER_VALUE_ON "on"
82#define AUDIO_PARAMETER_VALUE_OFF "off"
83
Eric Laurent70e81102011-08-07 10:05:40 -070084/* TTY mode selection */
85#define AUDIO_PARAMETER_KEY_TTY_MODE "tty_mode"
86#define AUDIO_PARAMETER_VALUE_TTY_OFF "tty_off"
87#define AUDIO_PARAMETER_VALUE_TTY_VCO "tty_vco"
88#define AUDIO_PARAMETER_VALUE_TTY_HCO "tty_hco"
89#define AUDIO_PARAMETER_VALUE_TTY_FULL "tty_full"
90
Eric Laurenta70c5d02012-03-07 18:59:47 -080091/* A2DP sink address set by framework */
92#define AUDIO_PARAMETER_A2DP_SINK_ADDRESS "a2dp_sink_address"
93
Eric Laurent70e81102011-08-07 10:05:40 -070094/**
95 * audio stream parameters
96 */
97
Glenn Kasten0cacd8d2012-02-10 13:42:44 -080098#define AUDIO_PARAMETER_STREAM_ROUTING "routing" // audio_devices_t
99#define AUDIO_PARAMETER_STREAM_FORMAT "format" // audio_format_t
100#define AUDIO_PARAMETER_STREAM_CHANNELS "channels" // audio_channel_mask_t
101#define AUDIO_PARAMETER_STREAM_FRAME_COUNT "frame_count" // size_t
102#define AUDIO_PARAMETER_STREAM_INPUT_SOURCE "input_source" // audio_source_t
103#define AUDIO_PARAMETER_STREAM_SAMPLING_RATE "sampling_rate" // uint32_t
Dima Zavin57dde282011-06-06 19:31:18 -0700104
Eric Laurent55786bc2012-04-10 16:56:32 -0700105
Eric Laurent70e81102011-08-07 10:05:40 -0700106/**************************************/
107
Eric Laurent55786bc2012-04-10 16:56:32 -0700108/* common audio stream configuration parameters */
109struct audio_config {
110 uint32_t sample_rate;
111 audio_channel_mask_t channel_mask;
112 audio_format_t format;
113};
114
115typedef struct audio_config audio_config_t;
116
Dima Zavinf1504db2011-03-11 11:20:49 -0800117/* common audio stream parameters and operations */
118struct audio_stream {
119
120 /**
Glenn Kasten0cacd8d2012-02-10 13:42:44 -0800121 * Return the sampling rate in Hz - eg. 44100.
Dima Zavinf1504db2011-03-11 11:20:49 -0800122 */
123 uint32_t (*get_sample_rate)(const struct audio_stream *stream);
Dima Zavin57dde282011-06-06 19:31:18 -0700124
125 /* currently unused - use set_parameters with key
126 * AUDIO_PARAMETER_STREAM_SAMPLING_RATE
127 */
Dima Zavinf1504db2011-03-11 11:20:49 -0800128 int (*set_sample_rate)(struct audio_stream *stream, uint32_t rate);
129
130 /**
Glenn Kasten0cacd8d2012-02-10 13:42:44 -0800131 * Return size of input/output buffer in bytes for this stream - eg. 4800.
132 * It should be a multiple of the frame size. See also get_input_buffer_size.
Dima Zavinf1504db2011-03-11 11:20:49 -0800133 */
134 size_t (*get_buffer_size)(const struct audio_stream *stream);
135
136 /**
Glenn Kasten0cacd8d2012-02-10 13:42:44 -0800137 * Return the channel mask -
Dima Zavinf1504db2011-03-11 11:20:49 -0800138 * e.g. AUDIO_CHANNEL_OUT_STEREO or AUDIO_CHANNEL_IN_STEREO
139 */
Eric Laurent55786bc2012-04-10 16:56:32 -0700140 audio_channel_mask_t (*get_channels)(const struct audio_stream *stream);
Dima Zavinf1504db2011-03-11 11:20:49 -0800141
142 /**
Glenn Kasten0cacd8d2012-02-10 13:42:44 -0800143 * Return the audio format - e.g. AUDIO_FORMAT_PCM_16_BIT
Dima Zavinf1504db2011-03-11 11:20:49 -0800144 */
Glenn Kastenfe79eb32012-01-12 14:55:57 -0800145 audio_format_t (*get_format)(const struct audio_stream *stream);
Dima Zavin57dde282011-06-06 19:31:18 -0700146
147 /* currently unused - use set_parameters with key
148 * AUDIO_PARAMETER_STREAM_FORMAT
149 */
Glenn Kastenfe79eb32012-01-12 14:55:57 -0800150 int (*set_format)(struct audio_stream *stream, audio_format_t format);
Dima Zavinf1504db2011-03-11 11:20:49 -0800151
152 /**
153 * Put the audio hardware input/output into standby mode.
Glenn Kasten0cacd8d2012-02-10 13:42:44 -0800154 * Driver should exit from standby mode at the next I/O operation.
Dima Zavinf1504db2011-03-11 11:20:49 -0800155 * Returns 0 on success and <0 on failure.
156 */
157 int (*standby)(struct audio_stream *stream);
158
159 /** dump the state of the audio input/output device */
160 int (*dump)(const struct audio_stream *stream, int fd);
161
Glenn Kasten0cacd8d2012-02-10 13:42:44 -0800162 /** Return the set of device(s) which this stream is connected to */
Dima Zavinf1504db2011-03-11 11:20:49 -0800163 audio_devices_t (*get_device)(const struct audio_stream *stream);
Glenn Kasten0cacd8d2012-02-10 13:42:44 -0800164
165 /**
166 * Currently unused - set_device() corresponds to set_parameters() with key
167 * AUDIO_PARAMETER_STREAM_ROUTING for both input and output.
168 * AUDIO_PARAMETER_STREAM_INPUT_SOURCE is an additional information used by
169 * input streams only.
170 */
Dima Zavinf1504db2011-03-11 11:20:49 -0800171 int (*set_device)(struct audio_stream *stream, audio_devices_t device);
172
173 /**
174 * set/get audio stream parameters. The function accepts a list of
175 * parameter key value pairs in the form: key1=value1;key2=value2;...
176 *
177 * Some keys are reserved for standard parameters (See AudioParameter class)
178 *
179 * If the implementation does not accept a parameter change while
180 * the output is active but the parameter is acceptable otherwise, it must
181 * return -ENOSYS.
182 *
183 * The audio flinger will put the stream in standby and then change the
184 * parameter value.
185 */
186 int (*set_parameters)(struct audio_stream *stream, const char *kv_pairs);
187
188 /*
189 * Returns a pointer to a heap allocated string. The caller is responsible
Glenn Kasten0cacd8d2012-02-10 13:42:44 -0800190 * for freeing the memory for it using free().
Dima Zavinf1504db2011-03-11 11:20:49 -0800191 */
192 char * (*get_parameters)(const struct audio_stream *stream,
193 const char *keys);
Eric Laurentf3008aa2011-06-17 16:53:12 -0700194 int (*add_audio_effect)(const struct audio_stream *stream,
195 effect_handle_t effect);
196 int (*remove_audio_effect)(const struct audio_stream *stream,
197 effect_handle_t effect);
Dima Zavinf1504db2011-03-11 11:20:49 -0800198};
199typedef struct audio_stream audio_stream_t;
200
201/**
202 * audio_stream_out is the abstraction interface for the audio output hardware.
203 *
204 * It provides information about various properties of the audio output
205 * hardware driver.
206 */
207
208struct audio_stream_out {
209 struct audio_stream common;
210
211 /**
Glenn Kasten0cacd8d2012-02-10 13:42:44 -0800212 * Return the audio hardware driver estimated latency in milliseconds.
Dima Zavinf1504db2011-03-11 11:20:49 -0800213 */
214 uint32_t (*get_latency)(const struct audio_stream_out *stream);
215
216 /**
217 * Use this method in situations where audio mixing is done in the
218 * hardware. This method serves as a direct interface with hardware,
219 * allowing you to directly set the volume as apposed to via the framework.
220 * This method might produce multiple PCM outputs or hardware accelerated
221 * codecs, such as MP3 or AAC.
222 */
223 int (*set_volume)(struct audio_stream_out *stream, float left, float right);
224
225 /**
Glenn Kasten0cacd8d2012-02-10 13:42:44 -0800226 * Write audio buffer to driver. Returns number of bytes written, or a
227 * negative status_t. If at least one frame was written successfully prior to the error,
228 * it is suggested that the driver return that successful (short) byte count
229 * and then return an error in the subsequent call.
Dima Zavinf1504db2011-03-11 11:20:49 -0800230 */
231 ssize_t (*write)(struct audio_stream_out *stream, const void* buffer,
232 size_t bytes);
233
234 /* return the number of audio frames written by the audio dsp to DAC since
235 * the output has exited standby
236 */
237 int (*get_render_position)(const struct audio_stream_out *stream,
238 uint32_t *dsp_frames);
Mike J. Chen5ad38a92011-08-15 12:05:00 -0700239
240 /**
Glenn Kasten0cacd8d2012-02-10 13:42:44 -0800241 * get the local time at which the next write to the audio driver will be presented.
242 * The units are microseconds, where the epoch is decided by the local audio HAL.
Mike J. Chen5ad38a92011-08-15 12:05:00 -0700243 */
244 int (*get_next_write_timestamp)(const struct audio_stream_out *stream,
245 int64_t *timestamp);
246
Dima Zavinf1504db2011-03-11 11:20:49 -0800247};
248typedef struct audio_stream_out audio_stream_out_t;
249
250struct audio_stream_in {
251 struct audio_stream common;
252
253 /** set the input gain for the audio driver. This method is for
254 * for future use */
255 int (*set_gain)(struct audio_stream_in *stream, float gain);
256
Glenn Kasten0cacd8d2012-02-10 13:42:44 -0800257 /** Read audio buffer in from audio driver. Returns number of bytes read, or a
258 * negative status_t. If at least one frame was read prior to the error,
259 * read should return that byte count and then return an error in the subsequent call.
260 */
Dima Zavinf1504db2011-03-11 11:20:49 -0800261 ssize_t (*read)(struct audio_stream_in *stream, void* buffer,
262 size_t bytes);
263
264 /**
265 * Return the amount of input frames lost in the audio driver since the
266 * last call of this function.
267 * Audio driver is expected to reset the value to 0 and restart counting
268 * upon returning the current value by this function call.
269 * Such loss typically occurs when the user space process is blocked
270 * longer than the capacity of audio driver buffers.
271 *
272 * Unit: the number of input audio frames
273 */
274 uint32_t (*get_input_frames_lost)(struct audio_stream_in *stream);
275};
276typedef struct audio_stream_in audio_stream_in_t;
277
278/**
279 * return the frame size (number of bytes per sample).
280 */
Glenn Kastena26cbac2012-01-13 14:53:35 -0800281static inline size_t audio_stream_frame_size(struct audio_stream *s)
Dima Zavinf1504db2011-03-11 11:20:49 -0800282{
Glenn Kastena26cbac2012-01-13 14:53:35 -0800283 size_t chan_samp_sz;
Dima Zavinf1504db2011-03-11 11:20:49 -0800284
285 switch (s->get_format(s)) {
286 case AUDIO_FORMAT_PCM_16_BIT:
287 chan_samp_sz = sizeof(int16_t);
288 break;
289 case AUDIO_FORMAT_PCM_8_BIT:
290 default:
291 chan_samp_sz = sizeof(int8_t);
292 break;
293 }
294
295 return popcount(s->get_channels(s)) * chan_samp_sz;
296}
297
298
299/**********************************************************************/
300
301/**
302 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
303 * and the fields of this data structure must begin with hw_module_t
304 * followed by module specific information.
305 */
306struct audio_module {
307 struct hw_module_t common;
308};
309
310struct audio_hw_device {
311 struct hw_device_t common;
312
313 /**
314 * used by audio flinger to enumerate what devices are supported by
315 * each audio_hw_device implementation.
316 *
317 * Return value is a bitmask of 1 or more values of audio_devices_t
318 */
319 uint32_t (*get_supported_devices)(const struct audio_hw_device *dev);
320
321 /**
322 * check to see if the audio hardware interface has been initialized.
323 * returns 0 on success, -ENODEV on failure.
324 */
325 int (*init_check)(const struct audio_hw_device *dev);
326
327 /** set the audio volume of a voice call. Range is between 0.0 and 1.0 */
328 int (*set_voice_volume)(struct audio_hw_device *dev, float volume);
329
330 /**
331 * set the audio volume for all audio activities other than voice call.
332 * Range between 0.0 and 1.0. If any value other than 0 is returned,
333 * the software mixer will emulate this capability.
334 */
335 int (*set_master_volume)(struct audio_hw_device *dev, float volume);
336
337 /**
Mike J. Chen5ad38a92011-08-15 12:05:00 -0700338 * Get the current master volume value for the HAL, if the HAL supports
339 * master volume control. AudioFlinger will query this value from the
340 * primary audio HAL when the service starts and use the value for setting
341 * the initial master volume across all HALs. HALs which do not support
342 * this method should may leave it set to NULL.
343 */
344 int (*get_master_volume)(struct audio_hw_device *dev, float *volume);
345
346 /**
Glenn Kasten6df641e2012-01-09 10:41:30 -0800347 * set_mode is called when the audio mode changes. AUDIO_MODE_NORMAL mode
Dima Zavinf1504db2011-03-11 11:20:49 -0800348 * is for standard audio playback, AUDIO_MODE_RINGTONE when a ringtone is
349 * playing, and AUDIO_MODE_IN_CALL when a call is in progress.
Dima Zavinf1504db2011-03-11 11:20:49 -0800350 */
Glenn Kasten6df641e2012-01-09 10:41:30 -0800351 int (*set_mode)(struct audio_hw_device *dev, audio_mode_t mode);
Dima Zavinf1504db2011-03-11 11:20:49 -0800352
353 /* mic mute */
354 int (*set_mic_mute)(struct audio_hw_device *dev, bool state);
355 int (*get_mic_mute)(const struct audio_hw_device *dev, bool *state);
356
357 /* set/get global audio parameters */
358 int (*set_parameters)(struct audio_hw_device *dev, const char *kv_pairs);
359
360 /*
361 * Returns a pointer to a heap allocated string. The caller is responsible
Glenn Kasten0cacd8d2012-02-10 13:42:44 -0800362 * for freeing the memory for it using free().
Dima Zavinf1504db2011-03-11 11:20:49 -0800363 */
364 char * (*get_parameters)(const struct audio_hw_device *dev,
365 const char *keys);
366
367 /* Returns audio input buffer size according to parameters passed or
Glenn Kasten0cacd8d2012-02-10 13:42:44 -0800368 * 0 if one of the parameters is not supported.
369 * See also get_buffer_size which is for a particular stream.
Dima Zavinf1504db2011-03-11 11:20:49 -0800370 */
371 size_t (*get_input_buffer_size)(const struct audio_hw_device *dev,
Eric Laurent55786bc2012-04-10 16:56:32 -0700372 const struct audio_config *config);
Dima Zavinf1504db2011-03-11 11:20:49 -0800373
374 /** This method creates and opens the audio hardware output stream */
Eric Laurent55786bc2012-04-10 16:56:32 -0700375 int (*open_output_stream)(struct audio_hw_device *dev,
376 audio_io_handle_t handle,
377 audio_devices_t devices,
378 audio_output_flags_t flags,
379 struct audio_config *config,
380 struct audio_stream_out **stream_out);
Dima Zavinf1504db2011-03-11 11:20:49 -0800381
382 void (*close_output_stream)(struct audio_hw_device *dev,
Eric Laurent55786bc2012-04-10 16:56:32 -0700383 struct audio_stream_out* stream_out);
Dima Zavinf1504db2011-03-11 11:20:49 -0800384
385 /** This method creates and opens the audio hardware input stream */
Eric Laurent55786bc2012-04-10 16:56:32 -0700386 int (*open_input_stream)(struct audio_hw_device *dev,
387 audio_io_handle_t handle,
388 audio_devices_t devices,
389 struct audio_config *config,
Dima Zavinf1504db2011-03-11 11:20:49 -0800390 struct audio_stream_in **stream_in);
391
392 void (*close_input_stream)(struct audio_hw_device *dev,
Eric Laurent55786bc2012-04-10 16:56:32 -0700393 struct audio_stream_in *stream_in);
Dima Zavinf1504db2011-03-11 11:20:49 -0800394
395 /** This method dumps the state of the audio hardware */
396 int (*dump)(const struct audio_hw_device *dev, int fd);
397};
398typedef struct audio_hw_device audio_hw_device_t;
399
400/** convenience API for opening and closing a supported device */
401
402static inline int audio_hw_device_open(const struct hw_module_t* module,
403 struct audio_hw_device** device)
404{
405 return module->methods->open(module, AUDIO_HARDWARE_INTERFACE,
406 (struct hw_device_t**)device);
407}
408
409static inline int audio_hw_device_close(struct audio_hw_device* device)
410{
411 return device->common.close(&device->common);
412}
413
414
415__END_DECLS
416
417#endif // ANDROID_AUDIO_INTERFACE_H