VirtualBox

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

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

Audio/Validation Kit: Added some more audio test verification options utility functions. ​bugref:10008

  • 屬性 svn:eol-style 設為 native
  • 屬性 svn:keywords 設為 Author Date Id Revision
檔案大小: 13.6 KB
 
1/* $Id: AudioTest.h 91178 2021-09-09 11:56: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.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/** Test object handle. */
155typedef R3R0PTRTYPE(struct AUDIOTESTOBJINT RT_FAR *) AUDIOTESTOBJ;
156/** Pointer to test object handle. */
157typedef AUDIOTESTOBJ RT_FAR *PAUDIOTESTOBJ;
158/** Nil test object handle. */
159#define NIL_AUDIOTESTOBJ ((AUDIOTESTOBJ)~(RTHCINTPTR)0)
160
161struct AUDIOTESTSET;
162
163/**
164 * Structure specifying a single audio test entry of a test set.
165 *
166 * A test set can contain zero or more test entry (tests).
167 */
168typedef struct AUDIOTESTENTRY
169{
170 /** List node. */
171 RTLISTNODE Node;
172 /** Pointer to test set parent. */
173 AUDIOTESTSET *pParent;
174 /** Friendly description of the test. */
175 char szDesc[64];
176 /** Audio test parameters this test needs to perform the actual test. */
177 AUDIOTESTPARMS Parms;
178 /** Number of test objects bound to this test. */
179 uint32_t cObj;
180 /** Absolute offset (in bytes) where to write the "obj_count" value later. */
181 uint64_t offObjCount;
182 /** Overall test result. */
183 int rc;
184} AUDIOTESTENTRY;
185/** Pointer to an audio test entry. */
186typedef AUDIOTESTENTRY *PAUDIOTESTENTRY;
187
188/**
189 * Structure specifying an audio test set.
190 */
191typedef struct AUDIOTESTSET
192{
193 /** The set's tag. */
194 char szTag[AUDIOTEST_TAG_MAX];
195 /** Absolute path where to store the test audio data. */
196 char szPathAbs[RTPATH_MAX];
197 /** Current mode the test set is in. */
198 AUDIOTESTSETMODE enmMode;
199 union
200 {
201 /** @todo r=bird: RTSTREAM not RTFILE. That means you don't have to check
202 * every write status code and it's buffered and thus faster. Also,
203 * you don't have to re-invent fprintf-style RTFileWrite wrappers. */
204 RTFILE hFile;
205 RTINIFILE hIniFile;
206 } f;
207 /** Number of test objects in lstObj. */
208 uint32_t cObj;
209 /** Absolute offset (in bytes) where to write the "obj_count" value later. */
210 uint64_t offObjCount;
211 /** List containing PAUDIOTESTOBJ test object entries. */
212 RTLISTANCHOR lstObj;
213 /** Number of performed tests.
214 * Not necessarily bound to the test object entries above. */
215 uint32_t cTests;
216 /** Absolute offset (in bytes) where to write the "test_count" value later. */
217 uint64_t offTestCount;
218 /** List containing PAUDIOTESTENTRY test entries. */
219 RTLISTANCHOR lstTest;
220 /** Current test running. Can be NULL if no test is running. */
221 PAUDIOTESTENTRY pTestCur;
222 /** Number of tests currently running.
223 * Currently we only allow one concurrent test running at a given time. */
224 uint32_t cTestsRunning;
225 /** Number of total (test) failures. */
226 uint32_t cTotalFailures;
227} AUDIOTESTSET;
228/** Pointer to an audio test set. */
229typedef AUDIOTESTSET *PAUDIOTESTSET;
230
231/**
232 * Audio test verification options.
233 */
234typedef struct AUDIOTESTVERIFYOPTS
235{
236 /** Flag indicating whether to keep going after an error has occurred. */
237 bool fKeepGoing;
238 /** Threshold of file differences (number of chunks) at when we consider audio files
239 * as not matching. 0 means an exact match. */
240 uint32_t cMaxDiff;
241 /** Threshold of file differences (difference in percent) at when we consider audio files
242 * as not matching. 0 means an exact match. */
243 uint8_t uMaxDiffPercent;
244 /** Threshold of file size (+/-, in percent) at when we consider audio files
245 * as not matching. 0 means an exact match.*/
246 uint8_t uMaxSizePercent;
247} AUDIOTESTVERIFYOPTS;
248/** Pointer to audio test verification options. */
249typedef AUDIOTESTVERIFYOPTS *PAUDIOTESTVERIFYOPTS;
250
251/**
252 * Structure for holding a single audio test error entry.
253 */
254typedef struct AUDIOTESTERRORENTRY
255{
256 /** The entrie's list node. */
257 RTLISTNODE Node;
258 /** Additional rc. */
259 int rc;
260 /** Actual error description. */
261 char szDesc[AUDIOTEST_ERROR_DESC_MAX];
262} AUDIOTESTERRORENTRY;
263/** Pointer to an audio test error description. */
264typedef AUDIOTESTERRORENTRY *PAUDIOTESTERRORENTRY;
265
266/**
267 * Structure for holding an audio test error description.
268 * This can contain multiple errors (FIFO list).
269 */
270typedef struct AUDIOTESTERRORDESC
271{
272 /** List entries containing the (FIFO-style) errors of type AUDIOTESTERRORENTRY. */
273 RTLISTANCHOR List;
274 /** Number of errors in the list. */
275 uint32_t cErrors;
276} AUDIOTESTERRORDESC;
277/** Pointer to an audio test error description. */
278typedef AUDIOTESTERRORDESC *PAUDIOTESTERRORDESC;
279/** Const pointer to an audio test error description. */
280typedef AUDIOTESTERRORDESC const *PCAUDIOTESTERRORDESC;
281
282double AudioTestToneInit(PAUDIOTESTTONE pTone, PPDMAUDIOPCMPROPS pProps, double dbFreq);
283double AudioTestToneInitRandom(PAUDIOTESTTONE pTone, PPDMAUDIOPCMPROPS pProps);
284double AudioTestToneGetRandomFreq(void);
285int AudioTestToneGenerate(PAUDIOTESTTONE pTone, void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten);
286
287int AudioTestGenTag(char *pszTag, size_t cbTag);
288
289int AudioTestPathGetTemp(char *pszPath, size_t cbPath);
290int AudioTestPathCreateTemp(char *pszPath, size_t cbPath, const char *pszUUID);
291int AudioTestPathCreate(char *pszPath, size_t cbPath, const char *pszUUID);
292
293int AudioTestSetObjCreateAndRegister(PAUDIOTESTSET pSet, const char *pszName, PAUDIOTESTOBJ pObj);
294
295int AudioTestObjWrite(AUDIOTESTOBJ Obj, const void *pvBuf, size_t cbBuf);
296int AudioTestObjAddMetadataStr(AUDIOTESTOBJ Obj, const char *pszFormat, ...);
297int AudioTestObjClose(AUDIOTESTOBJ Obj);
298
299int AudioTestSetTestBegin(PAUDIOTESTSET pSet, const char *pszDesc, PAUDIOTESTPARMS pParms, PAUDIOTESTENTRY *ppEntry);
300int AudioTestSetTestFailed(PAUDIOTESTENTRY pEntry, int rc, const char *pszErr);
301int AudioTestSetTestDone(PAUDIOTESTENTRY pEntry);
302bool AudioTestSetTestIsRunning(PAUDIOTESTENTRY pEntry);
303
304int AudioTestSetCreate(PAUDIOTESTSET pSet, const char *pszPath, const char *pszTag);
305int AudioTestSetDestroy(PAUDIOTESTSET pSet);
306int AudioTestSetOpen(PAUDIOTESTSET pSet, const char *pszPath);
307int AudioTestSetClose(PAUDIOTESTSET pSet);
308int AudioTestSetWipe(PAUDIOTESTSET pSet);
309const char *AudioTestSetGetTag(PAUDIOTESTSET pSet);
310uint32_t AudioTestSetGetTestsTotal(PAUDIOTESTSET pSet);
311uint32_t AudioTestSetGetTestsRunning(PAUDIOTESTSET pSet);
312uint32_t AudioTestSetGetTotalFailures(PAUDIOTESTSET pSet);
313bool AudioTestSetIsPacked(const char *pszPath);
314bool AudioTestSetIsRunning(PAUDIOTESTSET pSet);
315int AudioTestSetPack(PAUDIOTESTSET pSet, const char *pszOutDir, char *pszFileName, size_t cbFileName);
316int AudioTestSetUnpack(const char *pszFile, const char *pszOutDir);
317
318void AudioTestSetVerifyOptsInitStrict(PAUDIOTESTVERIFYOPTS pOpts);
319void AudioTestSetVerifyOptsInit(PAUDIOTESTVERIFYOPTS pOpts);
320bool AudioTestSetVerifyOptsAreEqual(PAUDIOTESTVERIFYOPTS pOptsA, PAUDIOTESTVERIFYOPTS pOptsB);
321
322int AudioTestSetVerify(PAUDIOTESTSET pSetA, PAUDIOTESTSET pSetB, PAUDIOTESTERRORDESC pErrDesc);
323int AudioTestSetVerifyEx(PAUDIOTESTSET pSetA, PAUDIOTESTSET pSetB, PAUDIOTESTVERIFYOPTS pOpts, PAUDIOTESTERRORDESC pErrDesc);
324
325uint32_t AudioTestErrorDescCount(PCAUDIOTESTERRORDESC pErr);
326bool AudioTestErrorDescFailed(PCAUDIOTESTERRORDESC pErr);
327
328void AudioTestErrorDescDestroy(PAUDIOTESTERRORDESC pErr);
329
330/** @name Wave File Accessors
331 * @{ */
332/**
333 * An open wave (.WAV) file.
334 */
335typedef struct AUDIOTESTWAVEFILE
336{
337 /** Magic value (AUDIOTESTWAVEFILE_MAGIC). */
338 uint32_t u32Magic;
339 /** Set if we're in read-mode, clear if in write mode. */
340 bool fReadMode;
341 /** The file handle. */
342 RTFILE hFile;
343 /** The absolute file offset of the first sample */
344 uint32_t offSamples;
345 /** Number of bytes of samples. */
346 uint32_t cbSamples;
347 /** The current read position relative to @a offSamples. */
348 uint32_t offCur;
349 /** The PCM properties for the file format. */
350 PDMAUDIOPCMPROPS Props;
351} AUDIOTESTWAVEFILE;
352/** Pointer to an open wave file. */
353typedef AUDIOTESTWAVEFILE *PAUDIOTESTWAVEFILE;
354
355/** Magic value for AUDIOTESTWAVEFILE::u32Magic (Miles Dewey Davis III). */
356#define AUDIOTESTWAVEFILE_MAGIC UINT32_C(0x19260526)
357/** Magic value for AUDIOTESTWAVEFILE::u32Magic after closing. */
358#define AUDIOTESTWAVEFILE_MAGIC_DEAD UINT32_C(0x19910928)
359
360int AudioTestWaveFileOpen(const char *pszFile, PAUDIOTESTWAVEFILE pWaveFile, PRTERRINFO pErrInfo);
361int AudioTestWaveFileCreate(const char *pszFile, PCPDMAUDIOPCMPROPS pProps, PAUDIOTESTWAVEFILE pWaveFile, PRTERRINFO pErrInfo);
362int AudioTestWaveFileRead(PAUDIOTESTWAVEFILE pWaveFile, void *pvBuf, size_t cbBuf, size_t *pcbRead);
363int AudioTestWaveFileWrite(PAUDIOTESTWAVEFILE pWaveFile, const void *pvBuf, size_t cbBuf);
364int AudioTestWaveFileClose(PAUDIOTESTWAVEFILE pWaveFile);
365
366/** @} */
367
368#endif /* !VBOX_INCLUDED_SRC_Audio_AudioTest_h */
369
注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

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