VirtualBox

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

最後變更 在這個檔案從89984是 89984,由 vboxsync 提交於 4 年 前

Audio/ValKit: More code for test (set) verification. bugref:10008
  • 屬性 svn:eol-style 設為 native
  • 屬性 svn:keywords 設為 Author Date Id Revision
檔案大小: 14.3 KB
行 
1/* $Id: AudioTest.h 89984 2021-07-01 08:36:56Z 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.alldomusa.eu.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 /** The UUID of the object.
221 * Used to identify an object within a test set. */
222 RTUUID Uuid;
223 /** Number of references to this test object. */
224 uint32_t cRefs;
225 /** Name of the test object.
226 * Must not contain a path and has to be able to serialize to disk. */
227 char szName[64];
228 /** The object type. */
229 AUDIOTESTOBJTYPE enmType;
230 /** Meta data list. */
231 RTLISTANCHOR lstMeta;
232 /** Union for holding the object type-specific data. */
233 union
234 {
235 AUDIOTESTOBJFILE File;
236 };
237} AUDIOTESTOBJ;
238/** Pointer to an audio test object. */
239typedef AUDIOTESTOBJ *PAUDIOTESTOBJ;
240
241struct AUDIOTESTSET;
242
243/**
244 * Structure specifying a single audio test entry of a test set.
245 *
246 * A test set can contain zero or more test entry (tests).
247 */
248typedef struct AUDIOTESTENTRY
249{
250 /** List node. */
251 RTLISTNODE Node;
252 /** Pointer to test set parent. */
253 AUDIOTESTSET *pParent;
254 /** Friendly description of the test. */
255 char szDesc[64];
256 /** Audio test parameters this test needs to perform the actual test. */
257 AUDIOTESTPARMS Parms;
258 /** Number of test objects bound to this test. */
259 uint32_t cObj;
260 /** Absolute offset (in bytes) where to write the "obj_count" value later. */
261 uint64_t offObjCount;
262 /** Overall test result. */
263 int rc;
264} AUDIOTESTENTRY;
265/** Pointer to an audio test entry. */
266typedef AUDIOTESTENTRY *PAUDIOTESTENTRY;
267
268/**
269 * Structure specifying an audio test set.
270 */
271typedef struct AUDIOTESTSET
272{
273 /** The set's tag. */
274 char szTag[AUDIOTEST_TAG_MAX];
275 /** Absolute path where to store the test audio data. */
276 char szPathAbs[RTPATH_MAX];
277 /** Current mode the test set is in. */
278 AUDIOTESTSETMODE enmMode;
279 union
280 {
281 /** @todo r=bird: RTSTREAM not RTFILE. That means you don't have to check
282 * every write status code and it's buffered and thus faster. Also,
283 * you don't have to re-invent fprintf-style RTFileWrite wrappers. */
284 RTFILE hFile;
285 RTINIFILE hIniFile;
286 } f;
287 /** Number of test objects in lstObj. */
288 uint32_t cObj;
289 /** Absolute offset (in bytes) where to write the "obj_count" value later. */
290 uint64_t offObjCount;
291 /** List containing PAUDIOTESTOBJ test object entries. */
292 RTLISTANCHOR lstObj;
293 /** Number of performed tests.
294 * Not necessarily bound to the test object entries above. */
295 uint32_t cTests;
296 /** Absolute offset (in bytes) where to write the "test_count" value later. */
297 uint64_t offTestCount;
298 /** List containing PAUDIOTESTENTRY test entries. */
299 RTLISTANCHOR lstTest;
300 /** Current test running. Can be NULL if no test is running. */
301 PAUDIOTESTENTRY pTestCur;
302 /** Number of tests currently running.
303 * Currently we only allow one concurrent test running at a given time. */
304 uint32_t cTestsRunning;
305 /** Number of total (test) failures. */
306 uint32_t cTotalFailures;
307} AUDIOTESTSET;
308/** Pointer to an audio test set. */
309typedef AUDIOTESTSET *PAUDIOTESTSET;
310
311/**
312 * Structure for holding a single audio test error entry.
313 */
314typedef struct AUDIOTESTERRORENTRY
315{
316 /** The entrie's list node. */
317 RTLISTNODE Node;
318 /** Additional rc. */
319 int rc;
320 /** Actual error description. */
321 char szDesc[AUDIOTEST_ERROR_DESC_MAX];
322} AUDIOTESTERRORENTRY;
323/** Pointer to an audio test error description. */
324typedef AUDIOTESTERRORENTRY *PAUDIOTESTERRORENTRY;
325
326/**
327 * Structure for holding an audio test error description.
328 * This can contain multiple errors (FIFO list).
329 */
330typedef struct AUDIOTESTERRORDESC
331{
332 /** List entries containing the (FIFO-style) errors of type AUDIOTESTERRORENTRY. */
333 RTLISTANCHOR List;
334 /** Number of errors in the list. */
335 uint32_t cErrors;
336} AUDIOTESTERRORDESC;
337/** Pointer to an audio test error description. */
338typedef AUDIOTESTERRORDESC *PAUDIOTESTERRORDESC;
339/** Const pointer to an audio test error description. */
340typedef AUDIOTESTERRORDESC const *PCAUDIOTESTERRORDESC;
341
342double AudioTestToneInit(PAUDIOTESTTONE pTone, PPDMAUDIOPCMPROPS pProps, double dbFreq);
343double AudioTestToneInitRandom(PAUDIOTESTTONE pTone, PPDMAUDIOPCMPROPS pProps);
344double AudioTestToneGetRandomFreq(void);
345int AudioTestToneGenerate(PAUDIOTESTTONE pTone, void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten);
346
347int AudioTestGenTag(char *pszTag, size_t cbTag);
348
349int AudioTestPathGetTemp(char *pszPath, size_t cbPath);
350int AudioTestPathCreateTemp(char *pszPath, size_t cbPath, const char *pszUUID);
351int AudioTestPathCreate(char *pszPath, size_t cbPath, const char *pszUUID);
352
353int AudioTestSetObjCreateAndRegister(PAUDIOTESTSET pSet, const char *pszName, PAUDIOTESTOBJ *ppObj);
354int AudioTestSetObjWrite(PAUDIOTESTOBJ pObj, const void *pvBuf, size_t cbBuf);
355int AudioTestSetObjAddMetadataStr(PAUDIOTESTOBJ pObj, const char *pszFormat, ...);
356int AudioTestSetObjClose(PAUDIOTESTOBJ pObj);
357
358int AudioTestSetTestBegin(PAUDIOTESTSET pSet, const char *pszDesc, PAUDIOTESTPARMS pParms, PAUDIOTESTENTRY *ppEntry);
359int AudioTestSetTestFailed(PAUDIOTESTENTRY pEntry, int rc, const char *pszErr);
360int AudioTestSetTestDone(PAUDIOTESTENTRY pEntry);
361bool AudioTestSetTestIsRunning(PAUDIOTESTENTRY pEntry);
362
363int AudioTestSetCreate(PAUDIOTESTSET pSet, const char *pszPath, const char *pszTag);
364int AudioTestSetDestroy(PAUDIOTESTSET pSet);
365int AudioTestSetOpen(PAUDIOTESTSET pSet, const char *pszPath);
366int AudioTestSetClose(PAUDIOTESTSET pSet);
367int AudioTestSetWipe(PAUDIOTESTSET pSet);
368const char *AudioTestSetGetTag(PAUDIOTESTSET pSet);
369bool AudioTestSetIsPacked(const char *pszPath);
370bool AudioTestSetIsRunning(PAUDIOTESTSET pSet);
371int AudioTestSetPack(PAUDIOTESTSET pSet, const char *pszOutDir, char *pszFileName, size_t cbFileName);
372int AudioTestSetUnpack(const char *pszFile, const char *pszOutDir);
373int AudioTestSetVerify(PAUDIOTESTSET pSetA, PAUDIOTESTSET pSetB, PAUDIOTESTERRORDESC pErrDesc);
374
375uint32_t AudioTestErrorDescCount(PCAUDIOTESTERRORDESC pErr);
376bool AudioTestErrorDescFailed(PCAUDIOTESTERRORDESC pErr);
377
378void AudioTestErrorDescDestroy(PAUDIOTESTERRORDESC pErr);
379
380/** @name Wave File Accessors
381 * @{ */
382/**
383 * An open wave (.WAV) file.
384 */
385typedef struct AUDIOTESTWAVEFILE
386{
387 /** Magic value (AUDIOTESTWAVEFILE_MAGIC). */
388 uint32_t u32Magic;
389 /** Set if we're in read-mode, clear if in write mode. */
390 bool fReadMode;
391 /** The file handle. */
392 RTFILE hFile;
393 /** The absolute file offset of the first sample */
394 uint32_t offSamples;
395 /** Number of bytes of samples. */
396 uint32_t cbSamples;
397 /** The current read position relative to @a offSamples. */
398 uint32_t offCur;
399 /** The PCM properties for the file format. */
400 PDMAUDIOPCMPROPS Props;
401} AUDIOTESTWAVEFILE;
402/** Pointer to an open wave file. */
403typedef AUDIOTESTWAVEFILE *PAUDIOTESTWAVEFILE;
404
405/** Magic value for AUDIOTESTWAVEFILE::u32Magic (Miles Dewey Davis III). */
406#define AUDIOTESTWAVEFILE_MAGIC UINT32_C(0x19260526)
407/** Magic value for AUDIOTESTWAVEFILE::u32Magic after closing. */
408#define AUDIOTESTWAVEFILE_MAGIC_DEAD UINT32_C(0x19910928)
409
410int AudioTestWaveFileOpen(const char *pszFile, PAUDIOTESTWAVEFILE pWaveFile, PRTERRINFO pErrInfo);
411int AudioTestWaveFileCreate(const char *pszFile, PCPDMAUDIOPCMPROPS pProps, PAUDIOTESTWAVEFILE pWaveFile, PRTERRINFO pErrInfo);
412int AudioTestWaveFileRead(PAUDIOTESTWAVEFILE pWaveFile, void *pvBuf, size_t cbBuf, size_t *pcbRead);
413int AudioTestWaveFileWrite(PAUDIOTESTWAVEFILE pWaveFile, const void *pvBuf, size_t cbBuf);
414int AudioTestWaveFileClose(PAUDIOTESTWAVEFILE pWaveFile);
415
416/** @} */
417
418#endif /* !VBOX_INCLUDED_SRC_Audio_AudioTest_h */
419
注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

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