VirtualBox

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

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

Audio: Need to copy PDMAUDIOHOSTDEV::pszId in PDMAudioHostDevDup. bugref:9890
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 67.1 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/critsect.h>
234#include <iprt/circbuf.h>
235#include <iprt/list.h>
236#include <iprt/path.h>
237
238#include <VBox/types.h>
239#include <VBox/vmm/pdmcommon.h>
240#include <VBox/vmm/stam.h>
241
242/** @defgroup grp_pdm_ifs_audio PDM Audio Interfaces
243 * @ingroup grp_pdm_interfaces
244 * @{
245 */
246
247#ifndef VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH
248# if defined(RT_OS_WINDOWS) || defined(RT_OS_OS2)
249# define VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "c:\\temp\\"
250# else
251# define VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "/tmp/"
252# endif
253#endif
254
255/** PDM audio driver instance flags. */
256typedef uint32_t PDMAUDIODRVFLAGS;
257
258/** No flags set. */
259#define PDMAUDIODRVFLAGS_NONE 0
260/** Marks a primary audio driver which is critical
261 * when running the VM. */
262#define PDMAUDIODRVFLAGS_PRIMARY RT_BIT(0)
263
264/**
265 * Audio format in signed or unsigned variants.
266 */
267typedef enum PDMAUDIOFMT
268{
269 /** Invalid format, do not use. */
270 PDMAUDIOFMT_INVALID = 0,
271 /** 8-bit, unsigned. */
272 PDMAUDIOFMT_U8,
273 /** 8-bit, signed. */
274 PDMAUDIOFMT_S8,
275 /** 16-bit, unsigned. */
276 PDMAUDIOFMT_U16,
277 /** 16-bit, signed. */
278 PDMAUDIOFMT_S16,
279 /** 32-bit, unsigned. */
280 PDMAUDIOFMT_U32,
281 /** 32-bit, signed. */
282 PDMAUDIOFMT_S32,
283 /** End of valid values. */
284 PDMAUDIOFMT_END,
285 /** Hack to blow the type up to 32-bit. */
286 PDMAUDIOFMT_32BIT_HACK = 0x7fffffff
287} PDMAUDIOFMT;
288
289/**
290 * Audio direction.
291 */
292typedef enum PDMAUDIODIR
293{
294 /** Invalid zero value as per usual (guards against using unintialized values). */
295 PDMAUDIODIR_INVALID = 0,
296 /** Unknown direction. */
297 PDMAUDIODIR_UNKNOWN,
298 /** Input. */
299 PDMAUDIODIR_IN,
300 /** Output. */
301 PDMAUDIODIR_OUT,
302 /** Duplex handling. */
303 PDMAUDIODIR_DUPLEX,
304 /** End of valid values. */
305 PDMAUDIODIR_END,
306 /** Hack to blow the type up to 32-bit. */
307 PDMAUDIODIR_32BIT_HACK = 0x7fffffff
308} PDMAUDIODIR;
309
310
311/** @name PDMAUDIOHOSTDEV_F_XXX
312 * @{ */
313/** No flags set. */
314#define PDMAUDIOHOSTDEV_F_NONE UINT32_C(0)
315/** The default input (capture/recording) device (for the user). */
316#define PDMAUDIOHOSTDEV_F_DEFAULT_IN RT_BIT_32(0)
317/** The default output (playback) device (for the user). */
318#define PDMAUDIOHOSTDEV_F_DEFAULT_OUT RT_BIT_32(1)
319/** The device can be removed at any time and we have to deal with it. */
320#define PDMAUDIOHOSTDEV_F_HOTPLUG RT_BIT_32(2)
321/** The device is known to be buggy and needs special treatment. */
322#define PDMAUDIOHOSTDEV_F_BUGGY RT_BIT_32(3)
323/** Ignore the device, no matter what. */
324#define PDMAUDIOHOSTDEV_F_IGNORE RT_BIT_32(4)
325/** The device is present but marked as locked by some other application. */
326#define PDMAUDIOHOSTDEV_F_LOCKED RT_BIT_32(5)
327/** The device is present but not in an alive state (dead). */
328#define PDMAUDIOHOSTDEV_F_DEAD RT_BIT_32(6)
329/** Set if the PDMAUDIOHOSTDEV::pszId is allocated. */
330#define PDMAUDIOHOSTDEV_F_ID_ALLOC RT_BIT_32(30)
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 */
338typedef 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 */
362typedef 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 /** Maximum number of input audio channels the device supports. */
377 uint8_t cMaxInputChannels;
378 /** Maximum number of output audio channels the device supports. */
379 uint8_t cMaxOutputChannels;
380 uint8_t abAlignment[ARCH_BITS == 32 ? 2 + 12 : 2];
381 /** Device identifier, OS specific, can be NULL.
382 * This can either point into some non-public part of this structure or to a
383 * RTStrAlloc allocation. PDMAUDIOHOSTDEV_F_ID_ALLOC is set in the latter
384 * case. */
385 char *pszId;
386 /** Friendly name of the device, if any. Could be truncated. */
387 char szName[64];
388} PDMAUDIOHOSTDEV;
389AssertCompileSizeAlignment(PDMAUDIOHOSTDEV, 16);
390/** Pointer to audio device info (enumeration result). */
391typedef PDMAUDIOHOSTDEV *PPDMAUDIOHOSTDEV;
392/** Pointer to a const audio device info (enumeration result). */
393typedef PDMAUDIOHOSTDEV const *PCPDMAUDIOHOSTDEV;
394
395/** Magic value for PDMAUDIOHOSTDEV. */
396#define PDMAUDIOHOSTDEV_MAGIC PDM_VERSION_MAKE(0xa0d0, 2, 0)
397
398
399/**
400 * A host audio device enumeration result.
401 *
402 * @sa PDMIHOSTAUDIO::pfnGetDevices
403 */
404typedef struct PDMAUDIOHOSTENUM
405{
406 /** Magic value (PDMAUDIOHOSTENUM_MAGIC). */
407 uint32_t uMagic;
408 /** Number of audio devices in the list. */
409 uint32_t cDevices;
410 /** List of audio devices (PDMAUDIOHOSTDEV). */
411 RTLISTANCHOR LstDevices;
412} PDMAUDIOHOSTENUM;
413/** Pointer to an audio device enumeration result. */
414typedef PDMAUDIOHOSTENUM *PPDMAUDIOHOSTENUM;
415/** Pointer to a const audio device enumeration result. */
416typedef PDMAUDIOHOSTENUM const *PCPDMAUDIOHOSTENUM;
417
418/** Magic for the host audio device enumeration. */
419#define PDMAUDIOHOSTENUM_MAGIC PDM_VERSION_MAKE(0xa0d1, 1, 0)
420
421
422/**
423 * Audio configuration (static) of an audio host backend.
424 */
425typedef struct PDMAUDIOBACKENDCFG
426{
427 /** The backend's friendly name. */
428 char szName[32];
429 /** The size of the backend specific stream data (in bytes). */
430 uint32_t cbStream;
431 /** PDMAUDIOBACKEND_F_XXX. */
432 uint32_t fFlags;
433 /** Number of concurrent output (playback) streams supported on the host.
434 * UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
435 uint32_t cMaxStreamsOut;
436 /** Number of concurrent input (recording) streams supported on the host.
437 * UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
438 uint32_t cMaxStreamsIn;
439} PDMAUDIOBACKENDCFG;
440/** Pointer to a static host audio audio configuration. */
441typedef PDMAUDIOBACKENDCFG *PPDMAUDIOBACKENDCFG;
442
443/** @name PDMAUDIOBACKEND_F_XXX - PDMAUDIOBACKENDCFG::fFlags
444 * @{ */
445/** PDMIHOSTAUDIO::pfnStreamConfigHint should preferably be called on a
446 * worker thread rather than EMT as it may take a good while. */
447#define PDMAUDIOBACKEND_F_ASYNC_HINT RT_BIT_32(0)
448/** PDMIHOSTAUDIO::pfnStreamDestroy and any preceeding
449 * PDMIHOSTAUDIO::pfnStreamControl/DISABLE should be preferably be called on a
450 * worker thread rather than EMT as it may take a good while. */
451#define PDMAUDIOBACKEND_F_ASYNC_STREAM_DESTROY RT_BIT_32(1)
452/** @} */
453
454
455/**
456 * A single audio frame.
457 *
458 * Currently only two (2) channels, left and right, are supported.
459 *
460 * @note When changing this structure, make sure to also handle
461 * VRDP's input / output processing in DrvAudioVRDE, as VRDP
462 * expects audio data in st_sample_t format (historical reasons)
463 * which happens to be the same as PDMAUDIOFRAME for now.
464 *
465 * @todo r=bird: This is an internal AudioMixBuffer structure which should not
466 * be exposed here, I think. Only used to some sizeof statements in VRDE.
467 * (The problem with exposing it, is that we would like to move away from
468 * stereo and instead to anything from 1 to 16 channels. That means
469 * removing this structure entirely.)
470 */
471typedef struct PDMAUDIOFRAME
472{
473 /** Left channel. */
474 int64_t i64LSample;
475 /** Right channel. */
476 int64_t i64RSample;
477} PDMAUDIOFRAME;
478/** Pointer to a single (stereo) audio frame. */
479typedef PDMAUDIOFRAME *PPDMAUDIOFRAME;
480/** Pointer to a const single (stereo) audio frame. */
481typedef PDMAUDIOFRAME const *PCPDMAUDIOFRAME;
482
483
484/**
485 * Audio path: input sources and playback destinations.
486 *
487 * Think of this as the name of the socket you plug the virtual audio stream
488 * jack into.
489 *
490 * @note Not quite sure what the purpose of this type is. It used to be two
491 * separate enums (PDMAUDIOPLAYBACKDST & PDMAUDIORECSRC) without overlapping
492 * values and most commonly used in a union (PDMAUDIODSTSRCUNION). The output
493 * values were designated "channel" (e.g. "Front channel"), whereas this was not
494 * done to the input ones. So, I'm (bird) a little confused what the actual
495 * meaning was.
496 */
497typedef enum PDMAUDIOPATH
498{
499 /** Customary invalid zero value. */
500 PDMAUDIOPATH_INVALID = 0,
501
502 /** Unknown path / Doesn't care. */
503 PDMAUDIOPATH_UNKNOWN,
504
505 /** First output value. */
506 PDMAUDIOPATH_OUT_FIRST,
507 /** Output: Front. */
508 PDMAUDIOPATH_OUT_FRONT = PDMAUDIOPATH_OUT_FIRST,
509 /** Output: Center / LFE (Subwoofer). */
510 PDMAUDIOPATH_OUT_CENTER_LFE,
511 /** Output: Rear. */
512 PDMAUDIOPATH_OUT_REAR,
513 /** Last output value (inclusive) */
514 PDMAUDIOPATH_OUT_END = PDMAUDIOPATH_OUT_REAR,
515
516 /** First input value. */
517 PDMAUDIOPATH_IN_FIRST,
518 /** Input: Microphone. */
519 PDMAUDIOPATH_IN_MIC = PDMAUDIOPATH_IN_FIRST,
520 /** Input: CD. */
521 PDMAUDIOPATH_IN_CD,
522 /** Input: Video-In. */
523 PDMAUDIOPATH_IN_VIDEO,
524 /** Input: AUX. */
525 PDMAUDIOPATH_IN_AUX,
526 /** Input: Line-In. */
527 PDMAUDIOPATH_IN_LINE,
528 /** Input: Phone-In. */
529 PDMAUDIOPATH_IN_PHONE,
530 /** Last intput value (inclusive). */
531 PDMAUDIOPATH_IN_LAST = PDMAUDIOPATH_IN_PHONE,
532
533 /** End of valid values. */
534 PDMAUDIOPATH_END,
535 /** Hack to blow the typ up to 32 bits. */
536 PDMAUDIOPATH_32BIT_HACK = 0x7fffffff
537} PDMAUDIOPATH;
538
539/**
540 * Audio stream (data) layout.
541 */
542typedef enum PDMAUDIOSTREAMLAYOUT
543{
544 /** Invalid zero value as per usual (guards against using unintialized values). */
545 PDMAUDIOSTREAMLAYOUT_INVALID = 0,
546 /** Unknown access type; do not use (hdaR3StreamMapReset uses it). */
547 PDMAUDIOSTREAMLAYOUT_UNKNOWN,
548 /** Non-interleaved access, that is, consecutive access to the data.
549 * @todo r=bird: For plain stereo this is actually interleaves left/right. What
550 * I guess non-interleaved means, is that there are no additional
551 * information interleaved next to the interleaved stereo.
552 * https://stackoverflow.com/questions/17879933/whats-the-interleaved-audio */
553 PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED,
554 /** Interleaved access, where the data can be mixed together with data of other audio streams. */
555 PDMAUDIOSTREAMLAYOUT_INTERLEAVED,
556 /** Complex layout, which does not fit into the interleaved / non-interleaved layouts. */
557 PDMAUDIOSTREAMLAYOUT_COMPLEX,
558 /** Raw (pass through) data, with no data layout processing done.
559 *
560 * This means that this stream will operate on PDMAUDIOFRAME data
561 * directly. Don't use this if you don't have to.
562 *
563 * @deprecated Replaced by S64 (signed, 64-bit sample size). */
564 PDMAUDIOSTREAMLAYOUT_RAW,
565 /** End of valid values. */
566 PDMAUDIOSTREAMLAYOUT_END,
567 /** Hack to blow the type up to 32-bit. */
568 PDMAUDIOSTREAMLAYOUT_32BIT_HACK = 0x7fffffff
569} PDMAUDIOSTREAMLAYOUT;
570
571/**
572 * Stream channel data block.
573 */
574typedef struct PDMAUDIOSTREAMCHANNELDATA
575{
576 /** Circular buffer for the channel data. */
577 PRTCIRCBUF pCircBuf;
578 /** Amount of audio data (in bytes) acquired for reading. */
579 size_t cbAcq;
580 /** Channel data flags, PDMAUDIOSTREAMCHANNELDATA_FLAGS_XXX. */
581 uint32_t fFlags;
582} PDMAUDIOSTREAMCHANNELDATA;
583/** Pointer to audio stream channel data buffer. */
584typedef PDMAUDIOSTREAMCHANNELDATA *PPDMAUDIOSTREAMCHANNELDATA;
585
586/** @name PDMAUDIOSTREAMCHANNELDATA_FLAGS_XXX
587 * @{ */
588/** No stream channel data flags defined. */
589#define PDMAUDIOSTREAMCHANNELDATA_FLAGS_NONE UINT32_C(0)
590/** @} */
591
592/**
593 * Standard speaker channel IDs.
594 *
595 * This can cover up to 11.0 surround sound.
596 *
597 * @note Any of those channels can be marked / used as the LFE channel (played
598 * through the subwoofer).
599 */
600typedef enum PDMAUDIOSTREAMCHANNELID
601{
602 /** Invalid zero value as per usual (guards against using unintialized values). */
603 PDMAUDIOSTREAMCHANNELID_INVALID = 0,
604 /** Unknown / not set channel ID. */
605 PDMAUDIOSTREAMCHANNELID_UNKNOWN,
606 /** Front left channel. */
607 PDMAUDIOSTREAMCHANNELID_FRONT_LEFT,
608 /** Front right channel. */
609 PDMAUDIOSTREAMCHANNELID_FRONT_RIGHT,
610 /** Front center channel. */
611 PDMAUDIOSTREAMCHANNELID_FRONT_CENTER,
612 /** Low frequency effects (subwoofer) channel. */
613 PDMAUDIOSTREAMCHANNELID_LFE,
614 /** Rear left channel. */
615 PDMAUDIOSTREAMCHANNELID_REAR_LEFT,
616 /** Rear right channel. */
617 PDMAUDIOSTREAMCHANNELID_REAR_RIGHT,
618 /** Front left of center channel. */
619 PDMAUDIOSTREAMCHANNELID_FRONT_LEFT_OF_CENTER,
620 /** Front right of center channel. */
621 PDMAUDIOSTREAMCHANNELID_FRONT_RIGHT_OF_CENTER,
622 /** Rear center channel. */
623 PDMAUDIOSTREAMCHANNELID_REAR_CENTER,
624 /** Side left channel. */
625 PDMAUDIOSTREAMCHANNELID_SIDE_LEFT,
626 /** Side right channel. */
627 PDMAUDIOSTREAMCHANNELID_SIDE_RIGHT,
628 /** Left height channel. */
629 PDMAUDIOSTREAMCHANNELID_LEFT_HEIGHT,
630 /** Right height channel. */
631 PDMAUDIOSTREAMCHANNELID_RIGHT_HEIGHT,
632 /** End of valid values. */
633 PDMAUDIOSTREAMCHANNELID_END,
634 /** Hack to blow the type up to 32-bit. */
635 PDMAUDIOSTREAMCHANNELID_32BIT_HACK = 0x7fffffff
636} PDMAUDIOSTREAMCHANNELID;
637
638/**
639 * Mappings channels onto an audio stream.
640 *
641 * The mappings are either for a single (mono) or dual (stereo) channels onto an
642 * audio stream (aka stream profile). An audio stream consists of one or
643 * multiple channels (e.g. 1 for mono, 2 for stereo), depending on the
644 * configuration.
645 */
646typedef struct PDMAUDIOSTREAMMAP
647{
648 /** Array of channel IDs being handled.
649 * @note The first (zero-based) index specifies the leftmost channel. */
650 PDMAUDIOSTREAMCHANNELID aenmIDs[2];
651 /** Step size (in bytes) to the channel's next frame. */
652 uint32_t cbStep;
653 /** Frame size (in bytes) of this channel. */
654 uint32_t cbFrame;
655 /** Byte offset to the first frame in the data block. */
656 uint32_t offFirst;
657 /** Byte offset to the next frame in the data block. */
658 uint32_t offNext;
659 /** Associated data buffer. */
660 PDMAUDIOSTREAMCHANNELDATA Data;
661
662 /** @todo r=bird: I'd structure this very differently.
663 * I would've had an array of channel descriptors like this:
664 *
665 * struct PDMAUDIOCHANNELDESC
666 * {
667 * uint8_t off; //< Stream offset in bytes.
668 * uint8_t id; //< PDMAUDIOSTREAMCHANNELID
669 * };
670 *
671 * And I'd baked it into PDMAUDIOPCMPROPS as a fixed sized array with 16 entries
672 * (max HDA channel count IIRC). */
673} PDMAUDIOSTREAMMAP;
674/** Pointer to an audio stream channel mapping. */
675typedef PDMAUDIOSTREAMMAP *PPDMAUDIOSTREAMMAP;
676
677/**
678 * Properties of audio streams for host/guest for in or out directions.
679 */
680typedef struct PDMAUDIOPCMPROPS
681{
682 /** The frame size. */
683 uint8_t cbFrame;
684 /** Shift count used with PDMAUDIOPCMPROPS_F2B and PDMAUDIOPCMPROPS_B2F.
685 * Depends on number of stream channels and the stream format being used, calc
686 * value using PDMAUDIOPCMPROPS_MAKE_SHIFT.
687 * @sa PDMAUDIOSTREAMCFG_B2F, PDMAUDIOSTREAMCFG_F2B */
688 uint8_t cShiftX;
689 /** Sample width (in bytes). */
690 RT_GCC_EXTENSION
691 uint8_t cbSampleX : 4;
692 /** Number of audio channels. */
693 RT_GCC_EXTENSION
694 uint8_t cChannelsX : 4;
695 /** Signed or unsigned sample. */
696 bool fSigned : 1;
697 /** Whether the endianness is swapped or not. */
698 bool fSwapEndian : 1;
699 /** Raw mixer frames, only applicable for signed 64-bit samples. */
700 bool fRaw : 1;
701 /** Sample frequency in Hertz (Hz). */
702 uint32_t uHz;
703} PDMAUDIOPCMPROPS;
704AssertCompileSize(PDMAUDIOPCMPROPS, 8);
705AssertCompileSizeAlignment(PDMAUDIOPCMPROPS, 8);
706/** Pointer to audio stream properties. */
707typedef PDMAUDIOPCMPROPS *PPDMAUDIOPCMPROPS;
708/** Pointer to const audio stream properties. */
709typedef PDMAUDIOPCMPROPS const *PCPDMAUDIOPCMPROPS;
710
711/** @name Macros for use with PDMAUDIOPCMPROPS
712 * @{ */
713/** Initializer for PDMAUDIOPCMPROPS. */
714#define PDMAUDIOPCMPROPS_INITIALIZER(a_cbSample, a_fSigned, a_cChannels, a_uHz, a_fSwapEndian) \
715 { (a_cbSample) * (a_cChannels), PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS(a_cbSample, a_cChannels), a_cbSample, a_cChannels, \
716 a_fSigned, a_fSwapEndian, false /*fRaw*/, a_uHz }
717/** Calculates the cShift value of given sample bits and audio channels.
718 * @note Does only support mono/stereo channels for now, for non-stereo/mono we
719 * returns a special value which the two conversion functions detect
720 * and make them fall back on cbSample * cChannels. */
721#define PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS(cbSample, cChannels) \
722 ( RT_IS_POWER_OF_TWO((unsigned)((cChannels) * (cbSample))) \
723 ? (uint8_t)(ASMBitFirstSetU32((unsigned)((cChannels) * (cbSample))) - 1) : (uint8_t)UINT8_MAX )
724/** Calculates the cShift value of a PDMAUDIOPCMPROPS structure. */
725#define PDMAUDIOPCMPROPS_MAKE_SHIFT(pProps) \
726 PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS((pProps)->cbSampleX, (pProps)->cChannelsX)
727/** Converts (audio) frames to bytes.
728 * @note Requires properly initialized properties, i.e. cbFrames correctly calculated
729 * and cShift set using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
730#define PDMAUDIOPCMPROPS_F2B(pProps, cFrames) \
731 ( (pProps)->cShiftX != UINT8_MAX ? (cFrames) << (pProps)->cShiftX : (cFrames) * (pProps)->cbFrame )
732/** Converts bytes to (audio) frames.
733 * @note Requires properly initialized properties, i.e. cbFrames correctly calculated
734 * and cShift set using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
735#define PDMAUDIOPCMPROPS_B2F(pProps, cb) \
736 ( (pProps)->cShiftX != UINT8_MAX ? (cb) >> (pProps)->cShiftX : (cb) / (pProps)->cbFrame )
737/** @} */
738
739/**
740 * An audio stream configuration.
741 */
742typedef struct PDMAUDIOSTREAMCFG
743{
744 /** Direction of the stream. */
745 PDMAUDIODIR enmDir;
746 /** Destination / source path. */
747 PDMAUDIOPATH enmPath;
748 /** The stream's PCM properties. */
749 PDMAUDIOPCMPROPS Props;
750 /** The stream's audio data layout.
751 * This indicates how the audio data buffers to/from the backend is being layouted.
752 *
753 * Currently, the following layouts are supported by the audio connector:
754 *
755 * PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED:
756 * One stream at once. The consecutive audio data is exactly in the format and frame width
757 * like defined in the PCM properties. This is the default.
758 *
759 * PDMAUDIOSTREAMLAYOUT_RAW:
760 * Can be one or many streams at once, depending on the stream's mixing buffer setup.
761 * The audio data will get handled as PDMAUDIOFRAME frames without any modification done.
762 *
763 * @todo r=bird: See PDMAUDIOSTREAMLAYOUT comments. */
764 PDMAUDIOSTREAMLAYOUT enmLayout;
765 /** Device emulation-specific data needed for the audio connector. */
766 struct
767 {
768 /** Scheduling hint set by the device emulation about when this stream is being served on average (in ms).
769 * Can be 0 if not hint given or some other mechanism (e.g. callbacks) is being used. */
770 uint32_t cMsSchedulingHint;
771 } Device;
772 /**
773 * Backend-specific data for the stream.
774 * On input (requested configuration) those values are set by the audio connector to let the backend know what we expect.
775 * On output (acquired configuration) those values reflect the values set and used by the backend.
776 * Set by the backend on return. Not all backends support all values / features.
777 */
778 struct
779 {
780 /** Period size of the stream (in audio frames).
781 * This value reflects the number of audio frames in between each hardware interrupt on the
782 * backend (host) side. 0 if not set / available by the backend. */
783 uint32_t cFramesPeriod;
784 /** (Ring) buffer size (in audio frames). Often is a multiple of cFramesPeriod.
785 * 0 if not set / available by the backend. */
786 uint32_t cFramesBufferSize;
787 /** Pre-buffering size (in audio frames). Frames needed in buffer before the stream becomes active (pre buffering).
788 * The bigger this value is, the more latency for the stream will occur.
789 * 0 if not set / available by the backend. UINT32_MAX if not defined (yet). */
790 uint32_t cFramesPreBuffering;
791 } Backend;
792 uint32_t u32Padding;
793 /** Friendly name of the stream. */
794 char szName[64];
795} PDMAUDIOSTREAMCFG;
796AssertCompileSizeAlignment(PDMAUDIOSTREAMCFG, 8);
797/** Pointer to audio stream configuration keeper. */
798typedef PDMAUDIOSTREAMCFG *PPDMAUDIOSTREAMCFG;
799/** Pointer to a const audio stream configuration keeper. */
800typedef PDMAUDIOSTREAMCFG const *PCPDMAUDIOSTREAMCFG;
801
802/** Converts (audio) frames to bytes. */
803#define PDMAUDIOSTREAMCFG_F2B(pCfg, frames) PDMAUDIOPCMPROPS_F2B(&(pCfg)->Props, (frames))
804/** Converts bytes to (audio) frames. */
805#define PDMAUDIOSTREAMCFG_B2F(pCfg, cb) PDMAUDIOPCMPROPS_B2F(&(pCfg)->Props, (cb))
806
807/**
808 * Audio mixer controls.
809 */
810typedef enum PDMAUDIOMIXERCTL
811{
812 /** Invalid zero value as per usual (guards against using unintialized values). */
813 PDMAUDIOMIXERCTL_INVALID = 0,
814 /** Unknown mixer control. */
815 PDMAUDIOMIXERCTL_UNKNOWN,
816 /** Master volume. */
817 PDMAUDIOMIXERCTL_VOLUME_MASTER,
818 /** Front. */
819 PDMAUDIOMIXERCTL_FRONT,
820 /** Center / LFE (Subwoofer). */
821 PDMAUDIOMIXERCTL_CENTER_LFE,
822 /** Rear. */
823 PDMAUDIOMIXERCTL_REAR,
824 /** Line-In. */
825 PDMAUDIOMIXERCTL_LINE_IN,
826 /** Microphone-In. */
827 PDMAUDIOMIXERCTL_MIC_IN,
828 /** End of valid values. */
829 PDMAUDIOMIXERCTL_END,
830 /** Hack to blow the type up to 32-bit. */
831 PDMAUDIOMIXERCTL_32BIT_HACK = 0x7fffffff
832} PDMAUDIOMIXERCTL;
833
834/**
835 * Audio stream commands.
836 *
837 * Used in the audio connector as well as in the actual host backends.
838 */
839typedef enum PDMAUDIOSTREAMCMD
840{
841 /** Invalid zero value as per usual (guards against using unintialized values). */
842 PDMAUDIOSTREAMCMD_INVALID = 0,
843 /** Enables the stream. */
844 PDMAUDIOSTREAMCMD_ENABLE,
845 /** Pauses the stream.
846 * This is currently only issued when the VM is suspended (paused).
847 * @remarks This is issued by DrvAudio, never by the mixer or devices. */
848 PDMAUDIOSTREAMCMD_PAUSE,
849 /** Resumes the stream.
850 * This is currently only issued when the VM is resumed.
851 * @remarks This is issued by DrvAudio, never by the mixer or devices. */
852 PDMAUDIOSTREAMCMD_RESUME,
853 /** Drain the stream, that is, play what's in the buffers and then stop.
854 *
855 * There will be no more samples written after this command is issued.
856 * PDMIAUDIOCONNECTOR::pfnStreamIterate will drive progress for DrvAudio and
857 * calls to PDMIHOSTAUDIO::pfnStreamPlay with a zero sized buffer will provide
858 * the backend with a way to drive it forwards. These calls will come at a
859 * frequency set by the device and be on an asynchronous I/O thread.
860 *
861 * A DISABLE command maybe submitted if the device/mixer wants to re-enable the
862 * stream while it's still draining or if it gets impatient and thinks the
863 * draining has been going on too long, in which case the stream should stop
864 * immediately.
865 *
866 * @note This should not wait for the stream to finish draining, just change
867 * the state. (The caller could be an EMT and it must not block for
868 * hundreds of milliseconds of buffer to finish draining.)
869 *
870 * @note Does not apply to input streams. Backends should refuse such requests. */
871 PDMAUDIOSTREAMCMD_DRAIN,
872 /** Stops the stream immediately w/o any draining. */
873 PDMAUDIOSTREAMCMD_DISABLE,
874 /** End of valid values. */
875 PDMAUDIOSTREAMCMD_END,
876 /** Hack to blow the type up to 32-bit. */
877 PDMAUDIOSTREAMCMD_32BIT_HACK = 0x7fffffff
878} PDMAUDIOSTREAMCMD;
879
880/**
881 * Audio volume parameters.
882 */
883typedef struct PDMAUDIOVOLUME
884{
885 /** Set to @c true if this stream is muted, @c false if not. */
886 bool fMuted;
887 /** Left channel volume.
888 * Range is from [0 ... 255], whereas 0 specifies
889 * the most silent and 255 the loudest value. */
890 uint8_t uLeft;
891 /** Right channel volume.
892 * Range is from [0 ... 255], whereas 0 specifies
893 * the most silent and 255 the loudest value. */
894 uint8_t uRight;
895} PDMAUDIOVOLUME;
896/** Pointer to audio volume settings. */
897typedef PDMAUDIOVOLUME *PPDMAUDIOVOLUME;
898/** Pointer to const audio volume settings. */
899typedef PDMAUDIOVOLUME const *PCPDMAUDIOVOLUME;
900
901/** Defines the minimum volume allowed. */
902#define PDMAUDIO_VOLUME_MIN (0)
903/** Defines the maximum volume allowed. */
904#define PDMAUDIO_VOLUME_MAX (255)
905
906
907/**
908 * Backend status.
909 */
910typedef enum PDMAUDIOBACKENDSTS
911{
912 /** Unknown/invalid status. */
913 PDMAUDIOBACKENDSTS_UNKNOWN = 0,
914 /** No backend attached. */
915 PDMAUDIOBACKENDSTS_NOT_ATTACHED,
916 /** The backend is in its initialization phase.
917 * Not all backends support this status. */
918 PDMAUDIOBACKENDSTS_INITIALIZING,
919 /** The backend has stopped its operation. */
920 PDMAUDIOBACKENDSTS_STOPPED,
921 /** The backend is up and running. */
922 PDMAUDIOBACKENDSTS_RUNNING,
923 /** The backend ran into an error and is unable to recover.
924 * A manual re-initialization might help. */
925 PDMAUDIOBACKENDSTS_ERROR,
926 /** Hack to blow the type up to 32-bit. */
927 PDMAUDIOBACKENDSTS_32BIT_HACK = 0x7fffffff
928} PDMAUDIOBACKENDSTS;
929
930/**
931 * PDM audio stream state.
932 *
933 * This is all the mixer/device needs. The PDMAUDIOSTREAM_STS_XXX stuff will
934 * become DrvAudio internal state once the backend stuff is destilled out of it.
935 *
936 * @note The value order is significant, don't change it willy-nilly.
937 */
938typedef enum PDMAUDIOSTREAMSTATE
939{
940 /** Invalid state value. */
941 PDMAUDIOSTREAMSTATE_INVALID = 0,
942 /** The stream is not operative and cannot be enabled. */
943 PDMAUDIOSTREAMSTATE_NOT_WORKING,
944 /** The stream needs to be re-initialized by the device/mixer
945 * (i.e. call PDMIAUDIOCONNECTOR::pfnStreamReInit). */
946 PDMAUDIOSTREAMSTATE_NEED_REINIT,
947 /** The stream is inactive (not enabled). */
948 PDMAUDIOSTREAMSTATE_INACTIVE,
949 /** The stream is enabled but nothing to read/write.
950 * @todo not sure if we need this variant... */
951 PDMAUDIOSTREAMSTATE_ENABLED,
952 /** The stream is enabled and captured samples can be read. */
953 PDMAUDIOSTREAMSTATE_ENABLED_READABLE,
954 /** The stream is enabled and samples can be written for playback. */
955 PDMAUDIOSTREAMSTATE_ENABLED_WRITABLE,
956 /** End of valid states. */
957 PDMAUDIOSTREAMSTATE_END,
958 /** Make sure the type is 32-bit wide. */
959 PDMAUDIOSTREAMSTATE_32BIT_HACK = 0x7fffffff
960} PDMAUDIOSTREAMSTATE;
961
962/** @name PDMAUDIOSTREAM_CREATE_F_XXX
963 * @{ */
964/** Does not need any mixing buffers, the device takes care of all conversion. */
965#define PDMAUDIOSTREAM_CREATE_F_NO_MIXBUF RT_BIT_32(0)
966/** @} */
967
968/** @name PDMAUDIOSTREAM_WARN_FLAGS_XXX
969 * @{ */
970/** No stream warning flags set. */
971#define PDMAUDIOSTREAM_WARN_FLAGS_NONE 0
972/** Warned about a disabled stream. */
973#define PDMAUDIOSTREAM_WARN_FLAGS_DISABLED RT_BIT(0)
974/** @} */
975
976/**
977 * An input or output audio stream.
978 */
979typedef struct PDMAUDIOSTREAM
980{
981 /** Critical section protecting the stream.
982 *
983 * When not otherwise stated, DrvAudio will enter this before calling the
984 * backend. The backend and device/mixer can normally safely enter it prior to
985 * a DrvAudio call, however not to pfnStreamDestroy, pfnStreamRelease or
986 * anything that may access the stream list.
987 *
988 * @note Lock ordering:
989 * - After DRVAUDIO::CritSectGlobals.
990 * - Before DRVAUDIO::CritSectHotPlug. */
991 RTCRITSECT CritSect;
992 /** Magic value (PDMAUDIOSTREAM_MAGIC). */
993 uint32_t uMagic;
994 /** Audio direction of this stream. */
995 PDMAUDIODIR enmDir;
996 /** Size (in bytes) of the backend-specific stream data. */
997 uint32_t cbBackend;
998 /** Warnings shown already in the release log.
999 * See PDMAUDIOSTREAM_WARN_FLAGS_XXX. */
1000 uint32_t fWarningsShown;
1001 /** The stream properties (both sides when PDMAUDIOSTREAM_CREATE_F_NO_MIXBUF
1002 * is used, otherwise the guest side). */
1003 PDMAUDIOPCMPROPS Props;
1004
1005 /** Name of this stream. */
1006 char szName[64];
1007} PDMAUDIOSTREAM;
1008/** Pointer to an audio stream. */
1009typedef struct PDMAUDIOSTREAM *PPDMAUDIOSTREAM;
1010/** Pointer to a const audio stream. */
1011typedef struct PDMAUDIOSTREAM const *PCPDMAUDIOSTREAM;
1012
1013/** Magic value for PDMAUDIOSTREAM. */
1014#define PDMAUDIOSTREAM_MAGIC PDM_VERSION_MAKE(0xa0d3, 5, 0)
1015
1016
1017
1018/** Pointer to a audio connector interface. */
1019typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
1020
1021/**
1022 * Audio connector interface (up).
1023 */
1024typedef struct PDMIAUDIOCONNECTOR
1025{
1026 /**
1027 * Enables or disables the given audio direction for this driver.
1028 *
1029 * When disabled, assiociated output streams consume written audio without passing them further down to the backends.
1030 * Associated input streams then return silence when read from those.
1031 *
1032 * @returns VBox status code.
1033 * @param pInterface Pointer to the interface structure containing the called function pointer.
1034 * @param enmDir Audio direction to enable or disable driver for.
1035 * @param fEnable Whether to enable or disable the specified audio direction.
1036 *
1037 * @note Be very careful when using this function, as this could
1038 * violate / run against the (global) VM settings. See @bugref{9882}.
1039 */
1040 DECLR3CALLBACKMEMBER(int, pfnEnable, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir, bool fEnable));
1041
1042 /**
1043 * Returns whether the given audio direction for this driver is enabled or not.
1044 *
1045 * @returns True if audio is enabled for the given direction, false if not.
1046 * @param pInterface Pointer to the interface structure containing the called function pointer.
1047 * @param enmDir Audio direction to retrieve enabled status for.
1048 */
1049 DECLR3CALLBACKMEMBER(bool, pfnIsEnabled, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
1050
1051 /**
1052 * Retrieves the current configuration of the host audio backend.
1053 *
1054 * @returns VBox status code.
1055 * @param pInterface Pointer to the interface structure containing the called function pointer.
1056 * @param pCfg Where to store the host audio backend configuration data.
1057 */
1058 DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOBACKENDCFG pCfg));
1059
1060 /**
1061 * Retrieves the current status of the host audio backend.
1062 *
1063 * @returns Status of the host audio backend.
1064 * @param pInterface Pointer to the interface structure containing the called function pointer.
1065 * @param enmDir Audio direction to check host audio backend for. Specify PDMAUDIODIR_DUPLEX for the overall
1066 * backend status.
1067 */
1068 DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
1069
1070 /**
1071 * Gives the audio drivers a hint about a typical configuration.
1072 *
1073 * This is a little hack for windows (and maybe other hosts) where stream
1074 * creation can take a relatively long time, making it very unsuitable for EMT.
1075 * The audio backend can use this hint to cache pre-configured stream setups,
1076 * so that when the guest actually wants to play something EMT won't be blocked
1077 * configuring host audio.
1078 *
1079 * @param pInterface Pointer to this interface.
1080 * @param pCfg The typical configuration. Can be modified by the
1081 * drivers in unspecified ways.
1082 */
1083 DECLR3CALLBACKMEMBER(void, pfnStreamConfigHint, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfg));
1084
1085 /**
1086 * Creates an audio stream.
1087 *
1088 * @returns VBox status code.
1089 * @param pInterface Pointer to the interface structure containing the called function pointer.
1090 * @param fFlags PDMAUDIOSTREAM_CREATE_F_XXX.
1091 * @param pCfgHost Stream configuration for host side.
1092 * @param pCfgGuest Stream configuration for guest side.
1093 * @param ppStream Pointer where to return the created audio stream on success.
1094 * @todo r=bird: It is not documented how pCfgHost and pCfgGuest can be
1095 * modified the DrvAudio...
1096 */
1097 DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIAUDIOCONNECTOR pInterface, uint32_t fFlags, PPDMAUDIOSTREAMCFG pCfgHost,
1098 PPDMAUDIOSTREAMCFG pCfgGuest, PPDMAUDIOSTREAM *ppStream));
1099
1100
1101 /**
1102 * Destroys an audio stream.
1103 *
1104 * @param pInterface Pointer to the interface structure containing the called function pointer.
1105 * @param pStream Pointer to audio stream.
1106 * @param fImmediate Whether to immdiately stop and destroy a draining
1107 * stream (@c true), or to allow it to complete
1108 * draining first (@c false) if that's feasable.
1109 * The latter depends on the draining stage and what
1110 * the backend is capable of.
1111 */
1112 DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, bool fImmediate));
1113
1114 /**
1115 * Re-initializes the stream in response to PDMAUDIOSTREAM_STS_NEED_REINIT.
1116 *
1117 * @returns VBox status code.
1118 * @param pInterface Pointer to this interface.
1119 * @param pStream The audio stream needing re-initialization.
1120 */
1121 DECLR3CALLBACKMEMBER(int, pfnStreamReInit, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1122
1123 /**
1124 * Adds a reference to the specified audio stream.
1125 *
1126 * @returns New reference count. UINT32_MAX on error.
1127 * @param pInterface Pointer to the interface structure containing the called function pointer.
1128 * @param pStream Pointer to audio stream adding the reference to.
1129 */
1130 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRetain, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1131
1132 /**
1133 * Releases a reference from the specified stream.
1134 *
1135 * @returns New reference count. UINT32_MAX on error.
1136 * @param pInterface Pointer to the interface structure containing the called function pointer.
1137 * @param pStream Pointer to audio stream releasing a reference from.
1138 */
1139 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRelease, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1140
1141 /**
1142 * Controls a specific audio stream.
1143 *
1144 * @returns VBox status code.
1145 * @param pInterface Pointer to the interface structure containing the called function pointer.
1146 * @param pStream Pointer to audio stream.
1147 * @param enmStreamCmd The stream command to issue.
1148 */
1149 DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1150 PDMAUDIOSTREAMCMD enmStreamCmd));
1151
1152 /**
1153 * Processes stream data.
1154 *
1155 * @param pInterface Pointer to the interface structure containing the called function pointer.
1156 * @param pStream Pointer to audio stream.
1157 */
1158 DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1159
1160 /**
1161 * Returns the number of readable data (in bytes) of a specific audio input stream.
1162 *
1163 * @returns Number of bytes of readable data.
1164 * @param pInterface Pointer to the interface structure containing the called function pointer.
1165 * @param pStream Pointer to audio stream.
1166 */
1167 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1168
1169 /**
1170 * Returns the number of writable data (in bytes) of a specific audio output stream.
1171 *
1172 * @returns Number of bytes writable data.
1173 * @param pInterface Pointer to the interface structure containing the called function pointer.
1174 * @param pStream Pointer to audio stream.
1175 */
1176 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1177
1178 /**
1179 * Returns the state of a specific audio stream (destilled status).
1180 *
1181 * @returns PDMAUDIOSTREAMSTATE value.
1182 * @retval PDMAUDIOSTREAMSTATE_INVALID if the input isn't valid (w/ assertion).
1183 * @param pInterface Pointer to the interface structure containing the called function pointer.
1184 * @param pStream Pointer to audio stream.
1185 */
1186 DECLR3CALLBACKMEMBER(PDMAUDIOSTREAMSTATE, pfnStreamGetState, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1187
1188 /**
1189 * Sets the audio volume of a specific audio stream.
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.
1194 * @param pVol Pointer to audio volume structure to set the stream's audio volume to.
1195 */
1196 DECLR3CALLBACKMEMBER(int, pfnStreamSetVolume, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOVOLUME pVol));
1197
1198 /**
1199 * Plays (writes to) an audio (output) stream.
1200 *
1201 * @returns VBox status code.
1202 * @param pInterface Pointer to the interface structure containing the called function pointer.
1203 * @param pStream Pointer to audio stream to read from.
1204 * @param pvBuf Audio data to be written.
1205 * @param cbBuf Number of bytes to be written.
1206 * @param pcbWritten Bytes of audio data written. Optional.
1207 */
1208 DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1209 const void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten));
1210
1211 /**
1212 * Reads PCM audio data from the host (input).
1213 *
1214 * @returns VBox status code.
1215 * @param pInterface Pointer to the interface structure containing the called function pointer.
1216 * @param pStream Pointer to audio stream to write to.
1217 * @param pvBuf Where to store the read data.
1218 * @param cbBuf Number of bytes to read.
1219 * @param pcbRead Bytes of audio data read. Optional.
1220 */
1221 DECLR3CALLBACKMEMBER(int, pfnStreamRead, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1222 void *pvBuf, uint32_t cbBuf, uint32_t *pcbRead));
1223
1224 /**
1225 * Captures (transfers) available audio frames from the host backend.
1226 *
1227 * Only works with input streams.
1228 *
1229 * @returns VBox status code.
1230 * @param pInterface Pointer to the interface structure containing the called function pointer.
1231 * @param pStream Pointer to audio stream.
1232 * @param pcFramesCaptured Number of frames captured. Optional.
1233 */
1234 DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1235 uint32_t *pcFramesCaptured));
1236
1237} PDMIAUDIOCONNECTOR;
1238
1239/** PDMIAUDIOCONNECTOR interface ID. */
1240#define PDMIAUDIOCONNECTOR_IID "ff9cabf0-4138-4c3a-aa99-28bf7a6feae7"
1241
1242
1243/**
1244 * Host audio backend specific stream data.
1245 *
1246 * The backend will put this as the first member of it's own data structure.
1247 */
1248typedef struct PDMAUDIOBACKENDSTREAM
1249{
1250 /** Magic value (PDMAUDIOBACKENDSTREAM_MAGIC). */
1251 uint32_t uMagic;
1252 /** Explicit zero padding - do not touch! */
1253 uint32_t uReserved;
1254 /** Pointer to the stream this backend data is associated with. */
1255 PPDMAUDIOSTREAM pStream;
1256 /** Reserved for future use (zeroed) - do not touch. */
1257 void *apvReserved[2];
1258} PDMAUDIOBACKENDSTREAM;
1259/** Pointer to host audio specific stream data! */
1260typedef PDMAUDIOBACKENDSTREAM *PPDMAUDIOBACKENDSTREAM;
1261
1262/** Magic value for PDMAUDIOBACKENDSTREAM. */
1263#define PDMAUDIOBACKENDSTREAM_MAGIC PDM_VERSION_MAKE(0xa0d4, 1, 0)
1264
1265/**
1266 * Host audio (backend) stream state returned by PDMIHOSTAUDIO::pfnStreamGetState.
1267 */
1268typedef enum PDMHOSTAUDIOSTREAMSTATE
1269{
1270 /** Invalid zero value, as per usual. */
1271 PDMHOSTAUDIOSTREAMSTATE_INVALID = 0,
1272 /** The stream is being initialized.
1273 * This should also be used when switching to a new device and the stream
1274 * stops to work with the old device while the new one being configured. */
1275 PDMHOSTAUDIOSTREAMSTATE_INITIALIZING,
1276 /** The stream does not work (async init failed, audio subsystem gone
1277 * fishing, or similar). */
1278 PDMHOSTAUDIOSTREAMSTATE_NOT_WORKING,
1279 /** Backend is working okay. */
1280 PDMHOSTAUDIOSTREAMSTATE_OKAY,
1281 /** Backend is working okay, but currently draining the stream. */
1282 PDMHOSTAUDIOSTREAMSTATE_DRAINING,
1283 /** Backend is working but doesn't want any commands or data reads/writes. */
1284 PDMHOSTAUDIOSTREAMSTATE_INACTIVE,
1285 /** End of valid values. */
1286 PDMHOSTAUDIOSTREAMSTATE_END,
1287 /** Blow the type up to 32 bits. */
1288 PDMHOSTAUDIOSTREAMSTATE_32BIT_HACK = 0x7fffffff
1289} PDMHOSTAUDIOSTREAMSTATE;
1290
1291
1292/** Pointer to a host audio interface. */
1293typedef struct PDMIHOSTAUDIO *PPDMIHOSTAUDIO;
1294
1295/**
1296 * PDM host audio interface.
1297 */
1298typedef struct PDMIHOSTAUDIO
1299{
1300 /**
1301 * Returns the host backend's configuration (backend).
1302 *
1303 * @returns VBox status code.
1304 * @param pInterface Pointer to the interface structure containing the called function pointer.
1305 * @param pBackendCfg Where to store the backend audio configuration to.
1306 */
1307 DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg));
1308
1309 /**
1310 * Returns (enumerates) host audio device information (optional).
1311 *
1312 * @returns VBox status code.
1313 * @param pInterface Pointer to the interface structure containing the called function pointer.
1314 * @param pDeviceEnum Where to return the enumerated audio devices.
1315 */
1316 DECLR3CALLBACKMEMBER(int, pfnGetDevices, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHOSTENUM pDeviceEnum));
1317
1318 /**
1319 * Returns the current status from the audio backend (optional).
1320 *
1321 * @returns PDMAUDIOBACKENDSTS enum.
1322 * @param pInterface Pointer to the interface structure containing the called function pointer.
1323 * @param enmDir Audio direction to get status for. Pass PDMAUDIODIR_DUPLEX for overall status.
1324 */
1325 DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir));
1326
1327 /**
1328 * Callback for genric on-worker-thread requests initiated by the backend itself.
1329 *
1330 * This is the counterpart to PDMIHOSTAUDIOPORT::pfnDoOnWorkerThread that will
1331 * be invoked on a worker thread when the backend requests it - optional.
1332 *
1333 * This does not return a value, so the backend must keep track of
1334 * failure/success on its own.
1335 *
1336 * This method is optional. A non-NULL will, together with pfnStreamInitAsync
1337 * and PDMAUDIOBACKEND_F_ASYNC_HINT, force DrvAudio to create the thread pool.
1338 *
1339 * @param pInterface Pointer to this interface.
1340 * @param pStream Optionally a backend stream if specified in the
1341 * PDMIHOSTAUDIOPORT::pfnDoOnWorkerThread() call.
1342 * @param uUser User specific value as specified in the
1343 * PDMIHOSTAUDIOPORT::pfnDoOnWorkerThread() call.
1344 * @param pvUser User specific pointer as specified in the
1345 * PDMIHOSTAUDIOPORT::pfnDoOnWorkerThread() call.
1346 */
1347 DECLR3CALLBACKMEMBER(void, pfnDoOnWorkerThread,(PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1348 uintptr_t uUser, void *pvUser));
1349
1350 /**
1351 * Gives the audio backend a hint about a typical configuration (optional).
1352 *
1353 * This is a little hack for windows (and maybe other hosts) where stream
1354 * creation can take a relatively long time, making it very unsuitable for EMT.
1355 * The audio backend can use this hint to cache pre-configured stream setups,
1356 * so that when the guest actually wants to play something EMT won't be blocked
1357 * configuring host audio.
1358 *
1359 * The backend can return PDMAUDIOBACKEND_F_ASYNC_HINT in
1360 * PDMIHOSTAUDIO::pfnGetConfig to avoid having EMT making this call and thereby
1361 * speeding up VM construction.
1362 *
1363 * @param pInterface Pointer to this interface.
1364 * @param pCfg The typical configuration. (Feel free to change it
1365 * to the actual stream config that would be used,
1366 * however caller will probably ignore this.)
1367 */
1368 DECLR3CALLBACKMEMBER(void, pfnStreamConfigHint, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAMCFG pCfg));
1369
1370 /**
1371 * Creates an audio stream using the requested stream configuration.
1372 *
1373 * If a backend is not able to create this configuration, it will return its
1374 * best match in the acquired configuration structure on success.
1375 *
1376 * @returns VBox status code.
1377 * @retval VINF_AUDIO_STREAM_ASYNC_INIT_NEEDED if
1378 * PDMIHOSTAUDIO::pfnStreamInitAsync should be called.
1379 * @param pInterface Pointer to the interface structure containing the called function pointer.
1380 * @param pStream Pointer to audio stream.
1381 * @param pCfgReq Pointer to requested stream configuration.
1382 * @param pCfgAcq Pointer to acquired stream configuration.
1383 * @todo r=bird: Implementation (at least Alsa) seems to make undocumented
1384 * assumptions about the content of @a pCfgAcq.
1385 */
1386 DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1387 PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq));
1388
1389 /**
1390 * Asynchronous stream initialization step, optional.
1391 *
1392 * This is called on a worker thread iff the PDMIHOSTAUDIO::pfnStreamCreate
1393 * method returns VINF_AUDIO_STREAM_ASYNC_INIT_NEEDED.
1394 *
1395 * @returns VBox status code.
1396 * @param pInterface Pointer to this interface.
1397 * @param pStream Pointer to audio stream to continue
1398 * initialization of.
1399 * @param fDestroyed Set to @c true if the stream has been destroyed
1400 * before the worker thread got to making this
1401 * call. The backend should just ready the stream
1402 * for destruction in that case.
1403 */
1404 DECLR3CALLBACKMEMBER(int, pfnStreamInitAsync, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, bool fDestroyed));
1405
1406 /**
1407 * Destroys an audio stream.
1408 *
1409 * @returns VBox status code.
1410 * @param pInterface Pointer to the interface containing the called function.
1411 * @param pStream Pointer to audio stream.
1412 * @param fImmediate Whether to immdiately stop and destroy a draining
1413 * stream (@c true), or to allow it to complete
1414 * draining first (@c false) if that's feasable.
1415 */
1416 DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, bool fImmediate));
1417
1418 /**
1419 * Called from PDMIHOSTAUDIOPORT::pfnNotifyDeviceChanged so the backend can start
1420 * the device change for a stream.
1421 *
1422 * This is mainly to avoid the need for a list of streams in the backend.
1423 *
1424 * @param pInterface Pointer to this interface.
1425 * @param pStream Pointer to audio stream (locked).
1426 * @param pvUser Backend specific parameter from the call to
1427 * PDMIHOSTAUDIOPORT::pfnNotifyDeviceChanged.
1428 */
1429 DECLR3CALLBACKMEMBER(void, pfnStreamNotifyDeviceChanged,(PPDMIHOSTAUDIO pInterface,
1430 PPDMAUDIOBACKENDSTREAM pStream, void *pvUser));
1431
1432 /**
1433 * Controls an audio stream.
1434 *
1435 * @returns VBox status code.
1436 * @retval VERR_AUDIO_STREAM_NOT_READY if stream is not ready for required operation (yet).
1437 * @param pInterface Pointer to the interface structure containing the called function pointer.
1438 * @param pStream Pointer to audio stream.
1439 * @param enmStreamCmd The stream command to issue.
1440 */
1441 DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1442 PDMAUDIOSTREAMCMD enmStreamCmd));
1443
1444 /**
1445 * Returns the amount which is readable from the audio (input) stream.
1446 *
1447 * @returns For non-raw layout streams: Number of readable bytes.
1448 * for raw layout streams : Number of readable audio frames.
1449 * @param pInterface Pointer to the interface structure containing the called function pointer.
1450 * @param pStream Pointer to audio stream.
1451 */
1452 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1453
1454 /**
1455 * Returns the amount which is writable to the audio (output) stream.
1456 *
1457 * @returns Number of writable bytes.
1458 * @param pInterface Pointer to the interface structure containing the called function pointer.
1459 * @param pStream Pointer to audio stream.
1460 */
1461 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1462
1463 /**
1464 * Returns the number of buffered bytes that hasn't been played yet (optional).
1465 *
1466 * Is not valid on an input stream, implementions shall assert and return zero.
1467 *
1468 * @returns Number of pending bytes.
1469 * @param pInterface Pointer to this interface.
1470 * @param pStream Pointer to audio stream.
1471 *
1472 * @todo This is no longer not used by DrvAudio and can probably be removed.
1473 */
1474 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetPending, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1475
1476 /**
1477 * Returns the current state of the given backend stream.
1478 *
1479 * @returns PDMHOSTAUDIOSTREAMSTATE value.
1480 * @retval PDMHOSTAUDIOSTREAMSTATE_INVALID if invalid stream.
1481 * @param pInterface Pointer to the interface structure containing the called function pointer.
1482 * @param pStream Pointer to audio stream.
1483 */
1484 DECLR3CALLBACKMEMBER(PDMHOSTAUDIOSTREAMSTATE, pfnStreamGetState, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1485
1486 /**
1487 * Plays (writes to) an audio (output) stream.
1488 *
1489 * This is always called with data in the buffer, except after
1490 * PDMAUDIOSTREAMCMD_DRAIN is issued when it's called every so often to assist
1491 * the backend with moving the draining operation forward (kind of like
1492 * PDMIAUDIOCONNECTOR::pfnStreamIterate).
1493 *
1494 * @returns VBox status code.
1495 * @param pInterface Pointer to the interface structure containing the called function pointer.
1496 * @param pStream Pointer to audio stream.
1497 * @param pvBuf Pointer to audio data buffer to play. This will be NULL
1498 * when called to assist draining the stream.
1499 * @param cbBuf The number of bytes of audio data to play. This will be
1500 * zero when called to assist draining the stream.
1501 * @param pcbWritten Where to return the actual number of bytes played.
1502 */
1503 DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1504 const void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten));
1505
1506 /**
1507 * Captures (reads from) an audio (input) stream.
1508 *
1509 * @returns VBox status code.
1510 * @param pInterface Pointer to the interface structure containing the called function pointer.
1511 * @param pStream Pointer to audio stream.
1512 * @param pvBuf Buffer where to store read audio data.
1513 * @param cbBuf Size of the audio data buffer in bytes.
1514 * @param pcbRead Where to return the number of bytes actually captured.
1515 */
1516 DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1517 void *pvBuf, uint32_t cbBuf, uint32_t *pcbRead));
1518} PDMIHOSTAUDIO;
1519
1520/** PDMIHOSTAUDIO interface ID. */
1521#define PDMIHOSTAUDIO_IID "a6b33abc-1393-4548-92ab-a308d54de1e8"
1522
1523
1524/** Pointer to a audio notify from host interface. */
1525typedef struct PDMIHOSTAUDIOPORT *PPDMIHOSTAUDIOPORT;
1526
1527/**
1528 * PDM host audio port interface, upwards sibling of PDMIHOSTAUDIO.
1529 */
1530typedef struct PDMIHOSTAUDIOPORT
1531{
1532 /**
1533 * Ask DrvAudio to call PDMIHOSTAUDIO::pfnDoOnWorkerThread on a worker thread.
1534 *
1535 * Generic method for doing asynchronous work using the DrvAudio thread pool.
1536 *
1537 * This function will not wait for PDMIHOSTAUDIO::pfnDoOnWorkerThread to
1538 * complete, but returns immediately after submitting the request to the thread
1539 * pool.
1540 *
1541 * @returns VBox status code.
1542 * @param pInterface Pointer to this interface.
1543 * @param pStream Optional backend stream structure to pass along. The
1544 * reference count will be increased till the call
1545 * completes to make sure the stream stays valid.
1546 * @param uUser User specific value.
1547 * @param pvUser User specific pointer.
1548 */
1549 DECLR3CALLBACKMEMBER(int, pfnDoOnWorkerThread,(PPDMIHOSTAUDIOPORT pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1550 uintptr_t uUser, void *pvUser));
1551
1552 /**
1553 * The device for the given direction changed.
1554 *
1555 * The driver above backend (DrvAudio) will call the backend back
1556 * (PDMIHOSTAUDIO::pfnStreamNotifyDeviceChanged) for all open streams in the
1557 * given direction. (This ASSUMES the backend uses one output device and one
1558 * input devices for all streams.)
1559 *
1560 * @param pInterface Pointer to this interface.
1561 * @param enmDir The audio direction.
1562 * @param pvUser Backend specific parameter for
1563 * PDMIHOSTAUDIO::pfnStreamNotifyDeviceChanged.
1564 */
1565 DECLR3CALLBACKMEMBER(void, pfnNotifyDeviceChanged,(PPDMIHOSTAUDIOPORT pInterface, PDMAUDIODIR enmDir, void *pvUser));
1566
1567 /**
1568 * Notification that the stream is about to change device in a bit.
1569 *
1570 * This will assume PDMAUDIOSTREAM_STS_PREPARING_SWITCH will be set when
1571 * PDMIHOSTAUDIO::pfnStreamGetStatus is next called and change the stream state
1572 * accordingly.
1573 *
1574 * @param pInterface Pointer to this interface.
1575 * @param pStream The stream that changed device (backend variant).
1576 */
1577 DECLR3CALLBACKMEMBER(void, pfnStreamNotifyPreparingDeviceSwitch,(PPDMIHOSTAUDIOPORT pInterface,
1578 PPDMAUDIOBACKENDSTREAM pStream));
1579
1580 /**
1581 * The stream has changed its device and left the
1582 * PDMAUDIOSTREAM_STS_PREPARING_SWITCH state (if it entered it at all).
1583 *
1584 * @param pInterface Pointer to this interface.
1585 * @param pStream The stream that changed device (backend variant).
1586 * @param fReInit Set if a re-init is required, clear if not.
1587 */
1588 DECLR3CALLBACKMEMBER(void, pfnStreamNotifyDeviceChanged,(PPDMIHOSTAUDIOPORT pInterface,
1589 PPDMAUDIOBACKENDSTREAM pStream, bool fReInit));
1590
1591 /**
1592 * One or more audio devices have changed in some way.
1593 *
1594 * The upstream driver/device should re-evaluate the devices they're using.
1595 *
1596 * @todo r=bird: The upstream driver/device does not know which host audio
1597 * devices they are using. This is mainly for triggering enumeration and
1598 * logging of the audio devices.
1599 *
1600 * @param pInterface Pointer to this interface.
1601 */
1602 DECLR3CALLBACKMEMBER(void, pfnNotifyDevicesChanged,(PPDMIHOSTAUDIOPORT pInterface));
1603} PDMIHOSTAUDIOPORT;
1604
1605/** PDMIHOSTAUDIOPORT interface ID. */
1606#define PDMIHOSTAUDIOPORT_IID "9f91ec59-95ba-4925-92dc-e75be1c63352"
1607
1608/** @} */
1609
1610#endif /* !VBOX_INCLUDED_vmm_pdmaudioifs_h */
1611
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette