VirtualBox

source: vbox/trunk/src/VBox/ValidationKit/utils/audio/vkatInternal.h@ 91211

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

Audio/VKAT: Implemented the "--count <N>" option. bugref:10008
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 20.1 KB
Line 
1/* $Id: vkatInternal.h 91211 2021-09-10 16:57:36Z vboxsync $ */
2/** @file
3 * VKAT - Internal header file for common definitions + structs.
4 */
5
6/*
7 * Copyright (C) 2021 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.virtualbox.org. This file is free software;
11 * you can redistribute it and/or modify it under the terms of the GNU
12 * General Public License (GPL) as published by the Free Software
13 * Foundation, in version 2 as it comes in the "COPYING" file of the
14 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16 *
17 * The contents of this file may alternatively be used under the terms
18 * of the Common Development and Distribution License Version 1.0
19 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20 * VirtualBox OSE distribution, in which case the provisions of the
21 * CDDL are applicable instead of those of the GPL.
22 *
23 * You may elect to license modified versions of this file under the
24 * terms and conditions of either the GPL or the CDDL or both.
25 */
26
27#ifndef VBOX_INCLUDED_SRC_audio_vkatInternal_h
28#define VBOX_INCLUDED_SRC_audio_vkatInternal_h
29#ifndef RT_WITHOUT_PRAGMA_ONCE
30# pragma once
31#endif
32
33
34/*********************************************************************************************************************************
35* Header Files *
36*********************************************************************************************************************************/
37#include <iprt/getopt.h>
38
39#include <VBox/vmm/pdmdrv.h>
40#include <VBox/vmm/pdmaudioinline.h>
41#include <VBox/vmm/pdmaudiohostenuminline.h>
42
43#include "Audio/AudioMixBuffer.h"
44#include "Audio/AudioTest.h"
45#include "Audio/AudioTestService.h"
46#include "Audio/AudioTestServiceClient.h"
47
48#include "VBoxDD.h"
49
50
51/*********************************************************************************************************************************
52* Structures and Typedefs *
53*********************************************************************************************************************************/
54/**
55 * Audio driver stack.
56 *
57 * This can be just be backend driver alone or DrvAudio with a backend.
58 * @todo add automatic resampling via mixer so we can test more of the audio
59 * stack used by the device emulations.
60 */
61typedef struct AUDIOTESTDRVSTACK
62{
63 /** The device registration record for the backend. */
64 PCPDMDRVREG pDrvReg;
65 /** The backend driver instance. */
66 PPDMDRVINS pDrvBackendIns;
67 /** The backend's audio interface. */
68 PPDMIHOSTAUDIO pIHostAudio;
69
70 /** The DrvAudio instance. */
71 PPDMDRVINS pDrvAudioIns;
72 /** This is NULL if we don't use DrvAudio. */
73 PPDMIAUDIOCONNECTOR pIAudioConnector;
74
75 /** The current (last) audio device enumeration to use. */
76 PDMAUDIOHOSTENUM DevEnum;
77} AUDIOTESTDRVSTACK;
78/** Pointer to an audio driver stack. */
79typedef AUDIOTESTDRVSTACK *PAUDIOTESTDRVSTACK;
80
81/**
82 * Backend-only stream structure.
83 */
84typedef struct AUDIOTESTDRVSTACKSTREAM
85{
86 /** The public stream data. */
87 PDMAUDIOSTREAM Core;
88 /** The backend data (variable size). */
89 PDMAUDIOBACKENDSTREAM Backend;
90} AUDIOTESTDRVSTACKSTREAM;
91/** Pointer to a backend-only stream structure. */
92typedef AUDIOTESTDRVSTACKSTREAM *PAUDIOTESTDRVSTACKSTREAM;
93
94/**
95 * Mixer setup for a stream.
96 */
97typedef struct AUDIOTESTDRVMIXSTREAM
98{
99 /** Pointer to the driver stack. */
100 PAUDIOTESTDRVSTACK pDrvStack;
101 /** Pointer to the stream. */
102 PPDMAUDIOSTREAM pStream;
103 /** Properties to use. */
104 PCPDMAUDIOPCMPROPS pProps;
105 /** Set if we're mixing or just passing thru to the driver stack. */
106 bool fDoMixing;
107 /** Mixer buffer. */
108 AUDIOMIXBUF MixBuf;
109 /** Write state. */
110 AUDIOMIXBUFWRITESTATE WriteState;
111 /** Peek state. */
112 AUDIOMIXBUFPEEKSTATE PeekState;
113} AUDIOTESTDRVMIXSTREAM;
114/** Pointer to mixer setup for a stream. */
115typedef AUDIOTESTDRVMIXSTREAM *PAUDIOTESTDRVMIXSTREAM;
116
117/**
118 * Enumeration specifying the current audio test mode.
119 */
120typedef enum AUDIOTESTMODE
121{
122 /** Unknown mode. */
123 AUDIOTESTMODE_UNKNOWN = 0,
124 /** VKAT is running on the guest side. */
125 AUDIOTESTMODE_GUEST,
126 /** VKAT is running on the host side. */
127 AUDIOTESTMODE_HOST
128} AUDIOTESTMODE;
129
130struct AUDIOTESTENV;
131/** Pointer a audio test environment. */
132typedef AUDIOTESTENV *PAUDIOTESTENV;
133
134struct AUDIOTESTDESC;
135/** Pointer a audio test descriptor. */
136typedef AUDIOTESTDESC *PAUDIOTESTDESC;
137
138/**
139 * Callback to set up the test parameters for a specific test.
140 *
141 * @returns IPRT status code.
142 * @retval VINF_SUCCESS if setting the parameters up succeeded. Any other error code
143 * otherwise indicating the kind of error.
144 * @param pszTest Test name.
145 * @param pTstParmsAcq The audio test parameters to set up.
146 */
147typedef DECLCALLBACKTYPE(int, FNAUDIOTESTSETUP,(PAUDIOTESTENV pTstEnv, PAUDIOTESTDESC pTstDesc, PAUDIOTESTPARMS pTstParmsAcq, void **ppvCtx));
148/** Pointer to an audio test setup callback. */
149typedef FNAUDIOTESTSETUP *PFNAUDIOTESTSETUP;
150
151typedef DECLCALLBACKTYPE(int, FNAUDIOTESTEXEC,(PAUDIOTESTENV pTstEnv, void *pvCtx, PAUDIOTESTPARMS pTstParms));
152/** Pointer to an audio test exec callback. */
153typedef FNAUDIOTESTEXEC *PFNAUDIOTESTEXEC;
154
155typedef DECLCALLBACKTYPE(int, FNAUDIOTESTDESTROY,(PAUDIOTESTENV pTstEnv, void *pvCtx));
156/** Pointer to an audio test destroy callback. */
157typedef FNAUDIOTESTDESTROY *PFNAUDIOTESTDESTROY;
158
159/**
160 * Structure for keeping an audio test audio stream.
161 */
162typedef struct AUDIOTESTSTREAM
163{
164 /** The PDM stream. */
165 PPDMAUDIOSTREAM pStream;
166 /** The backend stream. */
167 PPDMAUDIOBACKENDSTREAM pBackend;
168 /** The stream config. */
169 PDMAUDIOSTREAMCFG Cfg;
170 /** Associated mixing stream. Optional. */
171 AUDIOTESTDRVMIXSTREAM Mix;
172} AUDIOTESTSTREAM;
173/** Pointer to audio test stream. */
174typedef AUDIOTESTSTREAM *PAUDIOTESTSTREAM;
175
176/** Maximum audio streams a test environment can handle. */
177#define AUDIOTESTENV_MAX_STREAMS 8
178
179/**
180 * Structure for keeping TCP/IP-specific options.
181 */
182typedef struct AUDIOTESTENVTCPOPTS
183{
184 /** Connection mode(s) to use. */
185 ATSCONNMODE enmConnMode;
186 /** Bind address (server mode). When empty, "0.0.0.0" (any host) will be used. */
187 char szBindAddr[128];
188 /** Bind port (server mode). */
189 uint16_t uBindPort;
190 /** Connection address (client mode). */
191 char szConnectAddr[128];
192 /** Connection port (client mode). */
193 uint16_t uConnectPort;
194} AUDIOTESTENVTCPOPTS;
195/** Pointer to audio test TCP options. */
196typedef AUDIOTESTENVTCPOPTS *PAUDIOTESTENVTCPOPTS;
197
198/**
199 * Structure for keeping a user context for the test service callbacks.
200 */
201typedef struct ATSCALLBACKCTX
202{
203 /** The test environment bound to this context. */
204 PAUDIOTESTENV pTstEnv;
205 /** Absolute path to the packed up test set archive.
206 * Keep it simple for now and only support one (open) archive at a time. */
207 char szTestSetArchive[RTPATH_MAX];
208 /** File handle to the (opened) test set archive for reading. */
209 RTFILE hTestSetArchive;
210 /** Number of currently connected clients. */
211 uint8_t cClients;
212} ATSCALLBACKCTX;
213typedef ATSCALLBACKCTX *PATSCALLBACKCTX;
214
215/**
216 * Audio test environment parameters.
217 * Not necessarily bound to a specific test (can be reused).
218 */
219typedef struct AUDIOTESTENV
220{
221 /** Audio testing mode. */
222 AUDIOTESTMODE enmMode;
223 /** Whether self test mode is active or not. */
224 bool fSelftest;
225 /** Whether skip the actual verification or not. */
226 bool fSkipVerify;
227 /** The PCM properties to use. */
228 PDMAUDIOPCMPROPS Props;
229 /** Name of the audio device to use.
230 * If empty the default audio device will be used. */
231 char szDev[128];
232 /** Audio volume to use (in percent).
233 * Might not be available on all systems. */
234 uint8_t uVolumePercent;
235 /** Number of iterations for *all* tests specified.
236 * When set to 0 (default), a random value (see specific test) will be chosen. */
237 uint32_t cIterations;
238 /** Output path for storing the test environment's final test files. */
239 char szTag[AUDIOTEST_TAG_MAX];
240 /** Output path for storing the test environment's final test files. */
241 char szPathOut[RTPATH_MAX];
242 /** Temporary path for this test environment. */
243 char szPathTemp[RTPATH_MAX];
244 /** Buffer size (in ms). */
245 RTMSINTERVAL cMsBufferSize;
246 /** Pre-buffering time (in ms). */
247 RTMSINTERVAL cMsPreBuffer;
248 /** Scheduling hint (in ms). */
249 RTMSINTERVAL cMsSchedulingHint;
250 /** Pointer to audio test driver stack to use. */
251 PAUDIOTESTDRVSTACK pDrvStack;
252 /** Audio stream. */
253 AUDIOTESTSTREAM aStreams[AUDIOTESTENV_MAX_STREAMS];
254 /** The audio test set to use. */
255 AUDIOTESTSET Set;
256 /** TCP options to use for ATS. */
257 AUDIOTESTENVTCPOPTS TcpOpts;
258 /** ATS server instance to use.
259 * NULL if not in use. */
260 PATSSERVER pSrv;
261 /** ATS callback context to use. */
262 ATSCALLBACKCTX CallbackCtx;
263 union
264 {
265 struct
266 {
267 /** Client connected to the ATS on the guest side. */
268 ATSCLIENT AtsClGuest;
269 /** Path to the guest's test set downloaded to the host. */
270 char szPathTestSetGuest[RTPATH_MAX];
271 /** Client connected to the Validation Kit audio driver ATS. */
272 ATSCLIENT AtsClValKit;
273 /** Path to the Validation Kit audio driver's test set downloaded to the host. */
274 char szPathTestSetValKit[RTPATH_MAX];
275 } Host;
276 } u;
277} AUDIOTESTENV;
278
279/**
280 * Audio test descriptor.
281 */
282typedef struct AUDIOTESTDESC
283{
284 /** (Sort of) Descriptive test name. */
285 const char *pszName;
286 /** Flag whether the test is excluded. */
287 bool fExcluded;
288 /** The setup callback. */
289 PFNAUDIOTESTSETUP pfnSetup;
290 /** The exec callback. */
291 PFNAUDIOTESTEXEC pfnExec;
292 /** The destruction callback. */
293 PFNAUDIOTESTDESTROY pfnDestroy;
294} AUDIOTESTDESC;
295
296/**
297 * Backend description.
298 */
299typedef struct AUDIOTESTBACKENDDESC
300{
301 /** The driver registration structure. */
302 PCPDMDRVREG pDrvReg;
303 /** The backend name.
304 * Aliases are implemented by having multiple entries for the same backend. */
305 const char *pszName;
306} AUDIOTESTBACKENDDESC;
307
308/**
309 * VKAT command table entry.
310 */
311typedef struct VKATCMD
312{
313 /** The command name. */
314 const char *pszCommand;
315 /** The command handler. */
316 DECLCALLBACKMEMBER(RTEXITCODE, pfnHandler,(PRTGETOPTSTATE pGetState));
317
318 /** Command description. */
319 const char *pszDesc;
320 /** Options array. */
321 PCRTGETOPTDEF paOptions;
322 /** Number of options in the option array. */
323 size_t cOptions;
324 /** Gets help for an option. */
325 DECLCALLBACKMEMBER(const char *, pfnOptionHelp,(PCRTGETOPTDEF pOpt));
326 /** Flag indicating if the command needs the ATS transport layer.
327 * Needed for command line parsing. */
328 bool fNeedsTransport;
329} VKATCMD;
330/** Pointer to a const VKAT command entry. */
331typedef VKATCMD const *PCVKATCMD;
332
333
334/*********************************************************************************************************************************
335* Global Variables *
336*********************************************************************************************************************************/
337/** Terminate ASAP if set. Set on Ctrl-C. */
338extern bool volatile g_fTerminate;
339/** The release logger. */
340extern PRTLOGGER g_pRelLogger;
341
342/** The test handle. */
343extern RTTEST g_hTest;
344extern unsigned g_uVerbosity;
345extern bool g_fDrvAudioDebug;
346extern const char *g_pszDrvAudioDebug;
347
348/** The test handle. */
349extern RTTEST g_hTest;
350/** The current verbosity level. */
351extern unsigned g_uVerbosity;
352/** DrvAudio: Enable debug (or not). */
353extern bool g_fDrvAudioDebug;
354/** DrvAudio: The debug output path. */
355extern const char *g_pszDrvAudioDebug;
356
357extern const VKATCMD g_CmdEnum;
358extern const VKATCMD g_CmdPlay;
359extern const VKATCMD g_CmdRec;
360extern const VKATCMD g_CmdSelfTest;
361
362extern AUDIOTESTDESC g_aTests[];
363extern unsigned g_cTests;
364
365extern AUDIOTESTBACKENDDESC const g_aBackends[];
366extern unsigned g_cBackends;
367
368
369/*********************************************************************************************************************************
370* Prototypes *
371*********************************************************************************************************************************/
372
373/** @name Command line handlers
374 * @{ */
375RTEXITCODE audioTestUsage(PRTSTREAM pStrm);
376RTEXITCODE audioTestVersion(void);
377void audioTestShowLogo(PRTSTREAM pStream);
378/** @} */
379
380/** @name Driver stack
381 * @{ */
382void audioTestDriverStackDelete(PAUDIOTESTDRVSTACK pDrvStack);
383int audioTestDriverStackInitEx(PAUDIOTESTDRVSTACK pDrvStack, PCPDMDRVREG pDrvReg, bool fEnabledIn, bool fEnabledOut, bool fWithDrvAudio);
384int audioTestDriverStackInit(PAUDIOTESTDRVSTACK pDrvStack, PCPDMDRVREG pDrvReg, bool fWithDrvAudio);
385int audioTestDriverStackProbe(PAUDIOTESTDRVSTACK pDrvStack, PCPDMDRVREG pDrvReg, bool fEnabledIn, bool fEnabledOut, bool fWithDrvAudio);
386int audioTestDriverStackSetDevice(PAUDIOTESTDRVSTACK pDrvStack, PDMAUDIODIR enmDir, const char *pszDevId);
387/** @} */
388
389/** @name Driver
390 * @{ */
391int audioTestDrvConstruct(PAUDIOTESTDRVSTACK pDrvStack, PCPDMDRVREG pDrvReg, PPDMDRVINS pParentDrvIns, PPPDMDRVINS ppDrvIns);
392/** @} */
393
394/** @name Driver stack stream
395 * @{ */
396int audioTestDriverStackStreamCreateInput(PAUDIOTESTDRVSTACK pDrvStack, PCPDMAUDIOPCMPROPS pProps,
397 uint32_t cMsBufferSize, uint32_t cMsPreBuffer, uint32_t cMsSchedulingHint,
398 PPDMAUDIOSTREAM *ppStream, PPDMAUDIOSTREAMCFG pCfgAcq);
399int audioTestDriverStackStreamCreateOutput(PAUDIOTESTDRVSTACK pDrvStack, PCPDMAUDIOPCMPROPS pProps,
400 uint32_t cMsBufferSize, uint32_t cMsPreBuffer, uint32_t cMsSchedulingHint,
401 PPDMAUDIOSTREAM *ppStream, PPDMAUDIOSTREAMCFG pCfgAcq);
402void audioTestDriverStackStreamDestroy(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream);
403int audioTestDriverStackStreamDrain(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream, bool fSync);
404int audioTestDriverStackStreamEnable(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream);
405int AudioTestDriverStackStreamDisable(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream);
406bool audioTestDriverStackStreamIsOkay(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream);
407uint32_t audioTestDriverStackStreamGetWritable(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream);
408int audioTestDriverStackStreamPlay(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream, void const *pvBuf,
409 uint32_t cbBuf, uint32_t *pcbPlayed);
410uint32_t audioTestDriverStackStreamGetReadable(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream);
411int audioTestDriverStackStreamCapture(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream,
412 void *pvBuf, uint32_t cbBuf, uint32_t *pcbCaptured);
413/** @} */
414
415/** @name Backend handling
416 * @{ */
417PCPDMDRVREG AudioTestGetDefaultBackend(void);
418PCPDMDRVREG AudioTestFindBackendOpt(const char *pszBackend);
419/** @} */
420
421/** @name Mixing stream
422 * @{ */
423int AudioTestMixStreamInit(PAUDIOTESTDRVMIXSTREAM pMix, PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream,
424 PCPDMAUDIOPCMPROPS pProps, uint32_t cMsBuffer);
425void AudioTestMixStreamTerm(PAUDIOTESTDRVMIXSTREAM pMix);
426int AudioTestMixStreamEnable(PAUDIOTESTDRVMIXSTREAM pMix);
427int AudioTestMixStreamDrain(PAUDIOTESTDRVMIXSTREAM pMix, bool fSync);
428int AudioTestMixStreamDisable(PAUDIOTESTDRVMIXSTREAM pMix);
429bool AudioTestMixStreamIsOkay(PAUDIOTESTDRVMIXSTREAM pMix);
430uint32_t AudioTestMixStreamGetWritable(PAUDIOTESTDRVMIXSTREAM pMix);
431int AudioTestMixStreamPlay(PAUDIOTESTDRVMIXSTREAM pMix, void const *pvBuf, uint32_t cbBuf, uint32_t *pcbPlayed);
432uint32_t AudioTestMixStreamGetReadable(PAUDIOTESTDRVMIXSTREAM pMix);
433int AudioTestMixStreamCapture(PAUDIOTESTDRVMIXSTREAM pMix, void *pvBuf, uint32_t cbBuf, uint32_t *pcbCaptured);
434/** @} */
435
436/** @name Device handling
437 * @{ */
438int audioTestDeviceOpen(PPDMAUDIOHOSTDEV pDev);
439int audioTestDeviceClose(PPDMAUDIOHOSTDEV pDev);
440
441int audioTestDevicesEnumerateAndCheck(PAUDIOTESTDRVSTACK pDrvStack, const char *pszDev, PPDMAUDIOHOSTDEV *ppDev);
442/** @} */
443
444/** @name ATS routines
445 * @{ */
446int audioTestEnvConnectToValKitAts(PAUDIOTESTENV pTstEnv,
447 const char *pszHostTcpAddr, uint32_t uHostTcpPort);
448/** @} */
449
450/** @name Test environment handling
451 * @{ */
452int audioTestEnvInit(PAUDIOTESTENV pTstEnv, PAUDIOTESTDRVSTACK pDrvStack);
453void audioTestEnvDestroy(PAUDIOTESTENV pTstEnv);
454int audioTestEnvPrologue(PAUDIOTESTENV pTstEnv, bool fPack, char *pszPackFile, size_t cbPackFile);
455
456void audioTestParmsInit(PAUDIOTESTPARMS pTstParms);
457void audioTestParmsDestroy(PAUDIOTESTPARMS pTstParms);
458/** @} */
459
460int audioTestWorker(PAUDIOTESTENV pTstEnv);
461
462/** @todo Test tone handling */
463int audioTestPlayTone(PAUDIOTESTENV pTstEnv, PAUDIOTESTSTREAM pStream, PAUDIOTESTTONEPARMS pParms);
464/** @} */
465
466
467/*********************************************************************************************************************************
468* Common command line stuff *
469*********************************************************************************************************************************/
470
471/**
472 * Common long options values.
473 */
474enum
475{
476 AUDIO_TEST_OPT_CMN_DAEMONIZE = 256,
477 AUDIO_TEST_OPT_CMN_DAEMONIZED,
478 AUDIO_TEST_OPT_CMN_DEBUG_AUDIO_ENABLE,
479 AUDIO_TEST_OPT_CMN_DEBUG_AUDIO_PATH
480};
481
482/** For use in the option switch to handle common options. */
483#define AUDIO_TEST_COMMON_OPTION_CASES(a_ValueUnion) \
484 case 'q': \
485 g_uVerbosity = 0; \
486 if (g_pRelLogger) \
487 RTLogGroupSettings(g_pRelLogger, "all=0 all.e"); \
488 break; \
489 \
490 case 'v': \
491 g_uVerbosity++; \
492 if (g_pRelLogger) \
493 RTLogGroupSettings(g_pRelLogger, g_uVerbosity == 1 ? "all.e.l" : g_uVerbosity == 2 ? "all.e.l.f" : "all=~0"); \
494 break; \
495 \
496 case 'V': \
497 return audioTestVersion(); \
498 \
499 case 'h': \
500 audioTestShowLogo(g_pStdOut); \
501 return audioTestUsage(g_pStdOut); \
502 \
503 case AUDIO_TEST_OPT_CMN_DEBUG_AUDIO_ENABLE: \
504 g_fDrvAudioDebug = true; \
505 break; \
506 \
507 case AUDIO_TEST_OPT_CMN_DEBUG_AUDIO_PATH: \
508 g_pszDrvAudioDebug = (a_ValueUnion).psz; \
509 break; \
510 case AUDIO_TEST_OPT_CMN_DAEMONIZE: \
511 break; \
512 case AUDIO_TEST_OPT_CMN_DAEMONIZED: \
513 break;
514
515#endif /* !VBOX_INCLUDED_SRC_audio_vkatInternal_h */
516
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