1/*
2 * Copyright (C) 2018 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
17package android.hardware.audio@4.0;
18
19import android.hardware.audio.common@4.0;
20
21enum Result : int32_t {
22    OK,
23    NOT_INITIALIZED,
24    INVALID_ARGUMENTS,
25    INVALID_STATE,
26    /**
27     * Methods marked as "Optional method" must return this result value
28     * if the operation is not supported by HAL.
29     */
30    NOT_SUPPORTED
31};
32
33@export(name="audio_drain_type_t", value_prefix="AUDIO_DRAIN_")
34enum AudioDrain : int32_t {
35    /** drain() returns when all data has been played. */
36    ALL,
37    /**
38     * drain() returns a short time before all data from the current track has
39     * been played to give time for gapless track switch.
40     */
41    EARLY_NOTIFY
42};
43
44/**
45 * A substitute for POSIX timespec.
46 */
47struct TimeSpec {
48    uint64_t tvSec;   // seconds
49    uint64_t tvNSec;  // nanoseconds
50};
51
52/**
53 * IEEE 802 MAC address.
54 */
55typedef uint8_t[6] MacAddress;
56
57struct ParameterValue {
58    string key;
59    string value;
60};
61
62/**
63 * Specifies a device in case when several devices of the same type
64 * can be connected (e.g. BT A2DP, USB).
65 */
66struct DeviceAddress {
67    AudioDevice device;  // discriminator
68    union Address {
69        MacAddress mac;     // used for BLUETOOTH_A2DP_*
70        uint8_t[4] ipv4;    // used for IP
71        struct Alsa {
72            int32_t card;
73            int32_t device;
74        } alsa;             // used for USB_*
75    } address;
76    string busAddress;      // used for BUS
77    string rSubmixAddress;  // used for REMOTE_SUBMIX
78};
79
80enum MmapBufferFlag : uint32_t {
81    NONE    = 0x0,
82    /**
83     * If the buffer can be securely shared to untrusted applications
84     * through the AAudio exclusive mode.
85     * Only set this flag if applications are restricted from accessing the
86     * memory surrounding the audio data buffer by a kernel mechanism.
87     * See Linux kernel's dma_buf.
88     */
89    APPLICATION_SHAREABLE    = 0x1,
90};
91
92/**
93 * Mmap buffer descriptor returned by IStream.createMmapBuffer().
94 * Used by streams opened in mmap mode.
95 */
96struct MmapBufferInfo {
97    /** Mmap memory buffer */
98    memory  sharedMemory;
99    /** Total buffer size in frames */
100    uint32_t bufferSizeFrames;
101    /** Transfer size granularity in frames */
102    uint32_t burstSizeFrames;
103    /** Attributes describing the buffer. */
104    bitfield<MmapBufferFlag> flags;
105};
106
107/**
108 * Mmap buffer read/write position returned by IStream.getMmapPosition().
109 * Used by streams opened in mmap mode.
110 */
111struct MmapPosition {
112    int64_t  timeNanoseconds; // time stamp in ns, CLOCK_MONOTONIC
113    int32_t  positionFrames;  // increasing 32 bit frame count reset when IStream.stop() is called
114};
115
116/**
117 * The message queue flags used to synchronize reads and writes from
118 * message queues used by StreamIn and StreamOut.
119 */
120enum MessageQueueFlagBits : uint32_t {
121    NOT_EMPTY = 1 << 0,
122    NOT_FULL = 1 << 1
123};
124
125/** Metadata of a playback track for a StreamOut. */
126struct PlaybackTrackMetadata {
127    AudioUsage usage;
128    AudioContentType contentType;
129    /**
130     * Positive linear gain applied to the track samples. 0 being muted and 1 is no attenuation,
131     * 2 means double amplification...
132     * Must not be negative.
133     */
134    float gain;
135};
136
137/** Metadatas of the source of a StreamOut. */
138struct SourceMetadata {
139    vec<PlaybackTrackMetadata> tracks;
140};
141
142/** Metadata of a record track for a StreamIn. */
143struct RecordTrackMetadata {
144    AudioSource source;
145    /**
146     * Positive linear gain applied to the track samples. 0 being muted and 1 is no attenuation,
147     * 2 means double amplification...
148     * Must not be negative.
149     */
150    float gain;
151};
152
153/** Metadatas of the source of a StreamIn. */
154struct SinkMetadata {
155    vec<RecordTrackMetadata> tracks;
156};
157
158/*
159 * Microphone information
160 *
161 */
162
163/**
164 * A 3D point used to represent position or orientation of a microphone.
165 *
166 * Position: Coordinates of the microphone's capsule, in meters, from the
167 * bottom-left-back corner of the bounding box of android device in natural
168 * orientation (PORTRAIT for phones, LANDSCAPE for tablets, tvs, etc).
169 * The orientation musth match the reported by the api Display.getRotation().
170 *
171 * Orientation: Normalized vector to signal the main orientation of the
172 * microphone's capsule. Magnitude = sqrt(x^2 + y^2 + z^2) = 1
173 */
174struct AudioMicrophoneCoordinate {
175    float x;
176    float y;
177    float z;
178};
179
180/**
181 * Enum to identify the type of channel mapping for active microphones.
182 * Used channels further identify if the microphone has any significative
183 * process (e.g. High Pass Filtering, dynamic compression)
184 * Simple processing as constant gain adjustment must be DIRECT.
185 */
186enum AudioMicrophoneChannelMapping : uint32_t {
187    UNUSED      = 0, /* Channel not used */
188    DIRECT      = 1, /* Channel used and signal not processed */
189    PROCESSED   = 2, /* Channel used and signal has some process */
190};
191
192/**
193 * Enum to identify locations of microphones in regards to the body of the
194 * android device.
195 */
196enum AudioMicrophoneLocation : uint32_t {
197    UNKNOWN             = 0,
198    MAINBODY            = 1,
199    MAINBODY_MOVABLE    = 2,
200    PERIPHERAL          = 3,
201};
202
203/**
204 * Identifier to help group related microphones together
205 * e.g. microphone arrays should belong to the same group
206 */
207typedef int32_t AudioMicrophoneGroup;
208
209/**
210 * Enum with standard polar patterns of microphones
211 */
212enum AudioMicrophoneDirectionality : uint32_t {
213    UNKNOWN         = 0,
214    OMNI            = 1,
215    BI_DIRECTIONAL  = 2,
216    CARDIOID        = 3,
217    HYPER_CARDIOID  = 4,
218    SUPER_CARDIOID  = 5,
219};
220
221/**
222 * A (frequency, level) pair. Used to represent frequency response.
223 */
224struct AudioFrequencyResponsePoint {
225    /** In Hz */
226    float frequency;
227    /** In dB */
228    float level;
229};
230
231/**
232 * Structure used by the HAL to describe microphone's characteristics
233 * Used by StreamIn and Device
234 */
235struct MicrophoneInfo {
236    /** Unique alphanumeric id for microphone. Guaranteed to be the same
237     * even after rebooting.
238     */
239    string                                  deviceId;
240    /**
241     * Device specific information
242     */
243    DeviceAddress                           deviceAddress;
244    /** Each element of the vector must describe the channel with the same
245     *  index.
246     */
247    vec<AudioMicrophoneChannelMapping>      channelMapping;
248    /** Location of the microphone in regard to the body of the device */
249    AudioMicrophoneLocation                 location;
250    /** Identifier to help group related microphones together
251     *  e.g. microphone arrays should belong to the same group
252     */
253    AudioMicrophoneGroup                    group;
254    /** Index of this microphone within the group.
255     *  (group, index) must be unique within the same device.
256     */
257    uint32_t                                indexInTheGroup;
258    /** Level in dBFS produced by a 1000 Hz tone at 94 dB SPL */
259    float                                   sensitivity;
260    /** Level in dB of the max SPL supported at 1000 Hz */
261    float                                   maxSpl;
262    /** Level in dB of the min SPL supported at 1000 Hz */
263    float                                   minSpl;
264    /** Standard polar pattern of the microphone */
265    AudioMicrophoneDirectionality           directionality;
266    /** Vector with ordered frequency responses (from low to high frequencies)
267     *  with the frequency response of the microphone.
268     *  Levels are in dB, relative to level at 1000 Hz
269     */
270    vec<AudioFrequencyResponsePoint>        frequencyResponse;
271    /** Position of the microphone's capsule in meters, from the
272     *  bottom-left-back corner of the bounding box of device.
273     */
274    AudioMicrophoneCoordinate               position;
275    /** Normalized point to signal the main orientation of the microphone's
276     *  capsule. sqrt(x^2 + y^2 + z^2) = 1
277     */
278    AudioMicrophoneCoordinate               orientation;
279};
280