VirtualBox

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

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

Audio/ValKit: More validation code. bugref:10008
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 14.2 KB
Line 
1/* $Id: AudioTest.h 89711 2021-06-15 15:08:23Z 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 128
32/** Prefix for audio test (set) directories. */
33#define AUDIOTEST_PATH_PREFIX_STR "vkat"
34
35/**
36 * Enumeration for an audio test tone (wave) type.
37 */
38typedef enum AUDIOTESTTONETYPE
39{
40 /** Invalid type. */
41 AUDIOTESTTONETYPE_INVALID = 0,
42 /** Sine wave. */
43 AUDIOTESTTONETYPE_SINE,
44 /** Square wave. Not implemented yet. */
45 AUDIOTESTTONETYPE_SQUARE,
46 /** Triangluar wave. Not implemented yet. */
47 AUDIOTESTTONETYPE_TRIANGLE,
48 /** Sawtooth wave. Not implemented yet. */
49 AUDIOTESTTONETYPE_SAWTOOTH,
50 /** The usual 32-bit hack. */
51 AUDIOTESTTONETYPE_32BIT_HACK = 0x7fffffff
52} AUDIOTESTTONETYPE;
53
54/**
55 * Structure for handling an audio (sine wave) test tone.
56 */
57typedef struct AUDIOTESTTONE
58{
59 /** The tone's wave type. */
60 AUDIOTESTTONETYPE enmType;
61 /** The PCM properties. */
62 PDMAUDIOPCMPROPS Props;
63 /** Current sample index for generate the sine wave. */
64 uint64_t uSample;
65 /** The fixed portion of the sin() input. */
66 double rdFixed;
67 /** Frequency (in Hz) of the sine wave to generate. */
68 double rdFreqHz;
69} AUDIOTESTTONE;
70/** Pointer to an audio test tone. */
71typedef AUDIOTESTTONE *PAUDIOTESTTONE;
72
73/**
74 * Structure for handling audio test tone parameters.
75 */
76typedef struct AUDIOTESTTONEPARMS
77{
78 /** The PCM properties. */
79 PDMAUDIOPCMPROPS Props;
80 /** Tone frequency (in Hz) to use.
81 * Will be later converted to a double value. */
82 double dbFreqHz;
83 /** Prequel (in ms) to play silence. Optional and can be set to 0. */
84 RTMSINTERVAL msPrequel;
85 /** Duration (in ms) to play the test tone. */
86 RTMSINTERVAL msDuration;
87 /** Sequel (in ms) to play silence. Optional and can be set to 0. */
88 RTMSINTERVAL msSequel;
89 /** Volume (in percent, 0-100) to use.
90 * If set to 0, the tone is muted (i.e. silent). */
91 uint8_t uVolumePercent;
92} AUDIOTESTTONEPARMS;
93/** Pointer to audio test tone parameters. */
94typedef AUDIOTESTTONEPARMS *PAUDIOTESTTONEPARMS;
95
96/**
97 * Enumeration for the test set mode.
98 */
99typedef enum AUDIOTESTSETMODE
100{
101 /** Invalid test set mode. */
102 AUDIOTESTSETMODE_INVALID = 0,
103 /** Test set is being created (testing in progress). */
104 AUDIOTESTSETMODE_TEST,
105 /** Existing test set is being verified. */
106 AUDIOTESTSETMODE_VERIFY,
107 /** The usual 32-bit hack. */
108 AUDIOTESTSETMODE_32BIT_HACK = 0x7fffffff
109} AUDIOTESTSETMODE;
110
111/**
112 * Enumeration to specify an audio test type.
113 */
114typedef enum AUDIOTESTTYPE
115{
116 /** Invalid test type, do not use. */
117 AUDIOTESTTYPE_INVALID = 0,
118 /** Play a test tone. */
119 AUDIOTESTTYPE_TESTTONE_PLAY,
120 /** Record a test tone. */
121 AUDIOTESTTYPE_TESTTONE_RECORD,
122 /** The usual 32-bit hack. */
123 AUDIOTESTTYPE_32BIT_HACK = 0x7fffffff
124} AUDIOTESTTYPE;
125
126/**
127 * Audio test request data.
128 */
129typedef struct AUDIOTESTPARMS
130{
131 /** Specifies the current test iteration. */
132 uint32_t idxCurrent;
133 /** How many iterations the test should be executed. */
134 uint32_t cIterations;
135 /** PCM audio stream properties to use. */
136 PDMAUDIOPCMPROPS Props;
137 /** Audio device to use. */
138 PDMAUDIOHOSTDEV Dev;
139 /** How much to delay (wait, in ms) the test being executed. */
140 RTMSINTERVAL msDelay;
141 /** The test direction. */
142 PDMAUDIODIR enmDir;
143 /** The test type. */
144 AUDIOTESTTYPE enmType;
145 /** Union for test type-specific data. */
146 union
147 {
148 AUDIOTESTTONEPARMS TestTone;
149 };
150} AUDIOTESTPARMS;
151/** Pointer to a test parameter structure. */
152typedef AUDIOTESTPARMS *PAUDIOTESTPARMS;
153
154/**
155 * Enumeration for an audio test object type.
156 */
157typedef enum AUDIOTESTOBJTYPE
158{
159 /** Unknown / invalid, do not use. */
160 AUDIOTESTOBJTYPE_UNKNOWN = 0,
161 /** The test object is a file. */
162 AUDIOTESTOBJTYPE_FILE,
163 /** The usual 32-bit hack. */
164 AUDIOTESTOBJTYPE_32BIT_HACK = 0x7fffffff
165} AUDIOTESTOBJTYPE;
166
167/**
168 * Structure for keeping an audio test object file.
169 */
170typedef struct AUDIOTESTOBJFILE
171{
172 /** File handle. */
173 RTFILE hFile;
174 /** Total size (in bytes). */
175 size_t cbSize;
176} AUDIOTESTOBJFILE;
177/** Pointer to an audio test object file. */
178typedef AUDIOTESTOBJFILE *PAUDIOTESTOBJFILE;
179
180/**
181 * Enumeration for an audio test object meta data type.
182 */
183typedef enum AUDIOTESTOBJMETADATATYPE
184{
185 /** Unknown / invalid, do not use. */
186 AUDIOTESTOBJMETADATATYPE_INVALID = 0,
187 /** Meta data is an UTF-8 string. */
188 AUDIOTESTOBJMETADATATYPE_STRING,
189 /** The usual 32-bit hack. */
190 AUDIOTESTOBJMETADATATYPE_32BIT_HACK = 0x7fffffff
191} AUDIOTESTOBJMETADATATYPE;
192
193/**
194 * Structure for keeping a meta data block.
195 */
196typedef struct AUDIOTESTOBJMETA
197{
198 /** List node. */
199 RTLISTNODE Node;
200 /** Meta data type. */
201 AUDIOTESTOBJMETADATATYPE enmType;
202 /** Meta data block. */
203 void *pvMeta;
204 /** Size (in bytes) of \a pvMeta. */
205 size_t cbMeta;
206} AUDIOTESTOBJMETA;
207/** Pointer to an audio test object file. */
208typedef AUDIOTESTOBJMETA *PAUDIOTESTOBJMETA;
209
210/**
211 * Structure for keeping a single audio test object.
212 *
213 * A test object is data which is needed in order to perform and verify one or
214 * more audio test case(s).
215 */
216typedef struct AUDIOTESTOBJ
217{
218 /** List node. */
219 RTLISTNODE Node;
220 RTUUID Uuid;
221 /** Number of references to this test object. */
222 uint32_t cRefs;
223 /** Name of the test object.
224 * Must not contain a path and has to be able to serialize to disk. */
225 char szName[64];
226 /** The object type. */
227 AUDIOTESTOBJTYPE enmType;
228 /** Meta data list. */
229 RTLISTANCHOR lstMeta;
230 /** Union for holding the object type-specific data. */
231 union
232 {
233 AUDIOTESTOBJFILE File;
234 };
235} AUDIOTESTOBJ;
236/** Pointer to an audio test object. */
237typedef AUDIOTESTOBJ *PAUDIOTESTOBJ;
238
239struct AUDIOTESTSET;
240
241/**
242 * Structure specifying a single audio test entry of a test set.
243 *
244 * A test set can contain zero or more test entry (tests).
245 */
246typedef struct AUDIOTESTENTRY
247{
248 /** List node. */
249 RTLISTNODE Node;
250 /** Pointer to test set parent. */
251 AUDIOTESTSET *pParent;
252 /** Friendly description of the test. */
253 char szDesc[64];
254 /** Audio test parameters this test needs to perform the actual test. */
255 AUDIOTESTPARMS Parms;
256 /** Number of test objects bound to this test. */
257 uint32_t cObj;
258 /** Absolute offset (in bytes) where to write the "obj_count" value later. */
259 uint64_t offObjCount;
260 /** Overall test result. */
261 int rc;
262} AUDIOTESTENTRY;
263/** Pointer to an audio test entry. */
264typedef AUDIOTESTENTRY *PAUDIOTESTENTRY;
265
266/**
267 * Structure specifying an audio test set.
268 */
269typedef struct AUDIOTESTSET
270{
271 /** The set's tag. */
272 char szTag[AUDIOTEST_TAG_MAX];
273 /** Absolute path where to store the test audio data. */
274 char szPathAbs[RTPATH_MAX];
275 /** Current mode the test set is in. */
276 AUDIOTESTSETMODE enmMode;
277 union
278 {
279 /** @todo r=bird: RTSTREAM not RTFILE. That means you don't have to check
280 * every write status code and it's buffered and thus faster. Also,
281 * you don't have to re-invent fprintf-style RTFileWrite wrappers. */
282 RTFILE hFile;
283 RTINIFILE hIniFile;
284 } f;
285 /** Number of test objects in lstObj. */
286 uint32_t cObj;
287 /** Absolute offset (in bytes) where to write the "obj_count" value later. */
288 uint64_t offObjCount;
289 /** List containing PAUDIOTESTOBJ test object entries. */
290 RTLISTANCHOR lstObj;
291 /** Number of performed tests.
292 * Not necessarily bound to the test object entries above. */
293 uint32_t cTests;
294 /** Absolute offset (in bytes) where to write the "test_count" value later. */
295 uint64_t offTestCount;
296 /** List containing PAUDIOTESTENTRY test entries. */
297 RTLISTANCHOR lstTest;
298 /** Current test running. Can be NULL if no test is running. */
299 PAUDIOTESTENTRY pTestCur;
300 /** Number of tests currently running.
301 * Currently we only allow one concurrent test running at a given time. */
302 uint32_t cTestsRunning;
303 /** Number of total (test) failures. */
304 uint32_t cTotalFailures;
305} AUDIOTESTSET;
306/** Pointer to an audio test set. */
307typedef AUDIOTESTSET *PAUDIOTESTSET;
308
309/**
310 * Structure for holding a single audio test error entry.
311 */
312typedef struct AUDIOTESTERRORENTRY
313{
314 /** The entrie's list node. */
315 RTLISTNODE Node;
316 /** Additional rc. */
317 int rc;
318 /** Actual error description. */
319 char szDesc[AUDIOTEST_ERROR_DESC_MAX];
320} AUDIOTESTERRORENTRY;
321/** Pointer to an audio test error description. */
322typedef AUDIOTESTERRORENTRY *PAUDIOTESTERRORENTRY;
323
324/**
325 * Structure for holding an audio test error description.
326 * This can contain multiple errors (FIFO list).
327 */
328typedef struct AUDIOTESTERRORDESC
329{
330 /** List entries containing the (FIFO-style) errors of type AUDIOTESTERRORENTRY. */
331 RTLISTANCHOR List;
332 /** Number of errors in the list. */
333 uint32_t cErrors;
334} AUDIOTESTERRORDESC;
335/** Pointer to an audio test error description. */
336typedef AUDIOTESTERRORDESC *PAUDIOTESTERRORDESC;
337/** Const pointer to an audio test error description. */
338typedef AUDIOTESTERRORDESC const *PCAUDIOTESTERRORDESC;
339
340double AudioTestToneInit(PAUDIOTESTTONE pTone, PPDMAUDIOPCMPROPS pProps, double dbFreq);
341double AudioTestToneInitRandom(PAUDIOTESTTONE pTone, PPDMAUDIOPCMPROPS pProps);
342int AudioTestToneGenerate(PAUDIOTESTTONE pTone, void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten);
343
344int AudioTestToneParamsInitRandom(PAUDIOTESTTONEPARMS pToneParams, PPDMAUDIOPCMPROPS pProps);
345
346int AudioTestGenTag(char *pszTag, size_t cbTag);
347
348int AudioTestPathGetTemp(char *pszPath, size_t cbPath);
349int AudioTestPathCreateTemp(char *pszPath, size_t cbPath, const char *pszUUID);
350int AudioTestPathCreate(char *pszPath, size_t cbPath, const char *pszUUID);
351
352int AudioTestSetObjCreateAndRegister(PAUDIOTESTSET pSet, const char *pszName, PAUDIOTESTOBJ *ppObj);
353int AudioTestSetObjWrite(PAUDIOTESTOBJ pObj, const void *pvBuf, size_t cbBuf);
354int AudioTestSetObjAddMetadataStr(PAUDIOTESTOBJ pObj, const char *pszFormat, ...);
355int AudioTestSetObjClose(PAUDIOTESTOBJ pObj);
356
357int AudioTestSetTestBegin(PAUDIOTESTSET pSet, const char *pszDesc, PAUDIOTESTPARMS pParms, PAUDIOTESTENTRY *ppEntry);
358int AudioTestSetTestFailed(PAUDIOTESTENTRY pEntry, int rc, const char *pszErr);
359int AudioTestSetTestDone(PAUDIOTESTENTRY pEntry);
360
361int AudioTestSetCreate(PAUDIOTESTSET pSet, const char *pszPath, const char *pszTag);
362int AudioTestSetDestroy(PAUDIOTESTSET pSet);
363int AudioTestSetOpen(PAUDIOTESTSET pSet, const char *pszPath);
364int AudioTestSetClose(PAUDIOTESTSET pSet);
365int AudioTestSetWipe(PAUDIOTESTSET pSet);
366const char *AudioTestSetGetTag(PAUDIOTESTSET pSet);
367bool AudioTestSetIsPacked(const char *pszPath);
368int AudioTestSetPack(PAUDIOTESTSET pSet, const char *pszOutDir, char *pszFileName, size_t cbFileName);
369int AudioTestSetUnpack(const char *pszFile, const char *pszOutDir);
370int AudioTestSetVerify(PAUDIOTESTSET pSetA, PAUDIOTESTSET pSetB, PAUDIOTESTERRORDESC pErrDesc);
371
372uint32_t AudioTestErrorDescCount(PCAUDIOTESTERRORDESC pErr);
373bool AudioTestErrorDescFailed(PCAUDIOTESTERRORDESC pErr);
374
375void AudioTestErrorDescDestroy(PAUDIOTESTERRORDESC pErr);
376
377/** @name Wave File Accessors
378 * @{ */
379/**
380 * An open wave (.WAV) file.
381 */
382typedef struct AUDIOTESTWAVEFILE
383{
384 /** Magic value (AUDIOTESTWAVEFILE_MAGIC). */
385 uint32_t u32Magic;
386 /** Set if we're in read-mode, clear if in write mode. */
387 bool fReadMode;
388 /** The file handle. */
389 RTFILE hFile;
390 /** The absolute file offset of the first sample */
391 uint32_t offSamples;
392 /** Number of bytes of samples. */
393 uint32_t cbSamples;
394 /** The current read position relative to @a offSamples. */
395 uint32_t offCur;
396 /** The PCM properties for the file format. */
397 PDMAUDIOPCMPROPS Props;
398} AUDIOTESTWAVEFILE;
399/** Pointer to an open wave file. */
400typedef AUDIOTESTWAVEFILE *PAUDIOTESTWAVEFILE;
401
402/** Magic value for AUDIOTESTWAVEFILE::u32Magic (Miles Dewey Davis III). */
403#define AUDIOTESTWAVEFILE_MAGIC UINT32_C(0x19260526)
404/** Magic value for AUDIOTESTWAVEFILE::u32Magic after closing. */
405#define AUDIOTESTWAVEFILE_MAGIC_DEAD UINT32_C(0x19910928)
406
407int AudioTestWaveFileOpen(const char *pszFile, PAUDIOTESTWAVEFILE pWaveFile, PRTERRINFO pErrInfo);
408int AudioTestWaveFileCreate(const char *pszFile, PCPDMAUDIOPCMPROPS pProps, PAUDIOTESTWAVEFILE pWaveFile, PRTERRINFO pErrInfo);
409int AudioTestWaveFileRead(PAUDIOTESTWAVEFILE pWaveFile, void *pvBuf, size_t cbBuf, size_t *pcbRead);
410int AudioTestWaveFileWrite(PAUDIOTESTWAVEFILE pWaveFile, const void *pvBuf, size_t cbBuf);
411int AudioTestWaveFileClose(PAUDIOTESTWAVEFILE pWaveFile);
412
413/** @} */
414
415#endif /* !VBOX_INCLUDED_SRC_Audio_AudioTest_h */
416
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