VirtualBox

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

Last change on this file since 89489 was 89489, checked in by vboxsync, 3 years ago

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