blob: d8e5b00c5b692da05dd9b53df3e49380ae0ff1db [file] [log] [blame]
Phil Burk5ed503c2017-02-01 09:38:15 -08001/*
2 * Copyright 2016 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#ifndef UTILITY_AAUDIO_UTILITIES_H
18#define UTILITY_AAUDIO_UTILITIES_H
19
Andy Hung47c5e532017-06-26 18:28:00 -070020#include <algorithm>
21#include <functional>
jiabin4a341862022-09-20 17:58:37 +000022#include <vector>
Phil Burk5ed503c2017-02-01 09:38:15 -080023#include <stdint.h>
24#include <sys/types.h>
Tom Cherry7ae78252020-04-13 15:20:50 -070025#include <unistd.h>
Phil Burk5ed503c2017-02-01 09:38:15 -080026
jiabin4a341862022-09-20 17:58:37 +000027#include <android/media/audio/common/AudioMMapPolicyInfo.h>
Phil Burk5ed503c2017-02-01 09:38:15 -080028#include <utils/Errors.h>
Kevin Rocard6d7582e2018-01-11 19:28:14 -080029#include <system/audio.h>
Phil Burk5ed503c2017-02-01 09:38:15 -080030
Phil Burka4eb0d82017-04-12 15:44:06 -070031#include "aaudio/AAudio.h"
jiabin4a341862022-09-20 17:58:37 +000032#include "aaudio/AAudioTesting.h"
Phil Burk5ed503c2017-02-01 09:38:15 -080033
34/**
35 * Convert an AAudio result into the closest matching Android status.
36 */
37android::status_t AAudioConvert_aaudioToAndroidStatus(aaudio_result_t result);
38
39/**
40 * Convert an Android status into the closest matching AAudio result.
41 */
42aaudio_result_t AAudioConvert_androidToAAudioResult(android::status_t status);
43
Phil Burke572f462017-04-20 13:03:19 -070044/**
Phil Burk4e1af9f2018-01-03 15:54:35 -080045 * Convert an aaudio_session_id_t to a value that is safe to pass to AudioFlinger.
46 * @param sessionId
47 * @return safe value
48 */
49audio_session_t AAudioConvert_aaudioToAndroidSessionId(aaudio_session_id_t sessionId);
50
51/**
Phil Burk5ed503c2017-02-01 09:38:15 -080052 * Calculate the number of bytes and prevent numeric overflow.
Phil Burk7f680132018-03-12 14:48:06 -070053 * The *sizeInBytes will be set to zero if there is an error.
54 *
Phil Burk5ed503c2017-02-01 09:38:15 -080055 * @param numFrames frame count
56 * @param bytesPerFrame size of a frame in bytes
Phil Burk7f680132018-03-12 14:48:06 -070057 * @param sizeInBytes pointer to a variable to receive total size in bytes
Phil Burk5ed503c2017-02-01 09:38:15 -080058 * @return AAUDIO_OK or negative error, eg. AAUDIO_ERROR_OUT_OF_RANGE
59 */
Phil Burk3316d5e2017-02-15 11:23:01 -080060int32_t AAudioConvert_framesToBytes(int32_t numFrames,
Phil Burk7f680132018-03-12 14:48:06 -070061 int32_t bytesPerFrame,
62 int32_t *sizeInBytes);
Phil Burk5ed503c2017-02-01 09:38:15 -080063
Phil Burk9dca9822017-05-26 14:27:43 -070064audio_format_t AAudioConvert_aaudioToAndroidDataFormat(aaudio_format_t aaudio_format);
Phil Burk5ed503c2017-02-01 09:38:15 -080065
Phil Burk9dca9822017-05-26 14:27:43 -070066aaudio_format_t AAudioConvert_androidToAAudioDataFormat(audio_format_t format);
Phil Burk5ed503c2017-02-01 09:38:15 -080067
Robert Wu310037a2022-09-06 21:48:18 +000068aaudio_format_t AAudioConvert_androidToNearestAAudioDataFormat(audio_format_t format);
Phil Burkd4ccc622017-12-20 15:32:44 -080069
70/**
71 * Note that this function does not validate the passed in value.
72 * That is done somewhere else.
73 * @return internal value
74 */
75
76audio_usage_t AAudioConvert_usageToInternal(aaudio_usage_t usage);
77
78/**
79 * Note that this function does not validate the passed in value.
80 * That is done somewhere else.
81 * @return internal value
82 */
83audio_content_type_t AAudioConvert_contentTypeToInternal(aaudio_content_type_t contentType);
84
85/**
86 * Note that this function does not validate the passed in value.
87 * That is done somewhere else.
88 * @return internal audio source
89 */
90audio_source_t AAudioConvert_inputPresetToAudioSource(aaudio_input_preset_t preset);
91
Kevin Rocard68646ba2019-03-20 13:26:49 -070092/**
93 * Note that this function does not validate the passed in value.
94 * That is done somewhere else.
95 * @return internal audio flags mask
96 */
97audio_flags_mask_t AAudioConvert_allowCapturePolicyToAudioFlagsMask(
Jean-Michel Trivi656bfdc2021-09-20 18:42:37 -070098 aaudio_allowed_capture_policy_t policy,
99 aaudio_spatialization_behavior_t spatializationBehavior,
100 bool isContentSpatialized);
Kevin Rocard68646ba2019-03-20 13:26:49 -0700101
Eric Laurentd17c8502019-10-24 15:58:35 -0700102audio_flags_mask_t AAudioConvert_privacySensitiveToAudioFlagsMask(
103 bool privacySensitive);
104
jiabina9094092021-06-28 20:36:45 +0000105audio_channel_mask_t AAudioConvert_aaudioToAndroidChannelLayoutMask(
106 aaudio_channel_mask_t channelMask, bool isInput);
107
108aaudio_channel_mask_t AAudioConvert_androidToAAudioChannelLayoutMask(
109 audio_channel_mask_t channelMask, bool isInput);
110
111aaudio_channel_mask_t AAudioConvert_androidToAAudioChannelIndexMask(
112 audio_channel_mask_t channelMask);
113
114audio_channel_mask_t AAudioConvert_aaudioToAndroidChannelIndexMask(
115 aaudio_channel_mask_t channelMask);
116
117aaudio_channel_mask_t AAudioConvert_androidToAAudioChannelMask(
118 audio_channel_mask_t channelMask, bool isInput, bool indexMaskRequired);
119
120audio_channel_mask_t AAudioConvert_aaudioToAndroidChannelMask(
121 aaudio_channel_mask_t channelMask, bool isInput);
122
123bool AAudio_isChannelIndexMask(aaudio_channel_mask_t channelMask);
124
125int32_t AAudioConvert_channelMaskToCount(aaudio_channel_mask_t channelMask);
126
127aaudio_channel_mask_t AAudioConvert_channelCountToMask(int32_t channelCount);
128
129audio_channel_mask_t AAudio_getChannelMaskForOpen(
130 aaudio_channel_mask_t channelMask, int32_t samplesPerFrame, bool isInput);
131
Phil Burkc8f69a02017-05-11 15:53:06 -0700132// Note that this code may be replaced by Settings or by some other system configuration tool.
133
Phil Burkb31b66f2019-09-30 09:33:41 -0700134/**
Phil Burkfd34a932017-07-19 07:03:52 -0700135 * Read a system property that specifies the number of extra microseconds that a thread
136 * should sleep when waiting for another thread to service a FIFO. This is used
137 * to avoid the waking thread from being overly optimistic about the other threads
138 * wakeup timing. This value should be set high enough to cover typical scheduling jitter
139 * for a real-time thread.
140 *
141 * @return number of microseconds to delay the wakeup.
142 */
143int32_t AAudioProperty_getWakeupDelayMicros();
Phil Burkfd34a932017-07-19 07:03:52 -0700144#define AAUDIO_PROP_WAKEUP_DELAY_USEC "aaudio.wakeup_delay_usec"
145
146/**
147 * Read a system property that specifies the minimum sleep time when polling the FIFO.
148 *
149 * @return minimum number of microseconds to sleep.
150 */
151int32_t AAudioProperty_getMinimumSleepMicros();
Phil Burkfd34a932017-07-19 07:03:52 -0700152#define AAUDIO_PROP_MINIMUM_SLEEP_USEC "aaudio.minimum_sleep_usec"
153
154/**
Phil Burkb31b66f2019-09-30 09:33:41 -0700155 * Read a system property that specifies an offset that will be added to MMAP timestamps.
156 * This can be used to correct bias in the timestamp.
157 * It can also be used to analyze the time distribution of the timestamp
158 * by progressively modifying the offset and listening for glitches.
159 *
160 * @return number of microseconds to offset the time part of an MMAP timestamp
161 */
162int32_t AAudioProperty_getInputMMapOffsetMicros();
163#define AAUDIO_PROP_INPUT_MMAP_OFFSET_USEC "aaudio.in_mmap_offset_usec"
164
165int32_t AAudioProperty_getOutputMMapOffsetMicros();
166#define AAUDIO_PROP_OUTPUT_MMAP_OFFSET_USEC "aaudio.out_mmap_offset_usec"
Phil Burk5cc83c32017-11-28 15:43:18 -0800167
Phil Burkef34be52019-09-26 13:45:25 -0700168// These are powers of two that can be combined as a bit mask.
169// AAUDIO_LOG_CLOCK_MODEL_HISTOGRAM must be enabled before the stream is opened.
170#define AAUDIO_LOG_CLOCK_MODEL_HISTOGRAM 1
171#define AAUDIO_LOG_RESERVED_2 2
172#define AAUDIO_LOG_RESERVED_4 4
173#define AAUDIO_LOG_RESERVED_8 8
174
175/**
176 * Use a mask to enable various logs in AAudio.
177 * @return mask that enables various AAudio logs, such as AAUDIO_LOG_CLOCK_MODEL_HISTOGRAM
178 */
179int32_t AAudioProperty_getLogMask();
180#define AAUDIO_PROP_LOG_MASK "aaudio.log_mask"
181
Phil Burk5cc83c32017-11-28 15:43:18 -0800182/**
183 * Is flush allowed for the given state?
184 * @param state
185 * @return AAUDIO_OK if allowed or an error
186 */
187aaudio_result_t AAudio_isFlushAllowed(aaudio_stream_state_t state);
188
Andy Hung47c5e532017-06-26 18:28:00 -0700189/**
190 * Try a function f until it returns true.
191 *
192 * The function is always called at least once.
193 *
194 * @param f the function to evaluate, which returns a bool.
195 * @param times the number of times to evaluate f.
196 * @param sleepMs the sleep time per check of f, if greater than 0.
197 * @return true if f() eventually returns true.
198 */
199static inline bool AAudio_tryUntilTrue(
jiabind5bd06a2021-04-27 22:04:08 +0000200 const std::function<bool()>& f, int times, int sleepMs) {
Andy Hung47c5e532017-06-26 18:28:00 -0700201 static const useconds_t US_PER_MS = 1000;
202
203 sleepMs = std::max(sleepMs, 0);
204 for (;;) {
205 if (f()) return true;
206 if (times <= 1) return false;
207 --times;
208 usleep(sleepMs * US_PER_MS);
209 }
210}
211
Phil Burk97350f92017-07-21 15:59:44 -0700212
213/**
214 * Simple double buffer for a structure that can be written occasionally and read occasionally.
215 * This allows a SINGLE writer with multiple readers.
216 *
217 * It is OK if the FIFO overflows and we lose old values.
218 * It is also OK if we read an old value.
219 * Thread may return a non-atomic result if the other thread is rapidly writing
220 * new values on another core.
221 */
222template <class T>
223class SimpleDoubleBuffer {
224public:
225 SimpleDoubleBuffer()
Phil Burkbcc36742017-08-31 17:24:51 -0700226 : mValues() {}
Phil Burk97350f92017-07-21 15:59:44 -0700227
228 __attribute__((no_sanitize("integer")))
229 void write(T value) {
230 int index = mCounter.load() & 1;
231 mValues[index] = value;
232 mCounter++; // Increment AFTER updating storage, OK if it wraps.
233 }
234
Phil Burkbcc36742017-08-31 17:24:51 -0700235 /**
236 * This should only be called by the same thread that calls write() or when
237 * no other thread is calling write.
238 */
239 void clear() {
240 mCounter.store(0);
241 }
242
Phil Burk97350f92017-07-21 15:59:44 -0700243 T read() const {
244 T result;
245 int before;
246 int after;
247 int timeout = 3;
248 do {
249 // Check to see if a write occurred while were reading.
250 before = mCounter.load();
251 int index = (before & 1) ^ 1;
252 result = mValues[index];
253 after = mCounter.load();
Phil Burkbcc36742017-08-31 17:24:51 -0700254 } while ((after != before) && (after > 0) && (--timeout > 0));
Phil Burk97350f92017-07-21 15:59:44 -0700255 return result;
256 }
257
258 /**
259 * @return true if at least one value has been written
260 */
261 bool isValid() const {
262 return mCounter.load() > 0;
263 }
264
265private:
266 T mValues[2];
Phil Burkbcc36742017-08-31 17:24:51 -0700267 std::atomic<int> mCounter{0};
Phil Burk97350f92017-07-21 15:59:44 -0700268};
269
270class Timestamp {
271public:
jiabind5bd06a2021-04-27 22:04:08 +0000272 Timestamp() = default;
Phil Burk97350f92017-07-21 15:59:44 -0700273 Timestamp(int64_t position, int64_t nanoseconds)
274 : mPosition(position)
275 , mNanoseconds(nanoseconds) {}
276
277 int64_t getPosition() const { return mPosition; }
278
279 int64_t getNanoseconds() const { return mNanoseconds; }
280
281private:
282 // These cannot be const because we need to implement the copy assignment operator.
jiabind5bd06a2021-04-27 22:04:08 +0000283 int64_t mPosition{0};
284 int64_t mNanoseconds{0};
Phil Burk97350f92017-07-21 15:59:44 -0700285};
286
Phil Burkbcc36742017-08-31 17:24:51 -0700287
288/**
289 * Pass a request to another thread.
290 * This is used when one thread, A, wants another thread, B, to do something.
291 * A naive approach would be for A to set a flag and for B to clear it when done.
292 * But that creates a race condition. This technique avoids the race condition.
293 *
294 * Assumes only one requester and one acknowledger.
295 */
296class AtomicRequestor {
297public:
Phil Burk2d5ba532017-09-06 14:36:11 -0700298
299 __attribute__((no_sanitize("integer")))
Phil Burkbcc36742017-08-31 17:24:51 -0700300 void request() {
Phil Burkbcc36742017-08-31 17:24:51 -0700301 mRequested++;
302 }
303
Phil Burk2d5ba532017-09-06 14:36:11 -0700304 __attribute__((no_sanitize("integer")))
Phil Burkbcc36742017-08-31 17:24:51 -0700305 bool isRequested() {
Phil Burk2d5ba532017-09-06 14:36:11 -0700306 return (mRequested.load() - mAcknowledged.load()) > 0;
Phil Burkbcc36742017-08-31 17:24:51 -0700307 }
308
Phil Burk2d5ba532017-09-06 14:36:11 -0700309 __attribute__((no_sanitize("integer")))
Phil Burkbcc36742017-08-31 17:24:51 -0700310 void acknowledge() {
311 mAcknowledged++;
312 }
313
314private:
315 std::atomic<int> mRequested{0};
316 std::atomic<int> mAcknowledged{0};
317};
jiabina9094092021-06-28 20:36:45 +0000318
319enum {
320 /**
321 * Audio channel index mask, only used internally.
322 */
323 AAUDIO_CHANNEL_BIT_INDEX = 0x80000000,
324 AAUDIO_CHANNEL_INDEX_MASK_1 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 1) - 1,
325 AAUDIO_CHANNEL_INDEX_MASK_2 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 2) - 1,
326 AAUDIO_CHANNEL_INDEX_MASK_3 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 3) - 1,
327 AAUDIO_CHANNEL_INDEX_MASK_4 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 4) - 1,
328 AAUDIO_CHANNEL_INDEX_MASK_5 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 5) - 1,
329 AAUDIO_CHANNEL_INDEX_MASK_6 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 6) - 1,
330 AAUDIO_CHANNEL_INDEX_MASK_7 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 7) - 1,
331 AAUDIO_CHANNEL_INDEX_MASK_8 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 8) - 1,
332 AAUDIO_CHANNEL_INDEX_MASK_9 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 9) - 1,
333 AAUDIO_CHANNEL_INDEX_MASK_10 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 10) - 1,
334 AAUDIO_CHANNEL_INDEX_MASK_11 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 11) - 1,
335 AAUDIO_CHANNEL_INDEX_MASK_12 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 12) - 1,
336 AAUDIO_CHANNEL_INDEX_MASK_13 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 13) - 1,
337 AAUDIO_CHANNEL_INDEX_MASK_14 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 14) - 1,
338 AAUDIO_CHANNEL_INDEX_MASK_15 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 15) - 1,
339 AAUDIO_CHANNEL_INDEX_MASK_16 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 16) - 1,
340 AAUDIO_CHANNEL_INDEX_MASK_17 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 17) - 1,
341 AAUDIO_CHANNEL_INDEX_MASK_18 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 18) - 1,
342 AAUDIO_CHANNEL_INDEX_MASK_19 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 19) - 1,
343 AAUDIO_CHANNEL_INDEX_MASK_20 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 20) - 1,
344 AAUDIO_CHANNEL_INDEX_MASK_21 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 21) - 1,
345 AAUDIO_CHANNEL_INDEX_MASK_22 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 22) - 1,
346 AAUDIO_CHANNEL_INDEX_MASK_23 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 23) - 1,
347 AAUDIO_CHANNEL_INDEX_MASK_24 = AAUDIO_CHANNEL_BIT_INDEX | (1 << 24) - 1,
348};
349
jiabin4a341862022-09-20 17:58:37 +0000350// The aaudio policy will be ALWAYS, NEVER, UNSPECIFIED only when all policy info are
351// ALWAYS, NEVER or UNSPECIFIED. Otherwise, the aaudio policy will be AUTO.
352aaudio_policy_t AAudio_getAAudioPolicy(
353 const std::vector<android::media::audio::common::AudioMMapPolicyInfo>& policyInfos);
354
Phil Burk5ed503c2017-02-01 09:38:15 -0800355#endif //UTILITY_AAUDIO_UTILITIES_H