pdmaudioifs.h@ 99897

Last change on this file since 99897 was 98103, checked in by vboxsync, 23 months ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 66.6 KB

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

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

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

Download in other formats: