audio.h revision 48915acb392773c1fcb86e2711eab468410a0baa 
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_CURRENT AUDIO_DEVICE_API_VERSION_1_0
57
58/**
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
69/**************************************/
70
71/**
72 *  standard audio parameters that the HAL may need to handle
73 */
74
75/**
76 *  audio device parameters
77 */
78
79/* 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
84/* 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
91/* A2DP sink address set by framework */
92#define AUDIO_PARAMETER_A2DP_SINK_ADDRESS "a2dp_sink_address"
93
94/* Screen state */
95#define AUDIO_PARAMETER_KEY_SCREEN_STATE "screen_state"
96
97/**
98 *  audio stream parameters
99 */
100
101#define AUDIO_PARAMETER_STREAM_ROUTING "routing"            // audio_devices_t
102#define AUDIO_PARAMETER_STREAM_FORMAT "format"              // audio_format_t
103#define AUDIO_PARAMETER_STREAM_CHANNELS "channels"          // audio_channel_mask_t
104#define AUDIO_PARAMETER_STREAM_FRAME_COUNT "frame_count"    // size_t
105#define AUDIO_PARAMETER_STREAM_INPUT_SOURCE "input_source"  // audio_source_t
106#define AUDIO_PARAMETER_STREAM_SAMPLING_RATE "sampling_rate" // uint32_t
107
108/* Query supported formats. The response is a '|' separated list of strings from
109 * audio_format_t enum e.g: "sup_formats=AUDIO_FORMAT_PCM_16_BIT" */
110#define AUDIO_PARAMETER_STREAM_SUP_FORMATS "sup_formats"
111/* Query supported channel masks. The response is a '|' separated list of strings from
112 * audio_channel_mask_t enum e.g: "sup_channels=AUDIO_CHANNEL_OUT_STEREO|AUDIO_CHANNEL_OUT_MONO" */
113#define AUDIO_PARAMETER_STREAM_SUP_CHANNELS "sup_channels"
114/* Query supported sampling rates. The response is a '|' separated list of integer values e.g:
115 * "sup_sampling_rates=44100|48000" */
116#define AUDIO_PARAMETER_STREAM_SUP_SAMPLING_RATES "sup_sampling_rates"
117
118
119/**************************************/
120
121/* common audio stream configuration parameters */
122struct audio_config {
123    uint32_t sample_rate;
124    audio_channel_mask_t channel_mask;
125    audio_format_t  format;
126};
127
128typedef struct audio_config audio_config_t;
129
130/* common audio stream parameters and operations */
131struct audio_stream {
132
133    /**
134     * Return the sampling rate in Hz - eg. 44100.
135     */
136    uint32_t (*get_sample_rate)(const struct audio_stream *stream);
137
138    /* currently unused - use set_parameters with key
139     *    AUDIO_PARAMETER_STREAM_SAMPLING_RATE
140     */
141    int (*set_sample_rate)(struct audio_stream *stream, uint32_t rate);
142
143    /**
144     * Return size of input/output buffer in bytes for this stream - eg. 4800.
145     * It should be a multiple of the frame size.  See also get_input_buffer_size.
146     */
147    size_t (*get_buffer_size)(const struct audio_stream *stream);
148
149    /**
150     * Return the channel mask -
151     *  e.g. AUDIO_CHANNEL_OUT_STEREO or AUDIO_CHANNEL_IN_STEREO
152     */
153    audio_channel_mask_t (*get_channels)(const struct audio_stream *stream);
154
155    /**
156     * Return the audio format - e.g. AUDIO_FORMAT_PCM_16_BIT
157     */
158    audio_format_t (*get_format)(const struct audio_stream *stream);
159
160    /* currently unused - use set_parameters with key
161     *     AUDIO_PARAMETER_STREAM_FORMAT
162     */
163    int (*set_format)(struct audio_stream *stream, audio_format_t format);
164
165    /**
166     * Put the audio hardware input/output into standby mode.
167     * Driver should exit from standby mode at the next I/O operation.
168     * Returns 0 on success and <0 on failure.
169     */
170    int (*standby)(struct audio_stream *stream);
171
172    /** dump the state of the audio input/output device */
173    int (*dump)(const struct audio_stream *stream, int fd);
174
175    /** Return the set of device(s) which this stream is connected to */
176    audio_devices_t (*get_device)(const struct audio_stream *stream);
177
178    /**
179     * Currently unused - set_device() corresponds to set_parameters() with key
180     * AUDIO_PARAMETER_STREAM_ROUTING for both input and output.
181     * AUDIO_PARAMETER_STREAM_INPUT_SOURCE is an additional information used by
182     * input streams only.
183     */
184    int (*set_device)(struct audio_stream *stream, audio_devices_t device);
185
186    /**
187     * set/get audio stream parameters. The function accepts a list of
188     * parameter key value pairs in the form: key1=value1;key2=value2;...
189     *
190     * Some keys are reserved for standard parameters (See AudioParameter class)
191     *
192     * If the implementation does not accept a parameter change while
193     * the output is active but the parameter is acceptable otherwise, it must
194     * return -ENOSYS.
195     *
196     * The audio flinger will put the stream in standby and then change the
197     * parameter value.
198     */
199    int (*set_parameters)(struct audio_stream *stream, const char *kv_pairs);
200
201    /*
202     * Returns a pointer to a heap allocated string. The caller is responsible
203     * for freeing the memory for it using free().
204     */
205    char * (*get_parameters)(const struct audio_stream *stream,
206                             const char *keys);
207    int (*add_audio_effect)(const struct audio_stream *stream,
208                             effect_handle_t effect);
209    int (*remove_audio_effect)(const struct audio_stream *stream,
210                             effect_handle_t effect);
211};
212typedef struct audio_stream audio_stream_t;
213
214/**
215 * audio_stream_out is the abstraction interface for the audio output hardware.
216 *
217 * It provides information about various properties of the audio output
218 * hardware driver.
219 */
220
221struct audio_stream_out {
222    struct audio_stream common;
223
224    /**
225     * Return the audio hardware driver estimated latency in milliseconds.
226     */
227    uint32_t (*get_latency)(const struct audio_stream_out *stream);
228
229    /**
230     * Use this method in situations where audio mixing is done in the
231     * hardware. This method serves as a direct interface with hardware,
232     * allowing you to directly set the volume as apposed to via the framework.
233     * This method might produce multiple PCM outputs or hardware accelerated
234     * codecs, such as MP3 or AAC.
235     */
236    int (*set_volume)(struct audio_stream_out *stream, float left, float right);
237
238    /**
239     * Write audio buffer to driver. Returns number of bytes written, or a
240     * negative status_t. If at least one frame was written successfully prior to the error,
241     * it is suggested that the driver return that successful (short) byte count
242     * and then return an error in the subsequent call.
243     */
244    ssize_t (*write)(struct audio_stream_out *stream, const void* buffer,
245                     size_t bytes);
246
247    /* return the number of audio frames written by the audio dsp to DAC since
248     * the output has exited standby
249     */
250    int (*get_render_position)(const struct audio_stream_out *stream,
251                               uint32_t *dsp_frames);
252
253    /**
254     * get the local time at which the next write to the audio driver will be presented.
255     * The units are microseconds, where the epoch is decided by the local audio HAL.
256     */
257    int (*get_next_write_timestamp)(const struct audio_stream_out *stream,
258                                    int64_t *timestamp);
259
260};
261typedef struct audio_stream_out audio_stream_out_t;
262
263struct audio_stream_in {
264    struct audio_stream common;
265
266    /** set the input gain for the audio driver. This method is for
267     *  for future use */
268    int (*set_gain)(struct audio_stream_in *stream, float gain);
269
270    /** Read audio buffer in from audio driver. Returns number of bytes read, or a
271     *  negative status_t. If at least one frame was read prior to the error,
272     *  read should return that byte count and then return an error in the subsequent call.
273     */
274    ssize_t (*read)(struct audio_stream_in *stream, void* buffer,
275                    size_t bytes);
276
277    /**
278     * Return the amount of input frames lost in the audio driver since the
279     * last call of this function.
280     * Audio driver is expected to reset the value to 0 and restart counting
281     * upon returning the current value by this function call.
282     * Such loss typically occurs when the user space process is blocked
283     * longer than the capacity of audio driver buffers.
284     *
285     * Unit: the number of input audio frames
286     */
287    uint32_t (*get_input_frames_lost)(struct audio_stream_in *stream);
288};
289typedef struct audio_stream_in audio_stream_in_t;
290
291/**
292 * return the frame size (number of bytes per sample).
293 */
294static inline size_t audio_stream_frame_size(const struct audio_stream *s)
295{
296    size_t chan_samp_sz;
297
298    switch (s->get_format(s)) {
299    case AUDIO_FORMAT_PCM_16_BIT:
300        chan_samp_sz = sizeof(int16_t);
301        break;
302    case AUDIO_FORMAT_PCM_8_BIT:
303    default:
304        chan_samp_sz = sizeof(int8_t);
305        break;
306    }
307
308    return popcount(s->get_channels(s)) * chan_samp_sz;
309}
310
311
312/**********************************************************************/
313
314/**
315 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
316 * and the fields of this data structure must begin with hw_module_t
317 * followed by module specific information.
318 */
319struct audio_module {
320    struct hw_module_t common;
321};
322
323struct audio_hw_device {
324    struct hw_device_t common;
325
326    /**
327     * used by audio flinger to enumerate what devices are supported by
328     * each audio_hw_device implementation.
329     *
330     * Return value is a bitmask of 1 or more values of audio_devices_t
331     */
332    uint32_t (*get_supported_devices)(const struct audio_hw_device *dev);
333
334    /**
335     * check to see if the audio hardware interface has been initialized.
336     * returns 0 on success, -ENODEV on failure.
337     */
338    int (*init_check)(const struct audio_hw_device *dev);
339
340    /** set the audio volume of a voice call. Range is between 0.0 and 1.0 */
341    int (*set_voice_volume)(struct audio_hw_device *dev, float volume);
342
343    /**
344     * set the audio volume for all audio activities other than voice call.
345     * Range between 0.0 and 1.0. If any value other than 0 is returned,
346     * the software mixer will emulate this capability.
347     */
348    int (*set_master_volume)(struct audio_hw_device *dev, float volume);
349
350    /**
351     * Get the current master volume value for the HAL, if the HAL supports
352     * master volume control.  AudioFlinger will query this value from the
353     * primary audio HAL when the service starts and use the value for setting
354     * the initial master volume across all HALs.  HALs which do not support
355     * this method should may leave it set to NULL.
356     */
357    int (*get_master_volume)(struct audio_hw_device *dev, float *volume);
358
359    /**
360     * set_mode is called when the audio mode changes. AUDIO_MODE_NORMAL mode
361     * is for standard audio playback, AUDIO_MODE_RINGTONE when a ringtone is
362     * playing, and AUDIO_MODE_IN_CALL when a call is in progress.
363     */
364    int (*set_mode)(struct audio_hw_device *dev, audio_mode_t mode);
365
366    /* mic mute */
367    int (*set_mic_mute)(struct audio_hw_device *dev, bool state);
368    int (*get_mic_mute)(const struct audio_hw_device *dev, bool *state);
369
370    /* set/get global audio parameters */
371    int (*set_parameters)(struct audio_hw_device *dev, const char *kv_pairs);
372
373    /*
374     * Returns a pointer to a heap allocated string. The caller is responsible
375     * for freeing the memory for it using free().
376     */
377    char * (*get_parameters)(const struct audio_hw_device *dev,
378                             const char *keys);
379
380    /* Returns audio input buffer size according to parameters passed or
381     * 0 if one of the parameters is not supported.
382     * See also get_buffer_size which is for a particular stream.
383     */
384    size_t (*get_input_buffer_size)(const struct audio_hw_device *dev,
385                                    const struct audio_config *config);
386
387    /** This method creates and opens the audio hardware output stream */
388    int (*open_output_stream)(struct audio_hw_device *dev,
389                              audio_io_handle_t handle,
390                              audio_devices_t devices,
391                              audio_output_flags_t flags,
392                              struct audio_config *config,
393                              struct audio_stream_out **stream_out);
394
395    void (*close_output_stream)(struct audio_hw_device *dev,
396                                struct audio_stream_out* stream_out);
397
398    /** This method creates and opens the audio hardware input stream */
399    int (*open_input_stream)(struct audio_hw_device *dev,
400                             audio_io_handle_t handle,
401                             audio_devices_t devices,
402                             struct audio_config *config,
403                             struct audio_stream_in **stream_in);
404
405    void (*close_input_stream)(struct audio_hw_device *dev,
406                               struct audio_stream_in *stream_in);
407
408    /** This method dumps the state of the audio hardware */
409    int (*dump)(const struct audio_hw_device *dev, int fd);
410};
411typedef struct audio_hw_device audio_hw_device_t;
412
413/** convenience API for opening and closing a supported device */
414
415static inline int audio_hw_device_open(const struct hw_module_t* module,
416                                       struct audio_hw_device** device)
417{
418    return module->methods->open(module, AUDIO_HARDWARE_INTERFACE,
419                                 (struct hw_device_t**)device);
420}
421
422static inline int audio_hw_device_close(struct audio_hw_device* device)
423{
424    return device->common.close(&device->common);
425}
426
427
428__END_DECLS
429
430#endif  // ANDROID_AUDIO_INTERFACE_H
431