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@5.0;
18
19import android.hardware.audio.common@5.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
52struct ParameterValue {
53    string key;
54    string value;
55};
56
57enum MmapBufferFlag : uint32_t {
58    NONE    = 0x0,
59    /**
60     * If the buffer can be securely shared to untrusted applications
61     * through the AAudio exclusive mode.
62     * Only set this flag if applications are restricted from accessing the
63     * memory surrounding the audio data buffer by a kernel mechanism.
64     * See Linux kernel's dma_buf.
65     */
66    APPLICATION_SHAREABLE    = 0x1,
67};
68
69/**
70 * Mmap buffer descriptor returned by IStream.createMmapBuffer().
71 * Used by streams opened in mmap mode.
72 */
73struct MmapBufferInfo {
74    /** Mmap memory buffer */
75    memory  sharedMemory;
76    /** Total buffer size in frames */
77    uint32_t bufferSizeFrames;
78    /** Transfer size granularity in frames */
79    uint32_t burstSizeFrames;
80    /** Attributes describing the buffer. */
81    bitfield<MmapBufferFlag> flags;
82};
83
84/**
85 * Mmap buffer read/write position returned by IStream.getMmapPosition().
86 * Used by streams opened in mmap mode.
87 */
88struct MmapPosition {
89    int64_t  timeNanoseconds; // time stamp in ns, CLOCK_MONOTONIC
90    int32_t  positionFrames;  // increasing 32 bit frame count reset when IStream.stop() is called
91};
92
93/**
94 * The message queue flags used to synchronize reads and writes from
95 * message queues used by StreamIn and StreamOut.
96 */
97enum MessageQueueFlagBits : uint32_t {
98    NOT_EMPTY = 1 << 0,
99    NOT_FULL = 1 << 1
100};
101
102/*
103 * Microphone information
104 *
105 */
106
107/**
108 * A 3D point used to represent position or orientation of a microphone.
109 *
110 * Position: Coordinates of the microphone's capsule, in meters, from the
111 * bottom-left-back corner of the bounding box of android device in natural
112 * orientation (PORTRAIT for phones, LANDSCAPE for tablets, tvs, etc).
113 * The orientation musth match the reported by the api Display.getRotation().
114 *
115 * Orientation: Normalized vector to signal the main orientation of the
116 * microphone's capsule. Magnitude = sqrt(x^2 + y^2 + z^2) = 1
117 */
118struct AudioMicrophoneCoordinate {
119    float x;
120    float y;
121    float z;
122};
123
124/**
125 * Enum to identify the type of channel mapping for active microphones.
126 * Used channels further identify if the microphone has any significative
127 * process (e.g. High Pass Filtering, dynamic compression)
128 * Simple processing as constant gain adjustment must be DIRECT.
129 */
130enum AudioMicrophoneChannelMapping : uint32_t {
131    UNUSED      = 0, /* Channel not used */
132    DIRECT      = 1, /* Channel used and signal not processed */
133    PROCESSED   = 2, /* Channel used and signal has some process */
134};
135
136/**
137 * Enum to identify locations of microphones in regards to the body of the
138 * android device.
139 */
140enum AudioMicrophoneLocation : uint32_t {
141    UNKNOWN             = 0,
142    MAINBODY            = 1,
143    MAINBODY_MOVABLE    = 2,
144    PERIPHERAL          = 3,
145};
146
147/**
148 * Identifier to help group related microphones together
149 * e.g. microphone arrays should belong to the same group
150 */
151typedef int32_t AudioMicrophoneGroup;
152
153/**
154 * Enum with standard polar patterns of microphones
155 */
156enum AudioMicrophoneDirectionality : uint32_t {
157    UNKNOWN         = 0,
158    OMNI            = 1,
159    BI_DIRECTIONAL  = 2,
160    CARDIOID        = 3,
161    HYPER_CARDIOID  = 4,
162    SUPER_CARDIOID  = 5,
163};
164
165/**
166 * A (frequency, level) pair. Used to represent frequency response.
167 */
168struct AudioFrequencyResponsePoint {
169    /** In Hz */
170    float frequency;
171    /** In dB */
172    float level;
173};
174
175/**
176 * Structure used by the HAL to describe microphone's characteristics
177 * Used by StreamIn and Device
178 */
179struct MicrophoneInfo {
180    /** Unique alphanumeric id for microphone. Guaranteed to be the same
181     * even after rebooting.
182     */
183    string                                  deviceId;
184    /**
185     * Device specific information
186     */
187    DeviceAddress                           deviceAddress;
188    /** Each element of the vector must describe the channel with the same
189     *  index.
190     */
191    vec<AudioMicrophoneChannelMapping>      channelMapping;
192    /** Location of the microphone in regard to the body of the device */
193    AudioMicrophoneLocation                 location;
194    /** Identifier to help group related microphones together
195     *  e.g. microphone arrays should belong to the same group
196     */
197    AudioMicrophoneGroup                    group;
198    /** Index of this microphone within the group.
199     *  (group, index) must be unique within the same device.
200     */
201    uint32_t                                indexInTheGroup;
202    /** Level in dBFS produced by a 1000 Hz tone at 94 dB SPL */
203    float                                   sensitivity;
204    /** Level in dB of the max SPL supported at 1000 Hz */
205    float                                   maxSpl;
206    /** Level in dB of the min SPL supported at 1000 Hz */
207    float                                   minSpl;
208    /** Standard polar pattern of the microphone */
209    AudioMicrophoneDirectionality           directionality;
210    /** Vector with ordered frequency responses (from low to high frequencies)
211     *  with the frequency response of the microphone.
212     *  Levels are in dB, relative to level at 1000 Hz
213     */
214    vec<AudioFrequencyResponsePoint>        frequencyResponse;
215    /** Position of the microphone's capsule in meters, from the
216     *  bottom-left-back corner of the bounding box of device.
217     */
218    AudioMicrophoneCoordinate               position;
219    /** Normalized point to signal the main orientation of the microphone's
220     *  capsule. sqrt(x^2 + y^2 + z^2) = 1
221     */
222    AudioMicrophoneCoordinate               orientation;
223};
224
225/**
226 * Constants used by the HAL to determine how to select microphones and process those inputs in
227 * order to optimize for capture in the specified direction.
228 *
229 * MicrophoneDirection Constants are defined in MicrophoneDirection.java.
230 */
231@export(name="audio_microphone_direction_t", value_prefix="MIC_DIRECTION_")
232enum MicrophoneDirection : int32_t {
233    /**
234     * Don't do any directionality processing of the activated microphone(s).
235     */
236    UNSPECIFIED = 0,
237    /**
238     * Optimize capture for audio coming from the screen-side of the device.
239     */
240    FRONT = 1,
241    /**
242     * Optimize capture for audio coming from the side of the device opposite the screen.
243     */
244    BACK = 2,
245    /**
246     * Optimize capture for audio coming from an off-device microphone.
247     */
248    EXTERNAL = 3,
249};
250