pdmaudioifs.h@ 90828

Last change on this file since 90828 was 89801, checked in by vboxsync, 3 years ago
pdmaudioifs.h,AudioMix*h: Documentation. bugref:9890
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 66.3 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	* PDM provides audio device emulations and their driver chains with the
29	* interfaces they need to communicate with each other.
30	*
31	*
32	* @section sec_pdm_audio_overview Overview
33	*
34	@startuml
35	skinparam componentStyle rectangle
36
37	node VM {
38	[Music Player App] --> [Guest Audio Driver]
39	[Recording App] <-- [Guest Audio Driver]
40	}
41
42	component "DevAudio (DevHda / DevIchAc97 / DevSB16)" as DevAudio {
43	[Output DMA Engine]
44	[Input DMA Engine]
45	() LUN0
46	() LUN1
47
48	component "AudioMixer" {
49	component "Output Sink" {
50	() "Output Stream #0" as DrvStreamOut0
51	() "Output Stream #1" as DrvStreamOut1
52	[Output Mixer Buffer] --> DrvStreamOut0
53	[Output Mixer Buffer] --> DrvStreamOut1
54	[Output DMA Engine] --> [Output Mixer Buffer]
55	DrvStreamOut0 --> LUN0
56	DrvStreamOut1 --> LUN1
57	}
58	component "Input Sink" {
59	() "Input Stream #2" as DrvStreamIn0
60	() "Input Stream #3" as DrvStreamIn1
61	[Input Mixer Buffer] <-- DrvStreamIn0
62	[Input Mixer Buffer] <-- DrvStreamIn1
63	[Input DMA Engine] --> [Input Mixer Buffer]
64	DrvStreamIn0 <-- LUN0
65	DrvStreamIn1 <-- LUN1
66	}
67	}
68	}
69	[Guest Audio Driver] <..> DevAudio : " MMIO or Port I/O, DMA"
70
71	node "Driver Chain #0" {
72	component "DrvAudio#0" {
73	() PDMIHOSTAUDIOPORT0
74	() PDMIAUDIOCONNECTOR0
75	}
76	component "DrvHostAudioWasApi" {
77	() PDMIHOSTAUDIO0
78	}
79	}
80	PDMIHOSTAUDIOPORT0 <--> PDMIHOSTAUDIO0
81
82	node "Driver Chain #1" {
83	component "DrvAudio#1" {
84	() PDMIAUDIOCONNECTOR1
85	() PDMIHOSTAUDIOPORT1
86	}
87	component "DrvAudioVRDE" {
88	() PDMIHOSTAUDIO1
89	}
90	}
91	note bottom of DrvAudioVRDE
92	The backend driver is sometimes not configured if the component it represents
93	is not configured for the VM. However, Main will still set up the LUN but
94	with just DrvAudio attached to simplify runtime activation of the component.
95	In the meanwhile, the DrvAudio instance works as if DrvHostAudioNull were attached.
96	end note
97
98	LUN1 <--> PDMIAUDIOCONNECTOR1
99	LUN0 <--> PDMIAUDIOCONNECTOR0
100
101	PDMIHOSTAUDIOPORT1 <--> PDMIHOSTAUDIO1
102
103	@enduml
104	*
105	* Actors:
106	* - An audio device implementation: "DevAudio"
107	* - Mixer instance (AudioMixer.cpp) with one or more mixer
108	* sinks: "Output Sink", "Input Sink"
109	* - One DMA engine teamed up with each mixer sink: "Output DMA
110	* Engine", "Input DMA Engine"
111	* - The audio driver "DrvAudio" instances attached to LUN0 and LUN1
112	* respectively: "DrvAudio#0", "DrvAudio#1"
113	* - The Windows host audio driver attached to "DrvAudio0": "DrvHostAudioWas"
114	* - The VRDE/VRDP host audio driver attached to "DrvAudio1": "DrvAudioVRDE"
115	*
116	* Both "Output Sink" and "Input Sink" talks to all the attached driver chains
117	* ("DrvAudio #0" and "DrvAudio #1"), but using different PDMAUDIOSTREAM
118	* instances. There can be an arbritrary number of driver chains attached to an
119	* audio device, the mixer sinks will multiplex output to each of them and blend
120	* input from all of them, taking care of format and rate conversions. The
121	* mixer and mixer sinks does not fit into the PDM device/driver model, because
122	* a driver can only have exactly one or zero other drivers attached, so it is
123	* implemented as a separate component that all the audio devices share (see
124	* AudioMixer.h, AudioMixer.cpp, AudioMixBuffer.h and AudioMixBuffer.cpp).
125	*
126	* The driver chains attached to LUN0, LUN1, ... LUNn typically have two
127	* drivers attached, first DrvAudio and then a backend driver like
128	* DrvHostAudioWasApi, DrvHostAudioPulseAudio, or DrvAudioVRDE. DrvAudio
129	* exposes PDMIAUDIOCONNECTOR upwards towards the device and mixer component,
130	* and PDMIHOSTAUDIOPORT downwards towards DrvHostAudioWasApi and the other
131	* backends.
132	*
133	* The backend exposes the PDMIHOSTAUDIO upwards towards DrvAudio. It is
134	* possible, though, to only have the DrvAudio instance and not backend, in
135	* which case DrvAudio works as if the NULL backend was attached. Main does
136	* such setups when the main component we're interfacing with isn't currently
137	* active, as this simplifies runtime activation.
138	*
139	* The purpose of DrvAudio is to make the work of the backend as simple as
140	* possible and try avoid needing to write the same code over and over again for
141	* each backend. It takes care of:
142	* - Stream creation, operation, re-initialization and destruction.
143	* - Pre-buffering.
144	* - Thread pool.
145	*
146	* The purpose of a host audio driver (aka backend) is to interface with the
147	* host audio system (or other audio systems like VRDP and video recording).
148	* The backend will optionally provide a list of host audio devices, switch
149	* between them, and monitor changes to them. By default our host backends use
150	* the default host device and will trigger stream re-initialization if this
151	* changes while we're using it.
152	*
153	*
154	* @section sec_pdm_audio_device Virtual Audio Device
155	*
156	* The virtual device translates the settings of the emulated device into mixing
157	* sinks with sample format, sample rate, volume control, and whatnot.
158	*
159	* It also implements a DMA engine for transfering samples to (input) or from
160	* (output) the guest memory. The starting and stopping of the DMA engines are
161	* communicated to the associated mixing sinks and by then onto the
162	* PDMAUDIOSTREAM instance for each driver chain. A RTCIRCBUF is used as an
163	* intermediary between the DMA engine and the asynchronous worker thread of the
164	* mixing sink.
165	*
166	*
167	* @section sec_pdm_audio_mixing Audio Mixing
168	*
169	* The audio mixer is a mandatory component in an audio device. It consists of
170	* a mixer and one or more sinks with mixer buffers. The sinks are typically
171	* one per virtual output/input connector, so for instance you could have a
172	* device with a "PCM Output" sink and a "PCM Input" sink.
173	*
174	* The audio mixer takes care of:
175	* - Much of the driver chain (LUN) management work.
176	* - Multiplexing output to each active driver chain.
177	* - Blending input from each active driver chain into a single audio
178	* stream.
179	* - Do format conversion (it uses signed 32-bit PCM internally) between
180	* the audio device and all of the LUNs (no common format needed).
181	* - Do sample rate conversions between the device rate and that of the
182	* individual driver chains.
183	* - Apply the volume settings of the device to the audio stream.
184	* - Provide the asynchronous thread that pushes data from the device's
185	* internal DMA buffer and all the way to the backend for output sinks,
186	* and vice versa for input.
187	*
188	* The term active LUNs above means that not all LUNs will actually produce
189	* (input) or consume (output) audio. The mixer checks the return of
190	* PDMIHOSTAUDIO::pfnStreamGetState each time it's processing samples to see
191	* which streams are currently active and which aren't. Inactive streams are
192	* ignored.
193	*
194	* For more info: @ref pg_audio_mixer, @ref pg_audio_mixing_buffers
195	*
196	* The AudioMixer API reference can be found here:
197	* - @ref grp_pdm_ifs_audio_mixing
198	* - @ref grp_pdm_ifs_audio_mixing_buffers
199	*
200	*
201	* @section sec_pdm_audio_timing Timing
202	*
203	* Handling audio data in a virtual environment is hard, as the human perception
204	* is very sensitive to the slightest cracks and stutters in the audible data,
205	* and the task of playing back and recording audio is in the real-time domain.
206	*
207	* The virtual machine is not executed with any real-time guarentees, only best
208	* effort, mainly because it is subject to preemptive scheduling on the host
209	* side. The audio processing done on the guest side is typically also subject
210	* to preemptive scheduling on the guest side and available CPU processing power
211	* there.
212	*
213	* Thus, the guest may be lagging behind because the host prioritizes other
214	* processes/threads over the virtual machine. This will, if it's too servere,
215	* cause the virtual machine to speed up it's time sense while it's trying to
216	* catch up. So, we can easily have a bit of a seesaw execution going on here,
217	* where in the playback case, the guest produces data too slowly for while and
218	* then switches to producing it too quickly for a while to catch up.
219	*
220	* Our working principle is that the backends and the guest are producing and
221	* consuming samples at the same rate, but we have to deal with the uneven
222	* execution.
223	*
224	* To deal with this we employ (by default) 300ms of backend buffer and
225	* pre-buffer 150ms of that for both input and output audio streams. This means
226	* we have about 150ms worth of samples to feed to the host audio device should
227	* the virtual machine be starving and lagging behind. Likewise, we have about
228	* 150ms of buffer space will can fill when the VM is in a catch-up mode. Now,
229	* 300ms and 150 ms isn't much for the purpose of glossing over
230	* scheduling/timinig differences here, but we can't do too much more or the lag
231	* will grow rather annoying. The pre-buffering is implemented by DrvAudio.
232	*
233	* In addition to the backend buffer that defaults to 300ms, we have the
234	* internal DMA buffer of the device and the mixing buffer of the mixing sink.
235	* The latter two are typically rather small, sized to fit the anticipated DMA
236	* period currently in use by the guest.
237	*/
238
239	#ifndef VBOX_INCLUDED_vmm_pdmaudioifs_h
240	#define VBOX_INCLUDED_vmm_pdmaudioifs_h
241	#ifndef RT_WITHOUT_PRAGMA_ONCE
242	# pragma once
243	#endif
244
245	#include <iprt/assertcompile.h>
246	#include <iprt/critsect.h>
247	#include <iprt/circbuf.h>
248	#include <iprt/list.h>
249	#include <iprt/path.h>
250
251	#include <VBox/types.h>
252	#include <VBox/vmm/pdmcommon.h>
253	#include <VBox/vmm/stam.h>
254
255	RT_C_DECLS_BEGIN
256
257
258	/** @defgroup grp_pdm_ifs_audio PDM Audio Interfaces
259	* @ingroup grp_pdm_interfaces
260	* @{
261	*/
262
263	/** The maximum number of channels PDM supports. */
264	#define PDMAUDIO_MAX_CHANNELS 12
265
266	/**
267	* Audio direction.
268	*/
269	typedef enum PDMAUDIODIR
270	{
271	/** Invalid zero value as per usual (guards against using unintialized values). */
272	PDMAUDIODIR_INVALID = 0,
273	/** Unknown direction. */
274	PDMAUDIODIR_UNKNOWN,
275	/** Input. */
276	PDMAUDIODIR_IN,
277	/** Output. */
278	PDMAUDIODIR_OUT,
279	/** Duplex handling. */
280	PDMAUDIODIR_DUPLEX,
281	/** End of valid values. */
282	PDMAUDIODIR_END,
283	/** Hack to blow the type up to 32-bit. */
284	PDMAUDIODIR_32BIT_HACK = 0x7fffffff
285	} PDMAUDIODIR;
286
287
288	/** @name PDMAUDIOHOSTDEV_F_XXX
289	* @{ */
290	/** No flags set. */
291	#define PDMAUDIOHOSTDEV_F_NONE UINT32_C(0)
292	/** The default input (capture/recording) device (for the user). */
293	#define PDMAUDIOHOSTDEV_F_DEFAULT_IN RT_BIT_32(0)
294	/** The default output (playback) device (for the user). */
295	#define PDMAUDIOHOSTDEV_F_DEFAULT_OUT RT_BIT_32(1)
296	/** The device can be removed at any time and we have to deal with it. */
297	#define PDMAUDIOHOSTDEV_F_HOTPLUG RT_BIT_32(2)
298	/** The device is known to be buggy and needs special treatment. */
299	#define PDMAUDIOHOSTDEV_F_BUGGY RT_BIT_32(3)
300	/** Ignore the device, no matter what. */
301	#define PDMAUDIOHOSTDEV_F_IGNORE RT_BIT_32(4)
302	/** The device is present but marked as locked by some other application. */
303	#define PDMAUDIOHOSTDEV_F_LOCKED RT_BIT_32(5)
304	/** The device is present but not in an alive state (dead). */
305	#define PDMAUDIOHOSTDEV_F_DEAD RT_BIT_32(6)
306	/** Set if the PDMAUDIOHOSTDEV::pszName is allocated. */
307	#define PDMAUDIOHOSTDEV_F_NAME_ALLOC RT_BIT_32(29)
308	/** Set if the PDMAUDIOHOSTDEV::pszId is allocated. */
309	#define PDMAUDIOHOSTDEV_F_ID_ALLOC RT_BIT_32(30)
310	/** Set if the extra backend specific data cannot be duplicated. */
311	#define PDMAUDIOHOSTDEV_F_NO_DUP RT_BIT_32(31)
312	/** @} */
313
314	/**
315	* Audio device type.
316	*/
317	typedef enum PDMAUDIODEVICETYPE
318	{
319	/** Invalid zero value as per usual (guards against using unintialized values). */
320	PDMAUDIODEVICETYPE_INVALID = 0,
321	/** Unknown device type. This is the default. */
322	PDMAUDIODEVICETYPE_UNKNOWN,
323	/** Dummy device; for backends which are not able to report
324	* actual device information (yet). */
325	PDMAUDIODEVICETYPE_DUMMY,
326	/** The device is built into the host (non-removable). */
327	PDMAUDIODEVICETYPE_BUILTIN,
328	/** The device is an (external) USB device. */
329	PDMAUDIODEVICETYPE_USB,
330	/** End of valid values. */
331	PDMAUDIODEVICETYPE_END,
332	/** Hack to blow the type up to 32-bit. */
333	PDMAUDIODEVICETYPE_32BIT_HACK = 0x7fffffff
334	} PDMAUDIODEVICETYPE;
335
336	/**
337	* Host audio device info, part of enumeration result.
338	*
339	* @sa PDMAUDIOHOSTENUM, PDMIHOSTAUDIO::pfnGetDevices
340	*/
341	typedef struct PDMAUDIOHOSTDEV
342	{
343	/** List entry (like PDMAUDIOHOSTENUM::LstDevices). */
344	RTLISTNODE ListEntry;
345	/** Magic value (PDMAUDIOHOSTDEV_MAGIC). */
346	uint32_t uMagic;
347	/** Size of this structure and whatever backend specific data that follows it. */
348	uint32_t cbSelf;
349	/** The device type. */
350	PDMAUDIODEVICETYPE enmType;
351	/** Usage of the device. */
352	PDMAUDIODIR enmUsage;
353	/** Device flags, PDMAUDIOHOSTDEV_F_XXX. */
354	uint32_t fFlags;
355	/** Maximum number of input audio channels the device supports. */
356	uint8_t cMaxInputChannels;
357	/** Maximum number of output audio channels the device supports. */
358	uint8_t cMaxOutputChannels;
359	uint8_t abAlignment[ARCH_BITS == 32 ? 2 + 8 : 2 + 8];
360	/** Backend specific device identifier, can be NULL, used to select device.
361	* This can either point into some non-public part of this structure or to a
362	* RTStrAlloc allocation. PDMAUDIOHOSTDEV_F_ID_ALLOC is set in the latter
363	* case.
364	* @sa PDMIHOSTAUDIO::pfnSetDevice */
365	char *pszId;
366	/** The friendly device name. */
367	char *pszName;
368	} PDMAUDIOHOSTDEV;
369	AssertCompileSizeAlignment(PDMAUDIOHOSTDEV, 16);
370	/** Pointer to audio device info (enumeration result). */
371	typedef PDMAUDIOHOSTDEV *PPDMAUDIOHOSTDEV;
372	/** Pointer to a const audio device info (enumeration result). */
373	typedef PDMAUDIOHOSTDEV const *PCPDMAUDIOHOSTDEV;
374
375	/** Magic value for PDMAUDIOHOSTDEV. */
376	#define PDMAUDIOHOSTDEV_MAGIC PDM_VERSION_MAKE(0xa0d0, 3, 0)
377
378
379	/**
380	* A host audio device enumeration result.
381	*
382	* @sa PDMIHOSTAUDIO::pfnGetDevices
383	*/
384	typedef struct PDMAUDIOHOSTENUM
385	{
386	/** Magic value (PDMAUDIOHOSTENUM_MAGIC). */
387	uint32_t uMagic;
388	/** Number of audio devices in the list. */
389	uint32_t cDevices;
390	/** List of audio devices (PDMAUDIOHOSTDEV). */
391	RTLISTANCHOR LstDevices;
392	} PDMAUDIOHOSTENUM;
393	/** Pointer to an audio device enumeration result. */
394	typedef PDMAUDIOHOSTENUM *PPDMAUDIOHOSTENUM;
395	/** Pointer to a const audio device enumeration result. */
396	typedef PDMAUDIOHOSTENUM const *PCPDMAUDIOHOSTENUM;
397
398	/** Magic for the host audio device enumeration. */
399	#define PDMAUDIOHOSTENUM_MAGIC PDM_VERSION_MAKE(0xa0d1, 1, 0)
400
401
402	/**
403	* Audio configuration (static) of an audio host backend.
404	*/
405	typedef struct PDMAUDIOBACKENDCFG
406	{
407	/** The backend's friendly name. */
408	char szName[32];
409	/** The size of the backend specific stream data (in bytes). */
410	uint32_t cbStream;
411	/** PDMAUDIOBACKEND_F_XXX. */
412	uint32_t fFlags;
413	/** Number of concurrent output (playback) streams supported on the host.
414	* UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
415	uint32_t cMaxStreamsOut;
416	/** Number of concurrent input (recording) streams supported on the host.
417	* UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
418	uint32_t cMaxStreamsIn;
419	} PDMAUDIOBACKENDCFG;
420	/** Pointer to a static host audio audio configuration. */
421	typedef PDMAUDIOBACKENDCFG *PPDMAUDIOBACKENDCFG;
422
423	/** @name PDMAUDIOBACKEND_F_XXX - PDMAUDIOBACKENDCFG::fFlags
424	* @{ */
425	/** PDMIHOSTAUDIO::pfnStreamConfigHint should preferably be called on a
426	* worker thread rather than EMT as it may take a good while. */
427	#define PDMAUDIOBACKEND_F_ASYNC_HINT RT_BIT_32(0)
428	/** PDMIHOSTAUDIO::pfnStreamDestroy and any preceeding
429	* PDMIHOSTAUDIO::pfnStreamControl/DISABLE should be preferably be called on a
430	* worker thread rather than EMT as it may take a good while. */
431	#define PDMAUDIOBACKEND_F_ASYNC_STREAM_DESTROY RT_BIT_32(1)
432	/** @} */
433
434
435	/**
436	* Audio path: input sources and playback destinations.
437	*
438	* Think of this as the name of the socket you plug the virtual audio stream
439	* jack into.
440	*
441	* @note Not quite sure what the purpose of this type is. It used to be two
442	* separate enums (PDMAUDIOPLAYBACKDST & PDMAUDIORECSRC) without overlapping
443	* values and most commonly used in a union (PDMAUDIODSTSRCUNION). The output
444	* values were designated "channel" (e.g. "Front channel"), whereas this was not
445	* done to the input ones. So, I'm (bird) a little confused what the actual
446	* meaning was.
447	*/
448	typedef enum PDMAUDIOPATH
449	{
450	/** Customary invalid zero value. */
451	PDMAUDIOPATH_INVALID = 0,
452
453	/** Unknown path / Doesn't care. */
454	PDMAUDIOPATH_UNKNOWN,
455
456	/** First output value. */
457	PDMAUDIOPATH_OUT_FIRST,
458	/** Output: Front. */
459	PDMAUDIOPATH_OUT_FRONT = PDMAUDIOPATH_OUT_FIRST,
460	/** Output: Center / LFE (Subwoofer). */
461	PDMAUDIOPATH_OUT_CENTER_LFE,
462	/** Output: Rear. */
463	PDMAUDIOPATH_OUT_REAR,
464	/** Last output value (inclusive) */
465	PDMAUDIOPATH_OUT_END = PDMAUDIOPATH_OUT_REAR,
466
467	/** First input value. */
468	PDMAUDIOPATH_IN_FIRST,
469	/** Input: Microphone. */
470	PDMAUDIOPATH_IN_MIC = PDMAUDIOPATH_IN_FIRST,
471	/** Input: CD. */
472	PDMAUDIOPATH_IN_CD,
473	/** Input: Video-In. */
474	PDMAUDIOPATH_IN_VIDEO,
475	/** Input: AUX. */
476	PDMAUDIOPATH_IN_AUX,
477	/** Input: Line-In. */
478	PDMAUDIOPATH_IN_LINE,
479	/** Input: Phone-In. */
480	PDMAUDIOPATH_IN_PHONE,
481	/** Last intput value (inclusive). */
482	PDMAUDIOPATH_IN_LAST = PDMAUDIOPATH_IN_PHONE,
483
484	/** End of valid values. */
485	PDMAUDIOPATH_END,
486	/** Hack to blow the typ up to 32 bits. */
487	PDMAUDIOPATH_32BIT_HACK = 0x7fffffff
488	} PDMAUDIOPATH;
489
490
491	/**
492	* Standard speaker channel IDs.
493	*/
494	typedef enum PDMAUDIOCHANNELID
495	{
496	/** Invalid zero value as per usual (guards against using unintialized values). */
497	PDMAUDIOCHANNELID_INVALID = 0,
498
499	/** Unused channel - fill with zero when encoding, ignore when decoding. */
500	PDMAUDIOCHANNELID_UNUSED_ZERO,
501	/** Unused channel - fill with silence when encoding, ignore when decoding. */
502	PDMAUDIOCHANNELID_UNUSED_SILENCE,
503
504	/** Unknown channel ID (unable to map to PDM terms). */
505	PDMAUDIOCHANNELID_UNKNOWN,
506
507	/** The first ID in the standard WAV-file assignment block. */
508	PDMAUDIOCHANNELID_FIRST_STANDARD,
509	/** Front left channel (FR). */
510	PDMAUDIOCHANNELID_FRONT_LEFT = PDMAUDIOCHANNELID_FIRST_STANDARD,
511	/** Front right channel (FR). */
512	PDMAUDIOCHANNELID_FRONT_RIGHT,
513	/** Front center channel (FC). */
514	PDMAUDIOCHANNELID_FRONT_CENTER,
515	/** Mono channel (alias for front center). */
516	PDMAUDIOCHANNELID_MONO = PDMAUDIOCHANNELID_FRONT_CENTER,
517	/** Low frequency effects (subwoofer) channel. */
518	PDMAUDIOCHANNELID_LFE,
519	/** Rear left channel (BL). */
520	PDMAUDIOCHANNELID_REAR_LEFT,
521	/** Rear right channel (BR). */
522	PDMAUDIOCHANNELID_REAR_RIGHT,
523	/** Front left of center channel (FLC). */
524	PDMAUDIOCHANNELID_FRONT_LEFT_OF_CENTER,
525	/** Front right of center channel (FLR). */
526	PDMAUDIOCHANNELID_FRONT_RIGHT_OF_CENTER,
527	/** Rear center channel (BC). */
528	PDMAUDIOCHANNELID_REAR_CENTER,
529	/** Side left channel (SL). */
530	PDMAUDIOCHANNELID_SIDE_LEFT,
531	/** Side right channel (SR). */
532	PDMAUDIOCHANNELID_SIDE_RIGHT,
533	/** Top center (TC). */
534	PDMAUDIOCHANNELID_TOP_CENTER,
535	/** Front left height channel (TFL). */
536	PDMAUDIOCHANNELID_FRONT_LEFT_HEIGHT,
537	/** Front center height channel (TFC). */
538	PDMAUDIOCHANNELID_FRONT_CENTER_HEIGHT,
539	/** Front right height channel (TFR). */
540	PDMAUDIOCHANNELID_FRONT_RIGHT_HEIGHT,
541	/** Rear left height channel (TBL). */
542	PDMAUDIOCHANNELID_REAR_LEFT_HEIGHT,
543	/** Rear center height channel (TBC). */
544	PDMAUDIOCHANNELID_REAR_CENTER_HEIGHT,
545	/** Rear right height channel (TBR). */
546	PDMAUDIOCHANNELID_REAR_RIGHT_HEIGHT,
547	/** The end of the standard WAV-file assignment block. */
548	PDMAUDIOCHANNELID_END_STANDARD,
549
550	/** End of valid values. */
551	PDMAUDIOCHANNELID_END = PDMAUDIOCHANNELID_END_STANDARD,
552	/** Hack to blow the type up to 32-bit. */
553	PDMAUDIOCHANNELID_32BIT_HACK = 0x7fffffff
554	} PDMAUDIOCHANNELID;
555	AssertCompile(PDMAUDIOCHANNELID_FRONT_LEFT - PDMAUDIOCHANNELID_FIRST_STANDARD == 0);
556	AssertCompile(PDMAUDIOCHANNELID_LFE - PDMAUDIOCHANNELID_FIRST_STANDARD == 3);
557	AssertCompile(PDMAUDIOCHANNELID_REAR_CENTER - PDMAUDIOCHANNELID_FIRST_STANDARD == 8);
558	AssertCompile(PDMAUDIOCHANNELID_REAR_RIGHT_HEIGHT - PDMAUDIOCHANNELID_FIRST_STANDARD == 17);
559
560
561	/**
562	* Properties of audio streams for host/guest for in or out directions.
563	*/
564	typedef struct PDMAUDIOPCMPROPS
565	{
566	/** The frame size. */
567	uint8_t cbFrame;
568	/** Shift count used with PDMAUDIOPCMPROPS_F2B and PDMAUDIOPCMPROPS_B2F.
569	* Depends on number of stream channels and the stream format being used, calc
570	* value using PDMAUDIOPCMPROPS_MAKE_SHIFT.
571	* @sa PDMAUDIOSTREAMCFG_B2F, PDMAUDIOSTREAMCFG_F2B */
572	uint8_t cShiftX;
573	/** Sample width (in bytes). */
574	RT_GCC_EXTENSION
575	uint8_t cbSampleX : 4;
576	/** Number of audio channels. */
577	RT_GCC_EXTENSION
578	uint8_t cChannelsX : 4;
579	/** Signed or unsigned sample. */
580	bool fSigned : 1;
581	/** Whether the endianness is swapped or not. */
582	bool fSwapEndian : 1;
583	/** Raw mixer frames, only applicable for signed 64-bit samples.
584	* The raw mixer samples are really just signed 32-bit samples stored as 64-bit
585	* integers without any change in the value.
586	*
587	* @todo Get rid of this, only VRDE needs it an it should use the common
588	* mixer code rather than cooking its own stuff. */
589	bool fRaw : 1;
590	/** Sample frequency in Hertz (Hz). */
591	uint32_t uHz;
592	/** PDMAUDIOCHANNELID mappings for each channel.
593	* This ASSUMES all channels uses the same sample size. */
594	uint8_t aidChannels[PDMAUDIO_MAX_CHANNELS];
595	/** Padding the structure up to 32 bytes. */
596	uint32_t auPadding[3];
597	} PDMAUDIOPCMPROPS;
598	AssertCompileSize(PDMAUDIOPCMPROPS, 32);
599	AssertCompileSizeAlignment(PDMAUDIOPCMPROPS, 8);
600	/** Pointer to audio stream properties. */
601	typedef PDMAUDIOPCMPROPS *PPDMAUDIOPCMPROPS;
602	/** Pointer to const audio stream properties. */
603	typedef PDMAUDIOPCMPROPS const *PCPDMAUDIOPCMPROPS;
604
605	/** @name Macros for use with PDMAUDIOPCMPROPS
606	* @{ */
607	/** Initializer for PDMAUDIOPCMPROPS.
608	* @note The default channel mapping here is very simple and doesn't always
609	* match that of PDMAudioPropsInit and PDMAudioPropsInitEx. */
610	#define PDMAUDIOPCMPROPS_INITIALIZER(a_cbSample, a_fSigned, a_cChannels, a_uHz, a_fSwapEndian) \
611	{ \
612	(uint8_t)((a_cbSample) * (a_cChannels)), PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS(a_cbSample, a_cChannels), \
613	(uint8_t)(a_cbSample), (uint8_t)(a_cChannels), a_fSigned, a_fSwapEndian, false /fRaw/, a_uHz, \
614	/aidChannels =/ { \
615	(a_cChannels) > 1 ? PDMAUDIOCHANNELID_FRONT_LEFT : PDMAUDIOCHANNELID_MONO, \
616	(a_cChannels) >= 2 ? PDMAUDIOCHANNELID_FRONT_RIGHT : PDMAUDIOCHANNELID_INVALID, \
617	(a_cChannels) >= 3 ? PDMAUDIOCHANNELID_FRONT_CENTER : PDMAUDIOCHANNELID_INVALID, \
618	(a_cChannels) >= 4 ? PDMAUDIOCHANNELID_LFE : PDMAUDIOCHANNELID_INVALID, \
619	(a_cChannels) >= 5 ? PDMAUDIOCHANNELID_REAR_LEFT : PDMAUDIOCHANNELID_INVALID, \
620	(a_cChannels) >= 6 ? PDMAUDIOCHANNELID_REAR_RIGHT : PDMAUDIOCHANNELID_INVALID, \
621	(a_cChannels) >= 7 ? PDMAUDIOCHANNELID_FRONT_LEFT_OF_CENTER : PDMAUDIOCHANNELID_INVALID, \
622	(a_cChannels) >= 8 ? PDMAUDIOCHANNELID_FRONT_RIGHT_OF_CENTER : PDMAUDIOCHANNELID_INVALID, \
623	(a_cChannels) >= 9 ? PDMAUDIOCHANNELID_REAR_CENTER : PDMAUDIOCHANNELID_INVALID, \
624	(a_cChannels) >= 10 ? PDMAUDIOCHANNELID_SIDE_LEFT : PDMAUDIOCHANNELID_INVALID, \
625	(a_cChannels) >= 11 ? PDMAUDIOCHANNELID_SIDE_RIGHT : PDMAUDIOCHANNELID_INVALID, \
626	(a_cChannels) >= 12 ? PDMAUDIOCHANNELID_UNKNOWN : PDMAUDIOCHANNELID_INVALID, \
627	}, \
628	/* auPadding = */ { 0, 0, 0 } \
629	}
630
631	/** Calculates the cShift value of given sample bits and audio channels.
632	* @note Does only support mono/stereo channels for now, for non-stereo/mono we
633	* returns a special value which the two conversion functions detect
634	* and make them fall back on cbSample * cChannels. */
635	#define PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS(cbSample, cChannels) \
636	( RT_IS_POWER_OF_TWO((unsigned)((cChannels) * (cbSample))) \
637	? (uint8_t)(ASMBitFirstSetU32((unsigned)((cChannels) * (cbSample))) - 1) : (uint8_t)UINT8_MAX )
638	/** Calculates the cShift value of a PDMAUDIOPCMPROPS structure. */
639	#define PDMAUDIOPCMPROPS_MAKE_SHIFT(pProps) \
640	PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS((pProps)->cbSampleX, (pProps)->cChannelsX)
641	/** Converts (audio) frames to bytes.
642	* @note Requires properly initialized properties, i.e. cbFrames correctly calculated
643	* and cShift set using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
644	#define PDMAUDIOPCMPROPS_F2B(pProps, cFrames) \
645	( (pProps)->cShiftX != UINT8_MAX ? (cFrames) << (pProps)->cShiftX : (cFrames) * (pProps)->cbFrame )
646	/** Converts bytes to (audio) frames.
647	* @note Requires properly initialized properties, i.e. cbFrames correctly calculated
648	* and cShift set using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
649	#define PDMAUDIOPCMPROPS_B2F(pProps, cb) \
650	( (pProps)->cShiftX != UINT8_MAX ? (cb) >> (pProps)->cShiftX : (cb) / (pProps)->cbFrame )
651	/** @} */
652
653	/**
654	* An audio stream configuration.
655	*/
656	typedef struct PDMAUDIOSTREAMCFG
657	{
658	/** The stream's PCM properties. */
659	PDMAUDIOPCMPROPS Props;
660	/** Direction of the stream. */
661	PDMAUDIODIR enmDir;
662	/** Destination / source path. */
663	PDMAUDIOPATH enmPath;
664	/** Device emulation-specific data needed for the audio connector. */
665	struct
666	{
667	/** Scheduling hint set by the device emulation about when this stream is being served on average (in ms).
668	* Can be 0 if not hint given or some other mechanism (e.g. callbacks) is being used. */
669	uint32_t cMsSchedulingHint;
670	} Device;
671	/**
672	* Backend-specific data for the stream.
673	* On input (requested configuration) those values are set by the audio connector to let the backend know what we expect.
674	* On output (acquired configuration) those values reflect the values set and used by the backend.
675	* Set by the backend on return. Not all backends support all values / features.
676	*/
677	struct
678	{
679	/** Period size of the stream (in audio frames).
680	* This value reflects the number of audio frames in between each hardware interrupt on the
681	* backend (host) side. 0 if not set / available by the backend. */
682	uint32_t cFramesPeriod;
683	/** (Ring) buffer size (in audio frames). Often is a multiple of cFramesPeriod.
684	* 0 if not set / available by the backend. */
685	uint32_t cFramesBufferSize;
686	/** Pre-buffering size (in audio frames). Frames needed in buffer before the stream becomes active (pre buffering).
687	* The bigger this value is, the more latency for the stream will occur.
688	* 0 if not set / available by the backend. UINT32_MAX if not defined (yet). */
689	uint32_t cFramesPreBuffering;
690	} Backend;
691	/** Friendly name of the stream. */
692	char szName[64];
693	} PDMAUDIOSTREAMCFG;
694	AssertCompileSizeAlignment(PDMAUDIOSTREAMCFG, 8);
695	/** Pointer to audio stream configuration keeper. */
696	typedef PDMAUDIOSTREAMCFG *PPDMAUDIOSTREAMCFG;
697	/** Pointer to a const audio stream configuration keeper. */
698	typedef PDMAUDIOSTREAMCFG const *PCPDMAUDIOSTREAMCFG;
699
700	/** Converts (audio) frames to bytes. */
701	#define PDMAUDIOSTREAMCFG_F2B(pCfg, frames) PDMAUDIOPCMPROPS_F2B(&(pCfg)->Props, (frames))
702	/** Converts bytes to (audio) frames. */
703	#define PDMAUDIOSTREAMCFG_B2F(pCfg, cb) PDMAUDIOPCMPROPS_B2F(&(pCfg)->Props, (cb))
704
705	/**
706	* Audio stream commands.
707	*
708	* Used in the audio connector as well as in the actual host backends.
709	*/
710	typedef enum PDMAUDIOSTREAMCMD
711	{
712	/** Invalid zero value as per usual (guards against using unintialized values). */
713	PDMAUDIOSTREAMCMD_INVALID = 0,
714	/** Enables the stream. */
715	PDMAUDIOSTREAMCMD_ENABLE,
716	/** Pauses the stream.
717	* This is currently only issued when the VM is suspended (paused).
718	* @remarks This is issued by DrvAudio, never by the mixer or devices. */
719	PDMAUDIOSTREAMCMD_PAUSE,
720	/** Resumes the stream.
721	* This is currently only issued when the VM is resumed.
722	* @remarks This is issued by DrvAudio, never by the mixer or devices. */
723	PDMAUDIOSTREAMCMD_RESUME,
724	/** Drain the stream, that is, play what's in the buffers and then stop.
725	*
726	* There will be no more samples written after this command is issued.
727	* PDMIAUDIOCONNECTOR::pfnStreamIterate will drive progress for DrvAudio and
728	* calls to PDMIHOSTAUDIO::pfnStreamPlay with a zero sized buffer will provide
729	* the backend with a way to drive it forwards. These calls will come at a
730	* frequency set by the device and be on an asynchronous I/O thread.
731	*
732	* A DISABLE command maybe submitted if the device/mixer wants to re-enable the
733	* stream while it's still draining or if it gets impatient and thinks the
734	* draining has been going on too long, in which case the stream should stop
735	* immediately.
736	*
737	* @note This should not wait for the stream to finish draining, just change
738	* the state. (The caller could be an EMT and it must not block for
739	* hundreds of milliseconds of buffer to finish draining.)
740	*
741	* @note Does not apply to input streams. Backends should refuse such requests. */
742	PDMAUDIOSTREAMCMD_DRAIN,
743	/** Stops the stream immediately w/o any draining. */
744	PDMAUDIOSTREAMCMD_DISABLE,
745	/** End of valid values. */
746	PDMAUDIOSTREAMCMD_END,
747	/** Hack to blow the type up to 32-bit. */
748	PDMAUDIOSTREAMCMD_32BIT_HACK = 0x7fffffff
749	} PDMAUDIOSTREAMCMD;
750
751	/**
752	* Backend status.
753	*/
754	typedef enum PDMAUDIOBACKENDSTS
755	{
756	/** Unknown/invalid status. */
757	PDMAUDIOBACKENDSTS_UNKNOWN = 0,
758	/** No backend attached. */
759	PDMAUDIOBACKENDSTS_NOT_ATTACHED,
760	/** The backend is in its initialization phase.
761	* Not all backends support this status. */
762	PDMAUDIOBACKENDSTS_INITIALIZING,
763	/** The backend has stopped its operation. */
764	PDMAUDIOBACKENDSTS_STOPPED,
765	/** The backend is up and running. */
766	PDMAUDIOBACKENDSTS_RUNNING,
767	/** The backend ran into an error and is unable to recover.
768	* A manual re-initialization might help. */
769	PDMAUDIOBACKENDSTS_ERROR,
770	/** Hack to blow the type up to 32-bit. */
771	PDMAUDIOBACKENDSTS_32BIT_HACK = 0x7fffffff
772	} PDMAUDIOBACKENDSTS;
773
774	/**
775	* PDM audio stream state.
776	*
777	* This is all the mixer/device needs. The PDMAUDIOSTREAM_STS_XXX stuff will
778	* become DrvAudio internal state once the backend stuff is destilled out of it.
779	*
780	* @note The value order is significant, don't change it willy-nilly.
781	*/
782	typedef enum PDMAUDIOSTREAMSTATE
783	{
784	/** Invalid state value. */
785	PDMAUDIOSTREAMSTATE_INVALID = 0,
786	/** The stream is not operative and cannot be enabled. */
787	PDMAUDIOSTREAMSTATE_NOT_WORKING,
788	/** The stream needs to be re-initialized by the device/mixer
789	* (i.e. call PDMIAUDIOCONNECTOR::pfnStreamReInit). */
790	PDMAUDIOSTREAMSTATE_NEED_REINIT,
791	/** The stream is inactive (not enabled). */
792	PDMAUDIOSTREAMSTATE_INACTIVE,
793	/** The stream is enabled but nothing to read/write.
794	* @todo not sure if we need this variant... */
795	PDMAUDIOSTREAMSTATE_ENABLED,
796	/** The stream is enabled and captured samples can be read. */
797	PDMAUDIOSTREAMSTATE_ENABLED_READABLE,
798	/** The stream is enabled and samples can be written for playback. */
799	PDMAUDIOSTREAMSTATE_ENABLED_WRITABLE,
800	/** End of valid states. */
801	PDMAUDIOSTREAMSTATE_END,
802	/** Make sure the type is 32-bit wide. */
803	PDMAUDIOSTREAMSTATE_32BIT_HACK = 0x7fffffff
804	} PDMAUDIOSTREAMSTATE;
805
806	/** @name PDMAUDIOSTREAM_CREATE_F_XXX
807	* @{ */
808	/** Does not need any mixing buffers, the device takes care of all conversion.
809	* @note this is now default and assumed always set. */
810	#define PDMAUDIOSTREAM_CREATE_F_NO_MIXBUF RT_BIT_32(0)
811	/** @} */
812
813	/** @name PDMAUDIOSTREAM_WARN_FLAGS_XXX
814	* @{ */
815	/** No stream warning flags set. */
816	#define PDMAUDIOSTREAM_WARN_FLAGS_NONE 0
817	/** Warned about a disabled stream. */
818	#define PDMAUDIOSTREAM_WARN_FLAGS_DISABLED RT_BIT(0)
819	/** @} */
820
821	/**
822	* An input or output audio stream.
823	*/
824	typedef struct PDMAUDIOSTREAM
825	{
826	/** Critical section protecting the stream.
827	*
828	* When not otherwise stated, DrvAudio will enter this before calling the
829	* backend. The backend and device/mixer can normally safely enter it prior to
830	* a DrvAudio call, however not to pfnStreamDestroy, pfnStreamRelease or
831	* anything that may access the stream list.
832	*
833	* @note Lock ordering:
834	* - After DRVAUDIO::CritSectGlobals.
835	* - Before DRVAUDIO::CritSectHotPlug. */
836	RTCRITSECT CritSect;
837	/** Stream configuration. */
838	PDMAUDIOSTREAMCFG Cfg;
839	/** Magic value (PDMAUDIOSTREAM_MAGIC). */
840	uint32_t uMagic;
841	/** Size (in bytes) of the backend-specific stream data. */
842	uint32_t cbBackend;
843	/** Warnings shown already in the release log.
844	* See PDMAUDIOSTREAM_WARN_FLAGS_XXX. */
845	uint32_t fWarningsShown;
846	} PDMAUDIOSTREAM;
847	/** Pointer to an audio stream. */
848	typedef struct PDMAUDIOSTREAM *PPDMAUDIOSTREAM;
849	/** Pointer to a const audio stream. */
850	typedef struct PDMAUDIOSTREAM const *PCPDMAUDIOSTREAM;
851
852	/** Magic value for PDMAUDIOSTREAM. */
853	#define PDMAUDIOSTREAM_MAGIC PDM_VERSION_MAKE(0xa0d3, 5, 0)
854
855
856
857	/** Pointer to a audio connector interface. */
858	typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
859
860	/**
861	* Audio connector interface (up).
862	*/
863	typedef struct PDMIAUDIOCONNECTOR
864	{
865	/**
866	* Enables or disables the given audio direction for this driver.
867	*
868	* When disabled, assiociated output streams consume written audio without passing them further down to the backends.
869	* Associated input streams then return silence when read from those.
870	*
871	* @returns VBox status code.
872	* @param pInterface Pointer to the interface structure containing the called function pointer.
873	* @param enmDir Audio direction to enable or disable driver for.
874	* @param fEnable Whether to enable or disable the specified audio direction.
875	*
876	* @note Be very careful when using this function, as this could
877	* violate / run against the (global) VM settings. See @bugref{9882}.
878	*/
879	DECLR3CALLBACKMEMBER(int, pfnEnable, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir, bool fEnable));
880
881	/**
882	* Returns whether the given audio direction for this driver is enabled or not.
883	*
884	* @returns True if audio is enabled for the given direction, false if not.
885	* @param pInterface Pointer to the interface structure containing the called function pointer.
886	* @param enmDir Audio direction to retrieve enabled status for.
887	*/
888	DECLR3CALLBACKMEMBER(bool, pfnIsEnabled, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
889
890	/**
891	* Retrieves the current configuration of the host audio backend.
892	*
893	* @returns VBox status code.
894	* @param pInterface Pointer to the interface structure containing the called function pointer.
895	* @param pCfg Where to store the host audio backend configuration data.
896	*/
897	DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOBACKENDCFG pCfg));
898
899	/**
900	* Retrieves the current status of the host audio backend.
901	*
902	* @returns Status of the host audio backend.
903	* @param pInterface Pointer to the interface structure containing the called function pointer.
904	* @param enmDir Audio direction to check host audio backend for. Specify PDMAUDIODIR_DUPLEX for the overall
905	* backend status.
906	*/
907	DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
908
909	/**
910	* Gives the audio drivers a hint about a typical configuration.
911	*
912	* This is a little hack for windows (and maybe other hosts) where stream
913	* creation can take a relatively long time, making it very unsuitable for EMT.
914	* The audio backend can use this hint to cache pre-configured stream setups,
915	* so that when the guest actually wants to play something EMT won't be blocked
916	* configuring host audio.
917	*
918	* @param pInterface Pointer to this interface.
919	* @param pCfg The typical configuration. Can be modified by the
920	* drivers in unspecified ways.
921	*/
922	DECLR3CALLBACKMEMBER(void, pfnStreamConfigHint, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfg));
923
924	/**
925	* Creates an audio stream.
926	*
927	* @returns VBox status code.
928	* @param pInterface Pointer to this interface.
929	* @param fFlags PDMAUDIOSTREAM_CREATE_F_XXX.
930	* @param pCfgReq The requested stream configuration. The actual stream
931	* configuration can be found in pStream->Cfg on success.
932	* @param ppStream Pointer where to return the created audio stream on
933	* success.
934	*/
935	DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIAUDIOCONNECTOR pInterface, uint32_t fFlags, PCPDMAUDIOSTREAMCFG pCfgReq,
936	PPDMAUDIOSTREAM *ppStream));
937
938
939	/**
940	* Destroys an audio stream.
941	*
942	* @param pInterface Pointer to the interface structure containing the called function pointer.
943	* @param pStream Pointer to audio stream.
944	* @param fImmediate Whether to immdiately stop and destroy a draining
945	* stream (@c true), or to allow it to complete
946	* draining first (@c false) if that's feasable.
947	* The latter depends on the draining stage and what
948	* the backend is capable of.
949	*/
950	DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, bool fImmediate));
951
952	/**
953	* Re-initializes the stream in response to PDMAUDIOSTREAM_STS_NEED_REINIT.
954	*
955	* @returns VBox status code.
956	* @param pInterface Pointer to this interface.
957	* @param pStream The audio stream needing re-initialization.
958	*/
959	DECLR3CALLBACKMEMBER(int, pfnStreamReInit, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
960
961	/**
962	* Adds a reference to the specified audio stream.
963	*
964	* @returns New reference count. UINT32_MAX on error.
965	* @param pInterface Pointer to the interface structure containing the called function pointer.
966	* @param pStream Pointer to audio stream adding the reference to.
967	*/
968	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRetain, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
969
970	/**
971	* Releases a reference from the specified stream.
972	*
973	* @returns New reference count. UINT32_MAX on error.
974	* @param pInterface Pointer to the interface structure containing the called function pointer.
975	* @param pStream Pointer to audio stream releasing a reference from.
976	*/
977	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRelease, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
978
979	/**
980	* Controls a specific audio stream.
981	*
982	* @returns VBox status code.
983	* @param pInterface Pointer to the interface structure containing the called function pointer.
984	* @param pStream Pointer to audio stream.
985	* @param enmStreamCmd The stream command to issue.
986	*/
987	DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
988	PDMAUDIOSTREAMCMD enmStreamCmd));
989
990	/**
991	* Processes stream data.
992	*
993	* @param pInterface Pointer to the interface structure containing the called function pointer.
994	* @param pStream Pointer to audio stream.
995	*/
996	DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
997
998	/**
999	* Returns the state of a specific audio stream (destilled status).
1000	*
1001	* @returns PDMAUDIOSTREAMSTATE value.
1002	* @retval PDMAUDIOSTREAMSTATE_INVALID if the input isn't valid (w/ assertion).
1003	* @param pInterface Pointer to the interface structure containing the called function pointer.
1004	* @param pStream Pointer to audio stream.
1005	*/
1006	DECLR3CALLBACKMEMBER(PDMAUDIOSTREAMSTATE, pfnStreamGetState, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1007
1008	/**
1009	* Returns the number of bytes that can be written to an audio output stream.
1010	*
1011	* @returns Number of bytes writable data.
1012	* @param pInterface Pointer to the interface structure containing the called function pointer.
1013	* @param pStream Pointer to audio stream.
1014	*/
1015	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1016
1017	/**
1018	* Plays (writes to) an audio output stream.
1019	*
1020	* @returns VBox status code.
1021	* @param pInterface Pointer to the interface structure containing the called function pointer.
1022	* @param pStream Pointer to audio stream to read from.
1023	* @param pvBuf Audio data to be written.
1024	* @param cbBuf Number of bytes to be written.
1025	* @param pcbWritten Bytes of audio data written. Optional.
1026	*/
1027	DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1028	const void pvBuf, uint32_t cbBuf, uint32_t pcbWritten));
1029
1030	/**
1031	* Returns the number of bytes that can be read from an input stream.
1032	*
1033	* @returns Number of bytes of readable data.
1034	* @param pInterface Pointer to the interface structure containing the called function pointer.
1035	* @param pStream Pointer to audio stream.
1036	*/
1037	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1038
1039	/**
1040	* Captures (reads) samples from an audio input stream.
1041	*
1042	* @returns VBox status code.
1043	* @param pInterface Pointer to the interface structure containing the called function pointer.
1044	* @param pStream Pointer to audio stream to write to.
1045	* @param pvBuf Where to store the read data.
1046	* @param cbBuf Number of bytes to read.
1047	* @param pcbRead Bytes of audio data read. Optional.
1048	*/
1049	DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1050	void pvBuf, uint32_t cbBuf, uint32_t pcbRead));
1051	} PDMIAUDIOCONNECTOR;
1052
1053	/** PDMIAUDIOCONNECTOR interface ID. */
1054	#define PDMIAUDIOCONNECTOR_IID "2900fe2a-6aeb-4953-ac12-f8965612f446"
1055
1056
1057	/**
1058	* Host audio backend specific stream data.
1059	*
1060	* The backend will put this as the first member of it's own data structure.
1061	*/
1062	typedef struct PDMAUDIOBACKENDSTREAM
1063	{
1064	/** Magic value (PDMAUDIOBACKENDSTREAM_MAGIC). */
1065	uint32_t uMagic;
1066	/** Explicit zero padding - do not touch! */
1067	uint32_t uReserved;
1068	/** Pointer to the stream this backend data is associated with. */
1069	PPDMAUDIOSTREAM pStream;
1070	/** Reserved for future use (zeroed) - do not touch. */
1071	void *apvReserved[2];
1072	} PDMAUDIOBACKENDSTREAM;
1073	/** Pointer to host audio specific stream data! */
1074	typedef PDMAUDIOBACKENDSTREAM *PPDMAUDIOBACKENDSTREAM;
1075
1076	/** Magic value for PDMAUDIOBACKENDSTREAM. */
1077	#define PDMAUDIOBACKENDSTREAM_MAGIC PDM_VERSION_MAKE(0xa0d4, 1, 0)
1078
1079	/**
1080	* Host audio (backend) stream state returned by PDMIHOSTAUDIO::pfnStreamGetState.
1081	*/
1082	typedef enum PDMHOSTAUDIOSTREAMSTATE
1083	{
1084	/** Invalid zero value, as per usual. */
1085	PDMHOSTAUDIOSTREAMSTATE_INVALID = 0,
1086	/** The stream is being initialized.
1087	* This should also be used when switching to a new device and the stream
1088	* stops to work with the old device while the new one being configured. */
1089	PDMHOSTAUDIOSTREAMSTATE_INITIALIZING,
1090	/** The stream does not work (async init failed, audio subsystem gone
1091	* fishing, or similar). */
1092	PDMHOSTAUDIOSTREAMSTATE_NOT_WORKING,
1093	/** Backend is working okay. */
1094	PDMHOSTAUDIOSTREAMSTATE_OKAY,
1095	/** Backend is working okay, but currently draining the stream. */
1096	PDMHOSTAUDIOSTREAMSTATE_DRAINING,
1097	/** Backend is working but doesn't want any commands or data reads/writes. */
1098	PDMHOSTAUDIOSTREAMSTATE_INACTIVE,
1099	/** End of valid values. */
1100	PDMHOSTAUDIOSTREAMSTATE_END,
1101	/** Blow the type up to 32 bits. */
1102	PDMHOSTAUDIOSTREAMSTATE_32BIT_HACK = 0x7fffffff
1103	} PDMHOSTAUDIOSTREAMSTATE;
1104
1105
1106	/** Pointer to a host audio interface. */
1107	typedef struct PDMIHOSTAUDIO *PPDMIHOSTAUDIO;
1108
1109	/**
1110	* PDM host audio interface.
1111	*/
1112	typedef struct PDMIHOSTAUDIO
1113	{
1114	/**
1115	* Returns the host backend's configuration (backend).
1116	*
1117	* @returns VBox status code.
1118	* @param pInterface Pointer to the interface structure containing the called function pointer.
1119	* @param pBackendCfg Where to store the backend audio configuration to.
1120	*/
1121	DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg));
1122
1123	/**
1124	* Returns (enumerates) host audio device information (optional).
1125	*
1126	* @returns VBox status code.
1127	* @param pInterface Pointer to the interface structure containing the called function pointer.
1128	* @param pDeviceEnum Where to return the enumerated audio devices.
1129	*/
1130	DECLR3CALLBACKMEMBER(int, pfnGetDevices, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHOSTENUM pDeviceEnum));
1131
1132	/**
1133	* Changes the output or input device.
1134	*
1135	* @returns VBox status code.
1136	* @param pInterface Pointer to this interface.
1137	* @param enmDir The direction to set the device for: PDMAUDIODIR_IN,
1138	* PDMAUDIODIR_OUT or PDMAUDIODIR_DUPLEX (both the
1139	* previous).
1140	* @param pszId The PDMAUDIOHOSTDEV::pszId value of the device to
1141	* use, or NULL / empty string for the default device.
1142	*/
1143	DECLR3CALLBACKMEMBER(int, pfnSetDevice, (PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir, const char *pszId));
1144
1145	/**
1146	* Returns the current status from the audio backend (optional).
1147	*
1148	* @returns PDMAUDIOBACKENDSTS enum.
1149	* @param pInterface Pointer to the interface structure containing the called function pointer.
1150	* @param enmDir Audio direction to get status for. Pass PDMAUDIODIR_DUPLEX for overall status.
1151	*/
1152	DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir));
1153
1154	/**
1155	* Callback for genric on-worker-thread requests initiated by the backend itself.
1156	*
1157	* This is the counterpart to PDMIHOSTAUDIOPORT::pfnDoOnWorkerThread that will
1158	* be invoked on a worker thread when the backend requests it - optional.
1159	*
1160	* This does not return a value, so the backend must keep track of
1161	* failure/success on its own.
1162	*
1163	* This method is optional. A non-NULL will, together with pfnStreamInitAsync
1164	* and PDMAUDIOBACKEND_F_ASYNC_HINT, force DrvAudio to create the thread pool.
1165	*
1166	* @param pInterface Pointer to this interface.
1167	* @param pStream Optionally a backend stream if specified in the
1168	* PDMIHOSTAUDIOPORT::pfnDoOnWorkerThread() call.
1169	* @param uUser User specific value as specified in the
1170	* PDMIHOSTAUDIOPORT::pfnDoOnWorkerThread() call.
1171	* @param pvUser User specific pointer as specified in the
1172	* PDMIHOSTAUDIOPORT::pfnDoOnWorkerThread() call.
1173	*/
1174	DECLR3CALLBACKMEMBER(void, pfnDoOnWorkerThread,(PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1175	uintptr_t uUser, void *pvUser));
1176
1177	/**
1178	* Gives the audio backend a hint about a typical configuration (optional).
1179	*
1180	* This is a little hack for windows (and maybe other hosts) where stream
1181	* creation can take a relatively long time, making it very unsuitable for EMT.
1182	* The audio backend can use this hint to cache pre-configured stream setups,
1183	* so that when the guest actually wants to play something EMT won't be blocked
1184	* configuring host audio.
1185	*
1186	* The backend can return PDMAUDIOBACKEND_F_ASYNC_HINT in
1187	* PDMIHOSTAUDIO::pfnGetConfig to avoid having EMT making this call and thereby
1188	* speeding up VM construction.
1189	*
1190	* @param pInterface Pointer to this interface.
1191	* @param pCfg The typical configuration. (Feel free to change it
1192	* to the actual stream config that would be used,
1193	* however caller will probably ignore this.)
1194	*/
1195	DECLR3CALLBACKMEMBER(void, pfnStreamConfigHint, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAMCFG pCfg));
1196
1197	/**
1198	* Creates an audio stream using the requested stream configuration.
1199	*
1200	* If a backend is not able to create this configuration, it will return its
1201	* best match in the acquired configuration structure on success.
1202	*
1203	* @returns VBox status code.
1204	* @retval VINF_AUDIO_STREAM_ASYNC_INIT_NEEDED if
1205	* PDMIHOSTAUDIO::pfnStreamInitAsync should be called.
1206	* @param pInterface Pointer to this interface.
1207	* @param pStream Pointer to the audio stream.
1208	* @param pCfgReq The requested stream configuration.
1209	* @param pCfgAcq The acquired stream configuration - output. This is
1210	* the same as @a *pCfgReq when called, the
1211	* implementation will adjust it to make the actual
1212	* stream configuration as needed.
1213	*/
1214	DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1215	PCPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq));
1216
1217	/**
1218	* Asynchronous stream initialization step, optional.
1219	*
1220	* This is called on a worker thread iff the PDMIHOSTAUDIO::pfnStreamCreate
1221	* method returns VINF_AUDIO_STREAM_ASYNC_INIT_NEEDED.
1222	*
1223	* @returns VBox status code.
1224	* @param pInterface Pointer to this interface.
1225	* @param pStream Pointer to audio stream to continue
1226	* initialization of.
1227	* @param fDestroyed Set to @c true if the stream has been destroyed
1228	* before the worker thread got to making this
1229	* call. The backend should just ready the stream
1230	* for destruction in that case.
1231	*/
1232	DECLR3CALLBACKMEMBER(int, pfnStreamInitAsync, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, bool fDestroyed));
1233
1234	/**
1235	* Destroys an audio stream.
1236	*
1237	* @returns VBox status code.
1238	* @param pInterface Pointer to the interface containing the called function.
1239	* @param pStream Pointer to audio stream.
1240	* @param fImmediate Whether to immdiately stop and destroy a draining
1241	* stream (@c true), or to allow it to complete
1242	* draining first (@c false) if that's feasable.
1243	*/
1244	DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, bool fImmediate));
1245
1246	/**
1247	* Called from PDMIHOSTAUDIOPORT::pfnNotifyDeviceChanged so the backend can start
1248	* the device change for a stream.
1249	*
1250	* This is mainly to avoid the need for a list of streams in the backend.
1251	*
1252	* @param pInterface Pointer to this interface.
1253	* @param pStream Pointer to audio stream (locked).
1254	* @param pvUser Backend specific parameter from the call to
1255	* PDMIHOSTAUDIOPORT::pfnNotifyDeviceChanged.
1256	*/
1257	DECLR3CALLBACKMEMBER(void, pfnStreamNotifyDeviceChanged,(PPDMIHOSTAUDIO pInterface,
1258	PPDMAUDIOBACKENDSTREAM pStream, void *pvUser));
1259
1260	/**
1261	* Enables (starts) the stream.
1262	*
1263	* @returns VBox status code.
1264	* @param pInterface Pointer to this interface.
1265	* @param pStream Pointer to the audio stream to enable.
1266	* @sa PDMAUDIOSTREAMCMD_ENABLE
1267	*/
1268	DECLR3CALLBACKMEMBER(int, pfnStreamEnable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1269
1270	/**
1271	* Disables (stops) the stream immediately.
1272	*
1273	* @returns VBox status code.
1274	* @param pInterface Pointer to this interface.
1275	* @param pStream Pointer to the audio stream to disable.
1276	* @sa PDMAUDIOSTREAMCMD_DISABLE
1277	*/
1278	DECLR3CALLBACKMEMBER(int, pfnStreamDisable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1279
1280	/**
1281	* Pauses the stream - called when the VM is suspended.
1282	*
1283	* @returns VBox status code.
1284	* @param pInterface Pointer to this interface.
1285	* @param pStream Pointer to the audio stream to pause.
1286	* @sa PDMAUDIOSTREAMCMD_PAUSE
1287	*/
1288	DECLR3CALLBACKMEMBER(int, pfnStreamPause, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1289
1290	/**
1291	* Resumes a paused stream - called when the VM is resumed.
1292	*
1293	* @returns VBox status code.
1294	* @param pInterface Pointer to this interface.
1295	* @param pStream Pointer to the audio stream to resume.
1296	* @sa PDMAUDIOSTREAMCMD_RESUME
1297	*/
1298	DECLR3CALLBACKMEMBER(int, pfnStreamResume, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1299
1300	/**
1301	* Drain the stream, that is, play what's in the buffers and then stop.
1302	*
1303	* There will be no more samples written after this command is issued.
1304	* PDMIHOSTAUDIO::pfnStreamPlay with a zero sized buffer will provide the
1305	* backend with a way to drive it forwards. These calls will come at a
1306	* frequency set by the device and be on an asynchronous I/O thread.
1307	*
1308	* The PDMIHOSTAUDIO::pfnStreamDisable method maybe called if the device/mixer
1309	* wants to re-enable the stream while it's still draining or if it gets
1310	* impatient and thinks the draining has been going on too long, in which case
1311	* the stream should stop immediately.
1312	*
1313	* @note This should not wait for the stream to finish draining, just change
1314	* the state. (The caller could be an EMT and it must not block for
1315	* hundreds of milliseconds of buffer to finish draining.)
1316	*
1317	* @note Does not apply to input streams. Backends should refuse such
1318	* requests.
1319	*
1320	* @returns VBox status code.
1321	* @retval VERR_WRONG_ORDER if not output stream.
1322	* @param pInterface Pointer to this interface.
1323	* @param pStream Pointer to the audio stream to drain.
1324	* @sa PDMAUDIOSTREAMCMD_DRAIN
1325	*/
1326	DECLR3CALLBACKMEMBER(int, pfnStreamDrain, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1327
1328	/**
1329	* Returns the current state of the given backend stream.
1330	*
1331	* @returns PDMHOSTAUDIOSTREAMSTATE value.
1332	* @retval PDMHOSTAUDIOSTREAMSTATE_INVALID if invalid stream.
1333	* @param pInterface Pointer to the interface structure containing the called function pointer.
1334	* @param pStream Pointer to audio stream.
1335	*/
1336	DECLR3CALLBACKMEMBER(PDMHOSTAUDIOSTREAMSTATE, pfnStreamGetState, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1337
1338	/**
1339	* Returns the number of buffered bytes that hasn't been played yet (optional).
1340	*
1341	* Is not valid on an input stream, implementions shall assert and return zero.
1342	*
1343	* @returns Number of pending bytes.
1344	* @param pInterface Pointer to this interface.
1345	* @param pStream Pointer to the audio stream.
1346	*
1347	* @todo This is no longer not used by DrvAudio and can probably be removed.
1348	*/
1349	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetPending, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1350
1351	/**
1352	* Returns the amount which is writable to the audio (output) stream.
1353	*
1354	* @returns Number of writable bytes.
1355	* @param pInterface Pointer to the interface structure containing the called function pointer.
1356	* @param pStream Pointer to audio stream.
1357	*/
1358	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1359
1360	/**
1361	* Plays (writes to) an audio (output) stream.
1362	*
1363	* This is always called with data in the buffer, except after
1364	* PDMAUDIOSTREAMCMD_DRAIN is issued when it's called every so often to assist
1365	* the backend with moving the draining operation forward (kind of like
1366	* PDMIAUDIOCONNECTOR::pfnStreamIterate).
1367	*
1368	* @returns VBox status code.
1369	* @param pInterface Pointer to the interface structure containing the called function pointer.
1370	* @param pStream Pointer to audio stream.
1371	* @param pvBuf Pointer to audio data buffer to play. This will be NULL
1372	* when called to assist draining the stream.
1373	* @param cbBuf The number of bytes of audio data to play. This will be
1374	* zero when called to assist draining the stream.
1375	* @param pcbWritten Where to return the actual number of bytes played.
1376	*/
1377	DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1378	const void pvBuf, uint32_t cbBuf, uint32_t pcbWritten));
1379
1380	/**
1381	* Returns the amount which is readable from the audio (input) stream.
1382	*
1383	* @returns For non-raw layout streams: Number of readable bytes.
1384	* for raw layout streams : Number of readable audio frames.
1385	* @param pInterface Pointer to the interface structure containing the called function pointer.
1386	* @param pStream Pointer to audio stream.
1387	*/
1388	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1389
1390	/**
1391	* Captures (reads from) an audio (input) stream.
1392	*
1393	* @returns VBox status code.
1394	* @param pInterface Pointer to the interface structure containing the called function pointer.
1395	* @param pStream Pointer to audio stream.
1396	* @param pvBuf Buffer where to store read audio data.
1397	* @param cbBuf Size of the audio data buffer in bytes.
1398	* @param pcbRead Where to return the number of bytes actually captured.
1399	*/
1400	DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1401	void pvBuf, uint32_t cbBuf, uint32_t pcbRead));
1402	} PDMIHOSTAUDIO;
1403
1404	/** PDMIHOSTAUDIO interface ID. */
1405	#define PDMIHOSTAUDIO_IID "c0875b91-a4f9-48be-8595-31d27048432d"
1406
1407
1408	/** Pointer to a audio notify from host interface. */
1409	typedef struct PDMIHOSTAUDIOPORT *PPDMIHOSTAUDIOPORT;
1410
1411	/**
1412	* PDM host audio port interface, upwards sibling of PDMIHOSTAUDIO.
1413	*/
1414	typedef struct PDMIHOSTAUDIOPORT
1415	{
1416	/**
1417	* Ask DrvAudio to call PDMIHOSTAUDIO::pfnDoOnWorkerThread on a worker thread.
1418	*
1419	* Generic method for doing asynchronous work using the DrvAudio thread pool.
1420	*
1421	* This function will not wait for PDMIHOSTAUDIO::pfnDoOnWorkerThread to
1422	* complete, but returns immediately after submitting the request to the thread
1423	* pool.
1424	*
1425	* @returns VBox status code.
1426	* @param pInterface Pointer to this interface.
1427	* @param pStream Optional backend stream structure to pass along. The
1428	* reference count will be increased till the call
1429	* completes to make sure the stream stays valid.
1430	* @param uUser User specific value.
1431	* @param pvUser User specific pointer.
1432	*/
1433	DECLR3CALLBACKMEMBER(int, pfnDoOnWorkerThread,(PPDMIHOSTAUDIOPORT pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1434	uintptr_t uUser, void *pvUser));
1435
1436	/**
1437	* The device for the given direction changed.
1438	*
1439	* The driver above backend (DrvAudio) will call the backend back
1440	* (PDMIHOSTAUDIO::pfnStreamNotifyDeviceChanged) for all open streams in the
1441	* given direction. (This ASSUMES the backend uses one output device and one
1442	* input devices for all streams.)
1443	*
1444	* @param pInterface Pointer to this interface.
1445	* @param enmDir The audio direction.
1446	* @param pvUser Backend specific parameter for
1447	* PDMIHOSTAUDIO::pfnStreamNotifyDeviceChanged.
1448	*/
1449	DECLR3CALLBACKMEMBER(void, pfnNotifyDeviceChanged,(PPDMIHOSTAUDIOPORT pInterface, PDMAUDIODIR enmDir, void *pvUser));
1450
1451	/**
1452	* Notification that the stream is about to change device in a bit.
1453	*
1454	* This will assume PDMAUDIOSTREAM_STS_PREPARING_SWITCH will be set when
1455	* PDMIHOSTAUDIO::pfnStreamGetStatus is next called and change the stream state
1456	* accordingly.
1457	*
1458	* @param pInterface Pointer to this interface.
1459	* @param pStream The stream that changed device (backend variant).
1460	*/
1461	DECLR3CALLBACKMEMBER(void, pfnStreamNotifyPreparingDeviceSwitch,(PPDMIHOSTAUDIOPORT pInterface,
1462	PPDMAUDIOBACKENDSTREAM pStream));
1463
1464	/**
1465	* The stream has changed its device and left the
1466	* PDMAUDIOSTREAM_STS_PREPARING_SWITCH state (if it entered it at all).
1467	*
1468	* @param pInterface Pointer to this interface.
1469	* @param pStream The stream that changed device (backend variant).
1470	* @param fReInit Set if a re-init is required, clear if not.
1471	*/
1472	DECLR3CALLBACKMEMBER(void, pfnStreamNotifyDeviceChanged,(PPDMIHOSTAUDIOPORT pInterface,
1473	PPDMAUDIOBACKENDSTREAM pStream, bool fReInit));
1474
1475	/**
1476	* One or more audio devices have changed in some way.
1477	*
1478	* The upstream driver/device should re-evaluate the devices they're using.
1479	*
1480	* @todo r=bird: The upstream driver/device does not know which host audio
1481	* devices they are using. This is mainly for triggering enumeration and
1482	* logging of the audio devices.
1483	*
1484	* @param pInterface Pointer to this interface.
1485	*/
1486	DECLR3CALLBACKMEMBER(void, pfnNotifyDevicesChanged,(PPDMIHOSTAUDIOPORT pInterface));
1487	} PDMIHOSTAUDIOPORT;
1488
1489	/** PDMIHOSTAUDIOPORT interface ID. */
1490	#define PDMIHOSTAUDIOPORT_IID "92ea5169-8271-402d-99a7-9de26a52acaf"
1491
1492
1493	/**
1494	* Audio mixer controls.
1495	*
1496	* @note This isn't part of any official PDM interface as such, it's more of a
1497	* common thing that all the devices seem to need.
1498	*/
1499	typedef enum PDMAUDIOMIXERCTL
1500	{
1501	/** Invalid zero value as per usual (guards against using unintialized values). */
1502	PDMAUDIOMIXERCTL_INVALID = 0,
1503	/** Unknown mixer control. */
1504	PDMAUDIOMIXERCTL_UNKNOWN,
1505	/** Master volume. */
1506	PDMAUDIOMIXERCTL_VOLUME_MASTER,
1507	/** Front. */
1508	PDMAUDIOMIXERCTL_FRONT,
1509	/** Center / LFE (Subwoofer). */
1510	PDMAUDIOMIXERCTL_CENTER_LFE,
1511	/** Rear. */
1512	PDMAUDIOMIXERCTL_REAR,
1513	/** Line-In. */
1514	PDMAUDIOMIXERCTL_LINE_IN,
1515	/** Microphone-In. */
1516	PDMAUDIOMIXERCTL_MIC_IN,
1517	/** End of valid values. */
1518	PDMAUDIOMIXERCTL_END,
1519	/** Hack to blow the type up to 32-bit. */
1520	PDMAUDIOMIXERCTL_32BIT_HACK = 0x7fffffff
1521	} PDMAUDIOMIXERCTL;
1522
1523	/**
1524	* Audio volume parameters.
1525	*
1526	* @note This isn't part of any official PDM interface any more (it used to be
1527	* used to PDMIAUDIOCONNECTOR). It's currently only used by the mixer API.
1528	*/
1529	typedef struct PDMAUDIOVOLUME
1530	{
1531	/** Set to @c true if this stream is muted, @c false if not. */
1532	bool fMuted;
1533	/** The volume for each channel.
1534	* The values zero is the most silent one (although not quite muted), and 255
1535	* the loudest. */
1536	uint8_t auChannels[PDMAUDIO_MAX_CHANNELS];
1537	} PDMAUDIOVOLUME;
1538	/** Pointer to audio volume settings. */
1539	typedef PDMAUDIOVOLUME *PPDMAUDIOVOLUME;
1540	/** Pointer to const audio volume settings. */
1541	typedef PDMAUDIOVOLUME const *PCPDMAUDIOVOLUME;
1542
1543	/** Defines the minimum volume allowed. */
1544	#define PDMAUDIO_VOLUME_MIN (0)
1545	/** Defines the maximum volume allowed. */
1546	#define PDMAUDIO_VOLUME_MAX (255)
1547	/** Initializator for max volume on all channels. */
1548	#define PDMAUDIOVOLUME_INITIALIZER_MAX \
1549	{ /* .fMuted = */ false, \
1550	/* .auChannels = */ { 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255 } }
1551
1552	/** @} */
1553
1554	RT_C_DECLS_END
1555
1556	#endif /* !VBOX_INCLUDED_vmm_pdmaudioifs_h */
1557

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

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

Download in other formats: