VirtualBox

source: vbox/trunk/src/VBox/Devices/Audio/AudioTest.h@ 92378

Last change on this file since 92378 was 92234, checked in by vboxsync, 3 years ago

Audio/Validation Kit: More code for audio data beacon handling. Now has dedicated beacons for recording / playback tests. bugref:10008
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 17.6 KB
Line 
1/* $Id: AudioTest.h 92234 2021-11-05 08:44:14Z vboxsync $ */
2/** @file
3 * Audio testing routines.
4 * Common code which is being used by the ValidationKit audio test (VKAT)
5 * and the debug / ValdikationKit audio driver(s).
6 */
7
8/*
9 * Copyright (C) 2021 Oracle Corporation
10 *
11 * This file is part of VirtualBox Open Source Edition (OSE), as
12 * available from http://www.virtualbox.org. This file is free software;
13 * you can redistribute it and/or modify it under the terms of the GNU
14 * General Public License (GPL) as published by the Free Software
15 * Foundation, in version 2 as it comes in the "COPYING" file of the
16 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
17 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
18 */
19
20#ifndef VBOX_INCLUDED_SRC_Audio_AudioTest_h
21#define VBOX_INCLUDED_SRC_Audio_AudioTest_h
22#ifndef RT_WITHOUT_PRAGMA_ONCE
23# pragma once
24#endif
25
26/** @todo Some stuff here can be private-only to the implementation. */
27
28/** Maximum length in characters an audio test tag can have. */
29#define AUDIOTEST_TAG_MAX 64
30/** Maximum length in characters a single audio test error description can have. */
31#define AUDIOTEST_ERROR_DESC_MAX 256
32/** Prefix for audio test (set) directories. */
33#define AUDIOTEST_PATH_PREFIX_STR "vkat"
34/** Audio beacon data (single byte) to use for the playback pre beacon (intro). */
35#define AUDIOTEST_BEACON_BYTE_PLAY_PRE 0x42
36/** Audio beacon data (single byte) to use for the playback post beacon (outro). */
37#define AUDIOTEST_BEACON_BYTE_PLAY_POST 0x24
38/** Audio beacon data (single byte) to use for the recording pre beacon (intro). */
39#define AUDIOTEST_BEACON_BYTE_REC_PRE 0x75
40/** Audio beacon data (single byte) to use for the recording post beacon (outro). */
41#define AUDIOTEST_BEACON_BYTE_REC_POST 0x57
42/** Pre / post audio beacon size (in audio frames). */
43#define AUDIOTEST_BEACON_SIZE_FRAMES 1024
44
45/**
46 * Enumeration for an audio test tone (wave) type.
47 */
48typedef enum AUDIOTESTTONETYPE
49{
50 /** Invalid type. */
51 AUDIOTESTTONETYPE_INVALID = 0,
52 /** Sine wave. */
53 AUDIOTESTTONETYPE_SINE,
54 /** Square wave. Not implemented yet. */
55 AUDIOTESTTONETYPE_SQUARE,
56 /** Triangluar wave. Not implemented yet. */
57 AUDIOTESTTONETYPE_TRIANGLE,
58 /** Sawtooth wave. Not implemented yet. */
59 AUDIOTESTTONETYPE_SAWTOOTH,
60 /** The usual 32-bit hack. */
61 AUDIOTESTTONETYPE_32BIT_HACK = 0x7fffffff
62} AUDIOTESTTONETYPE;
63
64/**
65 * Structure for handling an audio (sine wave) test tone.
66 */
67typedef struct AUDIOTESTTONE
68{
69 /** The tone's wave type. */
70 AUDIOTESTTONETYPE enmType;
71 /** The PCM properties. */
72 PDMAUDIOPCMPROPS Props;
73 /** Current sample index for generate the sine wave. */
74 uint64_t uSample;
75 /** The fixed portion of the sin() input. */
76 double rdFixed;
77 /** Frequency (in Hz) of the sine wave to generate. */
78 double rdFreqHz;
79} AUDIOTESTTONE;
80/** Pointer to an audio test tone. */
81typedef AUDIOTESTTONE *PAUDIOTESTTONE;
82
83/**
84 * Structure for a common test parameters header.
85 */
86typedef struct AUDIOTESTPARMSHDR
87{
88 /** Index in some defined sequence this test has. Can be freely used / assigned
89 * and depends on the actual implementation.
90 * Set to UINT32_MAX if not being used. */
91 uint32_t idxSeq;
92 /** Time of the caller when this test was being created. */
93 RTTIME tsCreated;
94} AUDIOTESTPARMSHDR;
95/** Pointer to an audio test tone. */
96typedef AUDIOTESTPARMSHDR *PAUDIOTESTPARMSHDR;
97
98/**
99 * Structure for handling audio test tone parameters.
100 */
101typedef struct AUDIOTESTTONEPARMS
102{
103 /** Common test header. */
104 AUDIOTESTPARMSHDR Hdr;
105 /** The PCM properties. */
106 PDMAUDIOPCMPROPS Props;
107 /** Tone frequency (in Hz) to use.
108 * Will be later converted to a double value. */
109 double dbFreqHz;
110 /** Prequel (in ms) to play silence. Optional and can be set to 0. */
111 RTMSINTERVAL msPrequel;
112 /** Duration (in ms) to play the test tone. */
113 RTMSINTERVAL msDuration;
114 /** Sequel (in ms) to play silence. Optional and can be set to 0. */
115 RTMSINTERVAL msSequel;
116 /** Volume (in percent, 0-100) to use.
117 * If set to 0, the tone is muted (i.e. silent). */
118 uint8_t uVolumePercent;
119} AUDIOTESTTONEPARMS;
120/** Pointer to audio test tone parameters. */
121typedef AUDIOTESTTONEPARMS *PAUDIOTESTTONEPARMS;
122
123/**
124 * Enumeration defining an audio test beacon type.
125 */
126typedef enum AUDIOTESTTONEBEACONTYPE
127{
128 /** Invalid type. */
129 AUDIOTESTTONEBEACONTYPE_INVALID = 0,
130 /** Playback beacon (pre). */
131 AUDIOTESTTONEBEACONTYPE_PLAY_PRE = 1,
132 /** Playback beacon (post). */
133 AUDIOTESTTONEBEACONTYPE_PLAY_POST = 2,
134 /** Recording beacon (pre). */
135 AUDIOTESTTONEBEACONTYPE_REC_PRE = 3,
136 /** Recording beacon (post). */
137 AUDIOTESTTONEBEACONTYPE_REC_POST = 4,
138 /** The usual 32-bit hack. */
139 OTESTTONEBEACONTYPE_32BIT_HACK = 0x7fffffff
140} AUDIOTESTTONEBEACONTYPE;
141
142/**
143 * Structure defining an audio test tone beacon.
144 *
145 * This is being used for (optionally) marking beginning/ending of audio test data.
146 */
147typedef struct AUDIOTESTTONEBEACON
148{
149 /** The beacon type. */
150 AUDIOTESTTONEBEACONTYPE enmType;
151 /** PCM properties to use for this beacon. */
152 PDMAUDIOPCMPROPS Props;
153 /** Beacon bytes to process.
154 * When doing test tone playback: Beacon bytes to write.
155 * When doing test tone recording: Beacon bytes to read. */
156 uint32_t cbSize;
157 /** Beacon bytes already processed.
158 * When doing test tone playback: Beacon bytes written.
159 * When doing test tone recording: Beacon bytes read. */
160 uint32_t cbUsed;
161} AUDIOTESTTONEBEACON;
162/** Pointer to audio test tone beacon. */
163typedef AUDIOTESTTONEBEACON *PAUDIOTESTTONEBEACON;
164/** Pointer (const) to audio test tone beacon. */
165typedef AUDIOTESTTONEBEACON const *PCAUDIOTESTTONEBEACON;
166
167/**
168 * Enumeration for the test set mode.
169 */
170typedef enum AUDIOTESTSETMODE
171{
172 /** Invalid test set mode. */
173 AUDIOTESTSETMODE_INVALID = 0,
174 /** Test set is being created (testing in progress). */
175 AUDIOTESTSETMODE_TEST,
176 /** Existing test set is being verified. */
177 AUDIOTESTSETMODE_VERIFY,
178 /** The usual 32-bit hack. */
179 AUDIOTESTSETMODE_32BIT_HACK = 0x7fffffff
180} AUDIOTESTSETMODE;
181
182/**
183 * Enumeration to specify an audio test type.
184 */
185typedef enum AUDIOTESTTYPE
186{
187 /** Invalid test type, do not use. */
188 AUDIOTESTTYPE_INVALID = 0,
189 /** Play a test tone. */
190 AUDIOTESTTYPE_TESTTONE_PLAY,
191 /** Record a test tone. */
192 AUDIOTESTTYPE_TESTTONE_RECORD,
193 /** The usual 32-bit hack. */
194 AUDIOTESTTYPE_32BIT_HACK = 0x7fffffff
195} AUDIOTESTTYPE;
196
197/**
198 * Audio test request data.
199 */
200typedef struct AUDIOTESTPARMS
201{
202 /** Specifies the current test iteration. */
203 uint32_t idxCurrent;
204 /** How many iterations the test should be executed. */
205 uint32_t cIterations;
206 /** Audio device to use. */
207 PDMAUDIOHOSTDEV Dev;
208 /** How much to delay (wait, in ms) the test being executed. */
209 RTMSINTERVAL msDelay;
210 /** The test direction. */
211 PDMAUDIODIR enmDir;
212 /** The test type. */
213 AUDIOTESTTYPE enmType;
214 /** Union for test type-specific data. */
215 union
216 {
217 AUDIOTESTTONEPARMS TestTone;
218 };
219} AUDIOTESTPARMS;
220/** Pointer to a test parameter structure. */
221typedef AUDIOTESTPARMS *PAUDIOTESTPARMS;
222
223/** Test object handle. */
224typedef R3R0PTRTYPE(struct AUDIOTESTOBJINT RT_FAR *) AUDIOTESTOBJ;
225/** Pointer to test object handle. */
226typedef AUDIOTESTOBJ RT_FAR *PAUDIOTESTOBJ;
227/** Nil test object handle. */
228#define NIL_AUDIOTESTOBJ ((AUDIOTESTOBJ)~(RTHCINTPTR)0)
229
230struct AUDIOTESTSET;
231
232/**
233 * Structure specifying a single audio test entry of a test set.
234 *
235 * A test set can contain zero or more test entry (tests).
236 */
237typedef struct AUDIOTESTENTRY
238{
239 /** List node. */
240 RTLISTNODE Node;
241 /** Pointer to test set parent. */
242 AUDIOTESTSET *pParent;
243 /** Friendly description of the test. */
244 char szDesc[64];
245 /** Audio test parameters this test needs to perform the actual test. */
246 AUDIOTESTPARMS Parms;
247 /** Number of test objects bound to this test. */
248 uint32_t cObj;
249 /** Absolute offset (in bytes) where to write the "obj_count" value later. */
250 uint64_t offObjCount;
251 /** Overall test result. */
252 int rc;
253} AUDIOTESTENTRY;
254/** Pointer to an audio test entry. */
255typedef AUDIOTESTENTRY *PAUDIOTESTENTRY;
256
257/**
258 * Structure specifying an audio test set.
259 */
260typedef struct AUDIOTESTSET
261{
262 /** The set's tag. */
263 char szTag[AUDIOTEST_TAG_MAX];
264 /** Absolute path where to store the test audio data. */
265 char szPathAbs[RTPATH_MAX];
266 /** Current mode the test set is in. */
267 AUDIOTESTSETMODE enmMode;
268 union
269 {
270 /** @todo r=bird: RTSTREAM not RTFILE. That means you don't have to check
271 * every write status code and it's buffered and thus faster. Also,
272 * you don't have to re-invent fprintf-style RTFileWrite wrappers. */
273 RTFILE hFile;
274 RTINIFILE hIniFile;
275 } f;
276 /** Number of test objects in lstObj. */
277 uint32_t cObj;
278 /** Absolute offset (in bytes) where to write the "obj_count" value later. */
279 uint64_t offObjCount;
280 /** List containing PAUDIOTESTOBJ test object entries. */
281 RTLISTANCHOR lstObj;
282 /** Number of performed tests.
283 * Not necessarily bound to the test object entries above. */
284 uint32_t cTests;
285 /** Absolute offset (in bytes) where to write the "test_count" value later. */
286 uint64_t offTestCount;
287 /** List containing PAUDIOTESTENTRY test entries. */
288 RTLISTANCHOR lstTest;
289 /** Current test running. Can be NULL if no test is running. */
290 PAUDIOTESTENTRY pTestCur;
291 /** Number of tests currently running.
292 * Currently we only allow one concurrent test running at a given time. */
293 uint32_t cTestsRunning;
294 /** Number of total (test) failures. */
295 uint32_t cTotalFailures;
296} AUDIOTESTSET;
297/** Pointer to an audio test set. */
298typedef AUDIOTESTSET *PAUDIOTESTSET;
299
300/**
301 * Audio test verification options.
302 */
303typedef struct AUDIOTESTVERIFYOPTS
304{
305 /** Flag indicating whether to keep going after an error has occurred. */
306 bool fKeepGoing;
307 /** Whether to perform audio normalization or not. */
308 bool fNormalize;
309 /** Threshold of file differences (number of chunks) at when we consider audio files
310 * as not matching. 0 means an exact match. */
311 uint32_t cMaxDiff;
312 /** Threshold of file differences (difference in percent) at when we consider audio files
313 * as not matching. 0 means an exact match. */
314 uint8_t uMaxDiffPercent;
315 /** Threshold of file size (+/-, in percent) at when we consider audio files
316 * as not matching. 0 means an exact match.*/
317 uint8_t uMaxSizePercent;
318 /** Search window (in ms) to use for treating / classifying audio data. */
319 uint32_t msSearchWindow;
320} AUDIOTESTVERIFYOPTS;
321/** Pointer to audio test verification options. */
322typedef AUDIOTESTVERIFYOPTS *PAUDIOTESTVERIFYOPTS;
323
324/**
325 * Structure for holding a single audio test error entry.
326 */
327typedef struct AUDIOTESTERRORENTRY
328{
329 /** The entrie's list node. */
330 RTLISTNODE Node;
331 /** Additional rc. */
332 int rc;
333 /** Actual error description. */
334 char szDesc[AUDIOTEST_ERROR_DESC_MAX];
335} AUDIOTESTERRORENTRY;
336/** Pointer to an audio test error description. */
337typedef AUDIOTESTERRORENTRY *PAUDIOTESTERRORENTRY;
338
339/**
340 * Structure for holding an audio test error description.
341 * This can contain multiple errors (FIFO list).
342 */
343typedef struct AUDIOTESTERRORDESC
344{
345 /** List entries containing the (FIFO-style) errors of type AUDIOTESTERRORENTRY. */
346 RTLISTANCHOR List;
347 /** Number of errors in the list. */
348 uint32_t cErrors;
349} AUDIOTESTERRORDESC;
350/** Pointer to an audio test error description. */
351typedef AUDIOTESTERRORDESC *PAUDIOTESTERRORDESC;
352/** Const pointer to an audio test error description. */
353typedef AUDIOTESTERRORDESC const *PCAUDIOTESTERRORDESC;
354
355/**
356 * Enumeration specifying an internal test state.
357 */
358typedef enum AUDIOTESTSTATE
359{
360 /** Test is initializing. */
361 AUDIOTESTSTATE_INIT = 0,
362 /** Test is in pre-run phase. */
363 AUDIOTESTSTATE_PRE,
364 /** Test is running */
365 AUDIOTESTSTATE_RUN,
366 /** Test is in post-run phase. */
367 AUDIOTESTSTATE_POST,
368 /** Test has been run. */
369 AUDIOTESTSTATE_DONE,
370 /** The usual 32-bit hack. */
371 AUDIOTESTSTATE_32BIT_HACK = 0x7fffffff
372} AUDIOTESTSTATE;
373
374double AudioTestToneInit(PAUDIOTESTTONE pTone, PPDMAUDIOPCMPROPS pProps, double dbFreq);
375double AudioTestToneInitRandom(PAUDIOTESTTONE pTone, PPDMAUDIOPCMPROPS pProps);
376double AudioTestToneGetRandomFreq(void);
377int AudioTestToneGenerate(PAUDIOTESTTONE pTone, void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten);
378
379void AudioTestBeaconInit(PAUDIOTESTTONEBEACON pBeacon, AUDIOTESTTONEBEACONTYPE enmType, PPDMAUDIOPCMPROPS pProps);
380int AudioTestBeaconAddConsecutive(PAUDIOTESTTONEBEACON pBeacon, const uint8_t *auBuf, size_t cbBuf, size_t *pOff);
381int AudioTestBeaconWrite(PAUDIOTESTTONEBEACON pBeacon, void *pvBuf, uint32_t cbBuf);
382uint32_t AudioTestBeaconGetSize(PCAUDIOTESTTONEBEACON pBeacon);
383const char *AudioTestBeaconTypeGetName(AUDIOTESTTONEBEACONTYPE enmType);
384AUDIOTESTTONEBEACONTYPE AudioTestBeaconGetType(PCAUDIOTESTTONEBEACON pBeacon);
385uint32_t AudioTestBeaconGetRemaining(PCAUDIOTESTTONEBEACON pBeacon);
386uint32_t AudioTestBeaconGetUsed(PCAUDIOTESTTONEBEACON pBeacon);
387bool AudioTestBeaconIsComplete(PCAUDIOTESTTONEBEACON pBeacon);
388
389int AudioTestGenTag(char *pszTag, size_t cbTag);
390
391int AudioTestPathGetTemp(char *pszPath, size_t cbPath);
392int AudioTestPathCreateTemp(char *pszPath, size_t cbPath, const char *pszUUID);
393int AudioTestPathCreate(char *pszPath, size_t cbPath, const char *pszUUID);
394
395int AudioTestSetObjCreateAndRegister(PAUDIOTESTSET pSet, const char *pszName, PAUDIOTESTOBJ pObj);
396
397int AudioTestObjWrite(AUDIOTESTOBJ Obj, const void *pvBuf, size_t cbBuf);
398int AudioTestObjAddMetadataStr(AUDIOTESTOBJ Obj, const char *pszFormat, ...);
399int AudioTestObjClose(AUDIOTESTOBJ Obj);
400
401int AudioTestSetTestBegin(PAUDIOTESTSET pSet, const char *pszDesc, PAUDIOTESTPARMS pParms, PAUDIOTESTENTRY *ppEntry);
402int AudioTestSetTestFailed(PAUDIOTESTENTRY pEntry, int rc, const char *pszErr);
403int AudioTestSetTestDone(PAUDIOTESTENTRY pEntry);
404bool AudioTestSetTestIsRunning(PAUDIOTESTENTRY pEntry);
405
406int AudioTestSetCreate(PAUDIOTESTSET pSet, const char *pszPath, const char *pszTag);
407int AudioTestSetDestroy(PAUDIOTESTSET pSet);
408int AudioTestSetOpen(PAUDIOTESTSET pSet, const char *pszPath);
409int AudioTestSetClose(PAUDIOTESTSET pSet);
410int AudioTestSetWipe(PAUDIOTESTSET pSet);
411const char *AudioTestSetGetTag(PAUDIOTESTSET pSet);
412uint32_t AudioTestSetGetTestsTotal(PAUDIOTESTSET pSet);
413uint32_t AudioTestSetGetTestsRunning(PAUDIOTESTSET pSet);
414uint32_t AudioTestSetGetTotalFailures(PAUDIOTESTSET pSet);
415bool AudioTestSetIsPacked(const char *pszPath);
416bool AudioTestSetIsRunning(PAUDIOTESTSET pSet);
417int AudioTestSetPack(PAUDIOTESTSET pSet, const char *pszOutDir, char *pszFileName, size_t cbFileName);
418int AudioTestSetUnpack(const char *pszFile, const char *pszOutDir);
419
420void AudioTestSetVerifyOptsInitStrict(PAUDIOTESTVERIFYOPTS pOpts);
421void AudioTestSetVerifyOptsInit(PAUDIOTESTVERIFYOPTS pOpts);
422bool AudioTestSetVerifyOptsAreEqual(PAUDIOTESTVERIFYOPTS pOptsA, PAUDIOTESTVERIFYOPTS pOptsB);
423
424int AudioTestSetVerify(PAUDIOTESTSET pSetA, PAUDIOTESTSET pSetB, PAUDIOTESTERRORDESC pErrDesc);
425int AudioTestSetVerifyEx(PAUDIOTESTSET pSetA, PAUDIOTESTSET pSetB, PAUDIOTESTVERIFYOPTS pOpts, PAUDIOTESTERRORDESC pErrDesc);
426
427uint32_t AudioTestErrorDescCount(PCAUDIOTESTERRORDESC pErr);
428bool AudioTestErrorDescFailed(PCAUDIOTESTERRORDESC pErr);
429
430void AudioTestErrorDescDestroy(PAUDIOTESTERRORDESC pErr);
431
432const char *AudioTestStateToStr(AUDIOTESTSTATE enmState);
433
434/** @name Wave File Accessors
435 * @{ */
436/**
437 * An open wave (.WAV) file.
438 */
439typedef struct AUDIOTESTWAVEFILE
440{
441 /** Magic value (AUDIOTESTWAVEFILE_MAGIC). */
442 uint32_t u32Magic;
443 /** Set if we're in read-mode, clear if in write mode. */
444 bool fReadMode;
445 /** The file handle. */
446 RTFILE hFile;
447 /** The absolute file offset of the first sample */
448 uint32_t offSamples;
449 /** Number of bytes of samples. */
450 uint32_t cbSamples;
451 /** The current read position relative to @a offSamples. */
452 uint32_t offCur;
453 /** The PCM properties for the file format. */
454 PDMAUDIOPCMPROPS Props;
455} AUDIOTESTWAVEFILE;
456/** Pointer to an open wave file. */
457typedef AUDIOTESTWAVEFILE *PAUDIOTESTWAVEFILE;
458
459/** Magic value for AUDIOTESTWAVEFILE::u32Magic (Miles Dewey Davis III). */
460#define AUDIOTESTWAVEFILE_MAGIC UINT32_C(0x19260526)
461/** Magic value for AUDIOTESTWAVEFILE::u32Magic after closing. */
462#define AUDIOTESTWAVEFILE_MAGIC_DEAD UINT32_C(0x19910928)
463
464int AudioTestWaveFileOpen(const char *pszFile, PAUDIOTESTWAVEFILE pWaveFile, PRTERRINFO pErrInfo);
465int AudioTestWaveFileCreate(const char *pszFile, PCPDMAUDIOPCMPROPS pProps, PAUDIOTESTWAVEFILE pWaveFile, PRTERRINFO pErrInfo);
466int AudioTestWaveFileRead(PAUDIOTESTWAVEFILE pWaveFile, void *pvBuf, size_t cbBuf, size_t *pcbRead);
467int AudioTestWaveFileWrite(PAUDIOTESTWAVEFILE pWaveFile, const void *pvBuf, size_t cbBuf);
468int AudioTestWaveFileClose(PAUDIOTESTWAVEFILE pWaveFile);
469
470/** @} */
471
472#endif /* !VBOX_INCLUDED_SRC_Audio_AudioTest_h */
473
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette