pdmaudioifs.h@ 88726

Last change on this file since 88726 was 88726, checked in by vboxsync, 4 years ago
DrvAudio: Prep work for new backend stream status... bugref:9890
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 58.0 KB

Line
1	/** @file
2	* PDM - Pluggable Device Manager, Audio interfaces.
3	*/
4
5	/*
6	* Copyright (C) 2006-2020 Oracle Corporation
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	/** @page pg_pdm_audio PDM Audio
27	*
28	* @section sec_pdm_audio_overview Audio architecture overview
29	*
30	* The audio architecture mainly consists of two PDM interfaces,
31	* PDMIAUDIOCONNECTOR and PDMIHOSTAUDIO.
32	*
33	* The PDMIAUDIOCONNECTOR interface is responsible of connecting a device
34	* emulation, such as SB16, AC'97 and HDA to one or multiple audio backend(s).
35	* Its API abstracts audio stream handling and I/O functions, device enumeration
36	* and so on.
37	*
38	* The PDMIHOSTAUDIO interface must be implemented by all audio backends to
39	* provide an abstract and common way of accessing needed functions, such as
40	* transferring output audio data for playing audio or recording input from the
41	* host.
42	*
43	* A device emulation can have one or more LUNs attached to it, whereas these
44	* LUNs in turn then all have their own PDMIAUDIOCONNECTOR, making it possible
45	* to connect multiple backends to a certain device emulation stream
46	* (multiplexing).
47	*
48	* An audio backend's job is to record and/or play audio data (depending on its
49	* capabilities). It highly depends on the host it's running on and needs very
50	* specific (host-OS-dependent) code. The backend itself only has very limited
51	* ways of accessing and/or communicating with the PDMIAUDIOCONNECTOR interface
52	* via callbacks, but never directly with the device emulation or other parts of
53	* the audio sub system.
54	*
55	*
56	* @section sec_pdm_audio_mixing Mixing
57	*
58	* The AUDIOMIXER API is optionally available to create and manage virtual audio
59	* mixers. Such an audio mixer in turn then can be used by the device emulation
60	* code to manage all the multiplexing to/from the connected LUN audio streams.
61	*
62	* Currently only input and output stream are supported. Duplex stream are not
63	* supported yet.
64	*
65	* This also is handy if certain LUN audio streams should be added or removed
66	* during runtime.
67	*
68	* To create a group of either input or output streams the AUDMIXSINK API can be
69	* used.
70	*
71	* For example: The device emulation has one hardware output stream (HW0), and
72	* that output stream shall be available to all connected LUN backends. For that
73	* to happen, an AUDMIXSINK sink has to be created and attached to the device's
74	* AUDIOMIXER object.
75	*
76	* As every LUN has its own AUDMIXSTREAM object, adding all those
77	* objects to the just created audio mixer sink will do the job.
78	*
79	* @note The AUDIOMIXER API is purely optional and is not used by all currently
80	* implemented device emulations (e.g. SB16).
81	*
82	*
83	* @section sec_pdm_audio_data_processing Data processing
84	*
85	* Audio input / output data gets handed off to/from the device emulation in an
86	* unmodified (raw) way. The actual audio frame / sample conversion is done via
87	* the AUDIOMIXBUF API.
88	*
89	* This concentrates the audio data processing in one place and makes it easier
90	* to test / benchmark such code.
91	*
92	* A PDMAUDIOFRAME is the internal representation of a single audio frame, which
93	* consists of a single left and right audio sample in time. Only mono (1) and
94	* stereo (2) channel(s) currently are supported.
95	*
96	*
97	* @section sec_pdm_audio_timing Timing
98	*
99	* Handling audio data in a virtual environment is hard, as the human perception
100	* is very sensitive to the slightest cracks and stutters in the audible data.
101	* This can happen if the VM's timing is lagging behind or not within the
102	* expected time frame.
103	*
104	* The two main components which unfortunately contradict each other is a) the
105	* audio device emulation and b) the audio backend(s) on the host. Those need to
106	* be served in a timely manner to function correctly. To make e.g. the device
107	* emulation rely on the pace the host backend(s) set - or vice versa - will not
108	* work, as the guest's audio system / drivers then will not be able to
109	* compensate this accordingly.
110	*
111	* So each component, the device emulation, the audio connector(s) and the
112	* backend(s) must do its thing when it needs to do it, independently of the
113	* others. For that we use various (small) ring buffers to (hopefully) serve all
114	* components with the amount of data when they need it.
115	*
116	* Additionally, the device emulation can run with a different audio frame size,
117	* while the backends(s) may require a different frame size (16 bit stereo
118	* -> 8 bit mono, for example).
119	*
120	* The device emulation can give the audio connector(s) a scheduling hint
121	* (optional), e.g. in which interval it expects any data processing.
122	*
123	* A data transfer for playing audio data from the guest on the host looks like
124	* this: (RB = Ring Buffer, MB = Mixing Buffer)
125	*
126	* (A) Device DMA -> (B) Device RB -> (C) Audio Connector %Guest MB -> (D) Audio
127	* Connector %Host MB -> (E) Backend RB (optional, up to the backend) -> (F)
128	* Backend audio framework.
129	*
130	* When capturing audio data the chain is similar to the above one, just in a
131	* different direction, of course.
132	*
133	* The audio connector hereby plays a key role when it comes to (pre-)buffering
134	* data to minimize any audio stutters and/or cracks. The following values,
135	* which also can be tweaked via CFGM / extra-data are available:
136	*
137	* - The pre-buffering time (in ms): Audio data which needs to be buffered
138	* before any playback (or capturing) can happen.
139	* - The actual buffer size (in ms): How big the mixing buffer (for C and D)
140	* will be.
141	* - The period size (in ms): How big a chunk of audio (often called period or
142	* fragment) for F must be to get handled correctly.
143	*
144	* The above values can be set on a per-driver level, whereas input and output
145	* streams for a driver also can be handled set independently. The verbose audio
146	* (release) log will tell about the (final) state of each audio stream.
147	*
148	*
149	* @section sec_pdm_audio_diagram Diagram
150	*
151	* @todo r=bird: Not quite able to make sense of this, esp. the
152	* AUDMIXSINK/AUDIOMIXER bits crossing the LUN connections.
153	*
154	* @verbatim
155	+----------------------------------+
156	\|Device (SB16 / AC'97 / HDA) \|
157	\|----------------------------------\|
158	\|AUDIOMIXER (Optional) \|
159	\|AUDMIXSINK0 (Optional) \|
160	\|AUDMIXSINK1 (Optional) \|
161	\|AUDMIXSINKn (Optional) \|
162	\| \|
163	\| L L L \|
164	\| U U U \|
165	\| N N N \|
166	\| 0 1 n \|
167	+-----+----+----+------------------+
168	\| \| \|
169	\| \| \|
170	+--------------+ \| \| \| +-------------+
171	\|AUDMIXSINK \| \| \| \| \|AUDIOMIXER \|
172	\|--------------\| \| \| \| \|-------------\|
173	\|AUDMIXSTREAM0 \|+-\|----\|----\|-->\|AUDMIXSINK0 \|
174	\|AUDMIXSTREAM1 \|+-\|----\|----\|-->\|AUDMIXSINK1 \|
175	\|AUDMIXSTREAMn \|+-\|----\|----\|-->\|AUDMIXSINKn \|
176	+--------------+ \| \| \| +-------------+
177	\| \| \|
178	\| \| \|
179	+----+----+----+----+
180	\|LUN \|
181	\|-------------------\|
182	\|PDMIAUDIOCONNECTOR \|
183	\|AUDMIXSTREAM \|
184	\| +------+
185	\| \| \|
186	\| \| \|
187	\| \| \|
188	+-------------------+ \|
189	\|
190	+-------------------------+ \|
191	+-------------------------+ +----+--------------------+
192	\|PDMAUDIOSTREAM \| \|PDMIAUDIOCONNECTOR \|
193	\|-------------------------\| \|-------------------------\|
194	\|AUDIOMIXBUF \|+------>\|PDMAUDIOSTREAM Host \|
195	\|PDMAUDIOSTREAMCFG \|+------>\|PDMAUDIOSTREAM Guest \|
196	\| \| \|Device capabilities \|
197	\| \| \|Device configuration \|
198	\| \| \| \|
199	\| \| +--+\|PDMIHOSTAUDIO \|
200	\| \| \| \|+-----------------------+\|
201	+-------------------------+ \| \|\|Backend storage space \|\|
202	\| \|+-----------------------+\|
203	\| +-------------------------+
204	\|
205	+---------------------+ \|
206	\|PDMIHOSTAUDIO \| \|
207	\|+--------------+ \| \|
208	\|\|DirectSound \| \| \|
209	\|+--------------+ \| \|
210	\| \| \|
211	\|+--------------+ \| \|
212	\|\|PulseAudio \| \| \|
213	\|+--------------+ \|+-------+
214	\| \|
215	\|+--------------+ \|
216	\|\|Core Audio \| \|
217	\|+--------------+ \|
218	\| \|
219	\| \|
220	\| \|
221	\| \|
222	+---------------------+
223	@endverbatim
224	*/
225
226	#ifndef VBOX_INCLUDED_vmm_pdmaudioifs_h
227	#define VBOX_INCLUDED_vmm_pdmaudioifs_h
228	#ifndef RT_WITHOUT_PRAGMA_ONCE
229	# pragma once
230	#endif
231
232	#include <iprt/assertcompile.h>
233	#include <iprt/circbuf.h>
234	#include <iprt/list.h>
235	#include <iprt/path.h>
236
237	#include <VBox/types.h>
238	#include <VBox/vmm/pdmcommon.h>
239	#include <VBox/vmm/stam.h>
240
241	/** @defgroup grp_pdm_ifs_audio PDM Audio Interfaces
242	* @ingroup grp_pdm_interfaces
243	* @{
244	*/
245
246	#ifndef VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH
247	# if defined(RT_OS_WINDOWS) \|\| defined(RT_OS_OS2)
248	# define VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "c:\\temp\\"
249	# else
250	# define VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "/tmp/"
251	# endif
252	#endif
253
254	/** PDM audio driver instance flags. */
255	typedef uint32_t PDMAUDIODRVFLAGS;
256
257	/** No flags set. */
258	#define PDMAUDIODRVFLAGS_NONE 0
259	/** Marks a primary audio driver which is critical
260	* when running the VM. */
261	#define PDMAUDIODRVFLAGS_PRIMARY RT_BIT(0)
262
263	/**
264	* Audio format in signed or unsigned variants.
265	*/
266	typedef enum PDMAUDIOFMT
267	{
268	/** Invalid format, do not use. */
269	PDMAUDIOFMT_INVALID = 0,
270	/** 8-bit, unsigned. */
271	PDMAUDIOFMT_U8,
272	/** 8-bit, signed. */
273	PDMAUDIOFMT_S8,
274	/** 16-bit, unsigned. */
275	PDMAUDIOFMT_U16,
276	/** 16-bit, signed. */
277	PDMAUDIOFMT_S16,
278	/** 32-bit, unsigned. */
279	PDMAUDIOFMT_U32,
280	/** 32-bit, signed. */
281	PDMAUDIOFMT_S32,
282	/** End of valid values. */
283	PDMAUDIOFMT_END,
284	/** Hack to blow the type up to 32-bit. */
285	PDMAUDIOFMT_32BIT_HACK = 0x7fffffff
286	} PDMAUDIOFMT;
287
288	/**
289	* Audio direction.
290	*/
291	typedef enum PDMAUDIODIR
292	{
293	/** Invalid zero value as per usual (guards against using unintialized values). */
294	PDMAUDIODIR_INVALID = 0,
295	/** Unknown direction. */
296	PDMAUDIODIR_UNKNOWN,
297	/** Input. */
298	PDMAUDIODIR_IN,
299	/** Output. */
300	PDMAUDIODIR_OUT,
301	/** Duplex handling. */
302	PDMAUDIODIR_DUPLEX,
303	/** End of valid values. */
304	PDMAUDIODIR_END,
305	/** Hack to blow the type up to 32-bit. */
306	PDMAUDIODIR_32BIT_HACK = 0x7fffffff
307	} PDMAUDIODIR;
308
309	/** Device latency spec in milliseconds (ms). */
310	typedef uint32_t PDMAUDIODEVLATSPECMS;
311
312	/** Device latency spec in seconds (s). */
313	typedef uint32_t PDMAUDIODEVLATSPECSEC;
314
315	/** @name PDMAUDIOHOSTDEV_F_XXX
316	* @{ */
317	/** No flags set. */
318	#define PDMAUDIOHOSTDEV_F_NONE UINT32_C(0)
319	/** The device marks the default device within the host OS. */
320	#define PDMAUDIOHOSTDEV_F_DEFAULT RT_BIT_32(0)
321	/** The device can be removed at any time and we have to deal with it. */
322	#define PDMAUDIOHOSTDEV_F_HOTPLUG RT_BIT_32(1)
323	/** The device is known to be buggy and needs special treatment. */
324	#define PDMAUDIOHOSTDEV_F_BUGGY RT_BIT_32(2)
325	/** Ignore the device, no matter what. */
326	#define PDMAUDIOHOSTDEV_F_IGNORE RT_BIT_32(3)
327	/** The device is present but marked as locked by some other application. */
328	#define PDMAUDIOHOSTDEV_F_LOCKED RT_BIT_32(4)
329	/** The device is present but not in an alive state (dead). */
330	#define PDMAUDIOHOSTDEV_F_DEAD RT_BIT_32(5)
331	/** Set if the extra backend specific data cannot be duplicated. */
332	#define PDMAUDIOHOSTDEV_F_NO_DUP RT_BIT_32(31)
333	/** @} */
334
335	/**
336	* Audio device type.
337	*/
338	typedef enum PDMAUDIODEVICETYPE
339	{
340	/** Invalid zero value as per usual (guards against using unintialized values). */
341	PDMAUDIODEVICETYPE_INVALID = 0,
342	/** Unknown device type. This is the default. */
343	PDMAUDIODEVICETYPE_UNKNOWN,
344	/** Dummy device; for backends which are not able to report
345	* actual device information (yet). */
346	PDMAUDIODEVICETYPE_DUMMY,
347	/** The device is built into the host (non-removable). */
348	PDMAUDIODEVICETYPE_BUILTIN,
349	/** The device is an (external) USB device. */
350	PDMAUDIODEVICETYPE_USB,
351	/** End of valid values. */
352	PDMAUDIODEVICETYPE_END,
353	/** Hack to blow the type up to 32-bit. */
354	PDMAUDIODEVICETYPE_32BIT_HACK = 0x7fffffff
355	} PDMAUDIODEVICETYPE;
356
357	/**
358	* Host audio device info, part of enumeration result.
359	*
360	* @sa PDMAUDIOHOSTENUM, PDMIHOSTAUDIO::pfnGetDevices
361	*/
362	typedef struct PDMAUDIOHOSTDEV
363	{
364	/** List entry (like PDMAUDIOHOSTENUM::LstDevices). */
365	RTLISTNODE ListEntry;
366	/** Magic value (PDMAUDIOHOSTDEV_MAGIC). */
367	uint32_t uMagic;
368	/** Size of this structure and whatever backend specific data that follows it. */
369	uint32_t cbSelf;
370	/** The device type. */
371	PDMAUDIODEVICETYPE enmType;
372	/** Usage of the device. */
373	PDMAUDIODIR enmUsage;
374	/** Device flags, PDMAUDIOHOSTDEV_F_XXX. */
375	uint32_t fFlags;
376	/** Reference count indicating how many audio streams currently are relying on this device. */
377	uint8_t cRefCount;
378	/** Maximum number of input audio channels the device supports. */
379	uint8_t cMaxInputChannels;
380	/** Maximum number of output audio channels the device supports. */
381	uint8_t cMaxOutputChannels;
382	uint8_t bAlignment;
383	/** Device type union, based on enmType. */
384	union
385	{
386	/** USB type specifics. */
387	struct
388	{
389	/** Vendor ID. */
390	uint16_t idVendor;
391	/** Product ID. */
392	uint16_t idProduct;
393	} USB;
394	uint64_t uPadding[ARCH_BITS >= 64 ? 3 : 4];
395	} Type;
396	/** Friendly name of the device, if any. Could be truncated. */
397	char szName[64];
398	} PDMAUDIOHOSTDEV;
399	AssertCompileSizeAlignment(PDMAUDIOHOSTDEV, 16);
400	/** Pointer to audio device info (enumeration result). */
401	typedef PDMAUDIOHOSTDEV *PPDMAUDIOHOSTDEV;
402	/** Pointer to a const audio device info (enumeration result). */
403	typedef PDMAUDIOHOSTDEV const *PCPDMAUDIOHOSTDEV;
404
405	/** Magic value for PDMAUDIOHOSTDEV. */
406	#define PDMAUDIOHOSTDEV_MAGIC PDM_VERSION_MAKE(0xa0d0, 1, 0)
407
408
409	/**
410	* A host audio device enumeration result.
411	*
412	* @sa PDMIHOSTAUDIO::pfnGetDevices
413	*/
414	typedef struct PDMAUDIOHOSTENUM
415	{
416	/** Magic value (PDMAUDIOHOSTENUM_MAGIC). */
417	uint32_t uMagic;
418	/** Number of audio devices in the list. */
419	uint32_t cDevices;
420	/** List of audio devices (PDMAUDIOHOSTDEV). */
421	RTLISTANCHOR LstDevices;
422	} PDMAUDIOHOSTENUM;
423	/** Pointer to an audio device enumeration result. */
424	typedef PDMAUDIOHOSTENUM *PPDMAUDIOHOSTENUM;
425	/** Pointer to a const audio device enumeration result. */
426	typedef PDMAUDIOHOSTENUM const *PCPDMAUDIOHOSTENUM;
427
428	/** Magic for the host audio device enumeration. */
429	#define PDMAUDIOHOSTENUM_MAGIC PDM_VERSION_MAKE(0xa0d1, 1, 0)
430
431
432	/**
433	* Audio configuration (static) of an audio host backend.
434	*/
435	typedef struct PDMAUDIOBACKENDCFG
436	{
437	/** The backend's friendly name. */
438	char szName[32];
439	/** The size of the backend specific stream data (in bytes). */
440	uint32_t cbStream;
441	/** Flags, MBZ. */
442	uint32_t fFlags;
443	/** Number of concurrent output (playback) streams supported on the host.
444	* UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
445	uint32_t cMaxStreamsOut;
446	/** Number of concurrent input (recording) streams supported on the host.
447	* UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
448	uint32_t cMaxStreamsIn;
449	} PDMAUDIOBACKENDCFG;
450	/** Pointer to a static host audio audio configuration. */
451	typedef PDMAUDIOBACKENDCFG *PPDMAUDIOBACKENDCFG;
452
453	/**
454	* A single audio frame.
455	*
456	* Currently only two (2) channels, left and right, are supported.
457	*
458	* @note When changing this structure, make sure to also handle
459	* VRDP's input / output processing in DrvAudioVRDE, as VRDP
460	* expects audio data in st_sample_t format (historical reasons)
461	* which happens to be the same as PDMAUDIOFRAME for now.
462	*
463	* @todo r=bird: This is an internal AudioMixBuffer structure which should not
464	* be exposed here, I think. Only used to some sizeof statements in VRDE.
465	* (The problem with exposing it, is that we would like to move away from
466	* stereo and instead to anything from 1 to 16 channels. That means
467	* removing this structure entirely.)
468	*/
469	typedef struct PDMAUDIOFRAME
470	{
471	/** Left channel. */
472	int64_t i64LSample;
473	/** Right channel. */
474	int64_t i64RSample;
475	} PDMAUDIOFRAME;
476	/** Pointer to a single (stereo) audio frame. */
477	typedef PDMAUDIOFRAME *PPDMAUDIOFRAME;
478	/** Pointer to a const single (stereo) audio frame. */
479	typedef PDMAUDIOFRAME const *PCPDMAUDIOFRAME;
480
481	/**
482	* Audio playback destinations.
483	*/
484	typedef enum PDMAUDIOPLAYBACKDST
485	{
486	/** Invalid zero value as per usual (guards against using unintialized values). */
487	PDMAUDIOPLAYBACKDST_INVALID = 0,
488	/** Unknown destination. */
489	PDMAUDIOPLAYBACKDST_UNKNOWN,
490	/** Front channel. */
491	PDMAUDIOPLAYBACKDST_FRONT,
492	/** Center / LFE (Subwoofer) channel. */
493	PDMAUDIOPLAYBACKDST_CENTER_LFE,
494	/** Rear channel. */
495	PDMAUDIOPLAYBACKDST_REAR,
496	/** End of valid values. */
497	PDMAUDIOPLAYBACKDST_END,
498	/** Hack to blow the type up to 32-bit. */
499	PDMAUDIOPLAYBACKDST_32BIT_HACK = 0x7fffffff
500	} PDMAUDIOPLAYBACKDST;
501
502	/**
503	* Audio recording sources.
504	*
505	* @note Because this is almost exclusively used in PDMAUDIODSTSRCUNION where it
506	* overlaps with PDMAUDIOPLAYBACKDST, the values starts at 64 instead of 0.
507	*/
508	typedef enum PDMAUDIORECSRC
509	{
510	/** Unknown recording source. */
511	PDMAUDIORECSRC_UNKNOWN = 64,
512	/** Microphone-In. */
513	PDMAUDIORECSRC_MIC,
514	/** CD. */
515	PDMAUDIORECSRC_CD,
516	/** Video-In. */
517	PDMAUDIORECSRC_VIDEO,
518	/** AUX. */
519	PDMAUDIORECSRC_AUX,
520	/** Line-In. */
521	PDMAUDIORECSRC_LINE,
522	/** Phone-In. */
523	PDMAUDIORECSRC_PHONE,
524	/** End of valid values. */
525	PDMAUDIORECSRC_END,
526	/** Hack to blow the type up to 32-bit. */
527	PDMAUDIORECSRC_32BIT_HACK = 0x7fffffff
528	} PDMAUDIORECSRC;
529
530	/**
531	* Union for keeping an audio stream destination or source.
532	*/
533	typedef union PDMAUDIODSTSRCUNION
534	{
535	/** Desired playback destination (for an output stream). */
536	PDMAUDIOPLAYBACKDST enmDst;
537	/** Desired recording source (for an input stream). */
538	PDMAUDIORECSRC enmSrc;
539	} PDMAUDIODSTSRCUNION;
540	/** Pointer to an audio stream src/dst union. */
541	typedef PDMAUDIODSTSRCUNION *PPDMAUDIODSTSRCUNION;
542
543	/**
544	* Audio stream (data) layout.
545	*/
546	typedef enum PDMAUDIOSTREAMLAYOUT
547	{
548	/** Invalid zero value as per usual (guards against using unintialized values). */
549	PDMAUDIOSTREAMLAYOUT_INVALID = 0,
550	/** Unknown access type; do not use (hdaR3StreamMapReset uses it). */
551	PDMAUDIOSTREAMLAYOUT_UNKNOWN,
552	/** Non-interleaved access, that is, consecutive access to the data.
553	* @todo r=bird: For plain stereo this is actually interleaves left/right. What
554	* I guess non-interleaved means, is that there are no additional
555	* information interleaved next to the interleaved stereo.
556	* https://stackoverflow.com/questions/17879933/whats-the-interleaved-audio */
557	PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED,
558	/** Interleaved access, where the data can be mixed together with data of other audio streams. */
559	PDMAUDIOSTREAMLAYOUT_INTERLEAVED,
560	/** Complex layout, which does not fit into the interleaved / non-interleaved layouts. */
561	PDMAUDIOSTREAMLAYOUT_COMPLEX,
562	/** Raw (pass through) data, with no data layout processing done.
563	*
564	* This means that this stream will operate on PDMAUDIOFRAME data
565	* directly. Don't use this if you don't have to.
566	*
567	* @deprecated Replaced by S64 (signed, 64-bit sample size). */
568	PDMAUDIOSTREAMLAYOUT_RAW,
569	/** End of valid values. */
570	PDMAUDIOSTREAMLAYOUT_END,
571	/** Hack to blow the type up to 32-bit. */
572	PDMAUDIOSTREAMLAYOUT_32BIT_HACK = 0x7fffffff
573	} PDMAUDIOSTREAMLAYOUT;
574
575	/**
576	* Stream channel data block.
577	*/
578	typedef struct PDMAUDIOSTREAMCHANNELDATA
579	{
580	/** Circular buffer for the channel data. */
581	PRTCIRCBUF pCircBuf;
582	/** Amount of audio data (in bytes) acquired for reading. */
583	size_t cbAcq;
584	/** Channel data flags, PDMAUDIOSTREAMCHANNELDATA_FLAGS_XXX. */
585	uint32_t fFlags;
586	} PDMAUDIOSTREAMCHANNELDATA;
587	/** Pointer to audio stream channel data buffer. */
588	typedef PDMAUDIOSTREAMCHANNELDATA *PPDMAUDIOSTREAMCHANNELDATA;
589
590	/** @name PDMAUDIOSTREAMCHANNELDATA_FLAGS_XXX
591	* @{ */
592	/** No stream channel data flags defined. */
593	#define PDMAUDIOSTREAMCHANNELDATA_FLAGS_NONE UINT32_C(0)
594	/** @} */
595
596	/**
597	* Standard speaker channel IDs.
598	*
599	* This can cover up to 11.0 surround sound.
600	*
601	* @note Any of those channels can be marked / used as the LFE channel (played
602	* through the subwoofer).
603	*/
604	typedef enum PDMAUDIOSTREAMCHANNELID
605	{
606	/** Invalid zero value as per usual (guards against using unintialized values). */
607	PDMAUDIOSTREAMCHANNELID_INVALID = 0,
608	/** Unknown / not set channel ID. */
609	PDMAUDIOSTREAMCHANNELID_UNKNOWN,
610	/** Front left channel. */
611	PDMAUDIOSTREAMCHANNELID_FRONT_LEFT,
612	/** Front right channel. */
613	PDMAUDIOSTREAMCHANNELID_FRONT_RIGHT,
614	/** Front center channel. */
615	PDMAUDIOSTREAMCHANNELID_FRONT_CENTER,
616	/** Low frequency effects (subwoofer) channel. */
617	PDMAUDIOSTREAMCHANNELID_LFE,
618	/** Rear left channel. */
619	PDMAUDIOSTREAMCHANNELID_REAR_LEFT,
620	/** Rear right channel. */
621	PDMAUDIOSTREAMCHANNELID_REAR_RIGHT,
622	/** Front left of center channel. */
623	PDMAUDIOSTREAMCHANNELID_FRONT_LEFT_OF_CENTER,
624	/** Front right of center channel. */
625	PDMAUDIOSTREAMCHANNELID_FRONT_RIGHT_OF_CENTER,
626	/** Rear center channel. */
627	PDMAUDIOSTREAMCHANNELID_REAR_CENTER,
628	/** Side left channel. */
629	PDMAUDIOSTREAMCHANNELID_SIDE_LEFT,
630	/** Side right channel. */
631	PDMAUDIOSTREAMCHANNELID_SIDE_RIGHT,
632	/** Left height channel. */
633	PDMAUDIOSTREAMCHANNELID_LEFT_HEIGHT,
634	/** Right height channel. */
635	PDMAUDIOSTREAMCHANNELID_RIGHT_HEIGHT,
636	/** End of valid values. */
637	PDMAUDIOSTREAMCHANNELID_END,
638	/** Hack to blow the type up to 32-bit. */
639	PDMAUDIOSTREAMCHANNELID_32BIT_HACK = 0x7fffffff
640	} PDMAUDIOSTREAMCHANNELID;
641
642	/**
643	* Mappings channels onto an audio stream.
644	*
645	* The mappings are either for a single (mono) or dual (stereo) channels onto an
646	* audio stream (aka stream profile). An audio stream consists of one or
647	* multiple channels (e.g. 1 for mono, 2 for stereo), depending on the
648	* configuration.
649	*/
650	typedef struct PDMAUDIOSTREAMMAP
651	{
652	/** Array of channel IDs being handled.
653	* @note The first (zero-based) index specifies the leftmost channel. */
654	PDMAUDIOSTREAMCHANNELID aenmIDs[2];
655	/** Step size (in bytes) to the channel's next frame. */
656	uint32_t cbStep;
657	/** Frame size (in bytes) of this channel. */
658	uint32_t cbFrame;
659	/** Byte offset to the first frame in the data block. */
660	uint32_t offFirst;
661	/** Byte offset to the next frame in the data block. */
662	uint32_t offNext;
663	/** Associated data buffer. */
664	PDMAUDIOSTREAMCHANNELDATA Data;
665
666	/** @todo r=bird: I'd structure this very differently.
667	* I would've had an array of channel descriptors like this:
668	*
669	* struct PDMAUDIOCHANNELDESC
670	* {
671	* uint8_t off; //< Stream offset in bytes.
672	* uint8_t id; //< PDMAUDIOSTREAMCHANNELID
673	* };
674	*
675	* And I'd baked it into PDMAUDIOPCMPROPS as a fixed sized array with 16 entries
676	* (max HDA channel count IIRC). */
677	} PDMAUDIOSTREAMMAP;
678	/** Pointer to an audio stream channel mapping. */
679	typedef PDMAUDIOSTREAMMAP *PPDMAUDIOSTREAMMAP;
680
681	/**
682	* Properties of audio streams for host/guest for in or out directions.
683	*/
684	typedef struct PDMAUDIOPCMPROPS
685	{
686	/** The frame size. */
687	uint8_t cbFrame;
688	/** Shift count used with PDMAUDIOPCMPROPS_F2B and PDMAUDIOPCMPROPS_B2F.
689	* Depends on number of stream channels and the stream format being used, calc
690	* value using PDMAUDIOPCMPROPS_MAKE_SHIFT.
691	* @sa PDMAUDIOSTREAMCFG_B2F, PDMAUDIOSTREAMCFG_F2B */
692	uint8_t cShiftX;
693	/** Sample width (in bytes). */
694	RT_GCC_EXTENSION
695	uint8_t cbSampleX : 4;
696	/** Number of audio channels. */
697	RT_GCC_EXTENSION
698	uint8_t cChannelsX : 4;
699	/** Signed or unsigned sample. */
700	bool fSigned : 1;
701	/** Whether the endianness is swapped or not. */
702	bool fSwapEndian : 1;
703	/** Raw mixer frames, only applicable for signed 64-bit samples. */
704	bool fRaw : 1;
705	/** Sample frequency in Hertz (Hz). */
706	uint32_t uHz;
707	} PDMAUDIOPCMPROPS;
708	AssertCompileSize(PDMAUDIOPCMPROPS, 8);
709	AssertCompileSizeAlignment(PDMAUDIOPCMPROPS, 8);
710	/** Pointer to audio stream properties. */
711	typedef PDMAUDIOPCMPROPS *PPDMAUDIOPCMPROPS;
712	/** Pointer to const audio stream properties. */
713	typedef PDMAUDIOPCMPROPS const *PCPDMAUDIOPCMPROPS;
714
715	/** @name Macros for use with PDMAUDIOPCMPROPS
716	* @{ */
717	/** Initializer for PDMAUDIOPCMPROPS. */
718	#define PDMAUDIOPCMPROPS_INITIALIZER(a_cbSample, a_fSigned, a_cChannels, a_uHz, a_fSwapEndian) \
719	{ (a_cbSample) * (a_cChannels), PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS(a_cbSample, a_cChannels), a_cbSample, a_cChannels, \
720	a_fSigned, a_fSwapEndian, false /fRaw/, a_uHz }
721	/** Calculates the cShift value of given sample bits and audio channels.
722	* @note Does only support mono/stereo channels for now, for non-stereo/mono we
723	* returns a special value which the two conversion functions detect
724	* and make them fall back on cbSample * cChannels. */
725	#define PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS(cbSample, cChannels) \
726	( RT_IS_POWER_OF_TWO((unsigned)((cChannels) * (cbSample))) \
727	? (uint8_t)(ASMBitFirstSetU32((unsigned)((cChannels) * (cbSample))) - 1) : (uint8_t)UINT8_MAX )
728	/** Calculates the cShift value of a PDMAUDIOPCMPROPS structure. */
729	#define PDMAUDIOPCMPROPS_MAKE_SHIFT(pProps) \
730	PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS((pProps)->cbSampleX, (pProps)->cChannelsX)
731	/** Converts (audio) frames to bytes.
732	* @note Requires properly initialized properties, i.e. cbFrames correctly calculated
733	* and cShift set using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
734	#define PDMAUDIOPCMPROPS_F2B(pProps, cFrames) \
735	( (pProps)->cShiftX != UINT8_MAX ? (cFrames) << (pProps)->cShiftX : (cFrames) * (pProps)->cbFrame )
736	/** Converts bytes to (audio) frames.
737	* @note Requires properly initialized properties, i.e. cbFrames correctly calculated
738	* and cShift set using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
739	#define PDMAUDIOPCMPROPS_B2F(pProps, cb) \
740	( (pProps)->cShiftX != UINT8_MAX ? (cb) >> (pProps)->cShiftX : (cb) / (pProps)->cbFrame )
741	/** @} */
742
743	/**
744	* An audio stream configuration.
745	*/
746	typedef struct PDMAUDIOSTREAMCFG
747	{
748	/** Direction of the stream. */
749	PDMAUDIODIR enmDir;
750	/** Destination / source indicator, depending on enmDir. */
751	PDMAUDIODSTSRCUNION u;
752	/** The stream's PCM properties. */
753	PDMAUDIOPCMPROPS Props;
754	/** The stream's audio data layout.
755	* This indicates how the audio data buffers to/from the backend is being layouted.
756	*
757	* Currently, the following layouts are supported by the audio connector:
758	*
759	* PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED:
760	* One stream at once. The consecutive audio data is exactly in the format and frame width
761	* like defined in the PCM properties. This is the default.
762	*
763	* PDMAUDIOSTREAMLAYOUT_RAW:
764	* Can be one or many streams at once, depending on the stream's mixing buffer setup.
765	* The audio data will get handled as PDMAUDIOFRAME frames without any modification done.
766	*
767	* @todo r=bird: See PDMAUDIOSTREAMLAYOUT comments. */
768	PDMAUDIOSTREAMLAYOUT enmLayout;
769	/** Device emulation-specific data needed for the audio connector. */
770	struct
771	{
772	/** Scheduling hint set by the device emulation about when this stream is being served on average (in ms).
773	* Can be 0 if not hint given or some other mechanism (e.g. callbacks) is being used. */
774	uint32_t cMsSchedulingHint;
775	} Device;
776	/**
777	* Backend-specific data for the stream.
778	* On input (requested configuration) those values are set by the audio connector to let the backend know what we expect.
779	* On output (acquired configuration) those values reflect the values set and used by the backend.
780	* Set by the backend on return. Not all backends support all values / features.
781	*/
782	struct
783	{
784	/** Period size of the stream (in audio frames).
785	* This value reflects the number of audio frames in between each hardware interrupt on the
786	* backend (host) side. 0 if not set / available by the backend. */
787	uint32_t cFramesPeriod;
788	/** (Ring) buffer size (in audio frames). Often is a multiple of cFramesPeriod.
789	* 0 if not set / available by the backend. */
790	uint32_t cFramesBufferSize;
791	/** Pre-buffering size (in audio frames). Frames needed in buffer before the stream becomes active (pre buffering).
792	* The bigger this value is, the more latency for the stream will occur.
793	* 0 if not set / available by the backend. UINT32_MAX if not defined (yet). */
794	uint32_t cFramesPreBuffering;
795	} Backend;
796	uint32_t u32Padding;
797	/** Friendly name of the stream. */
798	char szName[64];
799	} PDMAUDIOSTREAMCFG;
800	AssertCompileSizeAlignment(PDMAUDIOSTREAMCFG, 8);
801	/** Pointer to audio stream configuration keeper. */
802	typedef PDMAUDIOSTREAMCFG *PPDMAUDIOSTREAMCFG;
803	/** Pointer to a const audio stream configuration keeper. */
804	typedef PDMAUDIOSTREAMCFG const *PCPDMAUDIOSTREAMCFG;
805
806	/** Converts (audio) frames to bytes. */
807	#define PDMAUDIOSTREAMCFG_F2B(pCfg, frames) PDMAUDIOPCMPROPS_F2B(&(pCfg)->Props, (frames))
808	/** Converts bytes to (audio) frames. */
809	#define PDMAUDIOSTREAMCFG_B2F(pCfg, cb) PDMAUDIOPCMPROPS_B2F(&(pCfg)->Props, (cb))
810
811	/**
812	* Audio mixer controls.
813	*/
814	typedef enum PDMAUDIOMIXERCTL
815	{
816	/** Invalid zero value as per usual (guards against using unintialized values). */
817	PDMAUDIOMIXERCTL_INVALID = 0,
818	/** Unknown mixer control. */
819	PDMAUDIOMIXERCTL_UNKNOWN,
820	/** Master volume. */
821	PDMAUDIOMIXERCTL_VOLUME_MASTER,
822	/** Front. */
823	PDMAUDIOMIXERCTL_FRONT,
824	/** Center / LFE (Subwoofer). */
825	PDMAUDIOMIXERCTL_CENTER_LFE,
826	/** Rear. */
827	PDMAUDIOMIXERCTL_REAR,
828	/** Line-In. */
829	PDMAUDIOMIXERCTL_LINE_IN,
830	/** Microphone-In. */
831	PDMAUDIOMIXERCTL_MIC_IN,
832	/** End of valid values. */
833	PDMAUDIOMIXERCTL_END,
834	/** Hack to blow the type up to 32-bit. */
835	PDMAUDIOMIXERCTL_32BIT_HACK = 0x7fffffff
836	} PDMAUDIOMIXERCTL;
837
838	/**
839	* Audio stream commands.
840	*
841	* Used in the audio connector as well as in the actual host backends.
842	*/
843	typedef enum PDMAUDIOSTREAMCMD
844	{
845	/** Invalid zero value as per usual (guards against using unintialized values). */
846	PDMAUDIOSTREAMCMD_INVALID = 0,
847	/** Enables the stream. */
848	PDMAUDIOSTREAMCMD_ENABLE,
849	/** Disables the stream.
850	* For output streams this stops the stream after playing the remaining (buffered) audio data.
851	* For input streams this will deliver the remaining (captured) audio data and not accepting
852	* any new audio input data afterwards. */
853	PDMAUDIOSTREAMCMD_DISABLE,
854	/** Pauses the stream.
855	* This is currently only issued when the VM is suspended (paused). */
856	PDMAUDIOSTREAMCMD_PAUSE,
857	/** Resumes the stream.
858	This is currently only issued when the VM is resumed. /
859	PDMAUDIOSTREAMCMD_RESUME,
860	/** Drain the stream, that is, play what's in the buffer and then stop.
861	*
862	* A separate DISABLE command will be issued to disable the stream.
863	*
864	* @note This should not wait for the stream to finish draining, just change the
865	* state. (EMT cannot wait hundreds of milliseconds of
866	* buffer to finish draining.)
867	* @note Does not apply to input streams. Backends should refuse such requests.
868	* @note No supported by all backends. */
869	PDMAUDIOSTREAMCMD_DRAIN,
870	/** End of valid values. */
871	PDMAUDIOSTREAMCMD_END,
872	/** Hack to blow the type up to 32-bit. */
873	PDMAUDIOSTREAMCMD_32BIT_HACK = 0x7fffffff
874	} PDMAUDIOSTREAMCMD;
875
876	/**
877	* Audio volume parameters.
878	*/
879	typedef struct PDMAUDIOVOLUME
880	{
881	/** Set to @c true if this stream is muted, @c false if not. */
882	bool fMuted;
883	/** Left channel volume.
884	* Range is from [0 ... 255], whereas 0 specifies
885	* the most silent and 255 the loudest value. */
886	uint8_t uLeft;
887	/** Right channel volume.
888	* Range is from [0 ... 255], whereas 0 specifies
889	* the most silent and 255 the loudest value. */
890	uint8_t uRight;
891	} PDMAUDIOVOLUME;
892	/** Pointer to audio volume settings. */
893	typedef PDMAUDIOVOLUME *PPDMAUDIOVOLUME;
894
895	/** Defines the minimum volume allowed. */
896	#define PDMAUDIO_VOLUME_MIN (0)
897	/** Defines the maximum volume allowed. */
898	#define PDMAUDIO_VOLUME_MAX (255)
899
900
901	/** @name PDMAUDIOSTREAM_STS_XXX
902	* @sa PDMIAUDIOCONNECTOR::pfnStreamGetStatus, PDMIHOSTAUDIO::pfnStreamGetStatus
903	* @{ */
904	/** No flags being set. */
905	#define PDMAUDIOSTREAM_STS_NONE UINT32_C(0)
906	/** Whether this stream has been initialized by the backend or not. */
907	#define PDMAUDIOSTREAM_STS_INITIALIZED RT_BIT_32(0)
908	/** Whether this stream is enabled or disabled. */
909	#define PDMAUDIOSTREAM_STS_ENABLED RT_BIT_32(1)
910	/** Whether this stream has been paused or not. This also implies
911	* that this is an enabled stream! */
912	#define PDMAUDIOSTREAM_STS_PAUSED RT_BIT_32(2)
913	/** Indicates that the stream is draining (output only).
914	* Whether this stream was marked as being disabled
915	* but there are still associated guest output streams
916	* which rely on its data. */
917	#define PDMAUDIOSTREAM_STS_PENDING_DISABLE RT_BIT_32(3)
918	/** Whether this stream is in re-initialization phase and requires the device
919	* to call pfnStreamReInit.
920	*
921	* All other bits remain untouched to be able to restore the stream's state
922	* after the re-initialization has been completed. */
923	#define PDMAUDIOSTREAM_STS_NEED_REINIT RT_BIT_32(4)
924	/** Validation mask. */
925	#define PDMAUDIOSTREAM_STS_VALID_MASK UINT32_C(0x0000001f)
926	/** @} */
927
928	/**
929	* Backend status.
930	*/
931	typedef enum PDMAUDIOBACKENDSTS
932	{
933	/** Unknown/invalid status. */
934	PDMAUDIOBACKENDSTS_UNKNOWN = 0,
935	/** No backend attached. */
936	PDMAUDIOBACKENDSTS_NOT_ATTACHED,
937	/** The backend is in its initialization phase.
938	* Not all backends support this status. */
939	PDMAUDIOBACKENDSTS_INITIALIZING,
940	/** The backend has stopped its operation. */
941	PDMAUDIOBACKENDSTS_STOPPED,
942	/** The backend is up and running. */
943	PDMAUDIOBACKENDSTS_RUNNING,
944	/** The backend ran into an error and is unable to recover.
945	* A manual re-initialization might help. */
946	PDMAUDIOBACKENDSTS_ERROR,
947	/** Hack to blow the type up to 32-bit. */
948	PDMAUDIOBACKENDSTS_32BIT_HACK = 0x7fffffff
949	} PDMAUDIOBACKENDSTS;
950
951	/** @name PDMAUDIOSTREAM_CREATE_F_XXX
952	* @{ */
953	/** Does not need any mixing buffers, the device takes care of all conversion. */
954	#define PDMAUDIOSTREAM_CREATE_F_NO_MIXBUF RT_BIT_32(0)
955	/** @} */
956
957	/** @name PDMAUDIOSTREAM_WARN_FLAGS_XXX
958	* @{ */
959	/** No stream warning flags set. */
960	#define PDMAUDIOSTREAM_WARN_FLAGS_NONE 0
961	/** Warned about a disabled stream. */
962	#define PDMAUDIOSTREAM_WARN_FLAGS_DISABLED RT_BIT(0)
963	/** @} */
964
965	/**
966	* An input or output audio stream.
967	*/
968	typedef struct PDMAUDIOSTREAM
969	{
970	/** Magic value (PDMAUDIOSTREAM_MAGIC). */
971	uint32_t uMagic;
972	/** Number of references to this stream.
973	* Only can be destroyed when the reference count reaches 0. */
974	uint32_t volatile cRefs;
975	/** Stream status flag. */
976	uint32_t fStatus;
977	/** Audio direction of this stream. */
978	PDMAUDIODIR enmDir;
979	/** Size (in bytes) of the backend-specific stream data. */
980	uint32_t cbBackend;
981	/** Warnings shown already in the release log.
982	* See PDMAUDIOSTREAM_WARN_FLAGS_XXX. */
983	uint32_t fWarningsShown;
984	/** The stream properties (both sides when PDMAUDIOSTREAM_CREATE_F_NO_MIXBUF
985	* is used, otherwise the guest side). */
986	PDMAUDIOPCMPROPS Props;
987
988	/** Name of this stream. */
989	char szName[64];
990	} PDMAUDIOSTREAM;
991	/** Pointer to an audio stream. */
992	typedef struct PDMAUDIOSTREAM *PPDMAUDIOSTREAM;
993	/** Pointer to a const audio stream. */
994	typedef struct PDMAUDIOSTREAM const *PCPDMAUDIOSTREAM;
995
996	/** Magic value for PDMAUDIOSTREAM. */
997	#define PDMAUDIOSTREAM_MAGIC PDM_VERSION_MAKE(0xa0d3, 3, 0)
998
999
1000
1001	/** Pointer to a audio connector interface. */
1002	typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
1003
1004	/**
1005	* Audio connector interface (up).
1006	*/
1007	typedef struct PDMIAUDIOCONNECTOR
1008	{
1009	/**
1010	* Enables or disables the given audio direction for this driver.
1011	*
1012	* When disabled, assiociated output streams consume written audio without passing them further down to the backends.
1013	* Associated input streams then return silence when read from those.
1014	*
1015	* @returns VBox status code.
1016	* @param pInterface Pointer to the interface structure containing the called function pointer.
1017	* @param enmDir Audio direction to enable or disable driver for.
1018	* @param fEnable Whether to enable or disable the specified audio direction.
1019	*
1020	* @note Be very careful when using this function, as this could
1021	* violate / run against the (global) VM settings. See @bugref{9882}.
1022	*/
1023	DECLR3CALLBACKMEMBER(int, pfnEnable, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir, bool fEnable));
1024
1025	/**
1026	* Returns whether the given audio direction for this driver is enabled or not.
1027	*
1028	* @returns True if audio is enabled for the given direction, false if not.
1029	* @param pInterface Pointer to the interface structure containing the called function pointer.
1030	* @param enmDir Audio direction to retrieve enabled status for.
1031	*/
1032	DECLR3CALLBACKMEMBER(bool, pfnIsEnabled, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
1033
1034	/**
1035	* Retrieves the current configuration of the host audio backend.
1036	*
1037	* @returns VBox status code.
1038	* @param pInterface Pointer to the interface structure containing the called function pointer.
1039	* @param pCfg Where to store the host audio backend configuration data.
1040	*/
1041	DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOBACKENDCFG pCfg));
1042
1043	/**
1044	* Retrieves the current status of the host audio backend.
1045	*
1046	* @returns Status of the host audio backend.
1047	* @param pInterface Pointer to the interface structure containing the called function pointer.
1048	* @param enmDir Audio direction to check host audio backend for. Specify PDMAUDIODIR_DUPLEX for the overall
1049	* backend status.
1050	*/
1051	DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
1052
1053	/**
1054	* Gives the audio drivers a hint about a typical configuration.
1055	*
1056	* This is a little hack for windows (and maybe other hosts) where stream
1057	* creation can take a relatively long time, making it very unsuitable for EMT.
1058	* The audio backend can use this hint to cache pre-configured stream setups,
1059	* so that when the guest actually wants to play something EMT won't be blocked
1060	* configuring host audio.
1061	*
1062	* @param pInterface Pointer to this interface.
1063	* @param pCfg The typical configuration. Can be modified by the
1064	* drivers in unspecified ways.
1065	*/
1066	DECLR3CALLBACKMEMBER(void, pfnStreamConfigHint, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfg));
1067
1068	/**
1069	* Creates an audio stream.
1070	*
1071	* @returns VBox status code.
1072	* @param pInterface Pointer to the interface structure containing the called function pointer.
1073	* @param fFlags PDMAUDIOSTREAM_CREATE_F_XXX.
1074	* @param pCfgHost Stream configuration for host side.
1075	* @param pCfgGuest Stream configuration for guest side.
1076	* @param ppStream Pointer where to return the created audio stream on success.
1077	* @todo r=bird: It is not documented how pCfgHost and pCfgGuest can be
1078	* modified the DrvAudio...
1079	*/
1080	DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIAUDIOCONNECTOR pInterface, uint32_t fFlags, PPDMAUDIOSTREAMCFG pCfgHost,
1081	PPDMAUDIOSTREAMCFG pCfgGuest, PPDMAUDIOSTREAM *ppStream));
1082
1083
1084	/**
1085	* Destroys an audio stream.
1086	*
1087	* @param pInterface Pointer to the interface structure containing the called function pointer.
1088	* @param pStream Pointer to audio stream.
1089	*/
1090	DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1091
1092	/**
1093	* Re-initializes the stream in response to PDMAUDIOSTREAM_STS_NEED_REINIT.
1094	*
1095	* @returns VBox status code.
1096	* @param pInterface Pointer to this interface.
1097	* @param pStream The audio stream needing re-initialization.
1098	*/
1099	DECLR3CALLBACKMEMBER(int, pfnStreamReInit, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1100
1101	/**
1102	* Adds a reference to the specified audio stream.
1103	*
1104	* @returns New reference count. UINT32_MAX on error.
1105	* @param pInterface Pointer to the interface structure containing the called function pointer.
1106	* @param pStream Pointer to audio stream adding the reference to.
1107	*/
1108	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRetain, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1109
1110	/**
1111	* Releases a reference from the specified stream.
1112	*
1113	* @returns New reference count. UINT32_MAX on error.
1114	* @param pInterface Pointer to the interface structure containing the called function pointer.
1115	* @param pStream Pointer to audio stream releasing a reference from.
1116	*/
1117	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRelease, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1118
1119	/**
1120	* Controls a specific audio stream.
1121	*
1122	* @returns VBox status code.
1123	* @param pInterface Pointer to the interface structure containing the called function pointer.
1124	* @param pStream Pointer to audio stream.
1125	* @param enmStreamCmd The stream command to issue.
1126	*/
1127	DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1128	PDMAUDIOSTREAMCMD enmStreamCmd));
1129
1130	/**
1131	* Processes stream data.
1132	*
1133	* @param pInterface Pointer to the interface structure containing the called function pointer.
1134	* @param pStream Pointer to audio stream.
1135	*/
1136	DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1137
1138	/**
1139	* Returns the number of readable data (in bytes) of a specific audio input stream.
1140	*
1141	* @returns Number of bytes of readable data.
1142	* @param pInterface Pointer to the interface structure containing the called function pointer.
1143	* @param pStream Pointer to audio stream.
1144	*/
1145	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1146
1147	/**
1148	* Returns the number of writable data (in bytes) of a specific audio output stream.
1149	*
1150	* @returns Number of bytes writable data.
1151	* @param pInterface Pointer to the interface structure containing the called function pointer.
1152	* @param pStream Pointer to audio stream.
1153	*/
1154	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1155
1156	/**
1157	* Returns the status of a specific audio stream.
1158	*
1159	* @returns PDMAUDIOSTREAM_STS_XXX
1160	* @param pInterface Pointer to the interface structure containing the called function pointer.
1161	* @param pStream Pointer to audio stream.
1162	*/
1163	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1164
1165	/**
1166	* Sets the audio volume of a specific audio stream.
1167	*
1168	* @returns VBox status code.
1169	* @param pInterface Pointer to the interface structure containing the called function pointer.
1170	* @param pStream Pointer to audio stream.
1171	* @param pVol Pointer to audio volume structure to set the stream's audio volume to.
1172	*/
1173	DECLR3CALLBACKMEMBER(int, pfnStreamSetVolume, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOVOLUME pVol));
1174
1175	/**
1176	* Plays (writes to) an audio (output) stream.
1177	*
1178	* @returns VBox status code.
1179	* @param pInterface Pointer to the interface structure containing the called function pointer.
1180	* @param pStream Pointer to audio stream to read from.
1181	* @param pvBuf Audio data to be written.
1182	* @param cbBuf Number of bytes to be written.
1183	* @param pcbWritten Bytes of audio data written. Optional.
1184	*/
1185	DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1186	const void pvBuf, uint32_t cbBuf, uint32_t pcbWritten));
1187
1188	/**
1189	* Reads PCM audio data from the host (input).
1190	*
1191	* @returns VBox status code.
1192	* @param pInterface Pointer to the interface structure containing the called function pointer.
1193	* @param pStream Pointer to audio stream to write to.
1194	* @param pvBuf Where to store the read data.
1195	* @param cbBuf Number of bytes to read.
1196	* @param pcbRead Bytes of audio data read. Optional.
1197	*/
1198	DECLR3CALLBACKMEMBER(int, pfnStreamRead, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1199	void pvBuf, uint32_t cbBuf, uint32_t pcbRead));
1200
1201	/**
1202	* Captures (transfers) available audio frames from the host backend.
1203	*
1204	* Only works with input streams.
1205	*
1206	* @returns VBox status code.
1207	* @param pInterface Pointer to the interface structure containing the called function pointer.
1208	* @param pStream Pointer to audio stream.
1209	* @param pcFramesCaptured Number of frames captured. Optional.
1210	*/
1211	DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1212	uint32_t *pcFramesCaptured));
1213
1214	} PDMIAUDIOCONNECTOR;
1215
1216	/** PDMIAUDIOCONNECTOR interface ID. */
1217	#define PDMIAUDIOCONNECTOR_IID "ff6788cc-1a4d-4d4b-a2e0-9f56fce9b397"
1218
1219
1220	/**
1221	* Host audio backend specific stream data.
1222	*
1223	* The backend will put this as the first member of it's own data structure.
1224	*/
1225	typedef struct PDMAUDIOBACKENDSTREAM
1226	{
1227	/** Magic value (PDMAUDIOBACKENDSTREAM_MAGIC). */
1228	uint32_t uMagic;
1229	/** Explicit zero padding - do not touch! */
1230	uint32_t uReserved;
1231	/** Pointer to the stream this backend data is associated with. */
1232	PPDMAUDIOSTREAM pStream;
1233	/** Reserved for future use (zeroed) - do not touch. */
1234	void *apvReserved[2];
1235	} PDMAUDIOBACKENDSTREAM;
1236	/** Pointer to host audio specific stream data! */
1237	typedef PDMAUDIOBACKENDSTREAM *PPDMAUDIOBACKENDSTREAM;
1238
1239	/** Magic value for PDMAUDIOBACKENDSTREAM. */
1240	#define PDMAUDIOBACKENDSTREAM_MAGIC PDM_VERSION_MAKE(0xa0d4, 1, 0)
1241
1242
1243	/** Pointer to a host audio interface. */
1244	typedef struct PDMIHOSTAUDIO *PPDMIHOSTAUDIO;
1245
1246	/**
1247	* PDM host audio interface.
1248	*/
1249	typedef struct PDMIHOSTAUDIO
1250	{
1251	/**
1252	* Returns the host backend's configuration (backend).
1253	*
1254	* @returns VBox status code.
1255	* @param pInterface Pointer to the interface structure containing the called function pointer.
1256	* @param pBackendCfg Where to store the backend audio configuration to.
1257	*/
1258	DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg));
1259
1260	/**
1261	* Returns (enumerates) host audio device information (optional).
1262	*
1263	* @returns VBox status code.
1264	* @param pInterface Pointer to the interface structure containing the called function pointer.
1265	* @param pDeviceEnum Where to return the enumerated audio devices.
1266	*/
1267	DECLR3CALLBACKMEMBER(int, pfnGetDevices, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHOSTENUM pDeviceEnum));
1268
1269	/**
1270	* Returns the current status from the audio backend (optional).
1271	*
1272	* @returns PDMAUDIOBACKENDSTS enum.
1273	* @param pInterface Pointer to the interface structure containing the called function pointer.
1274	* @param enmDir Audio direction to get status for. Pass PDMAUDIODIR_DUPLEX for overall status.
1275	*/
1276	DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir));
1277
1278	/**
1279	* Gives the audio backend a hint about a typical configuration (optional).
1280	*
1281	* This is a little hack for windows (and maybe other hosts) where stream
1282	* creation can take a relatively long time, making it very unsuitable for EMT.
1283	* The audio backend can use this hint to cache pre-configured stream setups,
1284	* so that when the guest actually wants to play something EMT won't be blocked
1285	* configuring host audio.
1286	*
1287	* @param pInterface Pointer to this interface.
1288	* @param pCfg The typical configuration. (Feel free to change it
1289	* to the actual stream config that would be used,
1290	* however caller will probably ignore this.)
1291	*/
1292	DECLR3CALLBACKMEMBER(void, pfnStreamConfigHint, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAMCFG pCfg));
1293
1294	/**
1295	* Creates an audio stream using the requested stream configuration.
1296	*
1297	* If a backend is not able to create this configuration, it will return its
1298	* best match in the acquired configuration structure on success.
1299	*
1300	* @returns VBox status code.
1301	* @param pInterface Pointer to the interface structure containing the called function pointer.
1302	* @param pStream Pointer to audio stream.
1303	* @param pCfgReq Pointer to requested stream configuration.
1304	* @param pCfgAcq Pointer to acquired stream configuration.
1305	* @todo r=bird: Implementation (at least Alsa) seems to make undocumented
1306	* assumptions about the content of @a pCfgAcq.
1307	*/
1308	DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1309	PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq));
1310
1311	/**
1312	* Destroys an audio stream.
1313	*
1314	* @returns VBox status code.
1315	* @param pInterface Pointer to the interface structure containing the called function pointer.
1316	* @param pStream Pointer to audio stream.
1317	*/
1318	DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1319
1320	/**
1321	* Controls an audio stream.
1322	*
1323	* @returns VBox status code.
1324	* @retval VERR_AUDIO_STREAM_NOT_READY if stream is not ready for required operation (yet).
1325	* @param pInterface Pointer to the interface structure containing the called function pointer.
1326	* @param pStream Pointer to audio stream.
1327	* @param enmStreamCmd The stream command to issue.
1328	*/
1329	DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1330	PDMAUDIOSTREAMCMD enmStreamCmd));
1331
1332	/**
1333	* Returns the amount which is readable from the audio (input) stream.
1334	*
1335	* @returns For non-raw layout streams: Number of readable bytes.
1336	* for raw layout streams : Number of readable audio frames.
1337	* @param pInterface Pointer to the interface structure containing the called function pointer.
1338	* @param pStream Pointer to audio stream.
1339	*/
1340	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1341
1342	/**
1343	* Returns the amount which is writable to the audio (output) stream.
1344	*
1345	* @returns Number of writable bytes.
1346	* @param pInterface Pointer to the interface structure containing the called function pointer.
1347	* @param pStream Pointer to audio stream.
1348	*/
1349	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1350
1351	/**
1352	* Returns the number of buffered bytes that hasn't been played yet (optional).
1353	*
1354	* This function is used by DrvAudio to detect when it is appropriate to fully
1355	* disable an output stream w/o cutting off the playback too early. The backend
1356	* should have already received the PDMAUDIOSTREAMCMD_DRAIN command prior to
1357	* this. It doesn't really matter whether the returned value is 100% correct,
1358	* as long as it isn't reported as zero too early (and that zero is reported).
1359	*
1360	* Is not valid on an input stream, implementions shall assert and return zero.
1361	*
1362	* @returns Number of pending bytes.
1363	* @param pInterface Pointer to this interface.
1364	* @param pStream Pointer to audio stream.
1365	*
1366	* @remarks This interface can be omitted if the backend properly implements the
1367	* drain operation, i.e. automatically disables the stream when done
1368	* draining and ignores any requests to disable the stream while doing
1369	* so (there will probably be one right after initiating draining).
1370	*/
1371	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetPending, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1372
1373	/**
1374	* Returns the current status of the given backend stream.
1375	*
1376	* @returns PDMAUDIOSTREAM_STS_XXX
1377	* @param pInterface Pointer to the interface structure containing the called function pointer.
1378	* @param pStream Pointer to audio stream.
1379	*/
1380	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetStatus, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1381
1382	/**
1383	* Plays (writes to) an audio (output) stream.
1384	*
1385	* @returns VBox status code.
1386	* @param pInterface Pointer to the interface structure containing the called function pointer.
1387	* @param pStream Pointer to audio stream.
1388	* @param pvBuf Pointer to audio data buffer to play.
1389	* @param cbBuf The number of bytes of audio data to play.
1390	* @param pcbWritten Where to return the actual number of bytes played.
1391	*/
1392	DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1393	const void pvBuf, uint32_t cbBuf, uint32_t pcbWritten));
1394
1395	/**
1396	* Captures (reads from) an audio (input) stream.
1397	*
1398	* @returns VBox status code.
1399	* @param pInterface Pointer to the interface structure containing the called function pointer.
1400	* @param pStream Pointer to audio stream.
1401	* @param pvBuf Buffer where to store read audio data.
1402	* @param cbBuf Size of the audio data buffer in bytes.
1403	* @param pcbRead Where to return the number of bytes actually captured.
1404	*/
1405	DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1406	void pvBuf, uint32_t cbBuf, uint32_t pcbRead));
1407
1408	} PDMIHOSTAUDIO;
1409
1410	/** PDMIHOSTAUDIO interface ID. */
1411	#define PDMIHOSTAUDIO_IID "109d8c74-dfed-4056-b5ad-022de4d249c2"
1412
1413
1414	/** Pointer to a audio notify from host interface. */
1415	typedef struct PDMIAUDIONOTIFYFROMHOST *PPDMIAUDIONOTIFYFROMHOST;
1416
1417	/**
1418	* PDM audio notification interface, for use by host audio.
1419	*
1420	* @todo better name?
1421	*/
1422	typedef struct PDMIAUDIONOTIFYFROMHOST
1423	{
1424	/**
1425	* One or more audio devices have changed in some way.
1426	*
1427	* The upstream driver/device should re-evaluate the devices they're using.
1428	*
1429	* @param pInterface Pointer to this interface.
1430	*/
1431	DECLR3CALLBACKMEMBER(void, pfnNotifyDevicesChanged,(PPDMIAUDIONOTIFYFROMHOST pInterface));
1432	} PDMIAUDIONOTIFYFROMHOST;
1433
1434	/** PDMIAUDIONOTIFYFROMHOST interface ID. */
1435	#define PDMIAUDIONOTIFYFROMHOST_IID "ec10f36b-ec2d-4b97-9044-2a59fba837ad"
1436
1437	/** @} */
1438
1439	#endif /* !VBOX_INCLUDED_vmm_pdmaudioifs_h */
1440

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

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

Download in other formats: