pdmaudioifs.h@ 87450

Last change on this file since 87450 was 87170, checked in by vboxsync, 4 years ago
pdmaudioifs.h: Use doxygen better. bugref:9882
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 70.5 KB

Line
1	/** @file
2	* PDM - Pluggable Device Manager, Audio interfaces.
3	*/
4
5	/*
6	* Copyright (C) 2006-2020 Oracle Corporation
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	/** @page pg_pdm_audio PDM Audio
27	*
28	* @section sec_pdm_audio_overview Audio architecture overview
29	*
30	* The audio architecture mainly consists of two PDM interfaces,
31	* PDMIAUDIOCONNECTOR and PDMIHOSTAUDIO.
32	*
33	* The PDMIAUDIOCONNECTOR interface is responsible of connecting a device
34	* emulation, such as SB16, AC'97 and HDA to one or multiple audio backend(s).
35	* Its API abstracts audio stream handling and I/O functions, device enumeration
36	* and so on.
37	*
38	* The PDMIHOSTAUDIO interface must be implemented by all audio backends to
39	* provide an abstract and common way of accessing needed functions, such as
40	* transferring output audio data for playing audio or recording input from the
41	* host.
42	*
43	* A device emulation can have one or more LUNs attached to it, whereas these
44	* LUNs in turn then all have their own PDMIAUDIOCONNECTOR, making it possible
45	* to connect multiple backends to a certain device emulation stream
46	* (multiplexing).
47	*
48	* An audio backend's job is to record and/or play audio data (depending on its
49	* capabilities). It highly depends on the host it's running on and needs very
50	* specific (host-OS-dependent) code. The backend itself only has very limited
51	* ways of accessing and/or communicating with the PDMIAUDIOCONNECTOR interface
52	* via callbacks, but never directly with the device emulation or other parts of
53	* the audio sub system.
54	*
55	*
56	* @section sec_pdm_audio_mixing Mixing
57	*
58	* The AUDIOMIXER API is optionally available to create and manage virtual audio
59	* mixers. Such an audio mixer in turn then can be used by the device emulation
60	* code to manage all the multiplexing to/from the connected LUN audio streams.
61	*
62	* Currently only input and output stream are supported. Duplex stream are not
63	* supported yet.
64	*
65	* This also is handy if certain LUN audio streams should be added or removed
66	* during runtime.
67	*
68	* To create a group of either input or output streams the AUDMIXSINK API can be
69	* used.
70	*
71	* For example: The device emulation has one hardware output stream (HW0), and
72	* that output stream shall be available to all connected LUN backends. For that
73	* to happen, an AUDMIXSINK sink has to be created and attached to the device's
74	* AUDIOMIXER object.
75	*
76	* As every LUN has its own AUDMIXSTREAM object, adding all those
77	* objects to the just created audio mixer sink will do the job.
78	*
79	* @note The AUDIOMIXER API is purely optional and is not used by all currently
80	* implemented device emulations (e.g. SB16).
81	*
82	*
83	* @section sec_pdm_audio_data_processing Data processing
84	*
85	* Audio input / output data gets handed off to/from the device emulation in an
86	* unmodified (raw) way. The actual audio frame / sample conversion is done via
87	* the PDMAUDIOMIXBUF API.
88	*
89	* This concentrates the audio data processing in one place and makes it easier
90	* to test / benchmark such code.
91	*
92	* A PDMAUDIOFRAME is the internal representation of a single audio frame, which
93	* consists of a single left and right audio sample in time. Only mono (1) and
94	* stereo (2) channel(s) currently are supported.
95	*
96	*
97	* @section sec_pdm_audio_timing Timing
98	*
99	* Handling audio data in a virtual environment is hard, as the human perception
100	* is very sensitive to the slightest cracks and stutters in the audible data.
101	* This can happen if the VM's timing is lagging behind or not within the
102	* expected time frame.
103	*
104	* The two main components which unfortunately contradict each other is a) the
105	* audio device emulation and b) the audio backend(s) on the host. Those need to
106	* be served in a timely manner to function correctly. To make e.g. the device
107	* emulation rely on the pace the host backend(s) set - or vice versa - will not
108	* work, as the guest's audio system / drivers then will not be able to
109	* compensate this accordingly.
110	*
111	* So each component, the device emulation, the audio connector(s) and the
112	* backend(s) must do its thing when it needs to do it, independently of the
113	* others. For that we use various (small) ring buffers to (hopefully) serve all
114	* components with the amount of data when they need it.
115	*
116	* Additionally, the device emulation can run with a different audio frame size,
117	* while the backends(s) may require a different frame size (16 bit stereo
118	* -> 8 bit mono, for example).
119	*
120	* The device emulation can give the audio connector(s) a scheduling hint
121	* (optional), e.g. in which interval it expects any data processing.
122	*
123	* A data transfer for playing audio data from the guest on the host looks like
124	* this: (RB = Ring Buffer, MB = Mixing Buffer)
125	*
126	* (A) Device DMA -> (B) Device RB -> (C) Audio Connector %Guest MB -> (D) Audio
127	* Connector %Host MB -> (E) Backend RB (optional, up to the backend) -> (F)
128	* Backend audio framework.
129	*
130	* When capturing audio data the chain is similar to the above one, just in a
131	* different direction, of course.
132	*
133	* The audio connector hereby plays a key role when it comes to (pre-)buffering
134	* data to minimize any audio stutters and/or cracks. The following values,
135	* which also can be tweaked via CFGM / extra-data are available:
136	*
137	* - The pre-buffering time (in ms): Audio data which needs to be buffered
138	* before any playback (or capturing) can happen.
139	* - The actual buffer size (in ms): How big the mixing buffer (for C and D)
140	* will be.
141	* - The period size (in ms): How big a chunk of audio (often called period or
142	* fragment) for F must be to get handled correctly.
143	*
144	* The above values can be set on a per-driver level, whereas input and output
145	* streams for a driver also can be handled set independently. The verbose audio
146	* (release) log will tell about the (final) state of each audio stream.
147	*
148	*
149	* @section sec_pdm_audio_diagram Diagram
150	*
151	* @todo r=bird: Not quite able to make sense of this, esp. the
152	* AUDMIXSINK/AUDIOMIXER bits crossing the LUN connections.
153	*
154	* @verbatim
155	+----------------------------------+
156	\|Device (SB16 / AC'97 / HDA) \|
157	\|----------------------------------\|
158	\|AUDIOMIXER (Optional) \|
159	\|AUDMIXSINK0 (Optional) \|
160	\|AUDMIXSINK1 (Optional) \|
161	\|AUDMIXSINKn (Optional) \|
162	\| \|
163	\| L L L \|
164	\| U U U \|
165	\| N N N \|
166	\| 0 1 n \|
167	+-----+----+----+------------------+
168	\| \| \|
169	\| \| \|
170	+--------------+ \| \| \| +-------------+
171	\|AUDMIXSINK \| \| \| \| \|AUDIOMIXER \|
172	\|--------------\| \| \| \| \|-------------\|
173	\|AUDMIXSTREAM0 \|+-\|----\|----\|-->\|AUDMIXSINK0 \|
174	\|AUDMIXSTREAM1 \|+-\|----\|----\|-->\|AUDMIXSINK1 \|
175	\|AUDMIXSTREAMn \|+-\|----\|----\|-->\|AUDMIXSINKn \|
176	+--------------+ \| \| \| +-------------+
177	\| \| \|
178	\| \| \|
179	+----+----+----+----+
180	\|LUN \|
181	\|-------------------\|
182	\|PDMIAUDIOCONNECTOR \|
183	\|AUDMIXSTREAM \|
184	\| +------+
185	\| \| \|
186	\| \| \|
187	\| \| \|
188	+-------------------+ \|
189	\|
190	+-------------------------+ \|
191	+-------------------------+ +----+--------------------+
192	\|PDMAUDIOSTREAM \| \|PDMIAUDIOCONNECTOR \|
193	\|-------------------------\| \|-------------------------\|
194	\|PDMAUDIOMIXBUF \|+------>\|PDMAUDIOSTREAM Host \|
195	\|PDMAUDIOSTREAMCFG \|+------>\|PDMAUDIOSTREAM Guest \|
196	\| \| \|Device capabilities \|
197	\| \| \|Device configuration \|
198	\| \| \| \|
199	\| \| +--+\|PDMIHOSTAUDIO \|
200	\| \| \| \|+-----------------------+\|
201	+-------------------------+ \| \|\|Backend storage space \|\|
202	\| \|+-----------------------+\|
203	\| +-------------------------+
204	\|
205	+---------------------+ \|
206	\|PDMIHOSTAUDIO \| \|
207	\|+--------------+ \| \|
208	\|\|DirectSound \| \| \|
209	\|+--------------+ \| \|
210	\| \| \|
211	\|+--------------+ \| \|
212	\|\|PulseAudio \| \| \|
213	\|+--------------+ \|+-------+
214	\| \|
215	\|+--------------+ \|
216	\|\|Core Audio \| \|
217	\|+--------------+ \|
218	\| \|
219	\| \|
220	\| \|
221	\| \|
222	+---------------------+
223	@endverbatim
224	*/
225
226	#ifndef VBOX_INCLUDED_vmm_pdmaudioifs_h
227	#define VBOX_INCLUDED_vmm_pdmaudioifs_h
228	#ifndef RT_WITHOUT_PRAGMA_ONCE
229	# pragma once
230	#endif
231
232	#include <iprt/assertcompile.h>
233	#include <iprt/circbuf.h>
234	#include <iprt/list.h>
235	#include <iprt/path.h>
236
237	#include <VBox/types.h>
238	#ifdef VBOX_WITH_STATISTICS
239	# include <VBox/vmm/stam.h>
240	#endif
241
242	/** @defgroup grp_pdm_ifs_audio PDM Audio Interfaces
243	* @ingroup grp_pdm_interfaces
244	* @{
245	*/
246
247	#ifndef VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH
248	# if defined(RT_OS_WINDOWS) \|\| defined(RT_OS_OS2)
249	# define VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "c:\\temp\\"
250	# else
251	# define VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "/tmp/"
252	# endif
253	#endif
254
255	/** PDM audio driver instance flags. */
256	typedef uint32_t PDMAUDIODRVFLAGS;
257
258	/** No flags set. */
259	#define PDMAUDIODRVFLAGS_NONE 0
260	/** Marks a primary audio driver which is critical
261	* when running the VM. */
262	#define PDMAUDIODRVFLAGS_PRIMARY RT_BIT(0)
263
264	/**
265	* Audio format in signed or unsigned variants.
266	*/
267	typedef enum PDMAUDIOFMT
268	{
269	/** Invalid format, do not use. */
270	PDMAUDIOFMT_INVALID = 0,
271	/** 8-bit, unsigned. */
272	PDMAUDIOFMT_U8,
273	/** 8-bit, signed. */
274	PDMAUDIOFMT_S8,
275	/** 16-bit, unsigned. */
276	PDMAUDIOFMT_U16,
277	/** 16-bit, signed. */
278	PDMAUDIOFMT_S16,
279	/** 32-bit, unsigned. */
280	PDMAUDIOFMT_U32,
281	/** 32-bit, signed. */
282	PDMAUDIOFMT_S32,
283	/** Hack to blow the type up to 32-bit. */
284	PDMAUDIOFMT_32BIT_HACK = 0x7fffffff
285	} PDMAUDIOFMT;
286
287	/**
288	* Audio direction.
289	*/
290	typedef enum PDMAUDIODIR
291	{
292	/** Invalid zero value as per usual (guards against using unintialized values). */
293	PDMAUDIODIR_INVALID = 0,
294	/** Unknown direction. */
295	PDMAUDIODIR_UNKNOWN,
296	/** Input. */
297	PDMAUDIODIR_IN,
298	/** Output. */
299	PDMAUDIODIR_OUT,
300	/** Duplex handling. */
301	PDMAUDIODIR_ANY,
302	/** Hack to blow the type up to 32-bit. */
303	PDMAUDIODIR_32BIT_HACK = 0x7fffffff
304	} PDMAUDIODIR;
305
306	/** Device latency spec in milliseconds (ms). */
307	typedef uint32_t PDMAUDIODEVLATSPECMS;
308
309	/** Device latency spec in seconds (s). */
310	typedef uint32_t PDMAUDIODEVLATSPECSEC;
311
312	/** @name PDMAUDIODEV_FLAGS_XXX
313	* @{ */
314	/** No flags set. */
315	#define PDMAUDIODEV_FLAGS_NONE UINT32_C(0)
316	/** The device marks the default device within the host OS. */
317	#define PDMAUDIODEV_FLAGS_DEFAULT RT_BIT_32(0)
318	/** The device can be removed at any time and we have to deal with it. */
319	#define PDMAUDIODEV_FLAGS_HOTPLUG RT_BIT_32(1)
320	/** The device is known to be buggy and needs special treatment. */
321	#define PDMAUDIODEV_FLAGS_BUGGY RT_BIT_32(2)
322	/** Ignore the device, no matter what. */
323	#define PDMAUDIODEV_FLAGS_IGNORE RT_BIT_32(3)
324	/** The device is present but marked as locked by some other application. */
325	#define PDMAUDIODEV_FLAGS_LOCKED RT_BIT_32(4)
326	/** The device is present but not in an alive state (dead). */
327	#define PDMAUDIODEV_FLAGS_DEAD RT_BIT_32(5)
328	/** @} */
329
330	/**
331	* Audio device type.
332	*/
333	typedef enum PDMAUDIODEVICETYPE
334	{
335	/** Invalid zero value as per usual (guards against using unintialized values). */
336	PDMAUDIODEVICETYPE_INVALID = 0,
337	/** Unknown device type. This is the default. */
338	PDMAUDIODEVICETYPE_UNKNOWN,
339	/** Dummy device; for backends which are not able to report
340	* actual device information (yet). */
341	PDMAUDIODEVICETYPE_DUMMY,
342	/** The device is built into the host (non-removable). */
343	PDMAUDIODEVICETYPE_BUILTIN,
344	/** The device is an (external) USB device. */
345	PDMAUDIODEVICETYPE_USB,
346	/** Hack to blow the type up to 32-bit. */
347	PDMAUDIODEVICETYPE_32BIT_HACK = 0x7fffffff
348	} PDMAUDIODEVICETYPE;
349
350	/**
351	* Audio device info (enumeration result).
352	* @sa PDMAUDIODEVICEENUM, PDMIHOSTAUDIO::pfnGetDevices
353	*/
354	typedef struct PDMAUDIODEVICE
355	{
356	/** List node. */
357	RTLISTNODE Node;
358	/** Additional data which might be relevant for the current context.
359	* @todo r=bird: I would do this C++ style, having the host specific bits
360	* appended after this structure and downcast. */
361	void *pvData;
362	/** Size of the additional data. */
363	size_t cbData;
364	/** The device type. */
365	PDMAUDIODEVICETYPE enmType;
366	/** Usage of the device. */
367	PDMAUDIODIR enmUsage;
368	/** Device flags, PDMAUDIODEV_FLAGS_XXX. */
369	uint32_t fFlags;
370	/** Reference count indicating how many audio streams currently are relying on this device. */
371	uint8_t cRefCount;
372	/** Maximum number of input audio channels the device supports. */
373	uint8_t cMaxInputChannels;
374	/** Maximum number of output audio channels the device supports. */
375	uint8_t cMaxOutputChannels;
376	/** Device type union, based on enmType. */
377	union
378	{
379	/** USB type specifics. */
380	struct
381	{
382	/** Vendor ID.
383	* @todo r=bird: Why signed?? VUSB uses uint16_t for idVendor and idProduct! */
384	int16_t VID;
385	/** Product ID. */
386	int16_t PID;
387	} USB;
388	} Type;
389	/** Friendly name of the device, if any. */
390	char szName[64];
391	} PDMAUDIODEVICE;
392	/** Pointer to audio device info (enum result). */
393	typedef PDMAUDIODEVICE *PPDMAUDIODEVICE;
394
395	/**
396	* An audio device enumeration result.
397	* @sa PDMIHOSTAUDIO::pfnGetDevices
398	*/
399	typedef struct PDMAUDIODEVICEENUM
400	{
401	/** Number of audio devices in the list. */
402	uint16_t cDevices;
403	/** List of audio devices. */
404	RTLISTANCHOR lstDevices;
405	} PDMAUDIODEVICEENUM;
406	/** Pointer to an audio device enumeration result. */
407	typedef PDMAUDIODEVICEENUM *PPDMAUDIODEVICEENUM;
408
409	/**
410	* Audio configuration (static) of an audio host backend.
411	*/
412	typedef struct PDMAUDIOBACKENDCFG
413	{
414	/** The backend's friendly name. */
415	char szName[32];
416	/** Size (in bytes) of the host backend's audio output stream structure. */
417	size_t cbStreamOut;
418	/** Size (in bytes) of the host backend's audio input stream structure. */
419	size_t cbStreamIn;
420	/** Number of concurrent output (playback) streams supported on the host.
421	* UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
422	uint32_t cMaxStreamsOut;
423	/** Number of concurrent input (recording) streams supported on the host.
424	* UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
425	uint32_t cMaxStreamsIn;
426	} PDMAUDIOBACKENDCFG;
427	/** Pointer to a static host audio audio configuration. */
428	typedef PDMAUDIOBACKENDCFG *PPDMAUDIOBACKENDCFG;
429
430	/**
431	* A single audio frame.
432	*
433	* Currently only two (2) channels, left and right, are supported.
434	*
435	* @note When changing this structure, make sure to also handle
436	* VRDP's input / output processing in DrvAudioVRDE, as VRDP
437	* expects audio data in st_sample_t format (historical reasons)
438	* which happens to be the same as PDMAUDIOFRAME for now.
439	*/
440	typedef struct PDMAUDIOFRAME
441	{
442	/** Left channel. */
443	int64_t i64LSample;
444	/** Right channel. */
445	int64_t i64RSample;
446	} PDMAUDIOFRAME;
447	/** Pointer to a single (stereo) audio frame. */
448	typedef PDMAUDIOFRAME *PPDMAUDIOFRAME;
449	/** Pointer to a const single (stereo) audio frame. */
450	typedef PDMAUDIOFRAME const *PCPDMAUDIOFRAME;
451
452	typedef enum PDMAUDIOENDIANNESS
453	{
454	/** The usual invalid value. */
455	PDMAUDIOENDIANNESS_INVALID = 0,
456	/** Little endian. */
457	PDMAUDIOENDIANNESS_LITTLE,
458	/** Bit endian. */
459	PDMAUDIOENDIANNESS_BIG,
460	/** Endianness doesn't have a meaning in the context. */
461	PDMAUDIOENDIANNESS_NA,
462	/** The end of the valid endian values (exclusive). */
463	PDMAUDIOENDIANNESS_END,
464	/** Hack to blow the type up to 32-bit. */
465	PDMAUDIOENDIANNESS_32BIT_HACK = 0x7fffffff
466	} PDMAUDIOENDIANNESS;
467
468	/** @def PDMAUDIOHOSTENDIANNESS
469	* The PDMAUDIOENDIANNESS value for the host. */
470	#if defined(RT_LITTLE_ENDIAN)
471	# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_LITTLE
472	#elif defined(RT_BIG_ENDIAN)
473	# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_BIG
474	#else
475	# error "Port me!"
476	#endif
477
478	/**
479	* Audio playback destinations.
480	*/
481	typedef enum PDMAUDIOPLAYBACKDST
482	{
483	/** Invalid zero value as per usual (guards against using unintialized values). */
484	PDMAUDIOPLAYBACKDST_INVALID = 0,
485	/** Unknown destination. */
486	PDMAUDIOPLAYBACKDST_UNKNOWN,
487	/** Front channel. */
488	PDMAUDIOPLAYBACKDST_FRONT,
489	/** Center / LFE (Subwoofer) channel. */
490	PDMAUDIOPLAYBACKDST_CENTER_LFE,
491	/** Rear channel. */
492	PDMAUDIOPLAYBACKDST_REAR,
493	/** Hack to blow the type up to 32-bit. */
494	PDMAUDIOPLAYBACKDST_32BIT_HACK = 0x7fffffff
495	} PDMAUDIOPLAYBACKDST;
496
497	/**
498	* Audio recording sources.
499	*
500	* @note Because this is almost exclusively used in PDMAUDIODSTSRCUNION where it
501	* overlaps with PDMAUDIOPLAYBACKDST, the values starts at 64 instead of 0.
502	*/
503	typedef enum PDMAUDIORECSRC
504	{
505	/** Unknown recording source. */
506	PDMAUDIORECSRC_UNKNOWN = 64,
507	/** Microphone-In. */
508	PDMAUDIORECSRC_MIC,
509	/** CD. */
510	PDMAUDIORECSRC_CD,
511	/** Video-In. */
512	PDMAUDIORECSRC_VIDEO,
513	/** AUX. */
514	PDMAUDIORECSRC_AUX,
515	/** Line-In. */
516	PDMAUDIORECSRC_LINE,
517	/** Phone-In. */
518	PDMAUDIORECSRC_PHONE,
519	/** Hack to blow the type up to 32-bit. */
520	PDMAUDIORECSRC_32BIT_HACK = 0x7fffffff
521	} PDMAUDIORECSRC;
522
523	/**
524	* Union for keeping an audio stream destination or source.
525	*/
526	typedef union PDMAUDIODSTSRCUNION
527	{
528	/** Desired playback destination (for an output stream). */
529	PDMAUDIOPLAYBACKDST enmDst;
530	/** Desired recording source (for an input stream). */
531	PDMAUDIORECSRC enmSrc;
532	} PDMAUDIODSTSRCUNION;
533	/** Pointer to an audio stream src/dst union. */
534	typedef PDMAUDIODSTSRCUNION *PPDMAUDIODSTSRCUNION;
535
536	/**
537	* Audio stream (data) layout.
538	*/
539	typedef enum PDMAUDIOSTREAMLAYOUT
540	{
541	/** Invalid zero value as per usual (guards against using unintialized values). */
542	PDMAUDIOSTREAMLAYOUT_INVALID = 0,
543	/** Unknown access type; do not use (hdaR3StreamMapReset uses it). */
544	PDMAUDIOSTREAMLAYOUT_UNKNOWN,
545	/** Non-interleaved access, that is, consecutive
546	* access to the data. */
547	PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED,
548	/** Interleaved access, where the data can be
549	* mixed together with data of other audio streams. */
550	PDMAUDIOSTREAMLAYOUT_INTERLEAVED,
551	/** Complex layout, which does not fit into the
552	* interleaved / non-interleaved layouts. */
553	PDMAUDIOSTREAMLAYOUT_COMPLEX,
554	/** Raw (pass through) data, with no data layout processing done.
555	*
556	* This means that this stream will operate on PDMAUDIOFRAME data
557	* directly. Don't use this if you don't have to. */
558	PDMAUDIOSTREAMLAYOUT_RAW,
559	/** Hack to blow the type up to 32-bit. */
560	PDMAUDIOSTREAMLAYOUT_32BIT_HACK = 0x7fffffff
561	} PDMAUDIOSTREAMLAYOUT;
562
563	/**
564	* Stream channel data block.
565	*/
566	typedef struct PDMAUDIOSTREAMCHANNELDATA
567	{
568	/** Circular buffer for the channel data. */
569	PRTCIRCBUF pCircBuf;
570	/** Amount of audio data (in bytes) acquired for reading. */
571	size_t cbAcq;
572	/** Channel data flags, PDMAUDIOSTREAMCHANNELDATA_FLAGS_XXX. */
573	uint32_t fFlags;
574	} PDMAUDIOSTREAMCHANNELDATA;
575	/** Pointer to audio stream channel data buffer. */
576	typedef PDMAUDIOSTREAMCHANNELDATA *PPDMAUDIOSTREAMCHANNELDATA;
577
578	/** @name PDMAUDIOSTREAMCHANNELDATA_FLAGS_XXX
579	* @{ */
580	/** No stream channel data flags defined. */
581	#define PDMAUDIOSTREAMCHANNELDATA_FLAGS_NONE UINT32_C(0)
582	/** @} */
583
584	/**
585	* Standard speaker channel IDs.
586	*
587	* This can cover up to 11.0 surround sound.
588	*
589	* @note Any of those channels can be marked / used as the LFE channel (played
590	* through the subwoofer).
591	*/
592	typedef enum PDMAUDIOSTREAMCHANNELID
593	{
594	/** Invalid zero value as per usual (guards against using unintialized values). */
595	PDMAUDIOSTREAMCHANNELID_INVALID = 0,
596	/** Unknown / not set channel ID. */
597	PDMAUDIOSTREAMCHANNELID_UNKNOWN,
598	/** Front left channel. */
599	PDMAUDIOSTREAMCHANNELID_FRONT_LEFT,
600	/** Front right channel. */
601	PDMAUDIOSTREAMCHANNELID_FRONT_RIGHT,
602	/** Front center channel. */
603	PDMAUDIOSTREAMCHANNELID_FRONT_CENTER,
604	/** Low frequency effects (subwoofer) channel. */
605	PDMAUDIOSTREAMCHANNELID_LFE,
606	/** Rear left channel. */
607	PDMAUDIOSTREAMCHANNELID_REAR_LEFT,
608	/** Rear right channel. */
609	PDMAUDIOSTREAMCHANNELID_REAR_RIGHT,
610	/** Front left of center channel. */
611	PDMAUDIOSTREAMCHANNELID_FRONT_LEFT_OF_CENTER,
612	/** Front right of center channel. */
613	PDMAUDIOSTREAMCHANNELID_FRONT_RIGHT_OF_CENTER,
614	/** Rear center channel. */
615	PDMAUDIOSTREAMCHANNELID_REAR_CENTER,
616	/** Side left channel. */
617	PDMAUDIOSTREAMCHANNELID_SIDE_LEFT,
618	/** Side right channel. */
619	PDMAUDIOSTREAMCHANNELID_SIDE_RIGHT,
620	/** Left height channel. */
621	PDMAUDIOSTREAMCHANNELID_LEFT_HEIGHT,
622	/** Right height channel. */
623	PDMAUDIOSTREAMCHANNELID_RIGHT_HEIGHT,
624	/** Hack to blow the type up to 32-bit. */
625	PDMAUDIOSTREAMCHANNELID_32BIT_HACK = 0x7fffffff
626	} PDMAUDIOSTREAMCHANNELID;
627
628	/**
629	* Mappings channels onto an audio stream.
630	*
631	* The mappings are either for a single (mono) or dual (stereo) channels onto an
632	* audio stream (aka stream profile). An audio stream consists of one or
633	* multiple channels (e.g. 1 for mono, 2 for stereo), depending on the
634	* configuration.
635	*/
636	typedef struct PDMAUDIOSTREAMMAP
637	{
638	/** Array of channel IDs being handled.
639	* @note The first (zero-based) index specifies the leftmost channel. */
640	PDMAUDIOSTREAMCHANNELID aenmIDs[2];
641	/** Step size (in bytes) to the channel's next frame. */
642	uint32_t cbStep;
643	/** Frame size (in bytes) of this channel. */
644	uint32_t cbFrame;
645	/** Byte offset to the first frame in the data block. */
646	uint32_t offFirst;
647	/** Byte offset to the next frame in the data block. */
648	uint32_t offNext;
649	/** Associated data buffer. */
650	PDMAUDIOSTREAMCHANNELDATA Data;
651	} PDMAUDIOSTREAMMAP;
652	/** Pointer to an audio stream channel mapping. */
653	typedef PDMAUDIOSTREAMMAP *PPDMAUDIOSTREAMMAP;
654
655	/**
656	* Properties of audio streams for host/guest for in or out directions.
657	*/
658	typedef struct PDMAUDIOPCMPROPS
659	{
660	/** Sample width (in bytes). */
661	uint8_t cbSample;
662	/** Number of audio channels. */
663	uint8_t cChannels;
664	/** Shift count used with PDMAUDIOPCMPROPS_F2B and PDMAUDIOPCMPROPS_B2F.
665	* Depends on number of stream channels and the stream format being used, calc
666	* value using PDMAUDIOPCMPROPS_MAKE_SHIFT.
667	* @sa PDMAUDIOSTREAMCFG_B2F, PDMAUDIOSTREAMCFG_F2B
668	* @todo r=bird: The original brief description: "Shift count used
669	* for faster calculation of various values, such as the alignment, bytes
670	* to frames and so on." I cannot make heads or tails from that.
671	* @todo Use some RTAsmXXX functions instead? */
672	uint8_t cShift;
673	/** Signed or unsigned sample. */
674	bool fSigned : 1;
675	/** Whether the endianness is swapped or not. */
676	bool fSwapEndian : 1;
677	/** Sample frequency in Hertz (Hz). */
678	uint32_t uHz;
679	} PDMAUDIOPCMPROPS;
680	AssertCompileSize(PDMAUDIOPCMPROPS, 8);
681	AssertCompileSizeAlignment(PDMAUDIOPCMPROPS, 8);
682	/** Pointer to audio stream properties. */
683	typedef PDMAUDIOPCMPROPS *PPDMAUDIOPCMPROPS;
684
685	/** @name Macros for use with PDMAUDIOPCMPROPS
686	* @{ */
687	/** Initializor for PDMAUDIOPCMPROPS. */
688	#define PDMAUDIOPCMPROPS_INITIALIZOR(a_cBytes, a_fSigned, a_cCannels, a_uHz, a_cShift, a_fSwapEndian) \
689	{ a_cBytes, a_cCannels, a_cShift, a_fSigned, a_fSwapEndian, a_uHz }
690	/** Calculates the cShift value of given sample bits and audio channels.
691	* @note Does only support mono/stereo channels for now. */
692	#define PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS(cBytes, cChannels) ((cChannels == 2) + (cBytes / 2))
693	/** Calculates the cShift value of a PDMAUDIOPCMPROPS structure. */
694	#define PDMAUDIOPCMPROPS_MAKE_SHIFT(pProps) PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS((pProps)->cbSample, (pProps)->cChannels)
695	/** Converts (audio) frames to bytes.
696	* Needs the cShift value set correctly, using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
697	#define PDMAUDIOPCMPROPS_F2B(pProps, frames) ((frames) << (pProps)->cShift)
698	/** Converts bytes to (audio) frames.
699	* Needs the cShift value set correctly, using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
700	#define PDMAUDIOPCMPROPS_B2F(pProps, cb) ((cb) >> (pProps)->cShift)
701	/** @} */
702
703	/**
704	* An audio stream configuration.
705	*/
706	typedef struct PDMAUDIOSTREAMCFG
707	{
708	/** Direction of the stream. */
709	PDMAUDIODIR enmDir;
710	/** Destination / source indicator, depending on enmDir. */
711	PDMAUDIODSTSRCUNION u;
712	/** The stream's PCM properties. */
713	PDMAUDIOPCMPROPS Props;
714	/** The stream's audio data layout.
715	* This indicates how the audio data buffers to/from the backend is being layouted.
716	*
717	* Currently, the following layouts are supported by the audio connector:
718	*
719	* PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED:
720	* One stream at once. The consecutive audio data is exactly in the format and frame width
721	* like defined in the PCM properties. This is the default.
722	*
723	* PDMAUDIOSTREAMLAYOUT_RAW:
724	* Can be one or many streams at once, depending on the stream's mixing buffer setup.
725	* The audio data will get handled as PDMAUDIOFRAME frames without any modification done. */
726	PDMAUDIOSTREAMLAYOUT enmLayout;
727	/** Device emulation-specific data needed for the audio connector. */
728	struct
729	{
730	/** Scheduling hint set by the device emulation about when this stream is being served on average (in ms).
731	* Can be 0 if not hint given or some other mechanism (e.g. callbacks) is being used. */
732	uint32_t cMsSchedulingHint;
733	} Device;
734	/**
735	* Backend-specific data for the stream.
736	* On input (requested configuration) those values are set by the audio connector to let the backend know what we expect.
737	* On output (acquired configuration) those values reflect the values set and used by the backend.
738	* Set by the backend on return. Not all backends support all values / features.
739	*/
740	struct
741	{
742	/** Period size of the stream (in audio frames).
743	* This value reflects the number of audio frames in between each hardware interrupt on the
744	* backend (host) side. 0 if not set / available by the backend. */
745	uint32_t cFramesPeriod;
746	/** (Ring) buffer size (in audio frames). Often is a multiple of cFramesPeriod.
747	* 0 if not set / available by the backend. */
748	uint32_t cFramesBufferSize;
749	/** Pre-buffering size (in audio frames). Frames needed in buffer before the stream becomes active (pre buffering).
750	* The bigger this value is, the more latency for the stream will occur.
751	* 0 if not set / available by the backend. UINT32_MAX if not defined (yet). */
752	uint32_t cFramesPreBuffering;
753	} Backend;
754	uint32_t u32Padding;
755	/** Friendly name of the stream. */
756	char szName[64];
757	} PDMAUDIOSTREAMCFG;
758	AssertCompileSizeAlignment(PDMAUDIOSTREAMCFG, 8);
759	/** Pointer to audio stream configuration keeper. */
760	typedef PDMAUDIOSTREAMCFG *PPDMAUDIOSTREAMCFG;
761
762	/** Converts (audio) frames to bytes. */
763	#define PDMAUDIOSTREAMCFG_F2B(pCfg, frames) ((frames) << (pCfg->Props).cShift)
764	/** Converts bytes to (audio) frames. */
765	#define PDMAUDIOSTREAMCFG_B2F(pCfg, cb) (cb >> (pCfg->Props).cShift)
766
767	/**
768	* Audio mixer controls.
769	*/
770	typedef enum PDMAUDIOMIXERCTL
771	{
772	/** Invalid zero value as per usual (guards against using unintialized values). */
773	PDMAUDIOMIXERCTL_INVALID = 0,
774	/** Unknown mixer control. */
775	PDMAUDIOMIXERCTL_UNKNOWN,
776	/** Master volume. */
777	PDMAUDIOMIXERCTL_VOLUME_MASTER,
778	/** Front. */
779	PDMAUDIOMIXERCTL_FRONT,
780	/** Center / LFE (Subwoofer). */
781	PDMAUDIOMIXERCTL_CENTER_LFE,
782	/** Rear. */
783	PDMAUDIOMIXERCTL_REAR,
784	/** Line-In. */
785	PDMAUDIOMIXERCTL_LINE_IN,
786	/** Microphone-In. */
787	PDMAUDIOMIXERCTL_MIC_IN,
788	/** Hack to blow the type up to 32-bit. */
789	PDMAUDIOMIXERCTL_32BIT_HACK = 0x7fffffff
790	} PDMAUDIOMIXERCTL;
791
792	/**
793	* Audio stream commands.
794	*
795	* Used in the audio connector as well as in the actual host backends.
796	*/
797	typedef enum PDMAUDIOSTREAMCMD
798	{
799	/** Invalid zero value as per usual (guards against using unintialized values). */
800	PDMAUDIOSTREAMCMD_INVALID = 0,
801	/** Unknown command, do not use. */
802	PDMAUDIOSTREAMCMD_UNKNOWN,
803	/** Enables the stream. */
804	PDMAUDIOSTREAMCMD_ENABLE,
805	/** Disables the stream.
806	* For output streams this stops the stream after playing the remaining (buffered) audio data.
807	* For input streams this will deliver the remaining (captured) audio data and not accepting
808	* any new audio input data afterwards. */
809	PDMAUDIOSTREAMCMD_DISABLE,
810	/** Pauses the stream. */
811	PDMAUDIOSTREAMCMD_PAUSE,
812	/** Resumes the stream. */
813	PDMAUDIOSTREAMCMD_RESUME,
814	/** Tells the stream to drain itself.
815	* For output streams this plays all remaining (buffered) audio frames,
816	* for input streams this permits receiving any new audio frames.
817	* No supported by all backends. */
818	PDMAUDIOSTREAMCMD_DRAIN,
819	/** Tells the stream to drop all (buffered) audio data immediately.
820	* No supported by all backends. */
821	PDMAUDIOSTREAMCMD_DROP,
822	/** Hack to blow the type up to 32-bit. */
823	PDMAUDIOSTREAMCMD_32BIT_HACK = 0x7fffffff
824	} PDMAUDIOSTREAMCMD;
825
826	/**
827	* Audio volume parameters.
828	*/
829	typedef struct PDMAUDIOVOLUME
830	{
831	/** Set to @c true if this stream is muted, @c false if not. */
832	bool fMuted;
833	/** Left channel volume.
834	* Range is from [0 ... 255], whereas 0 specifies
835	* the most silent and 255 the loudest value. */
836	uint8_t uLeft;
837	/** Right channel volume.
838	* Range is from [0 ... 255], whereas 0 specifies
839	* the most silent and 255 the loudest value. */
840	uint8_t uRight;
841	} PDMAUDIOVOLUME;
842	/** Pointer to audio volume settings. */
843	typedef PDMAUDIOVOLUME *PPDMAUDIOVOLUME;
844
845	/** Defines the minimum volume allowed. */
846	#define PDMAUDIO_VOLUME_MIN (0)
847	/** Defines the maximum volume allowed. */
848	#define PDMAUDIO_VOLUME_MAX (255)
849
850	/**
851	* Rate processing information of a source & destination audio stream.
852	*
853	* This is needed because both streams can differ regarding their rates and
854	* therefore need to be treated accordingly.
855	*/
856	typedef struct PDMAUDIOSTREAMRATE
857	{
858	/** Current (absolute) offset in the output (destination) stream.
859	* @todo r=bird: Please reveal which unit these members are given in. */
860	uint64_t offDst;
861	/** Increment for moving offDst for the destination stream.
862	* This is needed because the source <-> destination rate might be different. */
863	uint64_t uDstInc;
864	/** Current (absolute) offset in the input stream. */
865	uint32_t offSrc;
866	/** Explicit alignment padding. */
867	uint32_t u32AlignmentPadding;
868	/** Last processed frame of the input stream.
869	* Needed for interpolation. */
870	PDMAUDIOFRAME SrcFrameLast;
871	} PDMAUDIOSTREAMRATE;
872	/** Pointer to rate processing information of a stream. */
873	typedef PDMAUDIOSTREAMRATE *PPDMAUDIOSTREAMRATE;
874
875	/**
876	* Mixing buffer volume parameters.
877	*
878	* The volume values are in fixed point style and must be converted to/from
879	* before using with e.g. PDMAUDIOVOLUME.
880	*/
881	typedef struct PDMAUDMIXBUFVOL
882	{
883	/** Set to @c true if this stream is muted, @c false if not. */
884	bool fMuted;
885	/** Left volume to apply during conversion.
886	* Pass 0 to convert the original values. May not apply to all conversion functions. */
887	uint32_t uLeft;
888	/** Right volume to apply during conversion.
889	* Pass 0 to convert the original values. May not apply to all conversion functions. */
890	uint32_t uRight;
891	} PDMAUDMIXBUFVOL;
892	/** Pointer to mixing buffer volument parameters. */
893	typedef PDMAUDMIXBUFVOL *PPDMAUDMIXBUFVOL;
894
895	/*
896	* Frame conversion parameters for the audioMixBufConvFromXXX / audioMixBufConvToXXX functions.
897	*/
898	typedef struct PDMAUDMIXBUFCONVOPTS
899	{
900	/** Number of audio frames to convert. */
901	uint32_t cFrames;
902	union
903	{
904	struct
905	{
906	/** Volume to use for conversion. */
907	PDMAUDMIXBUFVOL Volume;
908	} From;
909	} RT_UNION_NM(u);
910	} PDMAUDMIXBUFCONVOPTS;
911	/** Pointer to conversion parameters for the audio mixer. */
912	typedef PDMAUDMIXBUFCONVOPTS *PPDMAUDMIXBUFCONVOPTS;
913	/** Pointer to const conversion parameters for the audio mixer. */
914	typedef PDMAUDMIXBUFCONVOPTS const *PCPDMAUDMIXBUFCONVOPTS;
915
916	/**
917	* @note All internal handling is done in audio frames, not in bytes!
918	* @todo r=bird: What does this node actually apply to?
919	*/
920	typedef uint32_t PDMAUDIOMIXBUFFMT;
921	typedef PDMAUDIOMIXBUFFMT *PPDMAUDIOMIXBUFFMT;
922
923	/**
924	* Convertion-from function used by the PDM audio buffer mixer.
925	*
926	* @returns Number of audio frames returned.
927	* @param paDst Where to return the converted frames.
928	* @param pvSrc The source frame bytes.
929	* @param cbSrc Number of bytes to convert.
930	* @param pOpts Conversion options.
931	* @todo r=bird: The @a paDst size is presumable given in @a pOpts->cFrames?
932	*/
933	typedef DECLCALLBACKTYPE(uint32_t, FNPDMAUDIOMIXBUFCONVFROM,(PPDMAUDIOFRAME paDst, const void *pvSrc, uint32_t cbSrc,
934	PCPDMAUDMIXBUFCONVOPTS pOpts));
935	/** Pointer to a convertion-from function used by the PDM audio buffer mixer. */
936	typedef FNPDMAUDIOMIXBUFCONVFROM *PFNPDMAUDIOMIXBUFCONVFROM;
937
938	/**
939	* Convertion-to function used by the PDM audio buffer mixer.
940	*
941	* @param pvDst Output buffer.
942	* @param paSrc The input frames.
943	* @param pOpts Conversion options.
944	* @todo r=bird: The @a paSrc size is presumable given in @a pOpts->cFrames and
945	* this implicitly gives the pvDst size too, right?
946	*/
947	typedef DECLCALLBACKTYPE(void, FNPDMAUDIOMIXBUFCONVTO,(void *pvDst, PCPDMAUDIOFRAME paSrc, PCPDMAUDMIXBUFCONVOPTS pOpts));
948	/** Pointer to a convertion-to function used by the PDM audio buffer mixer. */
949	typedef FNPDMAUDIOMIXBUFCONVTO *PFNPDMAUDIOMIXBUFCONVTO;
950
951	/** Pointer to audio mixing buffer. */
952	typedef struct PDMAUDIOMIXBUF *PPDMAUDIOMIXBUF;
953
954	/**
955	* Audio mixing buffer.
956	*/
957	typedef struct PDMAUDIOMIXBUF
958	{
959	RTLISTNODE Node;
960	/** Name of the buffer. */
961	char *pszName;
962	/** Frame buffer. */
963	PPDMAUDIOFRAME pFrames;
964	/** Size of the frame buffer (in audio frames). */
965	uint32_t cFrames;
966	/** The current read position (in frames). */
967	uint32_t offRead;
968	/** The current write position (in frames). */
969	uint32_t offWrite;
970	/**
971	* Total frames already mixed down to the parent buffer (if any).
972	*
973	* Always starting at the parent's offRead position.
974	* @note Count always is specified in parent frames, as the sample count can
975	* differ between parent and child.
976	*/
977	uint32_t cMixed;
978	/** How much audio frames are currently being used
979	* in this buffer.
980	* Note: This also is known as the distance in ring buffer terms. */
981	uint32_t cUsed;
982	/** Pointer to parent buffer (if any). */
983	PPDMAUDIOMIXBUF pParent;
984	/** List of children mix buffers to keep in sync with (if being a parent buffer). */
985	RTLISTANCHOR lstChildren;
986	/** Number of children mix buffers kept in lstChildren. */
987	uint32_t cChildren;
988	/** Intermediate structure for buffer conversion tasks. */
989	PPDMAUDIOSTREAMRATE pRate;
990	/** Internal representation of current volume used for mixing. */
991	PDMAUDMIXBUFVOL Volume;
992	/** This buffer's audio format.
993	* @todo r=bird: This seems to be a value created by AUDMIXBUF_AUDIO_FMT_MAKE(),
994	* which is not define here. Does this structure really belong here at
995	* all? */
996	PDMAUDIOMIXBUFFMT uAudioFmt;
997	/** Standard conversion-to function for set uAudioFmt. */
998	PFNPDMAUDIOMIXBUFCONVTO pfnConvTo;
999	/** Standard conversion-from function for set uAudioFmt. */
1000	PFNPDMAUDIOMIXBUFCONVFROM pfnConvFrom;
1001	/**
1002	* Ratio of the associated parent stream's frequency by this stream's
1003	* frequency (1<<32), represented as a signed 64 bit integer.
1004	*
1005	* For example, if the parent stream has a frequency of 44 khZ, and this
1006	* stream has a frequency of 11 kHz, the ration then would be
1007	* (44/11 * (1 << 32)).
1008	*
1009	* Currently this does not get changed once assigned.
1010	*/
1011	int64_t iFreqRatio;
1012	/** For quickly converting frames <-> bytes and vice versa. */
1013	uint8_t cShift;
1014	} PDMAUDIOMIXBUF;
1015
1016	/** @name PDMAUDIOFILE_FLAGS_XXX
1017	* @{ */
1018	/** No flags defined. */
1019	#define PDMAUDIOFILE_FLAGS_NONE UINT32_C(0)
1020	/** Keep the audio file even if it contains no audio data. */
1021	#define PDMAUDIOFILE_FLAGS_KEEP_IF_EMPTY RT_BIT_32(0)
1022	/** Audio file flag validation mask. */
1023	#define PDMAUDIOFILE_FLAGS_VALID_MASK UINT32_C(0x1)
1024	/** @} */
1025
1026	/** Audio file default open flags.
1027	* @todo r=bird: What is the exact purpose of this? */
1028	#define PDMAUDIOFILE_DEFAULT_OPEN_FLAGS (RTFILE_O_OPEN_CREATE \| RTFILE_O_APPEND \| RTFILE_O_WRITE \| RTFILE_O_DENY_WRITE)
1029
1030	/**
1031	* Audio file types.
1032	*/
1033	typedef enum PDMAUDIOFILETYPE
1034	{
1035	/** The customary invalid zero value. */
1036	PDMAUDIOFILETYPE_INVALID = 0,
1037	/** Unknown type, do not use. */
1038	PDMAUDIOFILETYPE_UNKNOWN,
1039	/** Raw (PCM) file. */
1040	PDMAUDIOFILETYPE_RAW,
1041	/** Wave (.WAV) file. */
1042	PDMAUDIOFILETYPE_WAV,
1043	/** Hack to blow the type up to 32-bit. */
1044	PDMAUDIOFILETYPE_32BIT_HACK = 0x7fffffff
1045	} PDMAUDIOFILETYPE;
1046
1047	/** @name PDMAUDIOFILENAME_FLAGS_XXX
1048	* @{ */
1049	/** No flags defined. */
1050	#define PDMAUDIOFILENAME_FLAGS_NONE UINT32_C(0)
1051	/** Adds an ISO timestamp to the file name. */
1052	#define PDMAUDIOFILENAME_FLAGS_TS RT_BIT(0)
1053	/** @} */
1054
1055	/**
1056	* Audio file handle.
1057	*/
1058	typedef struct PDMAUDIOFILE
1059	{
1060	/** Type of the audio file. */
1061	PDMAUDIOFILETYPE enmType;
1062	/** Audio file flags, PDMAUDIOFILE_FLAGS_XXX. */
1063	uint32_t fFlags;
1064	/** Actual file handle. */
1065	RTFILE hFile;
1066	/** Data needed for the specific audio file type implemented.
1067	* Optional, can be NULL. */
1068	void *pvData;
1069	/** Data size (in bytes). */
1070	size_t cbData;
1071	/** File name and path. */
1072	char szName[RTPATH_MAX];
1073	} PDMAUDIOFILE;
1074	/** Pointer to an audio file handle. */
1075	typedef PDMAUDIOFILE *PPDMAUDIOFILE;
1076
1077	/** @name PDMAUDIOSTREAMSTS_FLAGS_XXX
1078	* @{ */
1079	/** No flags being set. */
1080	#define PDMAUDIOSTREAMSTS_FLAGS_NONE UINT32_C(0)
1081	/** Whether this stream has been initialized by the
1082	* backend or not. */
1083	#define PDMAUDIOSTREAMSTS_FLAGS_INITIALIZED RT_BIT_32(0)
1084	/** Whether this stream is enabled or disabled. */
1085	#define PDMAUDIOSTREAMSTS_FLAGS_ENABLED RT_BIT_32(1)
1086	/** Whether this stream has been paused or not. This also implies
1087	* that this is an enabled stream! */
1088	#define PDMAUDIOSTREAMSTS_FLAGS_PAUSED RT_BIT_32(2)
1089	/** Whether this stream was marked as being disabled
1090	* but there are still associated guest output streams
1091	* which rely on its data. */
1092	#define PDMAUDIOSTREAMSTS_FLAGS_PENDING_DISABLE RT_BIT_32(3)
1093	/** Whether this stream is in re-initialization phase.
1094	* All other bits remain untouched to be able to restore
1095	* the stream's state after the re-initialization bas been
1096	* finished. */
1097	#define PDMAUDIOSTREAMSTS_FLAGS_PENDING_REINIT RT_BIT_32(4)
1098	/** Validation mask. */
1099	#define PDMAUDIOSTREAMSTS_VALID_MASK UINT32_C(0x0000001F)
1100	/** Stream status flag, PDMAUDIOSTREAMSTS_FLAGS_XXX. */
1101	typedef uint32_t PDMAUDIOSTREAMSTS;
1102	/** @} */
1103
1104	/**
1105	* Backend status.
1106	*/
1107	typedef enum PDMAUDIOBACKENDSTS
1108	{
1109	/** Unknown/invalid status. */
1110	PDMAUDIOBACKENDSTS_UNKNOWN = 0,
1111	/** No backend attached. */
1112	PDMAUDIOBACKENDSTS_NOT_ATTACHED,
1113	/** The backend is in its initialization phase.
1114	* Not all backends support this status. */
1115	PDMAUDIOBACKENDSTS_INITIALIZING,
1116	/** The backend has stopped its operation. */
1117	PDMAUDIOBACKENDSTS_STOPPED,
1118	/** The backend is up and running. */
1119	PDMAUDIOBACKENDSTS_RUNNING,
1120	/** The backend ran into an error and is unable to recover.
1121	* A manual re-initialization might help. */
1122	PDMAUDIOBACKENDSTS_ERROR,
1123	/** Hack to blow the type up to 32-bit. */
1124	PDMAUDIOBACKENDSTS_32BIT_HACK = 0x7fffffff
1125	} PDMAUDIOBACKENDSTS;
1126
1127	/**
1128	* The specifics for an audio input stream.
1129	*
1130	* Do not use directly, use PDMAUDIOSTREAM instead.
1131	*/
1132	typedef struct PDMAUDIOSTREAMIN
1133	{
1134	#ifdef VBOX_WITH_STATISTICS
1135	struct
1136	{
1137	STAMCOUNTER TotalFramesCaptured;
1138	STAMCOUNTER AvgFramesCaptured;
1139	STAMCOUNTER TotalTimesCaptured;
1140	STAMCOUNTER TotalFramesRead;
1141	STAMCOUNTER AvgFramesRead;
1142	STAMCOUNTER TotalTimesRead;
1143	} Stats;
1144	#endif
1145	struct
1146	{
1147	/** File for writing stream reads. */
1148	PPDMAUDIOFILE pFileStreamRead;
1149	/** File for writing non-interleaved captures. */
1150	PPDMAUDIOFILE pFileCaptureNonInterleaved;
1151	} Dbg;
1152	} PDMAUDIOSTREAMIN;
1153	/** Pointer to the specifics for an audio input stream. */
1154	typedef PDMAUDIOSTREAMIN *PPDMAUDIOSTREAMIN;
1155
1156	/**
1157	* The specifics for an audio output stream.
1158	*
1159	* Do not use directly, use PDMAUDIOSTREAM instead.
1160	*/
1161	typedef struct PDMAUDIOSTREAMOUT
1162	{
1163	#ifdef VBOX_WITH_STATISTICS
1164	struct
1165	{
1166	STAMCOUNTER TotalFramesPlayed;
1167	STAMCOUNTER AvgFramesPlayed;
1168	STAMCOUNTER TotalTimesPlayed;
1169	STAMCOUNTER TotalFramesWritten;
1170	STAMCOUNTER AvgFramesWritten;
1171	STAMCOUNTER TotalTimesWritten;
1172	} Stats;
1173	#endif
1174	struct
1175	{
1176	/** File for writing stream writes. */
1177	PPDMAUDIOFILE pFileStreamWrite;
1178	/** File for writing stream playback. */
1179	PPDMAUDIOFILE pFilePlayNonInterleaved;
1180	} Dbg;
1181	} PDMAUDIOSTREAMOUT;
1182	/** Pointer to the specifics for an audio output stream. */
1183	typedef PDMAUDIOSTREAMOUT *PPDMAUDIOSTREAMOUT;
1184
1185	/** Pointer to an audio stream. */
1186	typedef struct PDMAUDIOSTREAM *PPDMAUDIOSTREAM;
1187
1188	/**
1189	* Audio stream context.
1190	* Needed for separating data from the guest and host side (per stream).
1191	*/
1192	typedef struct PDMAUDIOSTREAMCTX
1193	{
1194	/** The stream's audio configuration. */
1195	PDMAUDIOSTREAMCFG Cfg;
1196	/** This stream's mixing buffer. */
1197	PDMAUDIOMIXBUF MixBuf;
1198	} PDMAUDIOSTREAMCTX;
1199
1200	/** Pointer to an audio stream context. */
1201	typedef struct PDMAUDIOSTREAM *PPDMAUDIOSTREAMCTX;
1202
1203	/**
1204	* An input or output audio stream.
1205	*/
1206	typedef struct PDMAUDIOSTREAM
1207	{
1208	/** List node. */
1209	RTLISTNODE Node;
1210	/** Name of this stream. */
1211	char szName[64];
1212	/** Number of references to this stream.
1213	* Only can be destroyed when the reference count reaches 0. */
1214	uint32_t cRefs;
1215	/** Number of (re-)tries while re-initializing the stream. */
1216	uint32_t cTriesReInit;
1217	/** Stream status flag. */
1218	PDMAUDIOSTREAMSTS fStatus;
1219	/** Audio direction of this stream. */
1220	PDMAUDIODIR enmDir;
1221	/** For output streams this indicates whether the stream has reached
1222	* its playback threshold, e.g. is playing audio.
1223	* For input streams this indicates whether the stream has enough input
1224	* data to actually start reading audio. */
1225	bool fThresholdReached;
1226	bool afPadding[3];
1227	/** The guest side of the stream. */
1228	PDMAUDIOSTREAMCTX Guest;
1229	/** The host side of the stream. */
1230	PDMAUDIOSTREAMCTX Host;
1231	/** Union for input/output specifics depending on enmDir. */
1232	union
1233	{
1234	PDMAUDIOSTREAMIN In;
1235	PDMAUDIOSTREAMOUT Out;
1236	} RT_UNION_NM(u);
1237	/** Timestamp (in ns) since last trying to re-initialize.
1238	* Might be 0 if has not been tried yet. */
1239	uint64_t tsLastReInitNs;
1240	/** Timestamp (in ns) since last iteration. */
1241	uint64_t tsLastIteratedNs;
1242	/** Timestamp (in ns) since last playback / capture. */
1243	uint64_t tsLastPlayedCapturedNs;
1244	/** Timestamp (in ns) since last read (input streams) or
1245	* write (output streams). */
1246	uint64_t tsLastReadWrittenNs;
1247	/** Data to backend-specific stream data.
1248	* This data block will be casted by the backend to access its backend-dependent data.
1249	*
1250	* That way the backends do not have access to the audio connector's data. */
1251	void *pvBackend;
1252	/** Size (in bytes) of the backend-specific stream data. */
1253	size_t cbBackend;
1254	} PDMAUDIOSTREAM;
1255
1256
1257	/**
1258	* Audio callback source.
1259	*/
1260	typedef enum PDMAUDIOCBSOURCE
1261	{
1262	/** Invalid, do not use. */
1263	PDMAUDIOCBSOURCE_INVALID = 0,
1264	/** Device emulation. */
1265	PDMAUDIOCBSOURCE_DEVICE,
1266	/** Audio connector interface. */
1267	PDMAUDIOCBSOURCE_CONNECTOR,
1268	/** Backend (lower). */
1269	PDMAUDIOCBSOURCE_BACKEND,
1270	/** Hack to blow the type up to 32-bit. */
1271	PDMAUDIOCBSOURCE_32BIT_HACK = 0x7fffffff
1272	} PDMAUDIOCBSOURCE;
1273
1274	/**
1275	* Audio device callback types.
1276	* Those callbacks are being sent from the audio connector -> device emulation.
1277	*/
1278	typedef enum PDMAUDIODEVICECBTYPE
1279	{
1280	/** Invalid, do not use. */
1281	PDMAUDIODEVICECBTYPE_INVALID = 0,
1282	/** Data is availabe as input for passing to the device emulation. */
1283	PDMAUDIODEVICECBTYPE_DATA_INPUT,
1284	/** Free data for the device emulation to write to the backend. */
1285	PDMAUDIODEVICECBTYPE_DATA_OUTPUT,
1286	/** Hack to blow the type up to 32-bit. */
1287	PDMAUDIODEVICECBTYPE_32BIT_HACK = 0x7fffffff
1288	} PDMAUDIODEVICECBTYPE;
1289
1290	#if 0 /** @todo r=bird: Who needs this exactly? Fix the style or remove */
1291	/**
1292	* Device callback data for audio input.
1293	*/
1294	typedef struct PDMAUDIODEVICECBDATA_DATA_INPUT
1295	{
1296	/** Input: How many bytes are availabe as input for passing
1297	* to the device emulation. */
1298	uint32_t cbInAvail;
1299	/** Output: How many bytes have been read. */
1300	uint32_t cbOutRead;
1301	} PDMAUDIODEVICECBDATA_DATA_INPUT;
1302	typedef PDMAUDIODEVICECBDATA_DATA_INPUT *PPDMAUDIODEVICECBDATA_DATA_INPUT;
1303
1304	/**
1305	* Device callback data for audio output.
1306	*/
1307	typedef struct PDMAUDIODEVICECBDATA_DATA_OUTPUT
1308	{
1309	/** Input: How many bytes are free for the device emulation to write. */
1310	uint32_t cbInFree;
1311	/** Output: How many bytes were written by the device emulation. */
1312	uint32_t cbOutWritten;
1313	} PDMAUDIODEVICECBDATA_DATA_OUTPUT, *PPDMAUDIODEVICECBDATA_DATA_OUTPUT;
1314	#endif
1315
1316	/**
1317	* Audio backend callback types.
1318	* Those callbacks are being sent from the backend -> audio connector.
1319	*/
1320	typedef enum PDMAUDIOBACKENDCBTYPE
1321	{
1322	/** Invalid, do not use. */
1323	PDMAUDIOBACKENDCBTYPE_INVALID = 0,
1324	/** The backend's status has changed. */
1325	PDMAUDIOBACKENDCBTYPE_STATUS,
1326	/** One or more host audio devices have changed. */
1327	PDMAUDIOBACKENDCBTYPE_DEVICES_CHANGED,
1328	/** Hack to blow the type up to 32-bit. */
1329	PDMAUDIOBACKENDCBTYPE_32BIT_HACK = 0x7fffffff
1330	} PDMAUDIOBACKENDCBTYPE;
1331
1332	/** Pointer to a host audio interface. */
1333	typedef struct PDMIHOSTAUDIO *PPDMIHOSTAUDIO;
1334
1335	/**
1336	* Host audio callback function.
1337	* This function will be called from a backend to communicate with the host audio interface.
1338	*
1339	* @returns IPRT status code.
1340	* @param pDrvIns Pointer to driver instance which called us.
1341	* @param enmType Callback type.
1342	* @param pvUser User argument.
1343	* @param cbUser Size (in bytes) of user argument.
1344	*/
1345	typedef DECLCALLBACKTYPE(int, FNPDMHOSTAUDIOCALLBACK,(PPDMDRVINS pDrvIns, PDMAUDIOBACKENDCBTYPE enmType,
1346	void *pvUser, size_t cbUser));
1347	/** Pointer to a FNPDMHOSTAUDIOCALLBACK(). */
1348	typedef FNPDMHOSTAUDIOCALLBACK *PFNPDMHOSTAUDIOCALLBACK;
1349
1350	/**
1351	* Audio callback registration record.
1352	*/
1353	typedef struct PDMAUDIOCBRECORD
1354	{
1355	/** List node. */
1356	RTLISTANCHOR Node;
1357	/** Callback source. */
1358	PDMAUDIOCBSOURCE enmSource;
1359	/** Callback type, based on the given source. */
1360	union
1361	{
1362	/** Device callback stuff. */
1363	struct
1364	{
1365	PDMAUDIODEVICECBTYPE enmType;
1366	} Device;
1367	} RT_UNION_NM(u);
1368	/** Pointer to context data. Optional. */
1369	void *pvCtx;
1370	/** Size (in bytes) of context data.
1371	* Must be 0 if pvCtx is NULL. */
1372	size_t cbCtx;
1373	} PDMAUDIOCBRECORD;
1374	/** Pointer to an audio callback registration record. */
1375	typedef PDMAUDIOCBRECORD *PPDMAUDIOCBRECORD;
1376
1377	/** @todo r=bird: What is this exactly? */
1378	#define PPDMAUDIOBACKENDSTREAM void *
1379
1380	/** Pointer to a audio connector interface. */
1381	typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
1382
1383	/**
1384	* Audio connector interface (up).
1385	*/
1386	typedef struct PDMIAUDIOCONNECTOR
1387	{
1388	/**
1389	* Enables or disables the given audio direction for this driver.
1390	*
1391	* When disabled, assiociated output streams consume written audio without passing them further down to the backends.
1392	* Associated input streams then return silence when read from those.
1393	*
1394	* @returns VBox status code.
1395	* @param pInterface Pointer to the interface structure containing the called function pointer.
1396	* @param enmDir Audio direction to enable or disable driver for.
1397	* @param fEnable Whether to enable or disable the specified audio direction.
1398	*
1399	* @note Be very careful when using this function, as this could
1400	* violate / run against the (global) VM settings. See @bugref{9882}.
1401	*/
1402	DECLR3CALLBACKMEMBER(int, pfnEnable, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir, bool fEnable));
1403
1404	/**
1405	* Returns whether the given audio direction for this driver is enabled or not.
1406	*
1407	* @returns True if audio is enabled for the given direction, false if not.
1408	* @param pInterface Pointer to the interface structure containing the called function pointer.
1409	* @param enmDir Audio direction to retrieve enabled status for.
1410	*/
1411	DECLR3CALLBACKMEMBER(bool, pfnIsEnabled, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
1412
1413	/**
1414	* Retrieves the current configuration of the host audio backend.
1415	*
1416	* @returns VBox status code.
1417	* @param pInterface Pointer to the interface structure containing the called function pointer.
1418	* @param pCfg Where to store the host audio backend configuration data.
1419	*/
1420	DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOBACKENDCFG pCfg));
1421
1422	/**
1423	* Retrieves the current status of the host audio backend.
1424	*
1425	* @returns Status of the host audio backend.
1426	* @param pInterface Pointer to the interface structure containing the called function pointer.
1427	* @param enmDir Audio direction to check host audio backend for. Specify PDMAUDIODIR_ANY for the overall
1428	* backend status.
1429	*/
1430	DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
1431
1432	/**
1433	* Creates an audio stream.
1434	*
1435	* @returns VBox status code.
1436	* @param pInterface Pointer to the interface structure containing the called function pointer.
1437	* @param pCfgHost Stream configuration for host side.
1438	* @param pCfgGuest Stream configuration for guest side.
1439	* @param ppStream Pointer where to return the created audio stream on success.
1440	*/
1441	DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfgHost,
1442	PPDMAUDIOSTREAMCFG pCfgGuest, PPDMAUDIOSTREAM *ppStream));
1443
1444	/**
1445	* Destroys an audio stream.
1446	*
1447	* @param pInterface Pointer to the interface structure containing the called function pointer.
1448	* @param pStream Pointer to audio stream.
1449	*/
1450	DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1451
1452	/**
1453	* Adds a reference to the specified audio stream.
1454	*
1455	* @returns New reference count. UINT32_MAX on error.
1456	* @param pInterface Pointer to the interface structure containing the called function pointer.
1457	* @param pStream Pointer to audio stream adding the reference to.
1458	*/
1459	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRetain, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1460
1461	/**
1462	* Releases a reference from the specified stream.
1463	*
1464	* @returns New reference count. UINT32_MAX on error.
1465	* @param pInterface Pointer to the interface structure containing the called function pointer.
1466	* @param pStream Pointer to audio stream releasing a reference from.
1467	*/
1468	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRelease, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1469
1470	/**
1471	* Reads PCM audio data from the host (input).
1472	*
1473	* @returns VBox status code.
1474	* @param pInterface Pointer to the interface structure containing the called function pointer.
1475	* @param pStream Pointer to audio stream to write to.
1476	* @param pvBuf Where to store the read data.
1477	* @param cbBuf Number of bytes to read.
1478	* @param pcbRead Bytes of audio data read. Optional.
1479	*/
1480	DECLR3CALLBACKMEMBER(int, pfnStreamRead, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1481	void pvBuf, uint32_t cbBuf, uint32_t pcbRead));
1482
1483	/**
1484	* Writes PCM audio data to the host (output).
1485	*
1486	* @returns VBox status code.
1487	* @param pInterface Pointer to the interface structure containing the called function pointer.
1488	* @param pStream Pointer to audio stream to read from.
1489	* @param pvBuf Audio data to be written.
1490	* @param cbBuf Number of bytes to be written.
1491	* @param pcbWritten Bytes of audio data written. Optional.
1492	*/
1493	DECLR3CALLBACKMEMBER(int, pfnStreamWrite, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1494	const void pvBuf, uint32_t cbBuf, uint32_t pcbWritten));
1495
1496	/**
1497	* Controls a specific audio stream.
1498	*
1499	* @returns VBox status code.
1500	* @param pInterface Pointer to the interface structure containing the called function pointer.
1501	* @param pStream Pointer to audio stream.
1502	* @param enmStreamCmd The stream command to issue.
1503	*/
1504	DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1505	PDMAUDIOSTREAMCMD enmStreamCmd));
1506
1507	/**
1508	* Processes stream data.
1509	*
1510	* @param pInterface Pointer to the interface structure containing the called function pointer.
1511	* @param pStream Pointer to audio stream.
1512	*/
1513	DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1514
1515	/**
1516	* Returns the number of readable data (in bytes) of a specific audio input stream.
1517	*
1518	* @returns Number of readable data (in bytes).
1519	* @param pInterface Pointer to the interface structure containing the called function pointer.
1520	* @param pStream Pointer to audio stream.
1521	*/
1522	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1523
1524	/**
1525	* Returns the number of writable data (in bytes) of a specific audio output stream.
1526	*
1527	* @returns Number of writable data (in bytes).
1528	* @param pInterface Pointer to the interface structure containing the called function pointer.
1529	* @param pStream Pointer to audio stream.
1530	*/
1531	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1532
1533	/**
1534	* Returns the status of a specific audio stream.
1535	*
1536	* @returns Audio stream status
1537	* @param pInterface Pointer to the interface structure containing the called function pointer.
1538	* @param pStream Pointer to audio stream.
1539	*/
1540	DECLR3CALLBACKMEMBER(PDMAUDIOSTREAMSTS, pfnStreamGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1541
1542	/**
1543	* Sets the audio volume of a specific audio stream.
1544	*
1545	* @returns VBox status code.
1546	* @param pInterface Pointer to the interface structure containing the called function pointer.
1547	* @param pStream Pointer to audio stream.
1548	* @param pVol Pointer to audio volume structure to set the stream's audio volume to.
1549	*/
1550	DECLR3CALLBACKMEMBER(int, pfnStreamSetVolume, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOVOLUME pVol));
1551
1552	/**
1553	* Plays (transfers) available audio frames to the host backend. Only works with output streams.
1554	*
1555	* @returns VBox status code.
1556	* @param pInterface Pointer to the interface structure containing the called function pointer.
1557	* @param pStream Pointer to audio stream.
1558	* @param pcFramesPlayed Number of frames played. Optional.
1559	*/
1560	DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcFramesPlayed));
1561
1562	/**
1563	* Captures (transfers) available audio frames from the host backend. Only works with input streams.
1564	*
1565	* @returns VBox status code.
1566	* @param pInterface Pointer to the interface structure containing the called function pointer.
1567	* @param pStream Pointer to audio stream.
1568	* @param pcFramesCaptured Number of frames captured. Optional.
1569	*/
1570	DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1571	uint32_t *pcFramesCaptured));
1572
1573	/**
1574	* Registers (device) callbacks.
1575	* This is handy for letting the device emulation know of certain events, e.g. processing input / output data
1576	* or configuration changes.
1577	*
1578	* @returns VBox status code.
1579	* @param pInterface Pointer to the interface structure containing the called function pointer.
1580	* @param paCallbacks Pointer to array of callbacks to register.
1581	* @param cCallbacks Number of callbacks to register.
1582	*/
1583	DECLR3CALLBACKMEMBER(int, pfnRegisterCallbacks, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOCBRECORD paCallbacks,
1584	size_t cCallbacks));
1585
1586	} PDMIAUDIOCONNECTOR;
1587
1588	/** PDMIAUDIOCONNECTOR interface ID. */
1589	#define PDMIAUDIOCONNECTOR_IID "00e704ef-0078-4bb6-0005-a5fd000ded9f"
1590
1591
1592	/**
1593	* PDM host audio interface.
1594	*/
1595	typedef struct PDMIHOSTAUDIO
1596	{
1597	/**
1598	* Initializes the host backend (driver).
1599	*
1600	* @returns VBox status code.
1601	* @param pInterface Pointer to the interface structure containing the called function pointer.
1602	*/
1603	DECLR3CALLBACKMEMBER(int, pfnInit, (PPDMIHOSTAUDIO pInterface));
1604
1605	/**
1606	* Shuts down the host backend (driver).
1607	*
1608	* @returns VBox status code.
1609	* @param pInterface Pointer to the interface structure containing the called function pointer.
1610	*/
1611	DECLR3CALLBACKMEMBER(void, pfnShutdown, (PPDMIHOSTAUDIO pInterface));
1612
1613	/**
1614	* Returns the host backend's configuration (backend).
1615	*
1616	* @returns VBox status code.
1617	* @param pInterface Pointer to the interface structure containing the called function pointer.
1618	* @param pBackendCfg Where to store the backend audio configuration to.
1619	*/
1620	DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg));
1621
1622	/**
1623	* Returns (enumerates) host audio device information.
1624	*
1625	* @returns VBox status code.
1626	* @param pInterface Pointer to the interface structure containing the called function pointer.
1627	* @param pDeviceEnum Where to return the enumerated audio devices.
1628	*/
1629	DECLR3CALLBACKMEMBER(int, pfnGetDevices, (PPDMIHOSTAUDIO pInterface, PPDMAUDIODEVICEENUM pDeviceEnum));
1630
1631	/**
1632	* Returns the current status from the audio backend.
1633	*
1634	* @returns PDMAUDIOBACKENDSTS enum.
1635	* @param pInterface Pointer to the interface structure containing the called function pointer.
1636	* @param enmDir Audio direction to get status for. Pass PDMAUDIODIR_ANY for overall status.
1637	*/
1638	DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir));
1639
1640	/**
1641	* Sets a callback the audio backend can call. Optional.
1642	*
1643	* @returns VBox status code.
1644	* @param pInterface Pointer to the interface structure containing the called function pointer.
1645	* @param pfnCallback The callback function to use, or NULL when unregistering.
1646	*/
1647	DECLR3CALLBACKMEMBER(int, pfnSetCallback, (PPDMIHOSTAUDIO pInterface, PFNPDMHOSTAUDIOCALLBACK pfnCallback));
1648
1649	/**
1650	* Creates an audio stream using the requested stream configuration.
1651	*
1652	* If a backend is not able to create this configuration, it will return its
1653	* best match in the acquired configuration structure on success.
1654	*
1655	* @returns VBox status code.
1656	* @param pInterface Pointer to the interface structure containing the called function pointer.
1657	* @param pStream Pointer to audio stream.
1658	* @param pCfgReq Pointer to requested stream configuration.
1659	* @param pCfgAcq Pointer to acquired stream configuration.
1660	* @todo r=bird: Implementation (at least Alsa) seems to make undocumented
1661	* assumptions about the content of @a pCfgAcq.
1662	*/
1663	DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1664	PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq));
1665
1666	/**
1667	* Destroys an audio stream.
1668	*
1669	* @returns VBox status code.
1670	* @param pInterface Pointer to the interface structure containing the called function pointer.
1671	* @param pStream Pointer to audio stream.
1672	*/
1673	DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1674
1675	/**
1676	* Controls an audio stream.
1677	*
1678	* @returns VBox status code.
1679	* @retval VERR_AUDIO_STREAM_NOT_READY if stream is not ready for required operation (yet).
1680	* @param pInterface Pointer to the interface structure containing the called function pointer.
1681	* @param pStream Pointer to audio stream.
1682	* @param enmStreamCmd The stream command to issue.
1683	*/
1684	DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1685	PDMAUDIOSTREAMCMD enmStreamCmd));
1686
1687	/**
1688	* Returns the amount which is readable from the audio (input) stream.
1689	*
1690	* @returns For non-raw layout streams: Number of readable bytes.
1691	* for raw layout streams : Number of readable audio frames.
1692	* @param pInterface Pointer to the interface structure containing the called function pointer.
1693	* @param pStream Pointer to audio stream.
1694	*/
1695	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1696
1697	/**
1698	* Returns the amount which is writable to the audio (output) stream.
1699	*
1700	* @returns For non-raw layout streams: Number of writable bytes.
1701	* for raw layout streams : Number of writable audio frames.
1702	* @param pInterface Pointer to the interface structure containing the called function pointer.
1703	* @param pStream Pointer to audio stream.
1704	*/
1705	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1706
1707	/**
1708	* Returns the amount which is pending (in other words has not yet been processed) by/from the backend yet.
1709	* Optional.
1710	*
1711	* For input streams this is read audio data by the backend which has not been processed by the host yet.
1712	* For output streams this is written audio data to the backend which has not been processed by the backend yet.
1713	*
1714	* @returns For non-raw layout streams: Number of pending bytes.
1715	* for raw layout streams : Number of pending audio frames.
1716	* @param pInterface Pointer to the interface structure containing the called function pointer.
1717	* @param pStream Pointer to audio stream.
1718	*/
1719	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetPending, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1720
1721	/**
1722	* Returns the current status of the given backend stream.
1723	*
1724	* @returns PDMAUDIOSTREAMSTS
1725	* @param pInterface Pointer to the interface structure containing the called function pointer.
1726	* @param pStream Pointer to audio stream.
1727	*/
1728	DECLR3CALLBACKMEMBER(PDMAUDIOSTREAMSTS, pfnStreamGetStatus, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1729
1730	/**
1731	* Gives the host backend the chance to do some (necessary) iteration work.
1732	*
1733	* @returns VBox status code.
1734	* @param pInterface Pointer to the interface structure containing the called function pointer.
1735	* @param pStream Pointer to audio stream.
1736	*/
1737	DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1738
1739	/**
1740	* Signals the backend that the host wants to begin playing for this iteration. Optional.
1741	*
1742	* @param pInterface Pointer to the interface structure containing the called function pointer.
1743	* @param pStream Pointer to audio stream.
1744	*/
1745	DECLR3CALLBACKMEMBER(void, pfnStreamPlayBegin, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1746
1747	/**
1748	* Plays (writes to) an audio (output) stream.
1749	*
1750	* @returns VBox status code.
1751	* @param pInterface Pointer to the interface structure containing the called function pointer.
1752	* @param pStream Pointer to audio stream.
1753	* @param pvBuf Pointer to audio data buffer to play.
1754	* @param uBufSize The audio data buffer size (see note below for unit).
1755	* @param puWritten Number of unit written.
1756	* @note The @a uBufSize and @a puWritten values are in bytes for non-raw
1757	* layout streams and in frames for raw layout ones.
1758	*/
1759	DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1760	const void pvBuf, uint32_t uBufSize, uint32_t puWritten));
1761
1762	/**
1763	* Signals the backend that the host finished playing for this iteration. Optional.
1764	*
1765	* @param pInterface Pointer to the interface structure containing the called function pointer.
1766	* @param pStream Pointer to audio stream.
1767	*/
1768	DECLR3CALLBACKMEMBER(void, pfnStreamPlayEnd, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1769
1770	/**
1771	* Signals the backend that the host wants to begin capturing for this iteration. Optional.
1772	*
1773	* @param pInterface Pointer to the interface structure containing the called function pointer.
1774	* @param pStream Pointer to audio stream.
1775	*/
1776	DECLR3CALLBACKMEMBER(void, pfnStreamCaptureBegin, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1777
1778	/**
1779	* Captures (reads from) an audio (input) stream.
1780	*
1781	* @returns VBox status code.
1782	* @param pInterface Pointer to the interface structure containing the called function pointer.
1783	* @param pStream Pointer to audio stream.
1784	* @param pvBuf Buffer where to store read audio data.
1785	* @param uBufSize Size of the audio data buffer (see note below for unit).
1786	* @param puRead Returns number of units read.
1787	* @note The @a uBufSize and @a puRead values are in bytes for non-raw
1788	* layout streams and in frames for raw layout ones.
1789	*/
1790	DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1791	void pvBuf, uint32_t uBufSize, uint32_t puRead));
1792
1793	/**
1794	* Signals the backend that the host finished capturing for this iteration. Optional.
1795	*
1796	* @param pInterface Pointer to the interface structure containing the called function pointer.
1797	* @param pStream Pointer to audio stream.
1798	*/
1799	DECLR3CALLBACKMEMBER(void, pfnStreamCaptureEnd, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1800
1801	} PDMIHOSTAUDIO;
1802
1803	/** PDMIHOSTAUDIO interface ID. */
1804	#define PDMIHOSTAUDIO_IID "007847a0-0075-4964-007d-343f0010f081"
1805
1806	/** @} */
1807
1808	#endif /* !VBOX_INCLUDED_vmm_pdmaudioifs_h */
1809

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/VBox/vmm/pdmaudioifs.h@ 87450

Download in other formats: