1 /*
2 * Copyright (C) 2011 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17
18 #ifndef ANDROID_AUDIO_HAL_INTERFACE_H
19 #define ANDROID_AUDIO_HAL_INTERFACE_H
20
21 #include <stdint.h>
22 #include <strings.h>
23 #include <sys/cdefs.h>
24 #include <sys/types.h>
25
26 #include <cutils/bitops.h>
27
28 #include <hardware/hardware.h>
29 #include <system/audio.h>
30 #include <hardware/audio_effect.h>
31
32 __BEGIN_DECLS
33
34 /**
35 * The id of this module
36 */
37 #define AUDIO_HARDWARE_MODULE_ID "audio"
38
39 /**
40 * Name of the audio devices to open
41 */
42 #define AUDIO_HARDWARE_INTERFACE "audio_hw_if"
43
44
45 /* Use version 0.1 to be compatible with first generation of audio hw module with version_major
46 * hardcoded to 1. No audio module API change.
47 */
48 #define AUDIO_MODULE_API_VERSION_0_1 HARDWARE_MODULE_API_VERSION(0, 1)
49 #define AUDIO_MODULE_API_VERSION_CURRENT AUDIO_MODULE_API_VERSION_0_1
50
51 /* First generation of audio devices had version hardcoded to 0. all devices with versions < 1.0
52 * will be considered of first generation API.
53 */
54 #define AUDIO_DEVICE_API_VERSION_0_0 HARDWARE_DEVICE_API_VERSION(0, 0)
55 #define AUDIO_DEVICE_API_VERSION_1_0 HARDWARE_DEVICE_API_VERSION(1, 0)
56 #define AUDIO_DEVICE_API_VERSION_2_0 HARDWARE_DEVICE_API_VERSION(2, 0)
57 #define AUDIO_DEVICE_API_VERSION_CURRENT AUDIO_DEVICE_API_VERSION_2_0
58
59 /**
60 * List of known audio HAL modules. This is the base name of the audio HAL
61 * library composed of the "audio." prefix, one of the base names below and
62 * a suffix specific to the device.
63 * e.g: audio.primary.goldfish.so or audio.a2dp.default.so
64 */
65
66 #define AUDIO_HARDWARE_MODULE_ID_PRIMARY "primary"
67 #define AUDIO_HARDWARE_MODULE_ID_A2DP "a2dp"
68 #define AUDIO_HARDWARE_MODULE_ID_USB "usb"
69 #define AUDIO_HARDWARE_MODULE_ID_REMOTE_SUBMIX "r_submix"
70
71 /**************************************/
72
73 /**
74 * standard audio parameters that the HAL may need to handle
75 */
76
77 /**
78 * audio device parameters
79 */
80
81 /* BT SCO Noise Reduction + Echo Cancellation parameters */
82 #define AUDIO_PARAMETER_KEY_BT_NREC "bt_headset_nrec"
83 #define AUDIO_PARAMETER_VALUE_ON "on"
84 #define AUDIO_PARAMETER_VALUE_OFF "off"
85
86 /* TTY mode selection */
87 #define AUDIO_PARAMETER_KEY_TTY_MODE "tty_mode"
88 #define AUDIO_PARAMETER_VALUE_TTY_OFF "tty_off"
89 #define AUDIO_PARAMETER_VALUE_TTY_VCO "tty_vco"
90 #define AUDIO_PARAMETER_VALUE_TTY_HCO "tty_hco"
91 #define AUDIO_PARAMETER_VALUE_TTY_FULL "tty_full"
92
93 /* A2DP sink address set by framework */
94 #define AUDIO_PARAMETER_A2DP_SINK_ADDRESS "a2dp_sink_address"
95
96 /* Screen state */
97 #define AUDIO_PARAMETER_KEY_SCREEN_STATE "screen_state"
98
99 /**
100 * audio stream parameters
101 */
102
103 #define AUDIO_PARAMETER_STREAM_ROUTING "routing" // audio_devices_t
104 #define AUDIO_PARAMETER_STREAM_FORMAT "format" // audio_format_t
105 #define AUDIO_PARAMETER_STREAM_CHANNELS "channels" // audio_channel_mask_t
106 #define AUDIO_PARAMETER_STREAM_FRAME_COUNT "frame_count" // size_t
107 #define AUDIO_PARAMETER_STREAM_INPUT_SOURCE "input_source" // audio_source_t
108 #define AUDIO_PARAMETER_STREAM_SAMPLING_RATE "sampling_rate" // uint32_t
109
110 /* Query supported formats. The response is a '|' separated list of strings from
111 * audio_format_t enum e.g: "sup_formats=AUDIO_FORMAT_PCM_16_BIT" */
112 #define AUDIO_PARAMETER_STREAM_SUP_FORMATS "sup_formats"
113 /* Query supported channel masks. The response is a '|' separated list of strings from
114 * audio_channel_mask_t enum e.g: "sup_channels=AUDIO_CHANNEL_OUT_STEREO|AUDIO_CHANNEL_OUT_MONO" */
115 #define AUDIO_PARAMETER_STREAM_SUP_CHANNELS "sup_channels"
116 /* Query supported sampling rates. The response is a '|' separated list of integer values e.g:
117 * "sup_sampling_rates=44100|48000" */
118 #define AUDIO_PARAMETER_STREAM_SUP_SAMPLING_RATES "sup_sampling_rates"
119
120
121 /**************************************/
122
123 /* common audio stream configuration parameters */
124 struct audio_config {
125 uint32_t sample_rate;
126 audio_channel_mask_t channel_mask;
127 audio_format_t format;
128 };
129
130 typedef struct audio_config audio_config_t;
131
132 /* common audio stream parameters and operations */
133 struct audio_stream {
134
135 /**
136 * Return the sampling rate in Hz - eg. 44100.
137 */
138 uint32_t (*get_sample_rate)(const struct audio_stream *stream);
139
140 /* currently unused - use set_parameters with key
141 * AUDIO_PARAMETER_STREAM_SAMPLING_RATE
142 */
143 int (*set_sample_rate)(struct audio_stream *stream, uint32_t rate);
144
145 /**
146 * Return size of input/output buffer in bytes for this stream - eg. 4800.
147 * It should be a multiple of the frame size. See also get_input_buffer_size.
148 */
149 size_t (*get_buffer_size)(const struct audio_stream *stream);
150
151 /**
152 * Return the channel mask -
153 * e.g. AUDIO_CHANNEL_OUT_STEREO or AUDIO_CHANNEL_IN_STEREO
154 */
155 audio_channel_mask_t (*get_channels)(const struct audio_stream *stream);
156
157 /**
158 * Return the audio format - e.g. AUDIO_FORMAT_PCM_16_BIT
159 */
160 audio_format_t (*get_format)(const struct audio_stream *stream);
161
162 /* currently unused - use set_parameters with key
163 * AUDIO_PARAMETER_STREAM_FORMAT
164 */
165 int (*set_format)(struct audio_stream *stream, audio_format_t format);
166
167 /**
168 * Put the audio hardware input/output into standby mode.
169 * Driver should exit from standby mode at the next I/O operation.
170 * Returns 0 on success and <0 on failure.
171 */
172 int (*standby)(struct audio_stream *stream);
173
174 /** dump the state of the audio input/output device */
175 int (*dump)(const struct audio_stream *stream, int fd);
176
177 /** Return the set of device(s) which this stream is connected to */
178 audio_devices_t (*get_device)(const struct audio_stream *stream);
179
180 /**
181 * Currently unused - set_device() corresponds to set_parameters() with key
182 * AUDIO_PARAMETER_STREAM_ROUTING for both input and output.
183 * AUDIO_PARAMETER_STREAM_INPUT_SOURCE is an additional information used by
184 * input streams only.
185 */
186 int (*set_device)(struct audio_stream *stream, audio_devices_t device);
187
188 /**
189 * set/get audio stream parameters. The function accepts a list of
190 * parameter key value pairs in the form: key1=value1;key2=value2;...
191 *
192 * Some keys are reserved for standard parameters (See AudioParameter class)
193 *
194 * If the implementation does not accept a parameter change while
195 * the output is active but the parameter is acceptable otherwise, it must
196 * return -ENOSYS.
197 *
198 * The audio flinger will put the stream in standby and then change the
199 * parameter value.
200 */
201 int (*set_parameters)(struct audio_stream *stream, const char *kv_pairs);
202
203 /*
204 * Returns a pointer to a heap allocated string. The caller is responsible
205 * for freeing the memory for it using free().
206 */
207 char * (*get_parameters)(const struct audio_stream *stream,
208 const char *keys);
209 int (*add_audio_effect)(const struct audio_stream *stream,
210 effect_handle_t effect);
211 int (*remove_audio_effect)(const struct audio_stream *stream,
212 effect_handle_t effect);
213 };
214 typedef struct audio_stream audio_stream_t;
215
216 /**
217 * audio_stream_out is the abstraction interface for the audio output hardware.
218 *
219 * It provides information about various properties of the audio output
220 * hardware driver.
221 */
222
223 struct audio_stream_out {
224 struct audio_stream common;
225
226 /**
227 * Return the audio hardware driver estimated latency in milliseconds.
228 */
229 uint32_t (*get_latency)(const struct audio_stream_out *stream);
230
231 /**
232 * Use this method in situations where audio mixing is done in the
233 * hardware. This method serves as a direct interface with hardware,
234 * allowing you to directly set the volume as apposed to via the framework.
235 * This method might produce multiple PCM outputs or hardware accelerated
236 * codecs, such as MP3 or AAC.
237 */
238 int (*set_volume)(struct audio_stream_out *stream, float left, float right);
239
240 /**
241 * Write audio buffer to driver. Returns number of bytes written, or a
242 * negative status_t. If at least one frame was written successfully prior to the error,
243 * it is suggested that the driver return that successful (short) byte count
244 * and then return an error in the subsequent call.
245 */
246 ssize_t (*write)(struct audio_stream_out *stream, const void* buffer,
247 size_t bytes);
248
249 /* return the number of audio frames written by the audio dsp to DAC since
250 * the output has exited standby
251 */
252 int (*get_render_position)(const struct audio_stream_out *stream,
253 uint32_t *dsp_frames);
254
255 /**
256 * get the local time at which the next write to the audio driver will be presented.
257 * The units are microseconds, where the epoch is decided by the local audio HAL.
258 */
259 int (*get_next_write_timestamp)(const struct audio_stream_out *stream,
260 int64_t *timestamp);
261
262 };
263 typedef struct audio_stream_out audio_stream_out_t;
264
265 struct audio_stream_in {
266 struct audio_stream common;
267
268 /** set the input gain for the audio driver. This method is for
269 * for future use */
270 int (*set_gain)(struct audio_stream_in *stream, float gain);
271
272 /** Read audio buffer in from audio driver. Returns number of bytes read, or a
273 * negative status_t. If at least one frame was read prior to the error,
274 * read should return that byte count and then return an error in the subsequent call.
275 */
276 ssize_t (*read)(struct audio_stream_in *stream, void* buffer,
277 size_t bytes);
278
279 /**
280 * Return the amount of input frames lost in the audio driver since the
281 * last call of this function.
282 * Audio driver is expected to reset the value to 0 and restart counting
283 * upon returning the current value by this function call.
284 * Such loss typically occurs when the user space process is blocked
285 * longer than the capacity of audio driver buffers.
286 *
287 * Unit: the number of input audio frames
288 */
289 uint32_t (*get_input_frames_lost)(struct audio_stream_in *stream);
290 };
291 typedef struct audio_stream_in audio_stream_in_t;
292
293 /**
294 * return the frame size (number of bytes per sample).
295 */
audio_stream_frame_size(const struct audio_stream * s)296 static inline size_t audio_stream_frame_size(const struct audio_stream *s)
297 {
298 size_t chan_samp_sz;
299
300 switch (s->get_format(s)) {
301 case AUDIO_FORMAT_PCM_16_BIT:
302 chan_samp_sz = sizeof(int16_t);
303 break;
304 case AUDIO_FORMAT_PCM_8_BIT:
305 default:
306 chan_samp_sz = sizeof(int8_t);
307 break;
308 }
309
310 return popcount(s->get_channels(s)) * chan_samp_sz;
311 }
312
313
314 /**********************************************************************/
315
316 /**
317 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
318 * and the fields of this data structure must begin with hw_module_t
319 * followed by module specific information.
320 */
321 struct audio_module {
322 struct hw_module_t common;
323 };
324
325 struct audio_hw_device {
326 struct hw_device_t common;
327
328 /**
329 * used by audio flinger to enumerate what devices are supported by
330 * each audio_hw_device implementation.
331 *
332 * Return value is a bitmask of 1 or more values of audio_devices_t
333 *
334 * NOTE: audio HAL implementations starting with
335 * AUDIO_DEVICE_API_VERSION_2_0 do not implement this function.
336 * All supported devices should be listed in audio_policy.conf
337 * file and the audio policy manager must choose the appropriate
338 * audio module based on information in this file.
339 */
340 uint32_t (*get_supported_devices)(const struct audio_hw_device *dev);
341
342 /**
343 * check to see if the audio hardware interface has been initialized.
344 * returns 0 on success, -ENODEV on failure.
345 */
346 int (*init_check)(const struct audio_hw_device *dev);
347
348 /** set the audio volume of a voice call. Range is between 0.0 and 1.0 */
349 int (*set_voice_volume)(struct audio_hw_device *dev, float volume);
350
351 /**
352 * set the audio volume for all audio activities other than voice call.
353 * Range between 0.0 and 1.0. If any value other than 0 is returned,
354 * the software mixer will emulate this capability.
355 */
356 int (*set_master_volume)(struct audio_hw_device *dev, float volume);
357
358 /**
359 * Get the current master volume value for the HAL, if the HAL supports
360 * master volume control. AudioFlinger will query this value from the
361 * primary audio HAL when the service starts and use the value for setting
362 * the initial master volume across all HALs. HALs which do not support
363 * this method may leave it set to NULL.
364 */
365 int (*get_master_volume)(struct audio_hw_device *dev, float *volume);
366
367 /**
368 * set_mode is called when the audio mode changes. AUDIO_MODE_NORMAL mode
369 * is for standard audio playback, AUDIO_MODE_RINGTONE when a ringtone is
370 * playing, and AUDIO_MODE_IN_CALL when a call is in progress.
371 */
372 int (*set_mode)(struct audio_hw_device *dev, audio_mode_t mode);
373
374 /* mic mute */
375 int (*set_mic_mute)(struct audio_hw_device *dev, bool state);
376 int (*get_mic_mute)(const struct audio_hw_device *dev, bool *state);
377
378 /* set/get global audio parameters */
379 int (*set_parameters)(struct audio_hw_device *dev, const char *kv_pairs);
380
381 /*
382 * Returns a pointer to a heap allocated string. The caller is responsible
383 * for freeing the memory for it using free().
384 */
385 char * (*get_parameters)(const struct audio_hw_device *dev,
386 const char *keys);
387
388 /* Returns audio input buffer size according to parameters passed or
389 * 0 if one of the parameters is not supported.
390 * See also get_buffer_size which is for a particular stream.
391 */
392 size_t (*get_input_buffer_size)(const struct audio_hw_device *dev,
393 const struct audio_config *config);
394
395 /** This method creates and opens the audio hardware output stream */
396 int (*open_output_stream)(struct audio_hw_device *dev,
397 audio_io_handle_t handle,
398 audio_devices_t devices,
399 audio_output_flags_t flags,
400 struct audio_config *config,
401 struct audio_stream_out **stream_out);
402
403 void (*close_output_stream)(struct audio_hw_device *dev,
404 struct audio_stream_out* stream_out);
405
406 /** This method creates and opens the audio hardware input stream */
407 int (*open_input_stream)(struct audio_hw_device *dev,
408 audio_io_handle_t handle,
409 audio_devices_t devices,
410 struct audio_config *config,
411 struct audio_stream_in **stream_in);
412
413 void (*close_input_stream)(struct audio_hw_device *dev,
414 struct audio_stream_in *stream_in);
415
416 /** This method dumps the state of the audio hardware */
417 int (*dump)(const struct audio_hw_device *dev, int fd);
418
419 /**
420 * set the audio mute status for all audio activities. If any value other
421 * than 0 is returned, the software mixer will emulate this capability.
422 */
423 int (*set_master_mute)(struct audio_hw_device *dev, bool mute);
424
425 /**
426 * Get the current master mute status for the HAL, if the HAL supports
427 * master mute control. AudioFlinger will query this value from the primary
428 * audio HAL when the service starts and use the value for setting the
429 * initial master mute across all HALs. HALs which do not support this
430 * method may leave it set to NULL.
431 */
432 int (*get_master_mute)(struct audio_hw_device *dev, bool *mute);
433 };
434 typedef struct audio_hw_device audio_hw_device_t;
435
436 /** convenience API for opening and closing a supported device */
437
audio_hw_device_open(const struct hw_module_t * module,struct audio_hw_device ** device)438 static inline int audio_hw_device_open(const struct hw_module_t* module,
439 struct audio_hw_device** device)
440 {
441 return module->methods->open(module, AUDIO_HARDWARE_INTERFACE,
442 (struct hw_device_t**)device);
443 }
444
audio_hw_device_close(struct audio_hw_device * device)445 static inline int audio_hw_device_close(struct audio_hw_device* device)
446 {
447 return device->common.close(&device->common);
448 }
449
450
451 __END_DECLS
452
453 #endif // ANDROID_AUDIO_INTERFACE_H
454