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#define AUDIO_HARDWARE_MODULE_ID_CODEC_OFFLOAD "codec_offload"
71
72/**************************************/
73
74/**
75 *  standard audio parameters that the HAL may need to handle
76 */
77
78/**
79 *  audio device parameters
80 */
81
82/* BT SCO Noise Reduction + Echo Cancellation parameters */
83#define AUDIO_PARAMETER_KEY_BT_NREC "bt_headset_nrec"
84#define AUDIO_PARAMETER_VALUE_ON "on"
85#define AUDIO_PARAMETER_VALUE_OFF "off"
86
87/* TTY mode selection */
88#define AUDIO_PARAMETER_KEY_TTY_MODE "tty_mode"
89#define AUDIO_PARAMETER_VALUE_TTY_OFF "tty_off"
90#define AUDIO_PARAMETER_VALUE_TTY_VCO "tty_vco"
91#define AUDIO_PARAMETER_VALUE_TTY_HCO "tty_hco"
92#define AUDIO_PARAMETER_VALUE_TTY_FULL "tty_full"
93
94/* A2DP sink address set by framework */
95#define AUDIO_PARAMETER_A2DP_SINK_ADDRESS "a2dp_sink_address"
96
97/* Screen state */
98#define AUDIO_PARAMETER_KEY_SCREEN_STATE "screen_state"
99
100/**
101 *  audio stream parameters
102 */
103
104#define AUDIO_PARAMETER_STREAM_ROUTING "routing"            // audio_devices_t
105#define AUDIO_PARAMETER_STREAM_FORMAT "format"              // audio_format_t
106#define AUDIO_PARAMETER_STREAM_CHANNELS "channels"          // audio_channel_mask_t
107#define AUDIO_PARAMETER_STREAM_FRAME_COUNT "frame_count"    // size_t
108#define AUDIO_PARAMETER_STREAM_INPUT_SOURCE "input_source"  // audio_source_t
109#define AUDIO_PARAMETER_STREAM_SAMPLING_RATE "sampling_rate" // uint32_t
110
111/* Query supported formats. The response is a '|' separated list of strings from
112 * audio_format_t enum e.g: "sup_formats=AUDIO_FORMAT_PCM_16_BIT" */
113#define AUDIO_PARAMETER_STREAM_SUP_FORMATS "sup_formats"
114/* Query supported channel masks. The response is a '|' separated list of strings from
115 * audio_channel_mask_t enum e.g: "sup_channels=AUDIO_CHANNEL_OUT_STEREO|AUDIO_CHANNEL_OUT_MONO" */
116#define AUDIO_PARAMETER_STREAM_SUP_CHANNELS "sup_channels"
117/* Query supported sampling rates. The response is a '|' separated list of integer values e.g:
118 * "sup_sampling_rates=44100|48000" */
119#define AUDIO_PARAMETER_STREAM_SUP_SAMPLING_RATES "sup_sampling_rates"
120
121/**
122 * audio codec parameters
123 */
124
125#define AUDIO_OFFLOAD_CODEC_PARAMS "music_offload_codec_param"
126#define AUDIO_OFFLOAD_CODEC_BIT_PER_SAMPLE "music_offload_bit_per_sample"
127#define AUDIO_OFFLOAD_CODEC_BIT_RATE "music_offload_bit_rate"
128#define AUDIO_OFFLOAD_CODEC_AVG_BIT_RATE "music_offload_avg_bit_rate"
129#define AUDIO_OFFLOAD_CODEC_ID "music_offload_codec_id"
130#define AUDIO_OFFLOAD_CODEC_BLOCK_ALIGN "music_offload_block_align"
131#define AUDIO_OFFLOAD_CODEC_SAMPLE_RATE "music_offload_sample_rate"
132#define AUDIO_OFFLOAD_CODEC_ENCODE_OPTION "music_offload_encode_option"
133#define AUDIO_OFFLOAD_CODEC_NUM_CHANNEL  "music_offload_num_channels"
134#define AUDIO_OFFLOAD_CODEC_DOWN_SAMPLING  "music_offload_down_sampling"
135#define AUDIO_OFFLOAD_CODEC_DELAY_SAMPLES  "delay_samples"
136#define AUDIO_OFFLOAD_CODEC_PADDING_SAMPLES  "padding_samples"
137
138/**************************************/
139
140/* common audio stream configuration parameters
141 * You should memset() the entire structure to zero before use to
142 * ensure forward compatibility
143 */
144struct audio_config {
145    uint32_t sample_rate;
146    audio_channel_mask_t channel_mask;
147    audio_format_t  format;
148    audio_offload_info_t offload_info;
149};
150typedef struct audio_config audio_config_t;
151
152/* common audio stream parameters and operations */
153struct audio_stream {
154
155    /**
156     * Return the sampling rate in Hz - eg. 44100.
157     */
158    uint32_t (*get_sample_rate)(const struct audio_stream *stream);
159
160    /* currently unused - use set_parameters with key
161     *    AUDIO_PARAMETER_STREAM_SAMPLING_RATE
162     */
163    int (*set_sample_rate)(struct audio_stream *stream, uint32_t rate);
164
165    /**
166     * Return size of input/output buffer in bytes for this stream - eg. 4800.
167     * It should be a multiple of the frame size.  See also get_input_buffer_size.
168     */
169    size_t (*get_buffer_size)(const struct audio_stream *stream);
170
171    /**
172     * Return the channel mask -
173     *  e.g. AUDIO_CHANNEL_OUT_STEREO or AUDIO_CHANNEL_IN_STEREO
174     */
175    audio_channel_mask_t (*get_channels)(const struct audio_stream *stream);
176
177    /**
178     * Return the audio format - e.g. AUDIO_FORMAT_PCM_16_BIT
179     */
180    audio_format_t (*get_format)(const struct audio_stream *stream);
181
182    /* currently unused - use set_parameters with key
183     *     AUDIO_PARAMETER_STREAM_FORMAT
184     */
185    int (*set_format)(struct audio_stream *stream, audio_format_t format);
186
187    /**
188     * Put the audio hardware input/output into standby mode.
189     * Driver should exit from standby mode at the next I/O operation.
190     * Returns 0 on success and <0 on failure.
191     */
192    int (*standby)(struct audio_stream *stream);
193
194    /** dump the state of the audio input/output device */
195    int (*dump)(const struct audio_stream *stream, int fd);
196
197    /** Return the set of device(s) which this stream is connected to */
198    audio_devices_t (*get_device)(const struct audio_stream *stream);
199
200    /**
201     * Currently unused - set_device() corresponds to set_parameters() with key
202     * AUDIO_PARAMETER_STREAM_ROUTING for both input and output.
203     * AUDIO_PARAMETER_STREAM_INPUT_SOURCE is an additional information used by
204     * input streams only.
205     */
206    int (*set_device)(struct audio_stream *stream, audio_devices_t device);
207
208    /**
209     * set/get audio stream parameters. The function accepts a list of
210     * parameter key value pairs in the form: key1=value1;key2=value2;...
211     *
212     * Some keys are reserved for standard parameters (See AudioParameter class)
213     *
214     * If the implementation does not accept a parameter change while
215     * the output is active but the parameter is acceptable otherwise, it must
216     * return -ENOSYS.
217     *
218     * The audio flinger will put the stream in standby and then change the
219     * parameter value.
220     */
221    int (*set_parameters)(struct audio_stream *stream, const char *kv_pairs);
222
223    /*
224     * Returns a pointer to a heap allocated string. The caller is responsible
225     * for freeing the memory for it using free().
226     */
227    char * (*get_parameters)(const struct audio_stream *stream,
228                             const char *keys);
229    int (*add_audio_effect)(const struct audio_stream *stream,
230                             effect_handle_t effect);
231    int (*remove_audio_effect)(const struct audio_stream *stream,
232                             effect_handle_t effect);
233};
234typedef struct audio_stream audio_stream_t;
235
236/* type of asynchronous write callback events. Mutually exclusive */
237typedef enum {
238    STREAM_CBK_EVENT_WRITE_READY, /* non blocking write completed */
239    STREAM_CBK_EVENT_DRAIN_READY  /* drain completed */
240} stream_callback_event_t;
241
242typedef int (*stream_callback_t)(stream_callback_event_t event, void *param, void *cookie);
243
244/* type of drain requested to audio_stream_out->drain(). Mutually exclusive */
245typedef enum {
246    AUDIO_DRAIN_ALL,            /* drain() returns when all data has been played */
247    AUDIO_DRAIN_EARLY_NOTIFY    /* drain() returns a short time before all data
248                                   from the current track has been played to
249                                   give time for gapless track switch */
250} audio_drain_type_t;
251
252/**
253 * audio_stream_out is the abstraction interface for the audio output hardware.
254 *
255 * It provides information about various properties of the audio output
256 * hardware driver.
257 */
258
259struct audio_stream_out {
260    struct audio_stream common;
261
262    /**
263     * Return the audio hardware driver estimated latency in milliseconds.
264     */
265    uint32_t (*get_latency)(const struct audio_stream_out *stream);
266
267    /**
268     * Use this method in situations where audio mixing is done in the
269     * hardware. This method serves as a direct interface with hardware,
270     * allowing you to directly set the volume as apposed to via the framework.
271     * This method might produce multiple PCM outputs or hardware accelerated
272     * codecs, such as MP3 or AAC.
273     */
274    int (*set_volume)(struct audio_stream_out *stream, float left, float right);
275
276    /**
277     * Write audio buffer to driver. Returns number of bytes written, or a
278     * negative status_t. If at least one frame was written successfully prior to the error,
279     * it is suggested that the driver return that successful (short) byte count
280     * and then return an error in the subsequent call.
281     *
282     * If set_callback() has previously been called to enable non-blocking mode
283     * the write() is not allowed to block. It must write only the number of
284     * bytes that currently fit in the driver/hardware buffer and then return
285     * this byte count. If this is less than the requested write size the
286     * callback function must be called when more space is available in the
287     * driver/hardware buffer.
288     */
289    ssize_t (*write)(struct audio_stream_out *stream, const void* buffer,
290                     size_t bytes);
291
292    /* return the number of audio frames written by the audio dsp to DAC since
293     * the output has exited standby
294     */
295    int (*get_render_position)(const struct audio_stream_out *stream,
296                               uint32_t *dsp_frames);
297
298    /**
299     * get the local time at which the next write to the audio driver will be presented.
300     * The units are microseconds, where the epoch is decided by the local audio HAL.
301     */
302    int (*get_next_write_timestamp)(const struct audio_stream_out *stream,
303                                    int64_t *timestamp);
304
305    /**
306     * set the callback function for notifying completion of non-blocking
307     * write and drain.
308     * Calling this function implies that all future write() and drain()
309     * must be non-blocking and use the callback to signal completion.
310     */
311    int (*set_callback)(struct audio_stream_out *stream,
312            stream_callback_t callback, void *cookie);
313
314    /**
315     * Notifies to the audio driver to stop playback however the queued buffers are
316     * retained by the hardware. Useful for implementing pause/resume. Empty implementation
317     * if not supported however should be implemented for hardware with non-trivial
318     * latency. In the pause state audio hardware could still be using power. User may
319     * consider calling suspend after a timeout.
320     *
321     * Implementation of this function is mandatory for offloaded playback.
322     */
323    int (*pause)(struct audio_stream_out* stream);
324
325    /**
326     * Notifies to the audio driver to resume playback following a pause.
327     * Returns error if called without matching pause.
328     *
329     * Implementation of this function is mandatory for offloaded playback.
330     */
331    int (*resume)(struct audio_stream_out* stream);
332
333    /**
334     * Requests notification when data buffered by the driver/hardware has
335     * been played. If set_callback() has previously been called to enable
336     * non-blocking mode, the drain() must not block, instead it should return
337     * quickly and completion of the drain is notified through the callback.
338     * If set_callback() has not been called, the drain() must block until
339     * completion.
340     * If type==AUDIO_DRAIN_ALL, the drain completes when all previously written
341     * data has been played.
342     * If type==AUDIO_DRAIN_EARLY_NOTIFY, the drain completes shortly before all
343     * data for the current track has played to allow time for the framework
344     * to perform a gapless track switch.
345     *
346     * Drain must return immediately on stop() and flush() call
347     *
348     * Implementation of this function is mandatory for offloaded playback.
349     */
350    int (*drain)(struct audio_stream_out* stream, audio_drain_type_t type );
351
352    /**
353     * Notifies to the audio driver to flush the queued data. Stream must already
354     * be paused before calling flush().
355     *
356     * Implementation of this function is mandatory for offloaded playback.
357     */
358   int (*flush)(struct audio_stream_out* stream);
359
360    /**
361     * Return a recent count of the number of audio frames presented to an external observer.
362     * This excludes frames which have been written but are still in the pipeline.
363     * The count is not reset to zero when output enters standby.
364     * Also returns the value of CLOCK_MONOTONIC as of this presentation count.
365     * The returned count is expected to be 'recent',
366     * but does not need to be the most recent possible value.
367     * However, the associated time should correspond to whatever count is returned.
368     * Example:  assume that N+M frames have been presented, where M is a 'small' number.
369     * Then it is permissible to return N instead of N+M,
370     * and the timestamp should correspond to N rather than N+M.
371     * The terms 'recent' and 'small' are not defined.
372     * They reflect the quality of the implementation.
373     *
374     * 3.0 and higher only.
375     */
376    int (*get_presentation_position)(const struct audio_stream_out *stream,
377                               uint64_t *frames, struct timespec *timestamp);
378
379};
380typedef struct audio_stream_out audio_stream_out_t;
381
382struct audio_stream_in {
383    struct audio_stream common;
384
385    /** set the input gain for the audio driver. This method is for
386     *  for future use */
387    int (*set_gain)(struct audio_stream_in *stream, float gain);
388
389    /** Read audio buffer in from audio driver. Returns number of bytes read, or a
390     *  negative status_t. If at least one frame was read prior to the error,
391     *  read should return that byte count and then return an error in the subsequent call.
392     */
393    ssize_t (*read)(struct audio_stream_in *stream, void* buffer,
394                    size_t bytes);
395
396    /**
397     * Return the amount of input frames lost in the audio driver since the
398     * last call of this function.
399     * Audio driver is expected to reset the value to 0 and restart counting
400     * upon returning the current value by this function call.
401     * Such loss typically occurs when the user space process is blocked
402     * longer than the capacity of audio driver buffers.
403     *
404     * Unit: the number of input audio frames
405     */
406    uint32_t (*get_input_frames_lost)(struct audio_stream_in *stream);
407};
408typedef struct audio_stream_in audio_stream_in_t;
409
410/**
411 * return the frame size (number of bytes per sample).
412 */
413static inline size_t audio_stream_frame_size(const struct audio_stream *s)
414{
415    size_t chan_samp_sz;
416    audio_format_t format = s->get_format(s);
417
418    if (audio_is_linear_pcm(format)) {
419        chan_samp_sz = audio_bytes_per_sample(format);
420        return popcount(s->get_channels(s)) * chan_samp_sz;
421    }
422
423    return sizeof(int8_t);
424}
425
426
427/**********************************************************************/
428
429/**
430 * Every hardware module must have a data structure named HAL_MODULE_INFO_SYM
431 * and the fields of this data structure must begin with hw_module_t
432 * followed by module specific information.
433 */
434struct audio_module {
435    struct hw_module_t common;
436};
437
438struct audio_hw_device {
439    struct hw_device_t common;
440
441    /**
442     * used by audio flinger to enumerate what devices are supported by
443     * each audio_hw_device implementation.
444     *
445     * Return value is a bitmask of 1 or more values of audio_devices_t
446     *
447     * NOTE: audio HAL implementations starting with
448     * AUDIO_DEVICE_API_VERSION_2_0 do not implement this function.
449     * All supported devices should be listed in audio_policy.conf
450     * file and the audio policy manager must choose the appropriate
451     * audio module based on information in this file.
452     */
453    uint32_t (*get_supported_devices)(const struct audio_hw_device *dev);
454
455    /**
456     * check to see if the audio hardware interface has been initialized.
457     * returns 0 on success, -ENODEV on failure.
458     */
459    int (*init_check)(const struct audio_hw_device *dev);
460
461    /** set the audio volume of a voice call. Range is between 0.0 and 1.0 */
462    int (*set_voice_volume)(struct audio_hw_device *dev, float volume);
463
464    /**
465     * set the audio volume for all audio activities other than voice call.
466     * Range between 0.0 and 1.0. If any value other than 0 is returned,
467     * the software mixer will emulate this capability.
468     */
469    int (*set_master_volume)(struct audio_hw_device *dev, float volume);
470
471    /**
472     * Get the current master volume value for the HAL, if the HAL supports
473     * master volume control.  AudioFlinger will query this value from the
474     * primary audio HAL when the service starts and use the value for setting
475     * the initial master volume across all HALs.  HALs which do not support
476     * this method may leave it set to NULL.
477     */
478    int (*get_master_volume)(struct audio_hw_device *dev, float *volume);
479
480    /**
481     * set_mode is called when the audio mode changes. AUDIO_MODE_NORMAL mode
482     * is for standard audio playback, AUDIO_MODE_RINGTONE when a ringtone is
483     * playing, and AUDIO_MODE_IN_CALL when a call is in progress.
484     */
485    int (*set_mode)(struct audio_hw_device *dev, audio_mode_t mode);
486
487    /* mic mute */
488    int (*set_mic_mute)(struct audio_hw_device *dev, bool state);
489    int (*get_mic_mute)(const struct audio_hw_device *dev, bool *state);
490
491    /* set/get global audio parameters */
492    int (*set_parameters)(struct audio_hw_device *dev, const char *kv_pairs);
493
494    /*
495     * Returns a pointer to a heap allocated string. The caller is responsible
496     * for freeing the memory for it using free().
497     */
498    char * (*get_parameters)(const struct audio_hw_device *dev,
499                             const char *keys);
500
501    /* Returns audio input buffer size according to parameters passed or
502     * 0 if one of the parameters is not supported.
503     * See also get_buffer_size which is for a particular stream.
504     */
505    size_t (*get_input_buffer_size)(const struct audio_hw_device *dev,
506                                    const struct audio_config *config);
507
508    /** This method creates and opens the audio hardware output stream */
509    int (*open_output_stream)(struct audio_hw_device *dev,
510                              audio_io_handle_t handle,
511                              audio_devices_t devices,
512                              audio_output_flags_t flags,
513                              struct audio_config *config,
514                              struct audio_stream_out **stream_out);
515
516    void (*close_output_stream)(struct audio_hw_device *dev,
517                                struct audio_stream_out* stream_out);
518
519    /** This method creates and opens the audio hardware input stream */
520    int (*open_input_stream)(struct audio_hw_device *dev,
521                             audio_io_handle_t handle,
522                             audio_devices_t devices,
523                             struct audio_config *config,
524                             struct audio_stream_in **stream_in);
525
526    void (*close_input_stream)(struct audio_hw_device *dev,
527                               struct audio_stream_in *stream_in);
528
529    /** This method dumps the state of the audio hardware */
530    int (*dump)(const struct audio_hw_device *dev, int fd);
531
532    /**
533     * set the audio mute status for all audio activities.  If any value other
534     * than 0 is returned, the software mixer will emulate this capability.
535     */
536    int (*set_master_mute)(struct audio_hw_device *dev, bool mute);
537
538    /**
539     * Get the current master mute status for the HAL, if the HAL supports
540     * master mute control.  AudioFlinger will query this value from the primary
541     * audio HAL when the service starts and use the value for setting the
542     * initial master mute across all HALs.  HALs which do not support this
543     * method may leave it set to NULL.
544     */
545    int (*get_master_mute)(struct audio_hw_device *dev, bool *mute);
546};
547typedef struct audio_hw_device audio_hw_device_t;
548
549/** convenience API for opening and closing a supported device */
550
551static inline int audio_hw_device_open(const struct hw_module_t* module,
552                                       struct audio_hw_device** device)
553{
554    return module->methods->open(module, AUDIO_HARDWARE_INTERFACE,
555                                 (struct hw_device_t**)device);
556}
557
558static inline int audio_hw_device_close(struct audio_hw_device* device)
559{
560    return device->common.close(&device->common);
561}
562
563
564__END_DECLS
565
566#endif  // ANDROID_AUDIO_INTERFACE_H
567