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 */
124struct audio_config {
125    uint32_t sample_rate;
126    audio_channel_mask_t channel_mask;
127    audio_format_t  format;
128};
129
130typedef struct audio_config audio_config_t;
131
132/* common audio stream parameters and operations */
133struct 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};
214typedef 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
223struct 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};
263typedef struct audio_stream_out audio_stream_out_t;
264
265struct 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};
291typedef struct audio_stream_in audio_stream_in_t;
292
293/**
294 * return the frame size (number of bytes per sample).
295 */
296static 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 */
321struct audio_module {
322    struct hw_module_t common;
323};
324
325struct 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};
434typedef struct audio_hw_device audio_hw_device_t;
435
436/** convenience API for opening and closing a supported device */
437
438static 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
445static 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