VirtualBox

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

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

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