VirtualBox

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

Last change on this file since 90117 was 90117, checked in by vboxsync, 4 years ago

Audio/ValKit: Made daemonizing of VKAT / VBoxAudioTest more generic to support all commands. bugref:10008
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 20.0 KB
Line 
1/* $Id: vkatInternal.h 90117 2021-07-09 11:45:26Z 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} AUDIOTESTDRVSTACK;
75/** Pointer to an audio driver stack. */
76typedef AUDIOTESTDRVSTACK *PAUDIOTESTDRVSTACK;
77
78/**
79 * Backend-only stream structure.
80 */
81typedef struct AUDIOTESTDRVSTACKSTREAM
82{
83 /** The public stream data. */
84 PDMAUDIOSTREAM Core;
85 /** The backend data (variable size). */
86 PDMAUDIOBACKENDSTREAM Backend;
87} AUDIOTESTDRVSTACKSTREAM;
88/** Pointer to a backend-only stream structure. */
89typedef AUDIOTESTDRVSTACKSTREAM *PAUDIOTESTDRVSTACKSTREAM;
90
91/**
92 * Mixer setup for a stream.
93 */
94typedef struct AUDIOTESTDRVMIXSTREAM
95{
96 /** Pointer to the driver stack. */
97 PAUDIOTESTDRVSTACK pDrvStack;
98 /** Pointer to the stream. */
99 PPDMAUDIOSTREAM pStream;
100 /** Properties to use. */
101 PCPDMAUDIOPCMPROPS pProps;
102 /** Set if we're mixing or just passing thru to the driver stack. */
103 bool fDoMixing;
104 /** Mixer buffer. */
105 AUDIOMIXBUF MixBuf;
106 /** Write state. */
107 AUDIOMIXBUFWRITESTATE WriteState;
108 /** Peek state. */
109 AUDIOMIXBUFPEEKSTATE PeekState;
110} AUDIOTESTDRVMIXSTREAM;
111/** Pointer to mixer setup for a stream. */
112typedef AUDIOTESTDRVMIXSTREAM *PAUDIOTESTDRVMIXSTREAM;
113
114/**
115 * Enumeration specifying the current audio test mode.
116 */
117typedef enum AUDIOTESTMODE
118{
119 /** Unknown mode. */
120 AUDIOTESTMODE_UNKNOWN = 0,
121 /** VKAT is running on the guest side. */
122 AUDIOTESTMODE_GUEST,
123 /** VKAT is running on the host side. */
124 AUDIOTESTMODE_HOST
125} AUDIOTESTMODE;
126
127struct AUDIOTESTENV;
128/** Pointer a audio test environment. */
129typedef AUDIOTESTENV *PAUDIOTESTENV;
130
131struct AUDIOTESTDESC;
132/** Pointer a audio test descriptor. */
133typedef AUDIOTESTDESC *PAUDIOTESTDESC;
134
135/**
136 * Callback to set up the test parameters for a specific test.
137 *
138 * @returns IPRT status code.
139 * @retval VINF_SUCCESS if setting the parameters up succeeded. Any other error code
140 * otherwise indicating the kind of error.
141 * @param pszTest Test name.
142 * @param pTstParmsAcq The audio test parameters to set up.
143 */
144typedef DECLCALLBACKTYPE(int, FNAUDIOTESTSETUP,(PAUDIOTESTENV pTstEnv, PAUDIOTESTDESC pTstDesc, PAUDIOTESTPARMS pTstParmsAcq, void **ppvCtx));
145/** Pointer to an audio test setup callback. */
146typedef FNAUDIOTESTSETUP *PFNAUDIOTESTSETUP;
147
148typedef DECLCALLBACKTYPE(int, FNAUDIOTESTEXEC,(PAUDIOTESTENV pTstEnv, void *pvCtx, PAUDIOTESTPARMS pTstParms));
149/** Pointer to an audio test exec callback. */
150typedef FNAUDIOTESTEXEC *PFNAUDIOTESTEXEC;
151
152typedef DECLCALLBACKTYPE(int, FNAUDIOTESTDESTROY,(PAUDIOTESTENV pTstEnv, void *pvCtx));
153/** Pointer to an audio test destroy callback. */
154typedef FNAUDIOTESTDESTROY *PFNAUDIOTESTDESTROY;
155
156/**
157 * Structure for keeping an audio test audio stream.
158 */
159typedef struct AUDIOTESTSTREAM
160{
161 /** The PDM stream. */
162 PPDMAUDIOSTREAM pStream;
163 /** The backend stream. */
164 PPDMAUDIOBACKENDSTREAM pBackend;
165 /** The stream config. */
166 PDMAUDIOSTREAMCFG Cfg;
167 /** Associated mixing stream. Optional. */
168 AUDIOTESTDRVMIXSTREAM Mix;
169} AUDIOTESTSTREAM;
170/** Pointer to audio test stream. */
171typedef AUDIOTESTSTREAM *PAUDIOTESTSTREAM;
172
173/** Maximum audio streams a test environment can handle. */
174#define AUDIOTESTENV_MAX_STREAMS 8
175
176/**
177 * Structure for keeping TCP/IP-specific options.
178 */
179typedef struct AUDIOTESTENVTCPOPTS
180{
181 /** Bind address (server mode). When empty, "0.0.0.0" (any host) will be used. */
182 char szTcpBindAddr[128];
183 /** Bind port (server mode). */
184 uint16_t uTcpBindPort;
185 /** Connection address (client mode). */
186 char szTcpConnectAddr[128];
187 /** Connection port (client mode). */
188 uint16_t uTcpConnectPort;
189} AUDIOTESTENVTCPOPTS;
190typedef AUDIOTESTENVTCPOPTS *PAUDIOTESTENVTCPOPTS;
191
192/**
193 * Audio test environment parameters.
194 * Not necessarily bound to a specific test (can be reused).
195 */
196typedef struct AUDIOTESTENV
197{
198 /** Audio testing mode. */
199 AUDIOTESTMODE enmMode;
200 /** Whether self test mode is active or not. */
201 bool fSelftest;
202 /** Whether skip the actual verification or not. */
203 bool fSkipVerify;
204 /** The PCM properties to use. */
205 PDMAUDIOPCMPROPS Props;
206 /** Name of the audio device to use.
207 * If empty the default audio device will be used. */
208 char szDev[128];
209 /** Audio volume to use (in percent).
210 * Might not be available on all systems. */
211 uint8_t uVolumePercent;
212 /** Output path for storing the test environment's final test files. */
213 char szTag[AUDIOTEST_TAG_MAX];
214 /** Output path for storing the test environment's final test files. */
215 char szPathOut[RTPATH_MAX];
216 /** Temporary path for this test environment. */
217 char szPathTemp[RTPATH_MAX];
218 /** Buffer size (in ms). */
219 RTMSINTERVAL cMsBufferSize;
220 /** Pre-buffering time (in ms). */
221 RTMSINTERVAL cMsPreBuffer;
222 /** Scheduling hint (in ms). */
223 RTMSINTERVAL cMsSchedulingHint;
224 /** The audio test driver stack. */
225 AUDIOTESTDRVSTACK DrvStack;
226 /** The current (last) audio device enumeration to use. */
227 PDMAUDIOHOSTENUM DevEnum;
228 /** Audio stream. */
229 AUDIOTESTSTREAM aStreams[AUDIOTESTENV_MAX_STREAMS];
230 /** The audio test set to use. */
231 AUDIOTESTSET Set;
232 union
233 {
234 struct
235 {
236 AUDIOTESTENVTCPOPTS TcpOpts;
237 /** ATS instance to use. */
238 ATSSERVER Srv;
239 } Guest;
240 struct
241 {
242 AUDIOTESTENVTCPOPTS TcpOpts;
243 /** ATS instance to use. */
244 ATSSERVER Srv;
245 /** Client connected to the ATS on the guest side. */
246 ATSCLIENT AtsClGuest;
247 /** Path to the guest's test set downloaded to the host. */
248 char szPathTestSetGuest[RTPATH_MAX];
249 /** Client connected to the Validation Kit audio driver ATS. */
250 ATSCLIENT AtsClValKit;
251 /** Path to the Validation Kit audio driver's test set downloaded to the host. */
252 char szPathTestSetValKit[RTPATH_MAX];
253 } Host;
254 } u;
255 AUDIOTESTENVTCPOPTS ValKitTcpOpts;
256} AUDIOTESTENV;
257
258/**
259 * Audio test descriptor.
260 */
261typedef struct AUDIOTESTDESC
262{
263 /** (Sort of) Descriptive test name. */
264 const char *pszName;
265 /** Flag whether the test is excluded. */
266 bool fExcluded;
267 /** The setup callback. */
268 PFNAUDIOTESTSETUP pfnSetup;
269 /** The exec callback. */
270 PFNAUDIOTESTEXEC pfnExec;
271 /** The destruction callback. */
272 PFNAUDIOTESTDESTROY pfnDestroy;
273} AUDIOTESTDESC;
274
275/**
276 * Structure for keeping a VKAT self test context.
277 */
278typedef struct SELFTESTCTX
279{
280 /** Common tag for guest and host side. */
281 char szTag[AUDIOTEST_TAG_MAX];
282 /** Whether to use DrvAudio in the driver stack or not. */
283 bool fWithDrvAudio;
284 struct
285 {
286 AUDIOTESTENV TstEnv;
287 /** Audio driver to use.
288 * Defaults to the platform's default driver. */
289 PCPDMDRVREG pDrvReg;
290 /** Where to bind the address of the guest ATS instance to.
291 * Defaults to localhost (127.0.0.1) if empty. */
292 char szAtsAddr[64];
293 /** Port of the guest ATS instance.
294 * Defaults to ATS_ALT_PORT if not set. */
295 uint32_t uAtsPort;
296 } Guest;
297 struct
298 {
299 AUDIOTESTENV TstEnv;
300 /** Address of the guest ATS instance.
301 * Defaults to localhost (127.0.0.1) if not set. */
302 char szGuestAtsAddr[64];
303 /** Port of the guest ATS instance.
304 * Defaults to ATS_DEFAULT_PORT if not set. */
305 uint32_t uGuestAtsPort;
306 /** Address of the Validation Kit audio driver ATS instance.
307 * Defaults to localhost (127.0.0.1) if not set. */
308 char szValKitAtsAddr[64];
309 /** Port of the Validation Kit audio driver ATS instance.
310 * Defaults to ATS_ALT_PORT if not set. */
311 uint32_t uValKitAtsPort;
312 } Host;
313} SELFTESTCTX;
314/** Pointer to a VKAT self test context. */
315typedef SELFTESTCTX *PSELFTESTCTX;
316
317/**
318 * VKAT command table entry.
319 */
320typedef struct VKATCMD
321{
322 /** The command name. */
323 const char *pszCommand;
324 /** The command handler. */
325 DECLCALLBACKMEMBER(RTEXITCODE, pfnHandler,(PRTGETOPTSTATE pGetState));
326
327 /** Command description. */
328 const char *pszDesc;
329 /** Options array. */
330 PCRTGETOPTDEF paOptions;
331 /** Number of options in the option array. */
332 size_t cOptions;
333 /** Gets help for an option. */
334 DECLCALLBACKMEMBER(const char *, pfnOptionHelp,(PCRTGETOPTDEF pOpt));
335 /** Flag indicating if the command needs the ATS transport layer.
336 * Needed for command line parsing. */
337 bool fNeedsTransport;
338} VKATCMD;
339/** Pointer to a const VKAT command entry. */
340typedef VKATCMD const *PCVKATCMD;
341
342
343/*********************************************************************************************************************************
344* Global Variables *
345*********************************************************************************************************************************/
346/** Terminate ASAP if set. Set on Ctrl-C. */
347extern bool volatile g_fTerminate;
348/** The release logger. */
349extern PRTLOGGER g_pRelLogger;
350
351/** The test handle. */
352extern RTTEST g_hTest;
353extern unsigned g_uVerbosity;
354extern bool g_fDrvAudioDebug;
355extern const char *g_pszDrvAudioDebug;
356
357/** The test handle. */
358extern RTTEST g_hTest;
359/** The current verbosity level. */
360extern unsigned g_uVerbosity;
361/** DrvAudio: Enable debug (or not). */
362extern bool g_fDrvAudioDebug;
363/** DrvAudio: The debug output path. */
364extern const char *g_pszDrvAudioDebug;
365
366extern const VKATCMD g_CmdEnum;
367extern const VKATCMD g_CmdPlay;
368extern const VKATCMD g_CmdRec;
369extern const VKATCMD g_CmdSelfTest;
370
371extern AUDIOTESTDESC g_aTests[];
372extern unsigned g_cTests;
373
374
375/*********************************************************************************************************************************
376* Prototypes *
377*********************************************************************************************************************************/
378
379/** @name Command line handlers
380 * @{ */
381RTEXITCODE audioTestUsage(PRTSTREAM pStrm);
382RTEXITCODE audioTestVersion(void);
383void audioTestShowLogo(PRTSTREAM pStream);
384/** @} */
385
386/** @name Driver stack
387 * @{ */
388void audioTestDriverStackDelete(PAUDIOTESTDRVSTACK pDrvStack);
389int audioTestDriverStackInitEx(PAUDIOTESTDRVSTACK pDrvStack, PCPDMDRVREG pDrvReg, bool fEnabledIn, bool fEnabledOut, bool fWithDrvAudio);
390int audioTestDriverStackInit(PAUDIOTESTDRVSTACK pDrvStack, PCPDMDRVREG pDrvReg, bool fWithDrvAudio);
391int audioTestDriverStackSetDevice(PAUDIOTESTDRVSTACK pDrvStack, PDMAUDIODIR enmDir, const char *pszDevId);
392/** @} */
393
394/** @name Driver
395 * @{ */
396int audioTestDrvConstruct(PAUDIOTESTDRVSTACK pDrvStack, PCPDMDRVREG pDrvReg, PPDMDRVINS pParentDrvIns, PPPDMDRVINS ppDrvIns);
397/** @} */
398
399/** @name Driver stack stream
400 * @{ */
401int audioTestDriverStackStreamCreateInput(PAUDIOTESTDRVSTACK pDrvStack, PCPDMAUDIOPCMPROPS pProps,
402 uint32_t cMsBufferSize, uint32_t cMsPreBuffer, uint32_t cMsSchedulingHint,
403 PPDMAUDIOSTREAM *ppStream, PPDMAUDIOSTREAMCFG pCfgAcq);
404int audioTestDriverStackStreamCreateOutput(PAUDIOTESTDRVSTACK pDrvStack, PCPDMAUDIOPCMPROPS pProps,
405 uint32_t cMsBufferSize, uint32_t cMsPreBuffer, uint32_t cMsSchedulingHint,
406 PPDMAUDIOSTREAM *ppStream, PPDMAUDIOSTREAMCFG pCfgAcq);
407void audioTestDriverStackStreamDestroy(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream);
408int audioTestDriverStackStreamDrain(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream, bool fSync);
409int audioTestDriverStackStreamEnable(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream);
410int AudioTestDriverStackStreamDisable(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream);
411bool audioTestDriverStackStreamIsOkay(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream);
412uint32_t audioTestDriverStackStreamGetWritable(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream);
413int audioTestDriverStackStreamPlay(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream, void const *pvBuf,
414 uint32_t cbBuf, uint32_t *pcbPlayed);
415uint32_t audioTestDriverStackStreamGetReadable(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream);
416int audioTestDriverStackStreamCapture(PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream,
417 void *pvBuf, uint32_t cbBuf, uint32_t *pcbCaptured);
418/** @} */
419
420/** @name Backend handling
421 * @{ */
422PCPDMDRVREG AudioTestGetDefaultBackend(void);
423PCPDMDRVREG AudioTestFindBackendOpt(const char *pszBackend);
424/** @} */
425
426/** @name Mixing stream
427 * @{ */
428int AudioTestMixStreamInit(PAUDIOTESTDRVMIXSTREAM pMix, PAUDIOTESTDRVSTACK pDrvStack, PPDMAUDIOSTREAM pStream,
429 PCPDMAUDIOPCMPROPS pProps, uint32_t cMsBuffer);
430void AudioTestMixStreamTerm(PAUDIOTESTDRVMIXSTREAM pMix);
431int AudioTestMixStreamEnable(PAUDIOTESTDRVMIXSTREAM pMix);
432int AudioTestMixStreamDrain(PAUDIOTESTDRVMIXSTREAM pMix, bool fSync);
433int AudioTestMixStreamDisable(PAUDIOTESTDRVMIXSTREAM pMix);
434bool AudioTestMixStreamIsOkay(PAUDIOTESTDRVMIXSTREAM pMix);
435uint32_t AudioTestMixStreamGetWritable(PAUDIOTESTDRVMIXSTREAM pMix);
436int AudioTestMixStreamPlay(PAUDIOTESTDRVMIXSTREAM pMix, void const *pvBuf, uint32_t cbBuf, uint32_t *pcbPlayed);
437uint32_t AudioTestMixStreamGetReadable(PAUDIOTESTDRVMIXSTREAM pMix);
438int AudioTestMixStreamCapture(PAUDIOTESTDRVMIXSTREAM pMix, void *pvBuf, uint32_t cbBuf, uint32_t *pcbCaptured);
439/** @} */
440
441/** @name Device handling
442 * @{ */
443int audioTestDeviceOpen(PPDMAUDIOHOSTDEV pDev);
444int audioTestDeviceClose(PPDMAUDIOHOSTDEV pDev);
445/** @} */
446
447/** @name ATS routines
448 * @{ */
449int audioTestEnvConnectToValKitAts(PAUDIOTESTENV pTstEnv,
450 const char *pszHostTcpAddr, uint32_t uHostTcpPort);
451/** @} */
452
453/** @name Test environment handling
454 * @{ */
455int audioTestEnvInit(PAUDIOTESTENV pTstEnv, PCPDMDRVREG pDrvReg, bool fWithDrvAudio);
456void audioTestEnvDestroy(PAUDIOTESTENV pTstEnv);
457int audioTestEnvPrologue(PAUDIOTESTENV pTstEnv, bool fPack, char *pszPackFile, size_t cbPackFile);
458
459void audioTestParmsInit(PAUDIOTESTPARMS pTstParms);
460void audioTestParmsDestroy(PAUDIOTESTPARMS pTstParms);
461/** @} */
462
463int audioTestWorker(PAUDIOTESTENV pTstEnv);
464
465/** @name Command handlers
466 * @{ */
467RTEXITCODE audioTestDoSelftest(PSELFTESTCTX pCtx);
468/** @} */
469
470
471/*********************************************************************************************************************************
472* Common command line stuff *
473*********************************************************************************************************************************/
474
475/**
476 * Common long options values.
477 */
478enum
479{
480 AUDIO_TEST_OPT_CMN_DAEMONIZE = 256,
481 AUDIO_TEST_OPT_CMN_DAEMONIZED,
482 AUDIO_TEST_OPT_CMN_DEBUG_AUDIO_ENABLE,
483 AUDIO_TEST_OPT_CMN_DEBUG_AUDIO_PATH
484};
485
486/** For use in the option switch to handle common options. */
487#define AUDIO_TEST_COMMON_OPTION_CASES(a_ValueUnion) \
488 case 'q': \
489 g_uVerbosity = 0; \
490 if (g_pRelLogger) \
491 RTLogGroupSettings(g_pRelLogger, "all=0 all.e"); \
492 break; \
493 \
494 case 'v': \
495 g_uVerbosity++; \
496 if (g_pRelLogger) \
497 RTLogGroupSettings(g_pRelLogger, g_uVerbosity == 1 ? "all.e.l" : g_uVerbosity == 2 ? "all.e.l.f" : "all=~0"); \
498 break; \
499 \
500 case 'V': \
501 return audioTestVersion(); \
502 \
503 case 'h': \
504 audioTestShowLogo(g_pStdOut); \
505 return audioTestUsage(g_pStdOut); \
506 \
507 case AUDIO_TEST_OPT_CMN_DEBUG_AUDIO_ENABLE: \
508 g_fDrvAudioDebug = true; \
509 break; \
510 \
511 case AUDIO_TEST_OPT_CMN_DEBUG_AUDIO_PATH: \
512 g_pszDrvAudioDebug = (a_ValueUnion).psz; \
513 break; \
514 case AUDIO_TEST_OPT_CMN_DAEMONIZE: \
515 break; \
516 case AUDIO_TEST_OPT_CMN_DAEMONIZED: \
517 break;
518
519#endif /* !VBOX_INCLUDED_SRC_audio_vkatInternal_h */
520
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