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