audio.h revision 5ad38a901dcca2961f3ed35ae0b206c13bc515cd 
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
46/**
47 *  standard audio parameters that the HAL may need to handle
48 */
49
50/**
51 *  audio device parameters
52 */
53
54/* BT SCO Noise Reduction + Echo Cancellation parameters */
55#define AUDIO_PARAMETER_KEY_BT_NREC "bt_headset_nrec"
56#define AUDIO_PARAMETER_VALUE_ON "on"
57#define AUDIO_PARAMETER_VALUE_OFF "off"
58
59/* TTY mode selection */
60#define AUDIO_PARAMETER_KEY_TTY_MODE "tty_mode"
61#define AUDIO_PARAMETER_VALUE_TTY_OFF "tty_off"
62#define AUDIO_PARAMETER_VALUE_TTY_VCO "tty_vco"
63#define AUDIO_PARAMETER_VALUE_TTY_HCO "tty_hco"
64#define AUDIO_PARAMETER_VALUE_TTY_FULL "tty_full"
65
66/**
67 *  audio stream parameters
68 */
69
70#define AUDIO_PARAMETER_STREAM_ROUTING "routing"
71#define AUDIO_PARAMETER_STREAM_FORMAT "format"
72#define AUDIO_PARAMETER_STREAM_CHANNELS "channels"
73#define AUDIO_PARAMETER_STREAM_FRAME_COUNT "frame_count"
74#define AUDIO_PARAMETER_STREAM_INPUT_SOURCE "input_source"
75
76/**************************************/
77
78/* common audio stream parameters and operations */
79struct audio_stream {
80
81    /**
82     * sampling rate is in Hz - eg. 44100
83     */
84    uint32_t (*get_sample_rate)(const struct audio_stream *stream);
85
86    /* currently unused - use set_parameters with key
87     *    AUDIO_PARAMETER_STREAM_SAMPLING_RATE
88     */
89    int (*set_sample_rate)(struct audio_stream *stream, uint32_t rate);
90
91    /**
92     * size of output buffer in bytes - eg. 4800
93     */
94    size_t (*get_buffer_size)(const struct audio_stream *stream);
95
96    /**
97     * the channel mask -
98     *  e.g. AUDIO_CHANNEL_OUT_STEREO or AUDIO_CHANNEL_IN_STEREO
99     */
100    uint32_t (*get_channels)(const struct audio_stream *stream);
101
102    /**
103     * audio format - eg. AUDIO_FORMAT_PCM_16_BIT
104     */
105    audio_format_t (*get_format)(const struct audio_stream *stream);
106
107    /* currently unused - use set_parameters with key
108     *     AUDIO_PARAMETER_STREAM_FORMAT
109     */
110    int (*set_format)(struct audio_stream *stream, audio_format_t format);
111
112    /**
113     * Put the audio hardware input/output into standby mode.
114     * Returns 0 on success and <0 on failure.
115     */
116    int (*standby)(struct audio_stream *stream);
117
118    /** dump the state of the audio input/output device */
119    int (*dump)(const struct audio_stream *stream, int fd);
120
121    audio_devices_t (*get_device)(const struct audio_stream *stream);
122    int (*set_device)(struct audio_stream *stream, audio_devices_t device);
123
124    /**
125     * set/get audio stream parameters. The function accepts a list of
126     * parameter key value pairs in the form: key1=value1;key2=value2;...
127     *
128     * Some keys are reserved for standard parameters (See AudioParameter class)
129     *
130     * If the implementation does not accept a parameter change while
131     * the output is active but the parameter is acceptable otherwise, it must
132     * return -ENOSYS.
133     *
134     * The audio flinger will put the stream in standby and then change the
135     * parameter value.
136     */
137    int (*set_parameters)(struct audio_stream *stream, const char *kv_pairs);
138
139    /*
140     * Returns a pointer to a heap allocated string. The caller is responsible
141     * for freeing the memory for it.
142     */
143    char * (*get_parameters)(const struct audio_stream *stream,
144                             const char *keys);
145    int (*add_audio_effect)(const struct audio_stream *stream,
146                             effect_handle_t effect);
147    int (*remove_audio_effect)(const struct audio_stream *stream,
148                             effect_handle_t effect);
149};
150typedef struct audio_stream audio_stream_t;
151
152/**
153 * audio_stream_out is the abstraction interface for the audio output hardware.
154 *
155 * It provides information about various properties of the audio output
156 * hardware driver.
157 */
158
159struct audio_stream_out {
160    struct audio_stream common;
161
162    /**
163     * return the audio hardware driver latency in milli seconds.
164     */
165    uint32_t (*get_latency)(const struct audio_stream_out *stream);
166
167    /**
168     * Use this method in situations where audio mixing is done in the
169     * hardware. This method serves as a direct interface with hardware,
170     * allowing you to directly set the volume as apposed to via the framework.
171     * This method might produce multiple PCM outputs or hardware accelerated
172     * codecs, such as MP3 or AAC.
173     */
174    int (*set_volume)(struct audio_stream_out *stream, float left, float right);
175
176    /**
177     * write audio buffer to driver. Returns number of bytes written
178     */
179    ssize_t (*write)(struct audio_stream_out *stream, const void* buffer,
180                     size_t bytes);
181
182    /* return the number of audio frames written by the audio dsp to DAC since
183     * the output has exited standby
184     */
185    int (*get_render_position)(const struct audio_stream_out *stream,
186                               uint32_t *dsp_frames);
187
188    /**
189     * get the local time at which the next write to the audio driver will be
190     * presented
191     */
192    int (*get_next_write_timestamp)(const struct audio_stream_out *stream,
193                                    int64_t *timestamp);
194
195};
196typedef struct audio_stream_out audio_stream_out_t;
197
198struct audio_stream_in {
199    struct audio_stream common;
200
201    /** set the input gain for the audio driver. This method is for
202     *  for future use */
203    int (*set_gain)(struct audio_stream_in *stream, float gain);
204
205    /** read audio buffer in from audio driver */
206    ssize_t (*read)(struct audio_stream_in *stream, void* buffer,
207                    size_t bytes);
208
209    /**
210     * Return the amount of input frames lost in the audio driver since the
211     * last call of this function.
212     * Audio driver is expected to reset the value to 0 and restart counting
213     * upon returning the current value by this function call.
214     * Such loss typically occurs when the user space process is blocked
215     * longer than the capacity of audio driver buffers.
216     *
217     * Unit: the number of input audio frames
218     */
219    uint32_t (*get_input_frames_lost)(struct audio_stream_in *stream);
220};
221typedef struct audio_stream_in audio_stream_in_t;
222
223/**
224 * return the frame size (number of bytes per sample).
225 */
226static inline size_t audio_stream_frame_size(struct audio_stream *s)
227{
228    size_t chan_samp_sz;
229
230    switch (s->get_format(s)) {
231    case AUDIO_FORMAT_PCM_16_BIT:
232        chan_samp_sz = sizeof(int16_t);
233        break;
234    case AUDIO_FORMAT_PCM_8_BIT:
235    default:
236        chan_samp_sz = sizeof(int8_t);
237        break;
238    }
239
240    return popcount(s->get_channels(s)) * chan_samp_sz;
241}
242
243
244/**********************************************************************/
245
246/**
247 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
248 * and the fields of this data structure must begin with hw_module_t
249 * followed by module specific information.
250 */
251struct audio_module {
252    struct hw_module_t common;
253};
254
255struct audio_hw_device {
256    struct hw_device_t common;
257
258    /**
259     * used by audio flinger to enumerate what devices are supported by
260     * each audio_hw_device implementation.
261     *
262     * Return value is a bitmask of 1 or more values of audio_devices_t
263     */
264    uint32_t (*get_supported_devices)(const struct audio_hw_device *dev);
265
266    /**
267     * check to see if the audio hardware interface has been initialized.
268     * returns 0 on success, -ENODEV on failure.
269     */
270    int (*init_check)(const struct audio_hw_device *dev);
271
272    /** set the audio volume of a voice call. Range is between 0.0 and 1.0 */
273    int (*set_voice_volume)(struct audio_hw_device *dev, float volume);
274
275    /**
276     * set the audio volume for all audio activities other than voice call.
277     * Range between 0.0 and 1.0. If any value other than 0 is returned,
278     * the software mixer will emulate this capability.
279     */
280    int (*set_master_volume)(struct audio_hw_device *dev, float volume);
281
282    /**
283     * Get the current master volume value for the HAL, if the HAL supports
284     * master volume control.  AudioFlinger will query this value from the
285     * primary audio HAL when the service starts and use the value for setting
286     * the initial master volume across all HALs.  HALs which do not support
287     * this method should may leave it set to NULL.
288     */
289    int (*get_master_volume)(struct audio_hw_device *dev, float *volume);
290
291    /**
292     * set_mode is called when the audio mode changes. AUDIO_MODE_NORMAL mode
293     * is for standard audio playback, AUDIO_MODE_RINGTONE when a ringtone is
294     * playing, and AUDIO_MODE_IN_CALL when a call is in progress.
295     */
296    int (*set_mode)(struct audio_hw_device *dev, audio_mode_t mode);
297
298    /* mic mute */
299    int (*set_mic_mute)(struct audio_hw_device *dev, bool state);
300    int (*get_mic_mute)(const struct audio_hw_device *dev, bool *state);
301
302    /* set/get global audio parameters */
303    int (*set_parameters)(struct audio_hw_device *dev, const char *kv_pairs);
304
305    /*
306     * Returns a pointer to a heap allocated string. The caller is responsible
307     * for freeing the memory for it.
308     */
309    char * (*get_parameters)(const struct audio_hw_device *dev,
310                             const char *keys);
311
312    /* Returns audio input buffer size according to parameters passed or
313     * 0 if one of the parameters is not supported
314     */
315    size_t (*get_input_buffer_size)(const struct audio_hw_device *dev,
316                                    uint32_t sample_rate, audio_format_t format,
317                                    int channel_count);
318
319    /** This method creates and opens the audio hardware output stream */
320    int (*open_output_stream)(struct audio_hw_device *dev, uint32_t devices,
321                              audio_format_t *format, uint32_t *channels,
322                              uint32_t *sample_rate,
323                              struct audio_stream_out **out);
324
325    void (*close_output_stream)(struct audio_hw_device *dev,
326                                struct audio_stream_out* out);
327
328    /** This method creates and opens the audio hardware input stream */
329    int (*open_input_stream)(struct audio_hw_device *dev, uint32_t devices,
330                             audio_format_t *format, uint32_t *channels,
331                             uint32_t *sample_rate,
332                             audio_in_acoustics_t acoustics,
333                             struct audio_stream_in **stream_in);
334
335    void (*close_input_stream)(struct audio_hw_device *dev,
336                               struct audio_stream_in *in);
337
338    /** This method dumps the state of the audio hardware */
339    int (*dump)(const struct audio_hw_device *dev, int fd);
340};
341typedef struct audio_hw_device audio_hw_device_t;
342
343/** convenience API for opening and closing a supported device */
344
345static inline int audio_hw_device_open(const struct hw_module_t* module,
346                                       struct audio_hw_device** device)
347{
348    return module->methods->open(module, AUDIO_HARDWARE_INTERFACE,
349                                 (struct hw_device_t**)device);
350}
351
352static inline int audio_hw_device_close(struct audio_hw_device* device)
353{
354    return device->common.close(&device->common);
355}
356
357
358__END_DECLS
359
360#endif  // ANDROID_AUDIO_INTERFACE_H
361