VirtualBox

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

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

Audio: Build fix. bugref:9890
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 72.8 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 PDMAUDIOMIXBUF 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 |PDMAUDIOMIXBUF |+------>|PDMAUDIOSTREAM Host |
195 |PDMAUDIOSTREAMCFG |+------>|PDMAUDIOSTREAM Guest |
196 | | |Device capabilities |
197 | | |Device configuration |
198 | | | |
199 | | +--+|PDMIHOSTAUDIO |
200 | | | |+-----------------------+|
201 +-------------------------+ | ||Backend storage space ||
202 | |+-----------------------+|
203 | +-------------------------+
204 |
205 +---------------------+ |
206 |PDMIHOSTAUDIO | |
207 |+--------------+ | |
208 ||DirectSound | | |
209 |+--------------+ | |
210 | | |
211 |+--------------+ | |
212 ||PulseAudio | | |
213 |+--------------+ |+-------+
214 | |
215 |+--------------+ |
216 ||Core Audio | |
217 |+--------------+ |
218 | |
219 | |
220 | |
221 | |
222 +---------------------+
223 @endverbatim
224 */
225
226#ifndef VBOX_INCLUDED_vmm_pdmaudioifs_h
227#define VBOX_INCLUDED_vmm_pdmaudioifs_h
228#ifndef RT_WITHOUT_PRAGMA_ONCE
229# pragma once
230#endif
231
232#include <iprt/assertcompile.h>
233#include <iprt/circbuf.h>
234#include <iprt/list.h>
235#include <iprt/path.h>
236
237#include <VBox/types.h>
238#include <VBox/vmm/pdmcommon.h>
239#include <VBox/vmm/stam.h>
240
241/** @defgroup grp_pdm_ifs_audio PDM Audio Interfaces
242 * @ingroup grp_pdm_interfaces
243 * @{
244 */
245
246#ifndef VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH
247# if defined(RT_OS_WINDOWS) || defined(RT_OS_OS2)
248# define VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "c:\\temp\\"
249# else
250# define VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "/tmp/"
251# endif
252#endif
253
254/** PDM audio driver instance flags. */
255typedef uint32_t PDMAUDIODRVFLAGS;
256
257/** No flags set. */
258#define PDMAUDIODRVFLAGS_NONE 0
259/** Marks a primary audio driver which is critical
260 * when running the VM. */
261#define PDMAUDIODRVFLAGS_PRIMARY RT_BIT(0)
262
263/**
264 * Audio format in signed or unsigned variants.
265 */
266typedef enum PDMAUDIOFMT
267{
268 /** Invalid format, do not use. */
269 PDMAUDIOFMT_INVALID = 0,
270 /** 8-bit, unsigned. */
271 PDMAUDIOFMT_U8,
272 /** 8-bit, signed. */
273 PDMAUDIOFMT_S8,
274 /** 16-bit, unsigned. */
275 PDMAUDIOFMT_U16,
276 /** 16-bit, signed. */
277 PDMAUDIOFMT_S16,
278 /** 32-bit, unsigned. */
279 PDMAUDIOFMT_U32,
280 /** 32-bit, signed. */
281 PDMAUDIOFMT_S32,
282 /** End of valid values. */
283 PDMAUDIOFMT_END,
284 /** Hack to blow the type up to 32-bit. */
285 PDMAUDIOFMT_32BIT_HACK = 0x7fffffff
286} PDMAUDIOFMT;
287
288/**
289 * Audio direction.
290 */
291typedef enum PDMAUDIODIR
292{
293 /** Invalid zero value as per usual (guards against using unintialized values). */
294 PDMAUDIODIR_INVALID = 0,
295 /** Unknown direction. */
296 PDMAUDIODIR_UNKNOWN,
297 /** Input. */
298 PDMAUDIODIR_IN,
299 /** Output. */
300 PDMAUDIODIR_OUT,
301 /** Duplex handling. */
302 PDMAUDIODIR_DUPLEX,
303 /** End of valid values. */
304 PDMAUDIODIR_END,
305 /** Hack to blow the type up to 32-bit. */
306 PDMAUDIODIR_32BIT_HACK = 0x7fffffff
307} PDMAUDIODIR;
308
309/** Device latency spec in milliseconds (ms). */
310typedef uint32_t PDMAUDIODEVLATSPECMS;
311
312/** Device latency spec in seconds (s). */
313typedef uint32_t PDMAUDIODEVLATSPECSEC;
314
315/** @name PDMAUDIOHOSTDEV_F_XXX
316 * @{ */
317/** No flags set. */
318#define PDMAUDIOHOSTDEV_F_NONE UINT32_C(0)
319/** The device marks the default device within the host OS. */
320#define PDMAUDIOHOSTDEV_F_DEFAULT RT_BIT_32(0)
321/** The device can be removed at any time and we have to deal with it. */
322#define PDMAUDIOHOSTDEV_F_HOTPLUG RT_BIT_32(1)
323/** The device is known to be buggy and needs special treatment. */
324#define PDMAUDIOHOSTDEV_F_BUGGY RT_BIT_32(2)
325/** Ignore the device, no matter what. */
326#define PDMAUDIOHOSTDEV_F_IGNORE RT_BIT_32(3)
327/** The device is present but marked as locked by some other application. */
328#define PDMAUDIOHOSTDEV_F_LOCKED RT_BIT_32(4)
329/** The device is present but not in an alive state (dead). */
330#define PDMAUDIOHOSTDEV_F_DEAD RT_BIT_32(5)
331/** Set if the extra backend specific data cannot be duplicated. */
332#define PDMAUDIOHOSTDEV_F_NO_DUP RT_BIT_32(31)
333/** @} */
334
335/**
336 * Audio device type.
337 */
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 /** Reference count indicating how many audio streams currently are relying on this device. */
377 uint8_t cRefCount;
378 /** Maximum number of input audio channels the device supports. */
379 uint8_t cMaxInputChannels;
380 /** Maximum number of output audio channels the device supports. */
381 uint8_t cMaxOutputChannels;
382 uint8_t bAlignment;
383 /** Device type union, based on enmType. */
384 union
385 {
386 /** USB type specifics. */
387 struct
388 {
389 /** Vendor ID. */
390 uint16_t idVendor;
391 /** Product ID. */
392 uint16_t idProduct;
393 } USB;
394 uint64_t uPadding[ARCH_BITS >= 64 ? 3 : 4];
395 } Type;
396 /** Friendly name of the device, if any. Could be truncated. */
397 char szName[64];
398} PDMAUDIOHOSTDEV;
399AssertCompileSizeAlignment(PDMAUDIOHOSTDEV, 16);
400/** Pointer to audio device info (enumeration result). */
401typedef PDMAUDIOHOSTDEV *PPDMAUDIOHOSTDEV;
402/** Pointer to a const audio device info (enumeration result). */
403typedef PDMAUDIOHOSTDEV const *PCPDMAUDIOHOSTDEV;
404
405/** Magic value for PDMAUDIOHOSTDEV. */
406#define PDMAUDIOHOSTDEV_MAGIC PDM_VERSION_MAKE(0xa0d0, 1, 0)
407
408
409/**
410 * A host audio device enumeration result.
411 *
412 * @sa PDMIHOSTAUDIO::pfnGetDevices
413 */
414typedef struct PDMAUDIOHOSTENUM
415{
416 /** Magic value (PDMAUDIOHOSTENUM_MAGIC). */
417 uint32_t uMagic;
418 /** Number of audio devices in the list. */
419 uint32_t cDevices;
420 /** List of audio devices (PDMAUDIOHOSTDEV). */
421 RTLISTANCHOR LstDevices;
422} PDMAUDIOHOSTENUM;
423/** Pointer to an audio device enumeration result. */
424typedef PDMAUDIOHOSTENUM *PPDMAUDIOHOSTENUM;
425/** Pointer to a const audio device enumeration result. */
426typedef PDMAUDIOHOSTENUM const *PCPDMAUDIOHOSTENUM;
427
428/** Magic for the host audio device enumeration. */
429#define PDMAUDIOHOSTENUM_MAGIC PDM_VERSION_MAKE(0xa0d1, 1, 0)
430
431
432/**
433 * Audio configuration (static) of an audio host backend.
434 */
435typedef struct PDMAUDIOBACKENDCFG
436{
437 /** The backend's friendly name. */
438 char szName[32];
439 /** Size (in bytes) of the host backend's audio output stream structure. */
440 size_t cbStreamOut;
441 /** Size (in bytes) of the host backend's audio input stream structure. */
442 size_t cbStreamIn;
443 /** Number of concurrent output (playback) streams supported on the host.
444 * UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
445 uint32_t cMaxStreamsOut;
446 /** Number of concurrent input (recording) streams supported on the host.
447 * UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
448 uint32_t cMaxStreamsIn;
449} PDMAUDIOBACKENDCFG;
450/** Pointer to a static host audio audio configuration. */
451typedef PDMAUDIOBACKENDCFG *PPDMAUDIOBACKENDCFG;
452
453/**
454 * A single audio frame.
455 *
456 * Currently only two (2) channels, left and right, are supported.
457 *
458 * @note When changing this structure, make sure to also handle
459 * VRDP's input / output processing in DrvAudioVRDE, as VRDP
460 * expects audio data in st_sample_t format (historical reasons)
461 * which happens to be the same as PDMAUDIOFRAME for now.
462 */
463typedef struct PDMAUDIOFRAME
464{
465 /** Left channel. */
466 int64_t i64LSample;
467 /** Right channel. */
468 int64_t i64RSample;
469} PDMAUDIOFRAME;
470/** Pointer to a single (stereo) audio frame. */
471typedef PDMAUDIOFRAME *PPDMAUDIOFRAME;
472/** Pointer to a const single (stereo) audio frame. */
473typedef PDMAUDIOFRAME const *PCPDMAUDIOFRAME;
474
475typedef enum PDMAUDIOENDIANNESS
476{
477 /** The usual invalid value. */
478 PDMAUDIOENDIANNESS_INVALID = 0,
479 /** Little endian. */
480 PDMAUDIOENDIANNESS_LITTLE,
481 /** Bit endian. */
482 PDMAUDIOENDIANNESS_BIG,
483 /** Endianness doesn't have a meaning in the context. */
484 PDMAUDIOENDIANNESS_NA,
485 /** The end of the valid endian values (exclusive). */
486 PDMAUDIOENDIANNESS_END,
487 /** Hack to blow the type up to 32-bit. */
488 PDMAUDIOENDIANNESS_32BIT_HACK = 0x7fffffff
489} PDMAUDIOENDIANNESS;
490
491/** @def PDMAUDIOHOSTENDIANNESS
492 * The PDMAUDIOENDIANNESS value for the host. */
493#if defined(RT_LITTLE_ENDIAN)
494# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_LITTLE
495#elif defined(RT_BIG_ENDIAN)
496# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_BIG
497#else
498# error "Port me!"
499#endif
500
501/**
502 * Audio playback destinations.
503 */
504typedef enum PDMAUDIOPLAYBACKDST
505{
506 /** Invalid zero value as per usual (guards against using unintialized values). */
507 PDMAUDIOPLAYBACKDST_INVALID = 0,
508 /** Unknown destination. */
509 PDMAUDIOPLAYBACKDST_UNKNOWN,
510 /** Front channel. */
511 PDMAUDIOPLAYBACKDST_FRONT,
512 /** Center / LFE (Subwoofer) channel. */
513 PDMAUDIOPLAYBACKDST_CENTER_LFE,
514 /** Rear channel. */
515 PDMAUDIOPLAYBACKDST_REAR,
516 /** End of valid values. */
517 PDMAUDIOPLAYBACKDST_END,
518 /** Hack to blow the type up to 32-bit. */
519 PDMAUDIOPLAYBACKDST_32BIT_HACK = 0x7fffffff
520} PDMAUDIOPLAYBACKDST;
521
522/**
523 * Audio recording sources.
524 *
525 * @note Because this is almost exclusively used in PDMAUDIODSTSRCUNION where it
526 * overlaps with PDMAUDIOPLAYBACKDST, the values starts at 64 instead of 0.
527 */
528typedef enum PDMAUDIORECSRC
529{
530 /** Unknown recording source. */
531 PDMAUDIORECSRC_UNKNOWN = 64,
532 /** Microphone-In. */
533 PDMAUDIORECSRC_MIC,
534 /** CD. */
535 PDMAUDIORECSRC_CD,
536 /** Video-In. */
537 PDMAUDIORECSRC_VIDEO,
538 /** AUX. */
539 PDMAUDIORECSRC_AUX,
540 /** Line-In. */
541 PDMAUDIORECSRC_LINE,
542 /** Phone-In. */
543 PDMAUDIORECSRC_PHONE,
544 /** End of valid values. */
545 PDMAUDIORECSRC_END,
546 /** Hack to blow the type up to 32-bit. */
547 PDMAUDIORECSRC_32BIT_HACK = 0x7fffffff
548} PDMAUDIORECSRC;
549
550/**
551 * Union for keeping an audio stream destination or source.
552 */
553typedef union PDMAUDIODSTSRCUNION
554{
555 /** Desired playback destination (for an output stream). */
556 PDMAUDIOPLAYBACKDST enmDst;
557 /** Desired recording source (for an input stream). */
558 PDMAUDIORECSRC enmSrc;
559} PDMAUDIODSTSRCUNION;
560/** Pointer to an audio stream src/dst union. */
561typedef PDMAUDIODSTSRCUNION *PPDMAUDIODSTSRCUNION;
562
563/**
564 * Audio stream (data) layout.
565 */
566typedef enum PDMAUDIOSTREAMLAYOUT
567{
568 /** Invalid zero value as per usual (guards against using unintialized values). */
569 PDMAUDIOSTREAMLAYOUT_INVALID = 0,
570 /** Unknown access type; do not use (hdaR3StreamMapReset uses it). */
571 PDMAUDIOSTREAMLAYOUT_UNKNOWN,
572 /** Non-interleaved access, that is, consecutive
573 * access to the data. */
574 PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED,
575 /** Interleaved access, where the data can be
576 * mixed together with data of other audio streams. */
577 PDMAUDIOSTREAMLAYOUT_INTERLEAVED,
578 /** Complex layout, which does not fit into the
579 * interleaved / non-interleaved layouts. */
580 PDMAUDIOSTREAMLAYOUT_COMPLEX,
581 /** Raw (pass through) data, with no data layout processing done.
582 *
583 * This means that this stream will operate on PDMAUDIOFRAME data
584 * directly. Don't use this if you don't have to. */
585 PDMAUDIOSTREAMLAYOUT_RAW,
586 /** End of valid values. */
587 PDMAUDIOSTREAMLAYOUT_END,
588 /** Hack to blow the type up to 32-bit. */
589 PDMAUDIOSTREAMLAYOUT_32BIT_HACK = 0x7fffffff
590} PDMAUDIOSTREAMLAYOUT;
591
592/**
593 * Stream channel data block.
594 */
595typedef struct PDMAUDIOSTREAMCHANNELDATA
596{
597 /** Circular buffer for the channel data. */
598 PRTCIRCBUF pCircBuf;
599 /** Amount of audio data (in bytes) acquired for reading. */
600 size_t cbAcq;
601 /** Channel data flags, PDMAUDIOSTREAMCHANNELDATA_FLAGS_XXX. */
602 uint32_t fFlags;
603} PDMAUDIOSTREAMCHANNELDATA;
604/** Pointer to audio stream channel data buffer. */
605typedef PDMAUDIOSTREAMCHANNELDATA *PPDMAUDIOSTREAMCHANNELDATA;
606
607/** @name PDMAUDIOSTREAMCHANNELDATA_FLAGS_XXX
608 * @{ */
609/** No stream channel data flags defined. */
610#define PDMAUDIOSTREAMCHANNELDATA_FLAGS_NONE UINT32_C(0)
611/** @} */
612
613/**
614 * Standard speaker channel IDs.
615 *
616 * This can cover up to 11.0 surround sound.
617 *
618 * @note Any of those channels can be marked / used as the LFE channel (played
619 * through the subwoofer).
620 */
621typedef enum PDMAUDIOSTREAMCHANNELID
622{
623 /** Invalid zero value as per usual (guards against using unintialized values). */
624 PDMAUDIOSTREAMCHANNELID_INVALID = 0,
625 /** Unknown / not set channel ID. */
626 PDMAUDIOSTREAMCHANNELID_UNKNOWN,
627 /** Front left channel. */
628 PDMAUDIOSTREAMCHANNELID_FRONT_LEFT,
629 /** Front right channel. */
630 PDMAUDIOSTREAMCHANNELID_FRONT_RIGHT,
631 /** Front center channel. */
632 PDMAUDIOSTREAMCHANNELID_FRONT_CENTER,
633 /** Low frequency effects (subwoofer) channel. */
634 PDMAUDIOSTREAMCHANNELID_LFE,
635 /** Rear left channel. */
636 PDMAUDIOSTREAMCHANNELID_REAR_LEFT,
637 /** Rear right channel. */
638 PDMAUDIOSTREAMCHANNELID_REAR_RIGHT,
639 /** Front left of center channel. */
640 PDMAUDIOSTREAMCHANNELID_FRONT_LEFT_OF_CENTER,
641 /** Front right of center channel. */
642 PDMAUDIOSTREAMCHANNELID_FRONT_RIGHT_OF_CENTER,
643 /** Rear center channel. */
644 PDMAUDIOSTREAMCHANNELID_REAR_CENTER,
645 /** Side left channel. */
646 PDMAUDIOSTREAMCHANNELID_SIDE_LEFT,
647 /** Side right channel. */
648 PDMAUDIOSTREAMCHANNELID_SIDE_RIGHT,
649 /** Left height channel. */
650 PDMAUDIOSTREAMCHANNELID_LEFT_HEIGHT,
651 /** Right height channel. */
652 PDMAUDIOSTREAMCHANNELID_RIGHT_HEIGHT,
653 /** End of valid values. */
654 PDMAUDIOSTREAMCHANNELID_END,
655 /** Hack to blow the type up to 32-bit. */
656 PDMAUDIOSTREAMCHANNELID_32BIT_HACK = 0x7fffffff
657} PDMAUDIOSTREAMCHANNELID;
658
659/**
660 * Mappings channels onto an audio stream.
661 *
662 * The mappings are either for a single (mono) or dual (stereo) channels onto an
663 * audio stream (aka stream profile). An audio stream consists of one or
664 * multiple channels (e.g. 1 for mono, 2 for stereo), depending on the
665 * configuration.
666 */
667typedef struct PDMAUDIOSTREAMMAP
668{
669 /** Array of channel IDs being handled.
670 * @note The first (zero-based) index specifies the leftmost channel. */
671 PDMAUDIOSTREAMCHANNELID aenmIDs[2];
672 /** Step size (in bytes) to the channel's next frame. */
673 uint32_t cbStep;
674 /** Frame size (in bytes) of this channel. */
675 uint32_t cbFrame;
676 /** Byte offset to the first frame in the data block. */
677 uint32_t offFirst;
678 /** Byte offset to the next frame in the data block. */
679 uint32_t offNext;
680 /** Associated data buffer. */
681 PDMAUDIOSTREAMCHANNELDATA Data;
682} PDMAUDIOSTREAMMAP;
683/** Pointer to an audio stream channel mapping. */
684typedef PDMAUDIOSTREAMMAP *PPDMAUDIOSTREAMMAP;
685
686/**
687 * Properties of audio streams for host/guest for in or out directions.
688 */
689typedef struct PDMAUDIOPCMPROPS
690{
691 /** Sample width (in bytes). */
692 uint8_t cbSample;
693 /** Number of audio channels. */
694 uint8_t cChannels;
695 /** Shift count used with PDMAUDIOPCMPROPS_F2B and PDMAUDIOPCMPROPS_B2F.
696 * Depends on number of stream channels and the stream format being used, calc
697 * value using PDMAUDIOPCMPROPS_MAKE_SHIFT.
698 * @sa PDMAUDIOSTREAMCFG_B2F, PDMAUDIOSTREAMCFG_F2B
699 * @todo r=bird: The original brief description: "Shift count used
700 * for faster calculation of various values, such as the alignment, bytes
701 * to frames and so on." I cannot make heads or tails from that.
702 * @todo Use some RTAsmXXX functions instead? */
703 uint8_t cShift;
704 /** Signed or unsigned sample. */
705 bool fSigned : 1;
706 /** Whether the endianness is swapped or not. */
707 bool fSwapEndian : 1;
708 /** Sample frequency in Hertz (Hz). */
709 uint32_t uHz;
710} PDMAUDIOPCMPROPS;
711AssertCompileSize(PDMAUDIOPCMPROPS, 8);
712AssertCompileSizeAlignment(PDMAUDIOPCMPROPS, 8);
713/** Pointer to audio stream properties. */
714typedef PDMAUDIOPCMPROPS *PPDMAUDIOPCMPROPS;
715/** Pointer to const audio stream properties. */
716typedef PDMAUDIOPCMPROPS const *PCPDMAUDIOPCMPROPS;
717
718/** @name Macros for use with PDMAUDIOPCMPROPS
719 * @{ */
720/** Initializor for PDMAUDIOPCMPROPS. */
721#define PDMAUDIOPCMPROPS_INITIALIZOR(a_cBytes, a_fSigned, a_cCannels, a_uHz, a_cShift, a_fSwapEndian) \
722 { a_cBytes, a_cCannels, a_cShift, a_fSigned, a_fSwapEndian, a_uHz }
723/** Calculates the cShift value of given sample bits and audio channels.
724 * @note Does only support mono/stereo channels for now. */
725#define PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS(cBytes, cChannels) ((cChannels == 2) + (cBytes / 2))
726/** Calculates the cShift value of a PDMAUDIOPCMPROPS structure. */
727#define PDMAUDIOPCMPROPS_MAKE_SHIFT(pProps) PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS((pProps)->cbSample, (pProps)->cChannels)
728/** Converts (audio) frames to bytes.
729 * Needs the cShift value set correctly, using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
730#define PDMAUDIOPCMPROPS_F2B(pProps, frames) ((frames) << (pProps)->cShift)
731/** Converts bytes to (audio) frames.
732 * Needs the cShift value set correctly, using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
733#define PDMAUDIOPCMPROPS_B2F(pProps, cb) ((cb) >> (pProps)->cShift)
734/** @} */
735
736/**
737 * An audio stream configuration.
738 */
739typedef struct PDMAUDIOSTREAMCFG
740{
741 /** Direction of the stream. */
742 PDMAUDIODIR enmDir;
743 /** Destination / source indicator, depending on enmDir. */
744 PDMAUDIODSTSRCUNION u;
745 /** The stream's PCM properties. */
746 PDMAUDIOPCMPROPS Props;
747 /** The stream's audio data layout.
748 * This indicates how the audio data buffers to/from the backend is being layouted.
749 *
750 * Currently, the following layouts are supported by the audio connector:
751 *
752 * PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED:
753 * One stream at once. The consecutive audio data is exactly in the format and frame width
754 * like defined in the PCM properties. This is the default.
755 *
756 * PDMAUDIOSTREAMLAYOUT_RAW:
757 * Can be one or many streams at once, depending on the stream's mixing buffer setup.
758 * The audio data will get handled as PDMAUDIOFRAME frames without any modification done. */
759 PDMAUDIOSTREAMLAYOUT enmLayout;
760 /** Device emulation-specific data needed for the audio connector. */
761 struct
762 {
763 /** Scheduling hint set by the device emulation about when this stream is being served on average (in ms).
764 * Can be 0 if not hint given or some other mechanism (e.g. callbacks) is being used. */
765 uint32_t cMsSchedulingHint;
766 } Device;
767 /**
768 * Backend-specific data for the stream.
769 * On input (requested configuration) those values are set by the audio connector to let the backend know what we expect.
770 * On output (acquired configuration) those values reflect the values set and used by the backend.
771 * Set by the backend on return. Not all backends support all values / features.
772 */
773 struct
774 {
775 /** Period size of the stream (in audio frames).
776 * This value reflects the number of audio frames in between each hardware interrupt on the
777 * backend (host) side. 0 if not set / available by the backend. */
778 uint32_t cFramesPeriod;
779 /** (Ring) buffer size (in audio frames). Often is a multiple of cFramesPeriod.
780 * 0 if not set / available by the backend. */
781 uint32_t cFramesBufferSize;
782 /** Pre-buffering size (in audio frames). Frames needed in buffer before the stream becomes active (pre buffering).
783 * The bigger this value is, the more latency for the stream will occur.
784 * 0 if not set / available by the backend. UINT32_MAX if not defined (yet). */
785 uint32_t cFramesPreBuffering;
786 } Backend;
787 uint32_t u32Padding;
788 /** Friendly name of the stream. */
789 char szName[64];
790} PDMAUDIOSTREAMCFG;
791AssertCompileSizeAlignment(PDMAUDIOSTREAMCFG, 8);
792/** Pointer to audio stream configuration keeper. */
793typedef PDMAUDIOSTREAMCFG *PPDMAUDIOSTREAMCFG;
794/** Pointer to a const audio stream configuration keeper. */
795typedef PDMAUDIOSTREAMCFG const *PCPDMAUDIOSTREAMCFG;
796
797/** Converts (audio) frames to bytes. */
798#define PDMAUDIOSTREAMCFG_F2B(pCfg, frames) ((frames) << (pCfg->Props).cShift)
799/** Converts bytes to (audio) frames. */
800#define PDMAUDIOSTREAMCFG_B2F(pCfg, cb) (cb >> (pCfg->Props).cShift)
801
802/**
803 * Audio mixer controls.
804 */
805typedef enum PDMAUDIOMIXERCTL
806{
807 /** Invalid zero value as per usual (guards against using unintialized values). */
808 PDMAUDIOMIXERCTL_INVALID = 0,
809 /** Unknown mixer control. */
810 PDMAUDIOMIXERCTL_UNKNOWN,
811 /** Master volume. */
812 PDMAUDIOMIXERCTL_VOLUME_MASTER,
813 /** Front. */
814 PDMAUDIOMIXERCTL_FRONT,
815 /** Center / LFE (Subwoofer). */
816 PDMAUDIOMIXERCTL_CENTER_LFE,
817 /** Rear. */
818 PDMAUDIOMIXERCTL_REAR,
819 /** Line-In. */
820 PDMAUDIOMIXERCTL_LINE_IN,
821 /** Microphone-In. */
822 PDMAUDIOMIXERCTL_MIC_IN,
823 /** End of valid values. */
824 PDMAUDIOMIXERCTL_END,
825 /** Hack to blow the type up to 32-bit. */
826 PDMAUDIOMIXERCTL_32BIT_HACK = 0x7fffffff
827} PDMAUDIOMIXERCTL;
828
829/**
830 * Audio stream commands.
831 *
832 * Used in the audio connector as well as in the actual host backends.
833 */
834typedef enum PDMAUDIOSTREAMCMD
835{
836 /** Invalid zero value as per usual (guards against using unintialized values). */
837 PDMAUDIOSTREAMCMD_INVALID = 0,
838 /** Unknown command, do not use. */
839 PDMAUDIOSTREAMCMD_UNKNOWN,
840 /** Enables the stream. */
841 PDMAUDIOSTREAMCMD_ENABLE,
842 /** Disables the stream.
843 * For output streams this stops the stream after playing the remaining (buffered) audio data.
844 * For input streams this will deliver the remaining (captured) audio data and not accepting
845 * any new audio input data afterwards. */
846 PDMAUDIOSTREAMCMD_DISABLE,
847 /** Pauses the stream. */
848 PDMAUDIOSTREAMCMD_PAUSE,
849 /** Resumes the stream. */
850 PDMAUDIOSTREAMCMD_RESUME,
851 /** Tells the stream to drain itself.
852 * For output streams this plays all remaining (buffered) audio frames,
853 * for input streams this permits receiving any new audio frames.
854 * No supported by all backends. */
855 PDMAUDIOSTREAMCMD_DRAIN,
856 /** Tells the stream to drop all (buffered) audio data immediately.
857 * No supported by all backends. */
858 PDMAUDIOSTREAMCMD_DROP,
859 /** End of valid values. */
860 PDMAUDIOSTREAMCMD_END,
861 /** Hack to blow the type up to 32-bit. */
862 PDMAUDIOSTREAMCMD_32BIT_HACK = 0x7fffffff
863} PDMAUDIOSTREAMCMD;
864
865/**
866 * Audio volume parameters.
867 */
868typedef struct PDMAUDIOVOLUME
869{
870 /** Set to @c true if this stream is muted, @c false if not. */
871 bool fMuted;
872 /** Left channel volume.
873 * Range is from [0 ... 255], whereas 0 specifies
874 * the most silent and 255 the loudest value. */
875 uint8_t uLeft;
876 /** Right channel volume.
877 * Range is from [0 ... 255], whereas 0 specifies
878 * the most silent and 255 the loudest value. */
879 uint8_t uRight;
880} PDMAUDIOVOLUME;
881/** Pointer to audio volume settings. */
882typedef PDMAUDIOVOLUME *PPDMAUDIOVOLUME;
883
884/** Defines the minimum volume allowed. */
885#define PDMAUDIO_VOLUME_MIN (0)
886/** Defines the maximum volume allowed. */
887#define PDMAUDIO_VOLUME_MAX (255)
888
889/**
890 * Rate processing information of a source & destination audio stream.
891 *
892 * This is needed because both streams can differ regarding their rates and
893 * therefore need to be treated accordingly.
894 */
895typedef struct PDMAUDIOSTREAMRATE
896{
897 /** Current (absolute) offset in the output (destination) stream.
898 * @todo r=bird: Please reveal which unit these members are given in. */
899 uint64_t offDst;
900 /** Increment for moving offDst for the destination stream.
901 * This is needed because the source <-> destination rate might be different. */
902 uint64_t uDstInc;
903 /** Current (absolute) offset in the input stream. */
904 uint32_t offSrc;
905 /** Explicit alignment padding. */
906 uint32_t u32AlignmentPadding;
907 /** Last processed frame of the input stream.
908 * Needed for interpolation. */
909 PDMAUDIOFRAME SrcFrameLast;
910} PDMAUDIOSTREAMRATE;
911/** Pointer to rate processing information of a stream. */
912typedef PDMAUDIOSTREAMRATE *PPDMAUDIOSTREAMRATE;
913
914/**
915 * Mixing buffer volume parameters.
916 *
917 * The volume values are in fixed point style and must be converted to/from
918 * before using with e.g. PDMAUDIOVOLUME.
919 */
920typedef struct PDMAUDMIXBUFVOL
921{
922 /** Set to @c true if this stream is muted, @c false if not. */
923 bool fMuted;
924 /** Left volume to apply during conversion.
925 * Pass 0 to convert the original values. May not apply to all conversion functions. */
926 uint32_t uLeft;
927 /** Right volume to apply during conversion.
928 * Pass 0 to convert the original values. May not apply to all conversion functions. */
929 uint32_t uRight;
930} PDMAUDMIXBUFVOL;
931/** Pointer to mixing buffer volument parameters. */
932typedef PDMAUDMIXBUFVOL *PPDMAUDMIXBUFVOL;
933
934/*
935 * Frame conversion parameters for the audioMixBufConvFromXXX / audioMixBufConvToXXX functions.
936 */
937typedef struct PDMAUDMIXBUFCONVOPTS
938{
939 /** Number of audio frames to convert. */
940 uint32_t cFrames;
941 union
942 {
943 struct
944 {
945 /** Volume to use for conversion. */
946 PDMAUDMIXBUFVOL Volume;
947 } From;
948 } RT_UNION_NM(u);
949} PDMAUDMIXBUFCONVOPTS;
950/** Pointer to conversion parameters for the audio mixer. */
951typedef PDMAUDMIXBUFCONVOPTS *PPDMAUDMIXBUFCONVOPTS;
952/** Pointer to const conversion parameters for the audio mixer. */
953typedef PDMAUDMIXBUFCONVOPTS const *PCPDMAUDMIXBUFCONVOPTS;
954
955/**
956 * @note All internal handling is done in audio frames, not in bytes!
957 * @todo r=bird: What does this node actually apply to?
958 */
959typedef uint32_t PDMAUDIOMIXBUFFMT;
960typedef PDMAUDIOMIXBUFFMT *PPDMAUDIOMIXBUFFMT;
961
962/**
963 * Convertion-from function used by the PDM audio buffer mixer.
964 *
965 * @returns Number of audio frames returned.
966 * @param paDst Where to return the converted frames.
967 * @param pvSrc The source frame bytes.
968 * @param cbSrc Number of bytes to convert.
969 * @param pOpts Conversion options.
970 * @todo r=bird: The @a paDst size is presumable given in @a pOpts->cFrames?
971 */
972typedef DECLCALLBACKTYPE(uint32_t, FNPDMAUDIOMIXBUFCONVFROM,(PPDMAUDIOFRAME paDst, const void *pvSrc, uint32_t cbSrc,
973 PCPDMAUDMIXBUFCONVOPTS pOpts));
974/** Pointer to a convertion-from function used by the PDM audio buffer mixer. */
975typedef FNPDMAUDIOMIXBUFCONVFROM *PFNPDMAUDIOMIXBUFCONVFROM;
976
977/**
978 * Convertion-to function used by the PDM audio buffer mixer.
979 *
980 * @param pvDst Output buffer.
981 * @param paSrc The input frames.
982 * @param pOpts Conversion options.
983 * @todo r=bird: The @a paSrc size is presumable given in @a pOpts->cFrames and
984 * this implicitly gives the pvDst size too, right?
985 */
986typedef DECLCALLBACKTYPE(void, FNPDMAUDIOMIXBUFCONVTO,(void *pvDst, PCPDMAUDIOFRAME paSrc, PCPDMAUDMIXBUFCONVOPTS pOpts));
987/** Pointer to a convertion-to function used by the PDM audio buffer mixer. */
988typedef FNPDMAUDIOMIXBUFCONVTO *PFNPDMAUDIOMIXBUFCONVTO;
989
990/** Pointer to audio mixing buffer. */
991typedef struct PDMAUDIOMIXBUF *PPDMAUDIOMIXBUF;
992
993/**
994 * Audio mixing buffer.
995 */
996typedef struct PDMAUDIOMIXBUF
997{
998 /** Magic value (PDMAUDIOMIXBUF_MAGIC). */
999 uint32_t uMagic;
1000 /** For quickly converting frames <-> bytes and vice versa. */
1001 uint8_t cShift;
1002 uint8_t abPadding[3];
1003 /* ???Undocumented??? */
1004 RTLISTNODE Node;
1005 /** Name of the buffer. */
1006 char *pszName;
1007 /** Frame buffer. */
1008 PPDMAUDIOFRAME pFrames;
1009 /** Size of the frame buffer (in audio frames). */
1010 uint32_t cFrames;
1011 /** The current read position (in frames). */
1012 uint32_t offRead;
1013 /** The current write position (in frames). */
1014 uint32_t offWrite;
1015 /** Total frames already mixed down to the parent buffer (if any).
1016 *
1017 * Always starting at the parent's offRead position.
1018 * @note Count always is specified in parent frames, as the sample count can
1019 * differ between parent and child. */
1020 uint32_t cMixed;
1021 /** How much audio frames are currently being used
1022 * in this buffer.
1023 * Note: This also is known as the distance in ring buffer terms. */
1024 uint32_t cUsed;
1025 /** Number of children mix buffers kept in lstChildren. */
1026 uint32_t cChildren;
1027 /** List of children mix buffers to keep in sync with (if being a parent buffer). */
1028 RTLISTANCHOR lstChildren;
1029 /** Pointer to parent buffer (if any). */
1030 PPDMAUDIOMIXBUF pParent;
1031 /** Intermediate structure for buffer conversion tasks. */
1032 PPDMAUDIOSTREAMRATE pRate;
1033 /** Internal representation of current volume used for mixing. */
1034 PDMAUDMIXBUFVOL Volume;
1035 /** This buffer's audio format.
1036 * @todo r=bird: This seems to be a value created by AUDMIXBUF_AUDIO_FMT_MAKE(),
1037 * which is not define here. Does this structure really belong here at
1038 * all? */
1039 PDMAUDIOMIXBUFFMT uAudioFmt;
1040 /** Standard conversion-to function for set uAudioFmt. */
1041 PFNPDMAUDIOMIXBUFCONVTO pfnConvTo;
1042 /** Standard conversion-from function for set uAudioFmt. */
1043 PFNPDMAUDIOMIXBUFCONVFROM pfnConvFrom;
1044 /** Ratio of the associated parent stream's frequency by this stream's
1045 * frequency (1<<32), represented as a signed 64 bit integer.
1046 *
1047 * For example, if the parent stream has a frequency of 44 khZ, and this
1048 * stream has a frequency of 11 kHz, the ration then would be
1049 * (44/11 * (1 << 32)).
1050 *
1051 * Currently this does not get changed once assigned. */
1052 int64_t iFreqRatio;
1053} PDMAUDIOMIXBUF;
1054
1055/** Magic value for PDMAUDIOMIXBUF. */
1056#define PDMAUDIOMIXBUF_MAGIC PDM_VERSION_MAKE(0xa0d2, 1, 0)
1057
1058/** @name PDMAUDIOFILE_FLAGS_XXX
1059 * @{ */
1060/** No flags defined. */
1061#define PDMAUDIOFILE_FLAGS_NONE UINT32_C(0)
1062/** Keep the audio file even if it contains no audio data. */
1063#define PDMAUDIOFILE_FLAGS_KEEP_IF_EMPTY RT_BIT_32(0)
1064/** Audio file flag validation mask. */
1065#define PDMAUDIOFILE_FLAGS_VALID_MASK UINT32_C(0x1)
1066/** @} */
1067
1068/** Audio file default open flags.
1069 * @todo r=bird: What is the exact purpose of this? */
1070#define PDMAUDIOFILE_DEFAULT_OPEN_FLAGS (RTFILE_O_OPEN_CREATE | RTFILE_O_APPEND | RTFILE_O_WRITE | RTFILE_O_DENY_WRITE)
1071
1072/**
1073 * Audio file types.
1074 * @todo r=bird: This does not really belong here.
1075 */
1076typedef enum PDMAUDIOFILETYPE
1077{
1078 /** The customary invalid zero value. */
1079 PDMAUDIOFILETYPE_INVALID = 0,
1080 /** Unknown type, do not use. */
1081 PDMAUDIOFILETYPE_UNKNOWN,
1082 /** Raw (PCM) file. */
1083 PDMAUDIOFILETYPE_RAW,
1084 /** Wave (.WAV) file. */
1085 PDMAUDIOFILETYPE_WAV,
1086 /** Hack to blow the type up to 32-bit. */
1087 PDMAUDIOFILETYPE_32BIT_HACK = 0x7fffffff
1088} PDMAUDIOFILETYPE;
1089
1090/** @name PDMAUDIOFILENAME_FLAGS_XXX
1091 * @{ */
1092/** No flags defined. */
1093#define PDMAUDIOFILENAME_FLAGS_NONE UINT32_C(0)
1094/** Adds an ISO timestamp to the file name. */
1095#define PDMAUDIOFILENAME_FLAGS_TS RT_BIT(0)
1096/** @} */
1097
1098/**
1099 * Audio file handle.
1100 */
1101typedef struct PDMAUDIOFILE
1102{
1103 /** Type of the audio file. */
1104 PDMAUDIOFILETYPE enmType;
1105 /** Audio file flags, PDMAUDIOFILE_FLAGS_XXX. */
1106 uint32_t fFlags;
1107 /** Actual file handle. */
1108 RTFILE hFile;
1109 /** Data needed for the specific audio file type implemented.
1110 * Optional, can be NULL. */
1111 void *pvData;
1112 /** Data size (in bytes). */
1113 size_t cbData;
1114 /** File name and path. */
1115 char szName[RTPATH_MAX];
1116} PDMAUDIOFILE;
1117/** Pointer to an audio file handle. */
1118typedef PDMAUDIOFILE *PPDMAUDIOFILE;
1119
1120/** @name PDMAUDIOSTREAMSTS_FLAGS_XXX
1121 * @{ */
1122/** No flags being set. */
1123#define PDMAUDIOSTREAMSTS_FLAGS_NONE UINT32_C(0)
1124/** Whether this stream has been initialized by the
1125 * backend or not. */
1126#define PDMAUDIOSTREAMSTS_FLAGS_INITIALIZED RT_BIT_32(0)
1127/** Whether this stream is enabled or disabled. */
1128#define PDMAUDIOSTREAMSTS_FLAGS_ENABLED RT_BIT_32(1)
1129/** Whether this stream has been paused or not. This also implies
1130 * that this is an enabled stream! */
1131#define PDMAUDIOSTREAMSTS_FLAGS_PAUSED RT_BIT_32(2)
1132/** Whether this stream was marked as being disabled
1133 * but there are still associated guest output streams
1134 * which rely on its data. */
1135#define PDMAUDIOSTREAMSTS_FLAGS_PENDING_DISABLE RT_BIT_32(3)
1136/** Whether this stream is in re-initialization phase.
1137 * All other bits remain untouched to be able to restore
1138 * the stream's state after the re-initialization bas been
1139 * finished. */
1140#define PDMAUDIOSTREAMSTS_FLAGS_PENDING_REINIT RT_BIT_32(4)
1141/** Validation mask. */
1142#define PDMAUDIOSTREAMSTS_VALID_MASK UINT32_C(0x0000001F)
1143/** Stream status flag, PDMAUDIOSTREAMSTS_FLAGS_XXX. */
1144typedef uint32_t PDMAUDIOSTREAMSTS;
1145/** @} */
1146
1147/**
1148 * Backend status.
1149 */
1150typedef enum PDMAUDIOBACKENDSTS
1151{
1152 /** Unknown/invalid status. */
1153 PDMAUDIOBACKENDSTS_UNKNOWN = 0,
1154 /** No backend attached. */
1155 PDMAUDIOBACKENDSTS_NOT_ATTACHED,
1156 /** The backend is in its initialization phase.
1157 * Not all backends support this status. */
1158 PDMAUDIOBACKENDSTS_INITIALIZING,
1159 /** The backend has stopped its operation. */
1160 PDMAUDIOBACKENDSTS_STOPPED,
1161 /** The backend is up and running. */
1162 PDMAUDIOBACKENDSTS_RUNNING,
1163 /** The backend ran into an error and is unable to recover.
1164 * A manual re-initialization might help. */
1165 PDMAUDIOBACKENDSTS_ERROR,
1166 /** Hack to blow the type up to 32-bit. */
1167 PDMAUDIOBACKENDSTS_32BIT_HACK = 0x7fffffff
1168} PDMAUDIOBACKENDSTS;
1169
1170/**
1171 * The specifics for an audio input stream.
1172 *
1173 * Do not use directly, use PDMAUDIOSTREAM instead.
1174 */
1175typedef struct PDMAUDIOSTREAMIN
1176{
1177 struct
1178 {
1179 /** File for writing stream reads. */
1180 PPDMAUDIOFILE pFileStreamRead;
1181 /** File for writing non-interleaved captures. */
1182 PPDMAUDIOFILE pFileCaptureNonInterleaved;
1183 } Dbg;
1184 struct
1185 {
1186 STAMCOUNTER TotalFramesCaptured;
1187 STAMCOUNTER AvgFramesCaptured;
1188 STAMCOUNTER TotalTimesCaptured;
1189 STAMCOUNTER TotalFramesRead;
1190 STAMCOUNTER AvgFramesRead;
1191 STAMCOUNTER TotalTimesRead;
1192 } Stats;
1193} PDMAUDIOSTREAMIN;
1194/** Pointer to the specifics for an audio input stream. */
1195typedef PDMAUDIOSTREAMIN *PPDMAUDIOSTREAMIN;
1196
1197/**
1198 * The specifics for an audio output stream.
1199 *
1200 * Do not use directly, use PDMAUDIOSTREAM instead.
1201 */
1202typedef struct PDMAUDIOSTREAMOUT
1203{
1204 struct
1205 {
1206 /** File for writing stream writes. */
1207 PPDMAUDIOFILE pFileStreamWrite;
1208 /** File for writing stream playback. */
1209 PPDMAUDIOFILE pFilePlayNonInterleaved;
1210 } Dbg;
1211 struct
1212 {
1213 STAMCOUNTER TotalFramesPlayed;
1214 STAMCOUNTER AvgFramesPlayed;
1215 STAMCOUNTER TotalTimesPlayed;
1216 STAMCOUNTER TotalFramesWritten;
1217 STAMCOUNTER AvgFramesWritten;
1218 STAMCOUNTER TotalTimesWritten;
1219 } Stats;
1220} PDMAUDIOSTREAMOUT;
1221/** Pointer to the specifics for an audio output stream. */
1222typedef PDMAUDIOSTREAMOUT *PPDMAUDIOSTREAMOUT;
1223
1224/** Pointer to an audio stream. */
1225typedef struct PDMAUDIOSTREAM *PPDMAUDIOSTREAM;
1226
1227/**
1228 * Audio stream context.
1229 * Needed for separating data from the guest and host side (per stream).
1230 */
1231typedef struct PDMAUDIOSTREAMCTX
1232{
1233 /** The stream's audio configuration. */
1234 PDMAUDIOSTREAMCFG Cfg;
1235 /** This stream's mixing buffer. */
1236 PDMAUDIOMIXBUF MixBuf;
1237} PDMAUDIOSTREAMCTX;
1238
1239/** Pointer to an audio stream context. */
1240typedef struct PDMAUDIOSTREAM *PPDMAUDIOSTREAMCTX;
1241
1242/** @name PDMAUDIOSTREAM_WARN_FLAGS_XXX
1243 * @{ */
1244/** No stream warning flags set. */
1245#define PDMAUDIOSTREAM_WARN_FLAGS_NONE 0
1246/** Warned about a disabled stream. */
1247#define PDMAUDIOSTREAM_WARN_FLAGS_DISABLED RT_BIT(0)
1248/** @} */
1249
1250/**
1251 * An input or output audio stream.
1252 */
1253typedef struct PDMAUDIOSTREAM
1254{
1255 /** Magic value (PDMAUDIOSTREAM_MAGIC). */
1256 uint32_t uMagic;
1257 /** Size (in bytes) of the backend-specific stream data. */
1258 uint32_t cbBackend;
1259 /** List entry (some DrvAudio internal list). */
1260 RTLISTNODE ListEntry;
1261 /** Number of references to this stream.
1262 * Only can be destroyed when the reference count reaches 0. */
1263 uint32_t cRefs;
1264 /** Number of (re-)tries while re-initializing the stream. */
1265 uint32_t cTriesReInit;
1266 /** Warnings shown already in the release log.
1267 * See PDMAUDIOSTREAM_WARN_FLAGS_XXX. */
1268 uint32_t fWarningsShown;
1269 /** Stream status flag. */
1270 PDMAUDIOSTREAMSTS fStatus;
1271 /** Audio direction of this stream. */
1272 PDMAUDIODIR enmDir;
1273 /** For output streams this indicates whether the stream has reached
1274 * its playback threshold, e.g. is playing audio.
1275 * For input streams this indicates whether the stream has enough input
1276 * data to actually start reading audio. */
1277 bool fThresholdReached;
1278 bool afPadding[3];
1279 /** The guest side of the stream. */
1280 PDMAUDIOSTREAMCTX Guest;
1281 /** The host side of the stream. */
1282 PDMAUDIOSTREAMCTX Host;
1283 /** Timestamp (in ns) since last trying to re-initialize.
1284 * Might be 0 if has not been tried yet. */
1285 uint64_t tsLastReInitNs;
1286 /** Timestamp (in ns) since last iteration. */
1287 uint64_t tsLastIteratedNs;
1288 /** Timestamp (in ns) since last playback / capture. */
1289 uint64_t tsLastPlayedCapturedNs;
1290 /** Timestamp (in ns) since last read (input streams) or
1291 * write (output streams). */
1292 uint64_t tsLastReadWrittenNs;
1293 /** Data to backend-specific stream data.
1294 * This data block will be casted by the backend to access its backend-dependent data.
1295 *
1296 * That way the backends do not have access to the audio connector's data. */
1297 void *pvBackend;
1298
1299 /** Name of this stream. */
1300 char szName[64];
1301
1302 /** Union for input/output specifics depending on enmDir. */
1303 union
1304 {
1305 PDMAUDIOSTREAMIN In;
1306 PDMAUDIOSTREAMOUT Out;
1307 } RT_UNION_NM(u);
1308} PDMAUDIOSTREAM;
1309
1310/** Magic value for PDMAUDIOSTREAM. */
1311#define PDMAUDIOSTREAM_MAGIC PDM_VERSION_MAKE(0xa0d3, 1, 0)
1312
1313
1314/**
1315 * Audio callback source.
1316 */
1317typedef enum PDMAUDIOCBSOURCE
1318{
1319 /** Invalid, do not use. */
1320 PDMAUDIOCBSOURCE_INVALID = 0,
1321 /** Device emulation. */
1322 PDMAUDIOCBSOURCE_DEVICE,
1323 /** Audio connector interface. */
1324 PDMAUDIOCBSOURCE_CONNECTOR,
1325 /** Backend (lower). */
1326 PDMAUDIOCBSOURCE_BACKEND,
1327 /** Hack to blow the type up to 32-bit. */
1328 PDMAUDIOCBSOURCE_32BIT_HACK = 0x7fffffff
1329} PDMAUDIOCBSOURCE;
1330
1331/**
1332 * Audio device callback types.
1333 * Those callbacks are being sent from the audio connector -> device emulation.
1334 */
1335typedef enum PDMAUDIODEVICECBTYPE
1336{
1337 /** Invalid, do not use. */
1338 PDMAUDIODEVICECBTYPE_INVALID = 0,
1339 /** Data is availabe as input for passing to the device emulation. */
1340 PDMAUDIODEVICECBTYPE_DATA_INPUT,
1341 /** Free data for the device emulation to write to the backend. */
1342 PDMAUDIODEVICECBTYPE_DATA_OUTPUT,
1343 /** Hack to blow the type up to 32-bit. */
1344 PDMAUDIODEVICECBTYPE_32BIT_HACK = 0x7fffffff
1345} PDMAUDIODEVICECBTYPE;
1346
1347#if 0 /** @todo r=bird: Who needs this exactly? Fix the style or remove */
1348/**
1349 * Device callback data for audio input.
1350 */
1351typedef struct PDMAUDIODEVICECBDATA_DATA_INPUT
1352{
1353 /** Input: How many bytes are availabe as input for passing
1354 * to the device emulation. */
1355 uint32_t cbInAvail;
1356 /** Output: How many bytes have been read. */
1357 uint32_t cbOutRead;
1358} PDMAUDIODEVICECBDATA_DATA_INPUT;
1359typedef PDMAUDIODEVICECBDATA_DATA_INPUT *PPDMAUDIODEVICECBDATA_DATA_INPUT;
1360
1361/**
1362 * Device callback data for audio output.
1363 */
1364typedef struct PDMAUDIODEVICECBDATA_DATA_OUTPUT
1365{
1366 /** Input: How many bytes are free for the device emulation to write. */
1367 uint32_t cbInFree;
1368 /** Output: How many bytes were written by the device emulation. */
1369 uint32_t cbOutWritten;
1370} PDMAUDIODEVICECBDATA_DATA_OUTPUT, *PPDMAUDIODEVICECBDATA_DATA_OUTPUT;
1371#endif
1372
1373/**
1374 * Audio backend callback types.
1375 * Those callbacks are being sent from the backend -> audio connector.
1376 */
1377typedef enum PDMAUDIOBACKENDCBTYPE
1378{
1379 /** Invalid, do not use. */
1380 PDMAUDIOBACKENDCBTYPE_INVALID = 0,
1381 /** The backend's status has changed. */
1382 PDMAUDIOBACKENDCBTYPE_STATUS,
1383 /** One or more host audio devices have changed. */
1384 PDMAUDIOBACKENDCBTYPE_DEVICES_CHANGED,
1385 /** Hack to blow the type up to 32-bit. */
1386 PDMAUDIOBACKENDCBTYPE_32BIT_HACK = 0x7fffffff
1387} PDMAUDIOBACKENDCBTYPE;
1388
1389/** Pointer to a host audio interface. */
1390typedef struct PDMIHOSTAUDIO *PPDMIHOSTAUDIO;
1391
1392/**
1393 * Host audio callback function.
1394 *
1395 * This function will be called from a backend to communicate with the host audio interface.
1396 *
1397 * @returns IPRT status code.
1398 * @param pDrvIns Pointer to driver instance which called us.
1399 * @param enmType Callback type.
1400 * @param pvUser User argument.
1401 * @param cbUser Size (in bytes) of user argument.
1402 */
1403typedef DECLCALLBACKTYPE(int, FNPDMHOSTAUDIOCALLBACK,(PPDMDRVINS pDrvIns, PDMAUDIOBACKENDCBTYPE enmType,
1404 void *pvUser, size_t cbUser));
1405/** Pointer to a FNPDMHOSTAUDIOCALLBACK(). */
1406typedef FNPDMHOSTAUDIOCALLBACK *PFNPDMHOSTAUDIOCALLBACK;
1407
1408/**
1409 * Audio callback registration record.
1410 */
1411typedef struct PDMAUDIOCBRECORD
1412{
1413 /** List node. */
1414 RTLISTANCHOR Node;
1415 /** Callback source. */
1416 PDMAUDIOCBSOURCE enmSource;
1417 /** Callback type, based on the given source. */
1418 union
1419 {
1420 /** Device callback stuff. */
1421 struct
1422 {
1423 PDMAUDIODEVICECBTYPE enmType;
1424 } Device;
1425 } RT_UNION_NM(u);
1426 /** Pointer to context data. Optional. */
1427 void *pvCtx;
1428 /** Size (in bytes) of context data.
1429 * Must be 0 if pvCtx is NULL. */
1430 size_t cbCtx;
1431} PDMAUDIOCBRECORD;
1432/** Pointer to an audio callback registration record. */
1433typedef PDMAUDIOCBRECORD *PPDMAUDIOCBRECORD;
1434
1435/** @todo r=bird: What is this exactly? */
1436#define PPDMAUDIOBACKENDSTREAM void *
1437
1438/** Pointer to a audio connector interface. */
1439typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
1440
1441/**
1442 * Audio connector interface (up).
1443 */
1444typedef struct PDMIAUDIOCONNECTOR
1445{
1446 /**
1447 * Enables or disables the given audio direction for this driver.
1448 *
1449 * When disabled, assiociated output streams consume written audio without passing them further down to the backends.
1450 * Associated input streams then return silence when read from those.
1451 *
1452 * @returns VBox status code.
1453 * @param pInterface Pointer to the interface structure containing the called function pointer.
1454 * @param enmDir Audio direction to enable or disable driver for.
1455 * @param fEnable Whether to enable or disable the specified audio direction.
1456 *
1457 * @note Be very careful when using this function, as this could
1458 * violate / run against the (global) VM settings. See @bugref{9882}.
1459 */
1460 DECLR3CALLBACKMEMBER(int, pfnEnable, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir, bool fEnable));
1461
1462 /**
1463 * Returns whether the given audio direction for this driver is enabled or not.
1464 *
1465 * @returns True if audio is enabled for the given direction, false if not.
1466 * @param pInterface Pointer to the interface structure containing the called function pointer.
1467 * @param enmDir Audio direction to retrieve enabled status for.
1468 */
1469 DECLR3CALLBACKMEMBER(bool, pfnIsEnabled, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
1470
1471 /**
1472 * Retrieves the current configuration of the host audio backend.
1473 *
1474 * @returns VBox status code.
1475 * @param pInterface Pointer to the interface structure containing the called function pointer.
1476 * @param pCfg Where to store the host audio backend configuration data.
1477 */
1478 DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOBACKENDCFG pCfg));
1479
1480 /**
1481 * Retrieves the current status of the host audio backend.
1482 *
1483 * @returns Status of the host audio backend.
1484 * @param pInterface Pointer to the interface structure containing the called function pointer.
1485 * @param enmDir Audio direction to check host audio backend for. Specify PDMAUDIODIR_DUPLEX for the overall
1486 * backend status.
1487 */
1488 DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
1489
1490 /**
1491 * Creates an audio stream.
1492 *
1493 * @returns VBox status code.
1494 * @param pInterface Pointer to the interface structure containing the called function pointer.
1495 * @param pCfgHost Stream configuration for host side.
1496 * @param pCfgGuest Stream configuration for guest side.
1497 * @param ppStream Pointer where to return the created audio stream on success.
1498 */
1499 DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfgHost,
1500 PPDMAUDIOSTREAMCFG pCfgGuest, PPDMAUDIOSTREAM *ppStream));
1501
1502 /**
1503 * Destroys an audio stream.
1504 *
1505 * @param pInterface Pointer to the interface structure containing the called function pointer.
1506 * @param pStream Pointer to audio stream.
1507 */
1508 DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1509
1510 /**
1511 * Adds a reference to the specified audio stream.
1512 *
1513 * @returns New reference count. UINT32_MAX on error.
1514 * @param pInterface Pointer to the interface structure containing the called function pointer.
1515 * @param pStream Pointer to audio stream adding the reference to.
1516 */
1517 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRetain, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1518
1519 /**
1520 * Releases a reference from the specified stream.
1521 *
1522 * @returns New reference count. UINT32_MAX on error.
1523 * @param pInterface Pointer to the interface structure containing the called function pointer.
1524 * @param pStream Pointer to audio stream releasing a reference from.
1525 */
1526 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRelease, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1527
1528 /**
1529 * Reads PCM audio data from the host (input).
1530 *
1531 * @returns VBox status code.
1532 * @param pInterface Pointer to the interface structure containing the called function pointer.
1533 * @param pStream Pointer to audio stream to write to.
1534 * @param pvBuf Where to store the read data.
1535 * @param cbBuf Number of bytes to read.
1536 * @param pcbRead Bytes of audio data read. Optional.
1537 */
1538 DECLR3CALLBACKMEMBER(int, pfnStreamRead, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1539 void *pvBuf, uint32_t cbBuf, uint32_t *pcbRead));
1540
1541 /**
1542 * Writes PCM audio data to the host (output).
1543 *
1544 * @returns VBox status code.
1545 * @param pInterface Pointer to the interface structure containing the called function pointer.
1546 * @param pStream Pointer to audio stream to read from.
1547 * @param pvBuf Audio data to be written.
1548 * @param cbBuf Number of bytes to be written.
1549 * @param pcbWritten Bytes of audio data written. Optional.
1550 */
1551 DECLR3CALLBACKMEMBER(int, pfnStreamWrite, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1552 const void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten));
1553
1554 /**
1555 * Controls a specific audio stream.
1556 *
1557 * @returns VBox status code.
1558 * @param pInterface Pointer to the interface structure containing the called function pointer.
1559 * @param pStream Pointer to audio stream.
1560 * @param enmStreamCmd The stream command to issue.
1561 */
1562 DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1563 PDMAUDIOSTREAMCMD enmStreamCmd));
1564
1565 /**
1566 * Processes stream data.
1567 *
1568 * @param pInterface Pointer to the interface structure containing the called function pointer.
1569 * @param pStream Pointer to audio stream.
1570 */
1571 DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1572
1573 /**
1574 * Returns the number of readable data (in bytes) of a specific audio input stream.
1575 *
1576 * @returns Number of readable data (in bytes).
1577 * @param pInterface Pointer to the interface structure containing the called function pointer.
1578 * @param pStream Pointer to audio stream.
1579 */
1580 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1581
1582 /**
1583 * Returns the number of writable data (in bytes) of a specific audio output stream.
1584 *
1585 * @returns Number of writable data (in bytes).
1586 * @param pInterface Pointer to the interface structure containing the called function pointer.
1587 * @param pStream Pointer to audio stream.
1588 */
1589 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1590
1591 /**
1592 * Returns the status of a specific audio stream.
1593 *
1594 * @returns Audio stream status
1595 * @param pInterface Pointer to the interface structure containing the called function pointer.
1596 * @param pStream Pointer to audio stream.
1597 */
1598 DECLR3CALLBACKMEMBER(PDMAUDIOSTREAMSTS, pfnStreamGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1599
1600 /**
1601 * Sets the audio volume of a specific audio stream.
1602 *
1603 * @returns VBox status code.
1604 * @param pInterface Pointer to the interface structure containing the called function pointer.
1605 * @param pStream Pointer to audio stream.
1606 * @param pVol Pointer to audio volume structure to set the stream's audio volume to.
1607 */
1608 DECLR3CALLBACKMEMBER(int, pfnStreamSetVolume, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOVOLUME pVol));
1609
1610 /**
1611 * Plays (transfers) available audio frames to the host backend. Only works with output streams.
1612 *
1613 * @returns VBox status code.
1614 * @param pInterface Pointer to the interface structure containing the called function pointer.
1615 * @param pStream Pointer to audio stream.
1616 * @param pcFramesPlayed Number of frames played. Optional.
1617 */
1618 DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcFramesPlayed));
1619
1620 /**
1621 * Captures (transfers) available audio frames from the host backend. Only works with input streams.
1622 *
1623 * @returns VBox status code.
1624 * @param pInterface Pointer to the interface structure containing the called function pointer.
1625 * @param pStream Pointer to audio stream.
1626 * @param pcFramesCaptured Number of frames captured. Optional.
1627 */
1628 DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1629 uint32_t *pcFramesCaptured));
1630
1631 /**
1632 * Registers (device) callbacks.
1633 * This is handy for letting the device emulation know of certain events, e.g. processing input / output data
1634 * or configuration changes.
1635 *
1636 * @returns VBox status code.
1637 * @param pInterface Pointer to the interface structure containing the called function pointer.
1638 * @param paCallbacks Pointer to array of callbacks to register.
1639 * @param cCallbacks Number of callbacks to register.
1640 */
1641 DECLR3CALLBACKMEMBER(int, pfnRegisterCallbacks, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOCBRECORD paCallbacks,
1642 size_t cCallbacks));
1643
1644} PDMIAUDIOCONNECTOR;
1645
1646/** PDMIAUDIOCONNECTOR interface ID. */
1647#define PDMIAUDIOCONNECTOR_IID "00e704ef-0078-4bb6-0005-a5fd000ded9f"
1648
1649
1650/**
1651 * PDM host audio interface.
1652 */
1653typedef struct PDMIHOSTAUDIO
1654{
1655 /**
1656 * Initializes the host backend (driver).
1657 *
1658 * @returns VBox status code.
1659 * @param pInterface Pointer to the interface structure containing the called function pointer.
1660 */
1661 DECLR3CALLBACKMEMBER(int, pfnInit, (PPDMIHOSTAUDIO pInterface));
1662
1663 /**
1664 * Shuts down the host backend (driver).
1665 *
1666 * @returns VBox status code.
1667 * @param pInterface Pointer to the interface structure containing the called function pointer.
1668 */
1669 DECLR3CALLBACKMEMBER(void, pfnShutdown, (PPDMIHOSTAUDIO pInterface));
1670
1671 /**
1672 * Returns the host backend's configuration (backend).
1673 *
1674 * @returns VBox status code.
1675 * @param pInterface Pointer to the interface structure containing the called function pointer.
1676 * @param pBackendCfg Where to store the backend audio configuration to.
1677 */
1678 DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg));
1679
1680 /**
1681 * Returns (enumerates) host audio device information.
1682 *
1683 * @returns VBox status code.
1684 * @param pInterface Pointer to the interface structure containing the called function pointer.
1685 * @param pDeviceEnum Where to return the enumerated audio devices.
1686 */
1687 DECLR3CALLBACKMEMBER(int, pfnGetDevices, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHOSTENUM pDeviceEnum));
1688
1689 /**
1690 * Returns the current status from the audio backend.
1691 *
1692 * @returns PDMAUDIOBACKENDSTS enum.
1693 * @param pInterface Pointer to the interface structure containing the called function pointer.
1694 * @param enmDir Audio direction to get status for. Pass PDMAUDIODIR_DUPLEX for overall status.
1695 */
1696 DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir));
1697
1698 /**
1699 * Sets a callback the audio backend can call. Optional.
1700 *
1701 * @returns VBox status code.
1702 * @param pInterface Pointer to the interface structure containing the called function pointer.
1703 * @param pfnCallback The callback function to use, or NULL when unregistering.
1704 */
1705 DECLR3CALLBACKMEMBER(int, pfnSetCallback, (PPDMIHOSTAUDIO pInterface, PFNPDMHOSTAUDIOCALLBACK pfnCallback));
1706
1707 /**
1708 * Creates an audio stream using the requested stream configuration.
1709 *
1710 * If a backend is not able to create this configuration, it will return its
1711 * best match in the acquired configuration structure on success.
1712 *
1713 * @returns VBox status code.
1714 * @param pInterface Pointer to the interface structure containing the called function pointer.
1715 * @param pStream Pointer to audio stream.
1716 * @param pCfgReq Pointer to requested stream configuration.
1717 * @param pCfgAcq Pointer to acquired stream configuration.
1718 * @todo r=bird: Implementation (at least Alsa) seems to make undocumented
1719 * assumptions about the content of @a pCfgAcq.
1720 */
1721 DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1722 PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq));
1723
1724 /**
1725 * Destroys an audio stream.
1726 *
1727 * @returns VBox status code.
1728 * @param pInterface Pointer to the interface structure containing the called function pointer.
1729 * @param pStream Pointer to audio stream.
1730 */
1731 DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1732
1733 /**
1734 * Controls an audio stream.
1735 *
1736 * @returns VBox status code.
1737 * @retval VERR_AUDIO_STREAM_NOT_READY if stream is not ready for required operation (yet).
1738 * @param pInterface Pointer to the interface structure containing the called function pointer.
1739 * @param pStream Pointer to audio stream.
1740 * @param enmStreamCmd The stream command to issue.
1741 */
1742 DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1743 PDMAUDIOSTREAMCMD enmStreamCmd));
1744
1745 /**
1746 * Returns the amount which is readable from the audio (input) stream.
1747 *
1748 * @returns For non-raw layout streams: Number of readable bytes.
1749 * for raw layout streams : Number of readable audio frames.
1750 * @param pInterface Pointer to the interface structure containing the called function pointer.
1751 * @param pStream Pointer to audio stream.
1752 */
1753 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1754
1755 /**
1756 * Returns the amount which is writable to the audio (output) stream.
1757 *
1758 * @returns For non-raw layout streams: Number of writable bytes.
1759 * for raw layout streams : Number of writable audio frames.
1760 * @param pInterface Pointer to the interface structure containing the called function pointer.
1761 * @param pStream Pointer to audio stream.
1762 */
1763 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1764
1765 /**
1766 * Returns the amount which is pending (in other words has not yet been processed) by/from the backend yet.
1767 * Optional.
1768 *
1769 * For input streams this is read audio data by the backend which has not been processed by the host yet.
1770 * For output streams this is written audio data to the backend which has not been processed by the backend yet.
1771 *
1772 * @returns For non-raw layout streams: Number of pending bytes.
1773 * for raw layout streams : Number of pending audio frames.
1774 * @param pInterface Pointer to the interface structure containing the called function pointer.
1775 * @param pStream Pointer to audio stream.
1776 */
1777 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetPending, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1778
1779 /**
1780 * Returns the current status of the given backend stream.
1781 *
1782 * @returns PDMAUDIOSTREAMSTS
1783 * @param pInterface Pointer to the interface structure containing the called function pointer.
1784 * @param pStream Pointer to audio stream.
1785 */
1786 DECLR3CALLBACKMEMBER(PDMAUDIOSTREAMSTS, pfnStreamGetStatus, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1787
1788 /**
1789 * Gives the host backend the chance to do some (necessary) iteration work.
1790 *
1791 * @returns VBox status code.
1792 * @param pInterface Pointer to the interface structure containing the called function pointer.
1793 * @param pStream Pointer to audio stream.
1794 */
1795 DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1796
1797 /**
1798 * Signals the backend that the host wants to begin playing for this iteration. Optional.
1799 *
1800 * @param pInterface Pointer to the interface structure containing the called function pointer.
1801 * @param pStream Pointer to audio stream.
1802 */
1803 DECLR3CALLBACKMEMBER(void, pfnStreamPlayBegin, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1804
1805 /**
1806 * Plays (writes to) an audio (output) stream.
1807 *
1808 * @returns VBox status code.
1809 * @param pInterface Pointer to the interface structure containing the called function pointer.
1810 * @param pStream Pointer to audio stream.
1811 * @param pvBuf Pointer to audio data buffer to play.
1812 * @param uBufSize The audio data buffer size (see note below for unit).
1813 * @param puWritten Number of unit written.
1814 * @note The @a uBufSize and @a puWritten values are in bytes for non-raw
1815 * layout streams and in frames for raw layout ones.
1816 */
1817 DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1818 const void *pvBuf, uint32_t uBufSize, uint32_t *puWritten));
1819
1820 /**
1821 * Signals the backend that the host finished playing for this iteration. Optional.
1822 *
1823 * @param pInterface Pointer to the interface structure containing the called function pointer.
1824 * @param pStream Pointer to audio stream.
1825 */
1826 DECLR3CALLBACKMEMBER(void, pfnStreamPlayEnd, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1827
1828 /**
1829 * Signals the backend that the host wants to begin capturing for this iteration. Optional.
1830 *
1831 * @param pInterface Pointer to the interface structure containing the called function pointer.
1832 * @param pStream Pointer to audio stream.
1833 */
1834 DECLR3CALLBACKMEMBER(void, pfnStreamCaptureBegin, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1835
1836 /**
1837 * Captures (reads from) an audio (input) stream.
1838 *
1839 * @returns VBox status code.
1840 * @param pInterface Pointer to the interface structure containing the called function pointer.
1841 * @param pStream Pointer to audio stream.
1842 * @param pvBuf Buffer where to store read audio data.
1843 * @param uBufSize Size of the audio data buffer (see note below for unit).
1844 * @param puRead Returns number of units read.
1845 * @note The @a uBufSize and @a puRead values are in bytes for non-raw
1846 * layout streams and in frames for raw layout ones.
1847 */
1848 DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1849 void *pvBuf, uint32_t uBufSize, uint32_t *puRead));
1850
1851 /**
1852 * Signals the backend that the host finished capturing for this iteration. Optional.
1853 *
1854 * @param pInterface Pointer to the interface structure containing the called function pointer.
1855 * @param pStream Pointer to audio stream.
1856 */
1857 DECLR3CALLBACKMEMBER(void, pfnStreamCaptureEnd, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1858
1859} PDMIHOSTAUDIO;
1860
1861/** PDMIHOSTAUDIO interface ID. */
1862#define PDMIHOSTAUDIO_IID "007847a0-0075-4964-007d-343f0010f081"
1863
1864/** @} */
1865
1866#endif /* !VBOX_INCLUDED_vmm_pdmaudioifs_h */
1867
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