VirtualBox

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

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

Audio: We don't return IPRT status codes, but VBox status codes. duh. bugref:9890
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 74.4 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 access to the data.
573 * @todo r=bird: For plain stereo this is actually interleaves left/right. What
574 * I guess non-interleaved means, is that there are no additional
575 * information interleaved next to the interleaved stereo.
576 * https://stackoverflow.com/questions/17879933/whats-the-interleaved-audio */
577 PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED,
578 /** Interleaved access, where the data can be mixed together with data of other audio streams. */
579 PDMAUDIOSTREAMLAYOUT_INTERLEAVED,
580 /** Complex layout, which does not fit into the interleaved / non-interleaved layouts. */
581 PDMAUDIOSTREAMLAYOUT_COMPLEX,
582 /** Raw (pass through) data, with no data layout processing done.
583 *
584 * This means that this stream will operate on PDMAUDIOFRAME data
585 * directly. Don't use this if you don't have to.
586 *
587 * @deprecated Replaced by S64 (signed, 64-bit sample size). */
588 PDMAUDIOSTREAMLAYOUT_RAW,
589 /** End of valid values. */
590 PDMAUDIOSTREAMLAYOUT_END,
591 /** Hack to blow the type up to 32-bit. */
592 PDMAUDIOSTREAMLAYOUT_32BIT_HACK = 0x7fffffff
593} PDMAUDIOSTREAMLAYOUT;
594
595/**
596 * Stream channel data block.
597 */
598typedef struct PDMAUDIOSTREAMCHANNELDATA
599{
600 /** Circular buffer for the channel data. */
601 PRTCIRCBUF pCircBuf;
602 /** Amount of audio data (in bytes) acquired for reading. */
603 size_t cbAcq;
604 /** Channel data flags, PDMAUDIOSTREAMCHANNELDATA_FLAGS_XXX. */
605 uint32_t fFlags;
606} PDMAUDIOSTREAMCHANNELDATA;
607/** Pointer to audio stream channel data buffer. */
608typedef PDMAUDIOSTREAMCHANNELDATA *PPDMAUDIOSTREAMCHANNELDATA;
609
610/** @name PDMAUDIOSTREAMCHANNELDATA_FLAGS_XXX
611 * @{ */
612/** No stream channel data flags defined. */
613#define PDMAUDIOSTREAMCHANNELDATA_FLAGS_NONE UINT32_C(0)
614/** @} */
615
616/**
617 * Standard speaker channel IDs.
618 *
619 * This can cover up to 11.0 surround sound.
620 *
621 * @note Any of those channels can be marked / used as the LFE channel (played
622 * through the subwoofer).
623 */
624typedef enum PDMAUDIOSTREAMCHANNELID
625{
626 /** Invalid zero value as per usual (guards against using unintialized values). */
627 PDMAUDIOSTREAMCHANNELID_INVALID = 0,
628 /** Unknown / not set channel ID. */
629 PDMAUDIOSTREAMCHANNELID_UNKNOWN,
630 /** Front left channel. */
631 PDMAUDIOSTREAMCHANNELID_FRONT_LEFT,
632 /** Front right channel. */
633 PDMAUDIOSTREAMCHANNELID_FRONT_RIGHT,
634 /** Front center channel. */
635 PDMAUDIOSTREAMCHANNELID_FRONT_CENTER,
636 /** Low frequency effects (subwoofer) channel. */
637 PDMAUDIOSTREAMCHANNELID_LFE,
638 /** Rear left channel. */
639 PDMAUDIOSTREAMCHANNELID_REAR_LEFT,
640 /** Rear right channel. */
641 PDMAUDIOSTREAMCHANNELID_REAR_RIGHT,
642 /** Front left of center channel. */
643 PDMAUDIOSTREAMCHANNELID_FRONT_LEFT_OF_CENTER,
644 /** Front right of center channel. */
645 PDMAUDIOSTREAMCHANNELID_FRONT_RIGHT_OF_CENTER,
646 /** Rear center channel. */
647 PDMAUDIOSTREAMCHANNELID_REAR_CENTER,
648 /** Side left channel. */
649 PDMAUDIOSTREAMCHANNELID_SIDE_LEFT,
650 /** Side right channel. */
651 PDMAUDIOSTREAMCHANNELID_SIDE_RIGHT,
652 /** Left height channel. */
653 PDMAUDIOSTREAMCHANNELID_LEFT_HEIGHT,
654 /** Right height channel. */
655 PDMAUDIOSTREAMCHANNELID_RIGHT_HEIGHT,
656 /** End of valid values. */
657 PDMAUDIOSTREAMCHANNELID_END,
658 /** Hack to blow the type up to 32-bit. */
659 PDMAUDIOSTREAMCHANNELID_32BIT_HACK = 0x7fffffff
660} PDMAUDIOSTREAMCHANNELID;
661
662/**
663 * Mappings channels onto an audio stream.
664 *
665 * The mappings are either for a single (mono) or dual (stereo) channels onto an
666 * audio stream (aka stream profile). An audio stream consists of one or
667 * multiple channels (e.g. 1 for mono, 2 for stereo), depending on the
668 * configuration.
669 */
670typedef struct PDMAUDIOSTREAMMAP
671{
672 /** Array of channel IDs being handled.
673 * @note The first (zero-based) index specifies the leftmost channel. */
674 PDMAUDIOSTREAMCHANNELID aenmIDs[2];
675 /** Step size (in bytes) to the channel's next frame. */
676 uint32_t cbStep;
677 /** Frame size (in bytes) of this channel. */
678 uint32_t cbFrame;
679 /** Byte offset to the first frame in the data block. */
680 uint32_t offFirst;
681 /** Byte offset to the next frame in the data block. */
682 uint32_t offNext;
683 /** Associated data buffer. */
684 PDMAUDIOSTREAMCHANNELDATA Data;
685} PDMAUDIOSTREAMMAP;
686/** Pointer to an audio stream channel mapping. */
687typedef PDMAUDIOSTREAMMAP *PPDMAUDIOSTREAMMAP;
688
689/**
690 * Properties of audio streams for host/guest for in or out directions.
691 */
692typedef struct PDMAUDIOPCMPROPS
693{
694 /** The frame size. */
695 uint8_t cbFrame;
696 /** Shift count used with PDMAUDIOPCMPROPS_F2B and PDMAUDIOPCMPROPS_B2F.
697 * Depends on number of stream channels and the stream format being used, calc
698 * value using PDMAUDIOPCMPROPS_MAKE_SHIFT.
699 * @sa PDMAUDIOSTREAMCFG_B2F, PDMAUDIOSTREAMCFG_F2B */
700 uint8_t cShiftX;
701 /** Sample width (in bytes). */
702 RT_GCC_EXTENSION
703 uint8_t cbSampleX : 4;
704 /** Number of audio channels. */
705 RT_GCC_EXTENSION
706 uint8_t cChannelsX : 4;
707 /** Signed or unsigned sample. */
708 bool fSigned : 1;
709 /** Whether the endianness is swapped or not. */
710 bool fSwapEndian : 1;
711 /** Raw mixer frames, only applicable for signed 64-bit samples. */
712 bool fRaw : 1;
713 /** Sample frequency in Hertz (Hz). */
714 uint32_t uHz;
715} PDMAUDIOPCMPROPS;
716AssertCompileSize(PDMAUDIOPCMPROPS, 8);
717AssertCompileSizeAlignment(PDMAUDIOPCMPROPS, 8);
718/** Pointer to audio stream properties. */
719typedef PDMAUDIOPCMPROPS *PPDMAUDIOPCMPROPS;
720/** Pointer to const audio stream properties. */
721typedef PDMAUDIOPCMPROPS const *PCPDMAUDIOPCMPROPS;
722
723/** @name Macros for use with PDMAUDIOPCMPROPS
724 * @{ */
725/** Initializer for PDMAUDIOPCMPROPS. */
726#define PDMAUDIOPCMPROPS_INITIALIZER(a_cbSample, a_fSigned, a_cChannels, a_uHz, a_fSwapEndian) \
727 { (a_cbSample) * (a_cChannels), PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS(a_cbSample, a_cChannels), a_cbSample, a_cChannels, \
728 a_fSigned, a_fSwapEndian, false /*fRaw*/, a_uHz }
729/** Calculates the cShift value of given sample bits and audio channels.
730 * @note Does only support mono/stereo channels for now, for non-stereo/mono we
731 * returns a special value which the two conversion functions detect
732 * and make them fall back on cbSample * cChannels. */
733#define PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS(cbSample, cChannels) \
734 ( RT_IS_POWER_OF_TWO((unsigned)((cChannels) * (cbSample))) \
735 ? (uint8_t)(ASMBitFirstSetU32((unsigned)((cChannels) * (cbSample))) - 1) : (uint8_t)UINT8_MAX )
736/** Calculates the cShift value of a PDMAUDIOPCMPROPS structure. */
737#define PDMAUDIOPCMPROPS_MAKE_SHIFT(pProps) \
738 PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS((pProps)->cbSampleX, (pProps)->cChannelsX)
739/** Converts (audio) frames to bytes.
740 * @note Requires properly initialized properties, i.e. cbFrames correctly calculated
741 * and cShift set using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
742#define PDMAUDIOPCMPROPS_F2B(pProps, cFrames) \
743 ( (pProps)->cShiftX != UINT8_MAX ? (cFrames) << (pProps)->cShiftX : (cFrames) * (pProps)->cbFrame )
744/** Converts bytes to (audio) frames.
745 * @note Requires properly initialized properties, i.e. cbFrames correctly calculated
746 * and cShift set using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
747#define PDMAUDIOPCMPROPS_B2F(pProps, cb) \
748 ( (pProps)->cShiftX != UINT8_MAX ? (cb) >> (pProps)->cShiftX : (cb) / (pProps)->cbFrame )
749/** @} */
750
751/**
752 * An audio stream configuration.
753 */
754typedef struct PDMAUDIOSTREAMCFG
755{
756 /** Direction of the stream. */
757 PDMAUDIODIR enmDir;
758 /** Destination / source indicator, depending on enmDir. */
759 PDMAUDIODSTSRCUNION u;
760 /** The stream's PCM properties. */
761 PDMAUDIOPCMPROPS Props;
762 /** The stream's audio data layout.
763 * This indicates how the audio data buffers to/from the backend is being layouted.
764 *
765 * Currently, the following layouts are supported by the audio connector:
766 *
767 * PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED:
768 * One stream at once. The consecutive audio data is exactly in the format and frame width
769 * like defined in the PCM properties. This is the default.
770 *
771 * PDMAUDIOSTREAMLAYOUT_RAW:
772 * Can be one or many streams at once, depending on the stream's mixing buffer setup.
773 * The audio data will get handled as PDMAUDIOFRAME frames without any modification done.
774 *
775 * @todo r=bird: See PDMAUDIOSTREAMLAYOUT comments. */
776 PDMAUDIOSTREAMLAYOUT enmLayout;
777 /** Device emulation-specific data needed for the audio connector. */
778 struct
779 {
780 /** Scheduling hint set by the device emulation about when this stream is being served on average (in ms).
781 * Can be 0 if not hint given or some other mechanism (e.g. callbacks) is being used. */
782 uint32_t cMsSchedulingHint;
783 } Device;
784 /**
785 * Backend-specific data for the stream.
786 * On input (requested configuration) those values are set by the audio connector to let the backend know what we expect.
787 * On output (acquired configuration) those values reflect the values set and used by the backend.
788 * Set by the backend on return. Not all backends support all values / features.
789 */
790 struct
791 {
792 /** Period size of the stream (in audio frames).
793 * This value reflects the number of audio frames in between each hardware interrupt on the
794 * backend (host) side. 0 if not set / available by the backend. */
795 uint32_t cFramesPeriod;
796 /** (Ring) buffer size (in audio frames). Often is a multiple of cFramesPeriod.
797 * 0 if not set / available by the backend. */
798 uint32_t cFramesBufferSize;
799 /** Pre-buffering size (in audio frames). Frames needed in buffer before the stream becomes active (pre buffering).
800 * The bigger this value is, the more latency for the stream will occur.
801 * 0 if not set / available by the backend. UINT32_MAX if not defined (yet). */
802 uint32_t cFramesPreBuffering;
803 } Backend;
804 uint32_t u32Padding;
805 /** Friendly name of the stream. */
806 char szName[64];
807} PDMAUDIOSTREAMCFG;
808AssertCompileSizeAlignment(PDMAUDIOSTREAMCFG, 8);
809/** Pointer to audio stream configuration keeper. */
810typedef PDMAUDIOSTREAMCFG *PPDMAUDIOSTREAMCFG;
811/** Pointer to a const audio stream configuration keeper. */
812typedef PDMAUDIOSTREAMCFG const *PCPDMAUDIOSTREAMCFG;
813
814/** Converts (audio) frames to bytes. */
815#define PDMAUDIOSTREAMCFG_F2B(pCfg, frames) PDMAUDIOPCMPROPS_F2B(&(pCfg)->Props, (frames))
816/** Converts bytes to (audio) frames. */
817#define PDMAUDIOSTREAMCFG_B2F(pCfg, cb) PDMAUDIOPCMPROPS_B2F(&(pCfg)->Props, (cb))
818
819/**
820 * Audio mixer controls.
821 */
822typedef enum PDMAUDIOMIXERCTL
823{
824 /** Invalid zero value as per usual (guards against using unintialized values). */
825 PDMAUDIOMIXERCTL_INVALID = 0,
826 /** Unknown mixer control. */
827 PDMAUDIOMIXERCTL_UNKNOWN,
828 /** Master volume. */
829 PDMAUDIOMIXERCTL_VOLUME_MASTER,
830 /** Front. */
831 PDMAUDIOMIXERCTL_FRONT,
832 /** Center / LFE (Subwoofer). */
833 PDMAUDIOMIXERCTL_CENTER_LFE,
834 /** Rear. */
835 PDMAUDIOMIXERCTL_REAR,
836 /** Line-In. */
837 PDMAUDIOMIXERCTL_LINE_IN,
838 /** Microphone-In. */
839 PDMAUDIOMIXERCTL_MIC_IN,
840 /** End of valid values. */
841 PDMAUDIOMIXERCTL_END,
842 /** Hack to blow the type up to 32-bit. */
843 PDMAUDIOMIXERCTL_32BIT_HACK = 0x7fffffff
844} PDMAUDIOMIXERCTL;
845
846/**
847 * Audio stream commands.
848 *
849 * Used in the audio connector as well as in the actual host backends.
850 */
851typedef enum PDMAUDIOSTREAMCMD
852{
853 /** Invalid zero value as per usual (guards against using unintialized values). */
854 PDMAUDIOSTREAMCMD_INVALID = 0,
855 /** Unknown command, do not use. */
856 PDMAUDIOSTREAMCMD_UNKNOWN,
857 /** Enables the stream. */
858 PDMAUDIOSTREAMCMD_ENABLE,
859 /** Disables the stream.
860 * For output streams this stops the stream after playing the remaining (buffered) audio data.
861 * For input streams this will deliver the remaining (captured) audio data and not accepting
862 * any new audio input data afterwards. */
863 PDMAUDIOSTREAMCMD_DISABLE,
864 /** Pauses the stream. */
865 PDMAUDIOSTREAMCMD_PAUSE,
866 /** Resumes the stream. */
867 PDMAUDIOSTREAMCMD_RESUME,
868 /** Tells the stream to drain itself.
869 * For output streams this plays all remaining (buffered) audio frames,
870 * for input streams this permits receiving any new audio frames.
871 * No supported by all backends. */
872 PDMAUDIOSTREAMCMD_DRAIN,
873 /** Tells the stream to drop all (buffered) audio data immediately.
874 * No supported by all backends. */
875 PDMAUDIOSTREAMCMD_DROP,
876 /** End of valid values. */
877 PDMAUDIOSTREAMCMD_END,
878 /** Hack to blow the type up to 32-bit. */
879 PDMAUDIOSTREAMCMD_32BIT_HACK = 0x7fffffff
880} PDMAUDIOSTREAMCMD;
881
882/**
883 * Audio volume parameters.
884 */
885typedef struct PDMAUDIOVOLUME
886{
887 /** Set to @c true if this stream is muted, @c false if not. */
888 bool fMuted;
889 /** Left channel volume.
890 * Range is from [0 ... 255], whereas 0 specifies
891 * the most silent and 255 the loudest value. */
892 uint8_t uLeft;
893 /** Right channel volume.
894 * Range is from [0 ... 255], whereas 0 specifies
895 * the most silent and 255 the loudest value. */
896 uint8_t uRight;
897} PDMAUDIOVOLUME;
898/** Pointer to audio volume settings. */
899typedef PDMAUDIOVOLUME *PPDMAUDIOVOLUME;
900
901/** Defines the minimum volume allowed. */
902#define PDMAUDIO_VOLUME_MIN (0)
903/** Defines the maximum volume allowed. */
904#define PDMAUDIO_VOLUME_MAX (255)
905
906/**
907 * Rate processing information of a source & destination audio stream.
908 *
909 * This is needed because both streams can differ regarding their rates and
910 * therefore need to be treated accordingly.
911 */
912typedef struct PDMAUDIOSTREAMRATE
913{
914 /** Current (absolute) offset in the output (destination) stream.
915 * @todo r=bird: Please reveal which unit these members are given in. */
916 uint64_t offDst;
917 /** Increment for moving offDst for the destination stream.
918 * This is needed because the source <-> destination rate might be different. */
919 uint64_t uDstInc;
920 /** Current (absolute) offset in the input stream. */
921 uint32_t offSrc;
922 /** Explicit alignment padding. */
923 uint32_t u32AlignmentPadding;
924 /** Last processed frame of the input stream.
925 * Needed for interpolation. */
926 PDMAUDIOFRAME SrcFrameLast;
927} PDMAUDIOSTREAMRATE;
928/** Pointer to rate processing information of a stream. */
929typedef PDMAUDIOSTREAMRATE *PPDMAUDIOSTREAMRATE;
930
931/**
932 * Mixing buffer volume parameters.
933 *
934 * The volume values are in fixed point style and must be converted to/from
935 * before using with e.g. PDMAUDIOVOLUME.
936 */
937typedef struct PDMAUDMIXBUFVOL
938{
939 /** Set to @c true if this stream is muted, @c false if not. */
940 bool fMuted;
941 /** Left volume to apply during conversion.
942 * Pass 0 to convert the original values. May not apply to all conversion functions. */
943 uint32_t uLeft;
944 /** Right volume to apply during conversion.
945 * Pass 0 to convert the original values. May not apply to all conversion functions. */
946 uint32_t uRight;
947} PDMAUDMIXBUFVOL;
948/** Pointer to mixing buffer volument parameters. */
949typedef PDMAUDMIXBUFVOL *PPDMAUDMIXBUFVOL;
950
951/*
952 * Frame conversion parameters for the audioMixBufConvFromXXX / audioMixBufConvToXXX functions.
953 */
954typedef struct PDMAUDMIXBUFCONVOPTS
955{
956 /** Number of audio frames to convert. */
957 uint32_t cFrames;
958 union
959 {
960 struct
961 {
962 /** Volume to use for conversion. */
963 PDMAUDMIXBUFVOL Volume;
964 } From;
965 } RT_UNION_NM(u);
966} PDMAUDMIXBUFCONVOPTS;
967/** Pointer to conversion parameters for the audio mixer. */
968typedef PDMAUDMIXBUFCONVOPTS *PPDMAUDMIXBUFCONVOPTS;
969/** Pointer to const conversion parameters for the audio mixer. */
970typedef PDMAUDMIXBUFCONVOPTS const *PCPDMAUDMIXBUFCONVOPTS;
971
972/**
973 * @note All internal handling is done in audio frames, not in bytes!
974 * @todo r=bird: What does this node actually apply to?
975 */
976typedef uint32_t PDMAUDIOMIXBUFFMT;
977typedef PDMAUDIOMIXBUFFMT *PPDMAUDIOMIXBUFFMT;
978
979/**
980 * Convertion-from function used by the PDM audio buffer mixer.
981 *
982 * @returns Number of audio frames returned.
983 * @param paDst Where to return the converted frames.
984 * @param pvSrc The source frame bytes.
985 * @param cbSrc Number of bytes to convert.
986 * @param pOpts Conversion options.
987 * @todo r=bird: The @a paDst size is presumable given in @a pOpts->cFrames?
988 */
989typedef DECLCALLBACKTYPE(uint32_t, FNPDMAUDIOMIXBUFCONVFROM,(PPDMAUDIOFRAME paDst, const void *pvSrc, uint32_t cbSrc,
990 PCPDMAUDMIXBUFCONVOPTS pOpts));
991/** Pointer to a convertion-from function used by the PDM audio buffer mixer. */
992typedef FNPDMAUDIOMIXBUFCONVFROM *PFNPDMAUDIOMIXBUFCONVFROM;
993
994/**
995 * Convertion-to function used by the PDM audio buffer mixer.
996 *
997 * @param pvDst Output buffer.
998 * @param paSrc The input frames.
999 * @param pOpts Conversion options.
1000 * @todo r=bird: The @a paSrc size is presumable given in @a pOpts->cFrames and
1001 * this implicitly gives the pvDst size too, right?
1002 */
1003typedef DECLCALLBACKTYPE(void, FNPDMAUDIOMIXBUFCONVTO,(void *pvDst, PCPDMAUDIOFRAME paSrc, PCPDMAUDMIXBUFCONVOPTS pOpts));
1004/** Pointer to a convertion-to function used by the PDM audio buffer mixer. */
1005typedef FNPDMAUDIOMIXBUFCONVTO *PFNPDMAUDIOMIXBUFCONVTO;
1006
1007/** Pointer to audio mixing buffer. */
1008typedef struct PDMAUDIOMIXBUF *PPDMAUDIOMIXBUF;
1009
1010/**
1011 * Audio mixing buffer.
1012 */
1013typedef struct PDMAUDIOMIXBUF
1014{
1015 /** Magic value (PDMAUDIOMIXBUF_MAGIC). */
1016 uint32_t uMagic;
1017 uint8_t abPadding[4];
1018 /* ???Undocumented??? */
1019 RTLISTNODE Node;
1020 /** Name of the buffer. */
1021 char *pszName;
1022 /** Frame buffer. */
1023 PPDMAUDIOFRAME pFrames;
1024 /** Size of the frame buffer (in audio frames). */
1025 uint32_t cFrames;
1026 /** The current read position (in frames). */
1027 uint32_t offRead;
1028 /** The current write position (in frames). */
1029 uint32_t offWrite;
1030 /** Total frames already mixed down to the parent buffer (if any).
1031 *
1032 * Always starting at the parent's offRead position.
1033 * @note Count always is specified in parent frames, as the sample count can
1034 * differ between parent and child. */
1035 uint32_t cMixed;
1036 /** How much audio frames are currently being used
1037 * in this buffer.
1038 * Note: This also is known as the distance in ring buffer terms. */
1039 uint32_t cUsed;
1040 /** Number of children mix buffers kept in lstChildren. */
1041 uint32_t cChildren;
1042 /** List of children mix buffers to keep in sync with (if being a parent buffer). */
1043 RTLISTANCHOR lstChildren;
1044 /** Pointer to parent buffer (if any). */
1045 PPDMAUDIOMIXBUF pParent;
1046 /** Intermediate structure for buffer conversion tasks. */
1047 PPDMAUDIOSTREAMRATE pRate;
1048 /** Internal representation of current volume used for mixing. */
1049 PDMAUDMIXBUFVOL Volume;
1050 /** This buffer's audio format.
1051 * @todo r=bird: This seems to be a value created by AUDMIXBUF_AUDIO_FMT_MAKE(),
1052 * which is not define here. Does this structure really belong here at
1053 * all? */
1054 PDMAUDIOMIXBUFFMT uAudioFmt;
1055 /** Audio input properties.
1056 * @note There is only one set of audio properties here because we have one
1057 * mixer buffer for the guest side and a separate one for the host side.
1058 * @todo r=bird: Why exactly do we need to use separate mixer buffers?
1059 * Couldn't we just have different conversion fuctions and save the
1060 * extra copying? */
1061 PDMAUDIOPCMPROPS Props;
1062 /** Standard conversion-to function for set uAudioFmt. */
1063 PFNPDMAUDIOMIXBUFCONVTO pfnConvTo;
1064 /** Standard conversion-from function for set uAudioFmt. */
1065 PFNPDMAUDIOMIXBUFCONVFROM pfnConvFrom;
1066
1067 /** Ratio of the associated parent stream's frequency by this stream's
1068 * frequency (1<<32), represented as a signed 64 bit integer.
1069 *
1070 * For example, if the parent stream has a frequency of 44 khZ, and this
1071 * stream has a frequency of 11 kHz, the ration then would be
1072 * (44/11 * (1 << 32)).
1073 *
1074 * Currently this does not get changed once assigned. */
1075 int64_t iFreqRatio;
1076} PDMAUDIOMIXBUF;
1077
1078/** Magic value for PDMAUDIOMIXBUF. */
1079#define PDMAUDIOMIXBUF_MAGIC PDM_VERSION_MAKE(0xa0d2, 1, 0)
1080
1081/** @name PDMAUDIOFILE_FLAGS_XXX
1082 * @{ */
1083/** No flags defined. */
1084#define PDMAUDIOFILE_FLAGS_NONE UINT32_C(0)
1085/** Keep the audio file even if it contains no audio data. */
1086#define PDMAUDIOFILE_FLAGS_KEEP_IF_EMPTY RT_BIT_32(0)
1087/** Audio file flag validation mask. */
1088#define PDMAUDIOFILE_FLAGS_VALID_MASK UINT32_C(0x1)
1089/** @} */
1090
1091/** Audio file default open flags.
1092 * @todo r=bird: What is the exact purpose of this? */
1093#define PDMAUDIOFILE_DEFAULT_OPEN_FLAGS (RTFILE_O_OPEN_CREATE | RTFILE_O_APPEND | RTFILE_O_WRITE | RTFILE_O_DENY_WRITE)
1094
1095/**
1096 * Audio file types.
1097 * @todo r=bird: This does not really belong here.
1098 */
1099typedef enum PDMAUDIOFILETYPE
1100{
1101 /** The customary invalid zero value. */
1102 PDMAUDIOFILETYPE_INVALID = 0,
1103 /** Unknown type, do not use. */
1104 PDMAUDIOFILETYPE_UNKNOWN,
1105 /** Raw (PCM) file. */
1106 PDMAUDIOFILETYPE_RAW,
1107 /** Wave (.WAV) file. */
1108 PDMAUDIOFILETYPE_WAV,
1109 /** Hack to blow the type up to 32-bit. */
1110 PDMAUDIOFILETYPE_32BIT_HACK = 0x7fffffff
1111} PDMAUDIOFILETYPE;
1112
1113/** @name PDMAUDIOFILENAME_FLAGS_XXX
1114 * @{ */
1115/** No flags defined. */
1116#define PDMAUDIOFILENAME_FLAGS_NONE UINT32_C(0)
1117/** Adds an ISO timestamp to the file name. */
1118#define PDMAUDIOFILENAME_FLAGS_TS RT_BIT(0)
1119/** @} */
1120
1121/**
1122 * Audio file handle.
1123 */
1124typedef struct PDMAUDIOFILE
1125{
1126 /** Type of the audio file. */
1127 PDMAUDIOFILETYPE enmType;
1128 /** Audio file flags, PDMAUDIOFILE_FLAGS_XXX. */
1129 uint32_t fFlags;
1130 /** Actual file handle. */
1131 RTFILE hFile;
1132 /** Data needed for the specific audio file type implemented.
1133 * Optional, can be NULL. */
1134 void *pvData;
1135 /** Data size (in bytes). */
1136 size_t cbData;
1137 /** File name and path. */
1138 char szName[RTPATH_MAX];
1139} PDMAUDIOFILE;
1140/** Pointer to an audio file handle. */
1141typedef PDMAUDIOFILE *PPDMAUDIOFILE;
1142
1143/** @name PDMAUDIOSTREAMSTS_FLAGS_XXX
1144 * @{ */
1145/** No flags being set. */
1146#define PDMAUDIOSTREAMSTS_FLAGS_NONE UINT32_C(0)
1147/** Whether this stream has been initialized by the
1148 * backend or not. */
1149#define PDMAUDIOSTREAMSTS_FLAGS_INITIALIZED RT_BIT_32(0)
1150/** Whether this stream is enabled or disabled. */
1151#define PDMAUDIOSTREAMSTS_FLAGS_ENABLED RT_BIT_32(1)
1152/** Whether this stream has been paused or not. This also implies
1153 * that this is an enabled stream! */
1154#define PDMAUDIOSTREAMSTS_FLAGS_PAUSED RT_BIT_32(2)
1155/** Whether this stream was marked as being disabled
1156 * but there are still associated guest output streams
1157 * which rely on its data. */
1158#define PDMAUDIOSTREAMSTS_FLAGS_PENDING_DISABLE RT_BIT_32(3)
1159/** Whether this stream is in re-initialization phase.
1160 * All other bits remain untouched to be able to restore
1161 * the stream's state after the re-initialization bas been
1162 * finished. */
1163#define PDMAUDIOSTREAMSTS_FLAGS_PENDING_REINIT RT_BIT_32(4)
1164/** Validation mask. */
1165#define PDMAUDIOSTREAMSTS_VALID_MASK UINT32_C(0x0000001F)
1166/** Stream status flag, PDMAUDIOSTREAMSTS_FLAGS_XXX. */
1167typedef uint32_t PDMAUDIOSTREAMSTS;
1168/** @} */
1169
1170/**
1171 * Backend status.
1172 */
1173typedef enum PDMAUDIOBACKENDSTS
1174{
1175 /** Unknown/invalid status. */
1176 PDMAUDIOBACKENDSTS_UNKNOWN = 0,
1177 /** No backend attached. */
1178 PDMAUDIOBACKENDSTS_NOT_ATTACHED,
1179 /** The backend is in its initialization phase.
1180 * Not all backends support this status. */
1181 PDMAUDIOBACKENDSTS_INITIALIZING,
1182 /** The backend has stopped its operation. */
1183 PDMAUDIOBACKENDSTS_STOPPED,
1184 /** The backend is up and running. */
1185 PDMAUDIOBACKENDSTS_RUNNING,
1186 /** The backend ran into an error and is unable to recover.
1187 * A manual re-initialization might help. */
1188 PDMAUDIOBACKENDSTS_ERROR,
1189 /** Hack to blow the type up to 32-bit. */
1190 PDMAUDIOBACKENDSTS_32BIT_HACK = 0x7fffffff
1191} PDMAUDIOBACKENDSTS;
1192
1193/**
1194 * The specifics for an audio input stream.
1195 *
1196 * Do not use directly, use PDMAUDIOSTREAM instead.
1197 */
1198typedef struct PDMAUDIOSTREAMIN
1199{
1200 struct
1201 {
1202 /** File for writing stream reads. */
1203 PPDMAUDIOFILE pFileStreamRead;
1204 /** File for writing non-interleaved captures. */
1205 PPDMAUDIOFILE pFileCaptureNonInterleaved;
1206 } Dbg;
1207 struct
1208 {
1209 STAMCOUNTER TotalFramesCaptured;
1210 STAMCOUNTER AvgFramesCaptured;
1211 STAMCOUNTER TotalTimesCaptured;
1212 STAMCOUNTER TotalFramesRead;
1213 STAMCOUNTER AvgFramesRead;
1214 STAMCOUNTER TotalTimesRead;
1215 } Stats;
1216} PDMAUDIOSTREAMIN;
1217/** Pointer to the specifics for an audio input stream. */
1218typedef PDMAUDIOSTREAMIN *PPDMAUDIOSTREAMIN;
1219
1220/**
1221 * The specifics for an audio output stream.
1222 *
1223 * Do not use directly, use PDMAUDIOSTREAM instead.
1224 */
1225typedef struct PDMAUDIOSTREAMOUT
1226{
1227 struct
1228 {
1229 /** File for writing stream writes. */
1230 PPDMAUDIOFILE pFileStreamWrite;
1231 /** File for writing stream playback. */
1232 PPDMAUDIOFILE pFilePlayNonInterleaved;
1233 } Dbg;
1234 struct
1235 {
1236 STAMCOUNTER TotalFramesPlayed;
1237 STAMCOUNTER AvgFramesPlayed;
1238 STAMCOUNTER TotalTimesPlayed;
1239 STAMCOUNTER TotalFramesWritten;
1240 STAMCOUNTER AvgFramesWritten;
1241 STAMCOUNTER TotalTimesWritten;
1242 } Stats;
1243 /** Hack alert: Max writable amount reported by the backend.
1244 * This is used to aid buffer underrun detection in DrvAudio while playing.
1245 * Ideally, the backend should have a method for querying number of buffered
1246 * bytes instead. However this will do for now. */
1247 uint32_t cbBackendMaxWritable;
1248} PDMAUDIOSTREAMOUT;
1249/** Pointer to the specifics for an audio output stream. */
1250typedef PDMAUDIOSTREAMOUT *PPDMAUDIOSTREAMOUT;
1251
1252/** Pointer to an audio stream. */
1253typedef struct PDMAUDIOSTREAM *PPDMAUDIOSTREAM;
1254
1255/**
1256 * Audio stream context.
1257 * Needed for separating data from the guest and host side (per stream).
1258 */
1259typedef struct PDMAUDIOSTREAMCTX
1260{
1261 /** The stream's audio configuration. */
1262 PDMAUDIOSTREAMCFG Cfg;
1263 /** This stream's mixing buffer. */
1264 PDMAUDIOMIXBUF MixBuf;
1265} PDMAUDIOSTREAMCTX;
1266
1267/** Pointer to an audio stream context. */
1268typedef struct PDMAUDIOSTREAM *PPDMAUDIOSTREAMCTX;
1269
1270/** @name PDMAUDIOSTREAM_WARN_FLAGS_XXX
1271 * @{ */
1272/** No stream warning flags set. */
1273#define PDMAUDIOSTREAM_WARN_FLAGS_NONE 0
1274/** Warned about a disabled stream. */
1275#define PDMAUDIOSTREAM_WARN_FLAGS_DISABLED RT_BIT(0)
1276/** @} */
1277
1278/**
1279 * An input or output audio stream.
1280 */
1281typedef struct PDMAUDIOSTREAM
1282{
1283 /** Magic value (PDMAUDIOSTREAM_MAGIC). */
1284 uint32_t uMagic;
1285 /** Size (in bytes) of the backend-specific stream data. */
1286 uint32_t cbBackend;
1287 /** List entry (some DrvAudio internal list). */
1288 RTLISTNODE ListEntry;
1289 /** Number of references to this stream.
1290 * Only can be destroyed when the reference count reaches 0. */
1291 uint32_t cRefs;
1292 /** Number of (re-)tries while re-initializing the stream. */
1293 uint32_t cTriesReInit;
1294 /** Warnings shown already in the release log.
1295 * See PDMAUDIOSTREAM_WARN_FLAGS_XXX. */
1296 uint32_t fWarningsShown;
1297 /** Stream status flag. */
1298 PDMAUDIOSTREAMSTS fStatus;
1299 /** Audio direction of this stream. */
1300 PDMAUDIODIR enmDir;
1301 /** For output streams this indicates whether the stream has reached
1302 * its playback threshold, e.g. is playing audio.
1303 * For input streams this indicates whether the stream has enough input
1304 * data to actually start reading audio. */
1305 bool fThresholdReached;
1306 bool afPadding[3];
1307 /** The guest side of the stream. */
1308 PDMAUDIOSTREAMCTX Guest;
1309 /** The host side of the stream. */
1310 PDMAUDIOSTREAMCTX Host;
1311 /** Timestamp (in ns) since last trying to re-initialize.
1312 * Might be 0 if has not been tried yet. */
1313 uint64_t tsLastReInitNs;
1314 /** Timestamp (in ns) since last iteration. */
1315 uint64_t tsLastIteratedNs;
1316 /** Timestamp (in ns) since last playback / capture. */
1317 uint64_t tsLastPlayedCapturedNs;
1318 /** Timestamp (in ns) since last read (input streams) or
1319 * write (output streams). */
1320 uint64_t tsLastReadWrittenNs;
1321 /** Data to backend-specific stream data.
1322 * This data block will be casted by the backend to access its backend-dependent data.
1323 *
1324 * That way the backends do not have access to the audio connector's data. */
1325 void *pvBackend;
1326
1327 /** Name of this stream. */
1328 char szName[64];
1329
1330 /** Union for input/output specifics depending on enmDir. */
1331 union
1332 {
1333 PDMAUDIOSTREAMIN In;
1334 PDMAUDIOSTREAMOUT Out;
1335 } RT_UNION_NM(u);
1336} PDMAUDIOSTREAM;
1337
1338/** Magic value for PDMAUDIOSTREAM. */
1339#define PDMAUDIOSTREAM_MAGIC PDM_VERSION_MAKE(0xa0d3, 1, 1)
1340
1341
1342/**
1343 * Audio callback source.
1344 */
1345typedef enum PDMAUDIOCBSOURCE
1346{
1347 /** Invalid, do not use. */
1348 PDMAUDIOCBSOURCE_INVALID = 0,
1349 /** Device emulation. */
1350 PDMAUDIOCBSOURCE_DEVICE,
1351 /** Audio connector interface. */
1352 PDMAUDIOCBSOURCE_CONNECTOR,
1353 /** Backend (lower). */
1354 PDMAUDIOCBSOURCE_BACKEND,
1355 /** Hack to blow the type up to 32-bit. */
1356 PDMAUDIOCBSOURCE_32BIT_HACK = 0x7fffffff
1357} PDMAUDIOCBSOURCE;
1358
1359/**
1360 * Audio device callback types.
1361 * Those callbacks are being sent from the audio connector -> device emulation.
1362 */
1363typedef enum PDMAUDIODEVICECBTYPE
1364{
1365 /** Invalid, do not use. */
1366 PDMAUDIODEVICECBTYPE_INVALID = 0,
1367 /** Data is availabe as input for passing to the device emulation. */
1368 PDMAUDIODEVICECBTYPE_DATA_INPUT,
1369 /** Free data for the device emulation to write to the backend. */
1370 PDMAUDIODEVICECBTYPE_DATA_OUTPUT,
1371 /** Hack to blow the type up to 32-bit. */
1372 PDMAUDIODEVICECBTYPE_32BIT_HACK = 0x7fffffff
1373} PDMAUDIODEVICECBTYPE;
1374
1375#if 0 /** @todo r=bird: Who needs this exactly? Fix the style or remove */
1376/**
1377 * Device callback data for audio input.
1378 */
1379typedef struct PDMAUDIODEVICECBDATA_DATA_INPUT
1380{
1381 /** Input: How many bytes are availabe as input for passing
1382 * to the device emulation. */
1383 uint32_t cbInAvail;
1384 /** Output: How many bytes have been read. */
1385 uint32_t cbOutRead;
1386} PDMAUDIODEVICECBDATA_DATA_INPUT;
1387typedef PDMAUDIODEVICECBDATA_DATA_INPUT *PPDMAUDIODEVICECBDATA_DATA_INPUT;
1388
1389/**
1390 * Device callback data for audio output.
1391 */
1392typedef struct PDMAUDIODEVICECBDATA_DATA_OUTPUT
1393{
1394 /** Input: How many bytes are free for the device emulation to write. */
1395 uint32_t cbInFree;
1396 /** Output: How many bytes were written by the device emulation. */
1397 uint32_t cbOutWritten;
1398} PDMAUDIODEVICECBDATA_DATA_OUTPUT, *PPDMAUDIODEVICECBDATA_DATA_OUTPUT;
1399#endif
1400
1401/**
1402 * Audio backend callback types.
1403 * Those callbacks are being sent from the backend -> audio connector.
1404 */
1405typedef enum PDMAUDIOBACKENDCBTYPE
1406{
1407 /** Invalid, do not use. */
1408 PDMAUDIOBACKENDCBTYPE_INVALID = 0,
1409 /** The backend's status has changed. */
1410 PDMAUDIOBACKENDCBTYPE_STATUS,
1411 /** One or more host audio devices have changed. */
1412 PDMAUDIOBACKENDCBTYPE_DEVICES_CHANGED,
1413 /** Hack to blow the type up to 32-bit. */
1414 PDMAUDIOBACKENDCBTYPE_32BIT_HACK = 0x7fffffff
1415} PDMAUDIOBACKENDCBTYPE;
1416
1417/** Pointer to a host audio interface. */
1418typedef struct PDMIHOSTAUDIO *PPDMIHOSTAUDIO;
1419
1420/**
1421 * Host audio callback function.
1422 *
1423 * This function will be called from a backend to communicate with the host audio interface.
1424 *
1425 * @returns VBox status code.
1426 * @param pDrvIns Pointer to driver instance which called us.
1427 * @param enmType Callback type.
1428 * @param pvUser User argument.
1429 * @param cbUser Size (in bytes) of user argument.
1430 */
1431typedef DECLCALLBACKTYPE(int, FNPDMHOSTAUDIOCALLBACK,(PPDMDRVINS pDrvIns, PDMAUDIOBACKENDCBTYPE enmType,
1432 void *pvUser, size_t cbUser));
1433/** Pointer to a FNPDMHOSTAUDIOCALLBACK(). */
1434typedef FNPDMHOSTAUDIOCALLBACK *PFNPDMHOSTAUDIOCALLBACK;
1435
1436/**
1437 * Audio callback registration record.
1438 */
1439typedef struct PDMAUDIOCBRECORD
1440{
1441 /** List node. */
1442 RTLISTANCHOR Node;
1443 /** Callback source. */
1444 PDMAUDIOCBSOURCE enmSource;
1445 /** Callback type, based on the given source. */
1446 union
1447 {
1448 /** Device callback stuff. */
1449 struct
1450 {
1451 PDMAUDIODEVICECBTYPE enmType;
1452 } Device;
1453 } RT_UNION_NM(u);
1454 /** Pointer to context data. Optional. */
1455 void *pvCtx;
1456 /** Size (in bytes) of context data.
1457 * Must be 0 if pvCtx is NULL. */
1458 size_t cbCtx;
1459} PDMAUDIOCBRECORD;
1460/** Pointer to an audio callback registration record. */
1461typedef PDMAUDIOCBRECORD *PPDMAUDIOCBRECORD;
1462
1463/** @todo r=bird: What is this exactly? */
1464#define PPDMAUDIOBACKENDSTREAM void *
1465
1466/** Pointer to a audio connector interface. */
1467typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
1468
1469/**
1470 * Audio connector interface (up).
1471 */
1472typedef struct PDMIAUDIOCONNECTOR
1473{
1474 /**
1475 * Enables or disables the given audio direction for this driver.
1476 *
1477 * When disabled, assiociated output streams consume written audio without passing them further down to the backends.
1478 * Associated input streams then return silence when read from those.
1479 *
1480 * @returns VBox status code.
1481 * @param pInterface Pointer to the interface structure containing the called function pointer.
1482 * @param enmDir Audio direction to enable or disable driver for.
1483 * @param fEnable Whether to enable or disable the specified audio direction.
1484 *
1485 * @note Be very careful when using this function, as this could
1486 * violate / run against the (global) VM settings. See @bugref{9882}.
1487 */
1488 DECLR3CALLBACKMEMBER(int, pfnEnable, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir, bool fEnable));
1489
1490 /**
1491 * Returns whether the given audio direction for this driver is enabled or not.
1492 *
1493 * @returns True if audio is enabled for the given direction, false if not.
1494 * @param pInterface Pointer to the interface structure containing the called function pointer.
1495 * @param enmDir Audio direction to retrieve enabled status for.
1496 */
1497 DECLR3CALLBACKMEMBER(bool, pfnIsEnabled, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
1498
1499 /**
1500 * Retrieves the current configuration of the host audio backend.
1501 *
1502 * @returns VBox status code.
1503 * @param pInterface Pointer to the interface structure containing the called function pointer.
1504 * @param pCfg Where to store the host audio backend configuration data.
1505 */
1506 DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOBACKENDCFG pCfg));
1507
1508 /**
1509 * Retrieves the current status of the host audio backend.
1510 *
1511 * @returns Status of the host audio backend.
1512 * @param pInterface Pointer to the interface structure containing the called function pointer.
1513 * @param enmDir Audio direction to check host audio backend for. Specify PDMAUDIODIR_DUPLEX for the overall
1514 * backend status.
1515 */
1516 DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
1517
1518 /**
1519 * Creates an audio stream.
1520 *
1521 * @returns VBox status code.
1522 * @param pInterface Pointer to the interface structure containing the called function pointer.
1523 * @param pCfgHost Stream configuration for host side.
1524 * @param pCfgGuest Stream configuration for guest side.
1525 * @param ppStream Pointer where to return the created audio stream on success.
1526 */
1527 DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfgHost,
1528 PPDMAUDIOSTREAMCFG pCfgGuest, PPDMAUDIOSTREAM *ppStream));
1529
1530 /**
1531 * Destroys an audio stream.
1532 *
1533 * @param pInterface Pointer to the interface structure containing the called function pointer.
1534 * @param pStream Pointer to audio stream.
1535 */
1536 DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1537
1538 /**
1539 * Adds a reference to the specified audio stream.
1540 *
1541 * @returns New reference count. UINT32_MAX on error.
1542 * @param pInterface Pointer to the interface structure containing the called function pointer.
1543 * @param pStream Pointer to audio stream adding the reference to.
1544 */
1545 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRetain, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1546
1547 /**
1548 * Releases a reference from the specified stream.
1549 *
1550 * @returns New reference count. UINT32_MAX on error.
1551 * @param pInterface Pointer to the interface structure containing the called function pointer.
1552 * @param pStream Pointer to audio stream releasing a reference from.
1553 */
1554 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRelease, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1555
1556 /**
1557 * Reads PCM audio data from the host (input).
1558 *
1559 * @returns VBox status code.
1560 * @param pInterface Pointer to the interface structure containing the called function pointer.
1561 * @param pStream Pointer to audio stream to write to.
1562 * @param pvBuf Where to store the read data.
1563 * @param cbBuf Number of bytes to read.
1564 * @param pcbRead Bytes of audio data read. Optional.
1565 */
1566 DECLR3CALLBACKMEMBER(int, pfnStreamRead, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1567 void *pvBuf, uint32_t cbBuf, uint32_t *pcbRead));
1568
1569 /**
1570 * Writes PCM audio data to the host (output).
1571 *
1572 * @returns VBox status code.
1573 * @param pInterface Pointer to the interface structure containing the called function pointer.
1574 * @param pStream Pointer to audio stream to read from.
1575 * @param pvBuf Audio data to be written.
1576 * @param cbBuf Number of bytes to be written.
1577 * @param pcbWritten Bytes of audio data written. Optional.
1578 */
1579 DECLR3CALLBACKMEMBER(int, pfnStreamWrite, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1580 const void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten));
1581
1582 /**
1583 * Controls a specific audio stream.
1584 *
1585 * @returns VBox status code.
1586 * @param pInterface Pointer to the interface structure containing the called function pointer.
1587 * @param pStream Pointer to audio stream.
1588 * @param enmStreamCmd The stream command to issue.
1589 */
1590 DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1591 PDMAUDIOSTREAMCMD enmStreamCmd));
1592
1593 /**
1594 * Processes stream data.
1595 *
1596 * @param pInterface Pointer to the interface structure containing the called function pointer.
1597 * @param pStream Pointer to audio stream.
1598 */
1599 DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1600
1601 /**
1602 * Returns the number of readable data (in bytes) of a specific audio input stream.
1603 *
1604 * @returns Number of bytes of readable data.
1605 * @param pInterface Pointer to the interface structure containing the called function pointer.
1606 * @param pStream Pointer to audio stream.
1607 */
1608 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1609
1610 /**
1611 * Returns the number of writable data (in bytes) of a specific audio output stream.
1612 *
1613 * @returns Number of bytes writable data.
1614 * @param pInterface Pointer to the interface structure containing the called function pointer.
1615 * @param pStream Pointer to audio stream.
1616 */
1617 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1618
1619 /**
1620 * Returns the status of a specific audio stream.
1621 *
1622 * @returns Audio stream status
1623 * @param pInterface Pointer to the interface structure containing the called function pointer.
1624 * @param pStream Pointer to audio stream.
1625 */
1626 DECLR3CALLBACKMEMBER(PDMAUDIOSTREAMSTS, pfnStreamGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1627
1628 /**
1629 * Sets the audio volume of a specific audio stream.
1630 *
1631 * @returns VBox status code.
1632 * @param pInterface Pointer to the interface structure containing the called function pointer.
1633 * @param pStream Pointer to audio stream.
1634 * @param pVol Pointer to audio volume structure to set the stream's audio volume to.
1635 */
1636 DECLR3CALLBACKMEMBER(int, pfnStreamSetVolume, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOVOLUME pVol));
1637
1638 /**
1639 * Plays (transfers) available audio frames to the host backend.
1640 *
1641 * Only works with output streams.
1642 *
1643 * @returns VBox status code.
1644 * @param pInterface Pointer to the interface structure containing the called function pointer.
1645 * @param pStream Pointer to audio stream.
1646 * @param pcFramesPlayed Number of frames played. Optional.
1647 */
1648 DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcFramesPlayed));
1649
1650 /**
1651 * Captures (transfers) available audio frames from the host backend.
1652 *
1653 * Only works with input streams.
1654 *
1655 * @returns VBox status code.
1656 * @param pInterface Pointer to the interface structure containing the called function pointer.
1657 * @param pStream Pointer to audio stream.
1658 * @param pcFramesCaptured Number of frames captured. Optional.
1659 */
1660 DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
1661 uint32_t *pcFramesCaptured));
1662
1663 /**
1664 * Registers (device) callbacks.
1665 * This is handy for letting the device emulation know of certain events, e.g. processing input / output data
1666 * or configuration changes.
1667 *
1668 * @returns VBox status code.
1669 * @param pInterface Pointer to the interface structure containing the called function pointer.
1670 * @param paCallbacks Pointer to array of callbacks to register.
1671 * @param cCallbacks Number of callbacks to register.
1672 */
1673 DECLR3CALLBACKMEMBER(int, pfnRegisterCallbacks, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOCBRECORD paCallbacks,
1674 size_t cCallbacks));
1675
1676} PDMIAUDIOCONNECTOR;
1677
1678/** PDMIAUDIOCONNECTOR interface ID. */
1679#define PDMIAUDIOCONNECTOR_IID "00e704ef-0078-4bb6-0005-a5fd000ded9f"
1680
1681
1682/**
1683 * PDM host audio interface.
1684 */
1685typedef struct PDMIHOSTAUDIO
1686{
1687 /**
1688 * Initializes the host backend (driver).
1689 *
1690 * @returns VBox status code.
1691 * @param pInterface Pointer to the interface structure containing the called function pointer.
1692 * @deprecated Just stub this and do the real work in the driver constructor.
1693 */
1694 DECLR3CALLBACKMEMBER(int, pfnInit, (PPDMIHOSTAUDIO pInterface));
1695
1696 /**
1697 * Shuts down the host backend (driver).
1698 *
1699 * @returns VBox status code.
1700 * @param pInterface Pointer to the interface structure containing the called function pointer.
1701 * @deprecated Just stub this and do the real work in the driver destructor.
1702 */
1703 DECLR3CALLBACKMEMBER(void, pfnShutdown, (PPDMIHOSTAUDIO pInterface));
1704
1705 /**
1706 * Returns the host backend's configuration (backend).
1707 *
1708 * @returns VBox status code.
1709 * @param pInterface Pointer to the interface structure containing the called function pointer.
1710 * @param pBackendCfg Where to store the backend audio configuration to.
1711 */
1712 DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg));
1713
1714 /**
1715 * Returns (enumerates) host audio device information.
1716 *
1717 * @returns VBox status code.
1718 * @param pInterface Pointer to the interface structure containing the called function pointer.
1719 * @param pDeviceEnum Where to return the enumerated audio devices.
1720 */
1721 DECLR3CALLBACKMEMBER(int, pfnGetDevices, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHOSTENUM pDeviceEnum));
1722
1723 /**
1724 * Returns the current status from the audio backend.
1725 *
1726 * @returns PDMAUDIOBACKENDSTS enum.
1727 * @param pInterface Pointer to the interface structure containing the called function pointer.
1728 * @param enmDir Audio direction to get status for. Pass PDMAUDIODIR_DUPLEX for overall status.
1729 */
1730 DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir));
1731
1732 /**
1733 * Sets a callback the audio backend can call. Optional.
1734 *
1735 * @returns VBox status code.
1736 * @param pInterface Pointer to the interface structure containing the called function pointer.
1737 * @param pfnCallback The callback function to use, or NULL when unregistering.
1738 */
1739 DECLR3CALLBACKMEMBER(int, pfnSetCallback, (PPDMIHOSTAUDIO pInterface, PFNPDMHOSTAUDIOCALLBACK pfnCallback));
1740
1741 /**
1742 * Creates an audio stream using the requested stream configuration.
1743 *
1744 * If a backend is not able to create this configuration, it will return its
1745 * best match in the acquired configuration structure on success.
1746 *
1747 * @returns VBox status code.
1748 * @param pInterface Pointer to the interface structure containing the called function pointer.
1749 * @param pStream Pointer to audio stream.
1750 * @param pCfgReq Pointer to requested stream configuration.
1751 * @param pCfgAcq Pointer to acquired stream configuration.
1752 * @todo r=bird: Implementation (at least Alsa) seems to make undocumented
1753 * assumptions about the content of @a pCfgAcq.
1754 */
1755 DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1756 PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq));
1757
1758 /**
1759 * Destroys an audio stream.
1760 *
1761 * @returns VBox status code.
1762 * @param pInterface Pointer to the interface structure containing the called function pointer.
1763 * @param pStream Pointer to audio stream.
1764 */
1765 DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1766
1767 /**
1768 * Controls an audio stream.
1769 *
1770 * @returns VBox status code.
1771 * @retval VERR_AUDIO_STREAM_NOT_READY if stream is not ready for required operation (yet).
1772 * @param pInterface Pointer to the interface structure containing the called function pointer.
1773 * @param pStream Pointer to audio stream.
1774 * @param enmStreamCmd The stream command to issue.
1775 */
1776 DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1777 PDMAUDIOSTREAMCMD enmStreamCmd));
1778
1779 /**
1780 * Returns the amount which is readable from the audio (input) stream.
1781 *
1782 * @returns For non-raw layout streams: Number of readable bytes.
1783 * for raw layout streams : Number of readable audio frames.
1784 * @param pInterface Pointer to the interface structure containing the called function pointer.
1785 * @param pStream Pointer to audio stream.
1786 */
1787 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1788
1789 /**
1790 * Returns the amount which is writable to the audio (output) stream.
1791 *
1792 * @returns Number of writable bytes.
1793 * @param pInterface Pointer to the interface structure containing the called function pointer.
1794 * @param pStream Pointer to audio stream.
1795 */
1796 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1797
1798 /**
1799 * Returns the amount which is pending (in other words has not yet been processed) by/from the backend yet.
1800 * Optional.
1801 *
1802 * For input streams this is read audio data by the backend which has not been processed by the host yet.
1803 * For output streams this is written audio data to the backend which has not been processed by the backend yet.
1804 *
1805 * @returns For non-raw layout streams: Number of pending bytes.
1806 * for raw layout streams : Number of pending audio frames.
1807 * @param pInterface Pointer to the interface structure containing the called function pointer.
1808 * @param pStream Pointer to audio stream.
1809 */
1810 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetPending, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1811
1812 /**
1813 * Returns the current status of the given backend stream.
1814 *
1815 * @returns PDMAUDIOSTREAMSTS
1816 * @param pInterface Pointer to the interface structure containing the called function pointer.
1817 * @param pStream Pointer to audio stream.
1818 */
1819 DECLR3CALLBACKMEMBER(PDMAUDIOSTREAMSTS, pfnStreamGetStatus, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1820
1821 /**
1822 * Gives the host backend the chance to do some (necessary) iteration work.
1823 *
1824 * @returns VBox status code.
1825 * @param pInterface Pointer to the interface structure containing the called function pointer.
1826 * @param pStream Pointer to audio stream.
1827 */
1828 DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1829
1830 /**
1831 * Signals the backend that the host wants to begin playing for this iteration. Optional.
1832 *
1833 * @param pInterface Pointer to the interface structure containing the called function pointer.
1834 * @param pStream Pointer to audio stream.
1835 */
1836 DECLR3CALLBACKMEMBER(void, pfnStreamPlayBegin, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1837
1838 /**
1839 * Plays (writes to) an audio (output) stream.
1840 *
1841 * @returns VBox status code.
1842 * @param pInterface Pointer to the interface structure containing the called function pointer.
1843 * @param pStream Pointer to audio stream.
1844 * @param pvBuf Pointer to audio data buffer to play.
1845 * @param cbBuf The number of bytes of audio data to play.
1846 * @param pcbWritten Where to return the actual number of bytes played.
1847 */
1848 DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1849 const void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten));
1850
1851 /**
1852 * Signals the backend that the host finished playing 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, pfnStreamPlayEnd, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1858
1859 /**
1860 * Signals the backend that the host wants to begin capturing for this iteration. Optional.
1861 *
1862 * @param pInterface Pointer to the interface structure containing the called function pointer.
1863 * @param pStream Pointer to audio stream.
1864 */
1865 DECLR3CALLBACKMEMBER(void, pfnStreamCaptureBegin, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1866
1867 /**
1868 * Captures (reads from) an audio (input) stream.
1869 *
1870 * @returns VBox status code.
1871 * @param pInterface Pointer to the interface structure containing the called function pointer.
1872 * @param pStream Pointer to audio stream.
1873 * @param pvBuf Buffer where to store read audio data.
1874 * @param uBufSize Size of the audio data buffer (see note below for unit).
1875 * @param puRead Returns number of units read.
1876 * @note The @a uBufSize and @a puRead values are in bytes for non-raw
1877 * layout streams and in frames for raw layout ones.
1878 */
1879 DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
1880 void *pvBuf, uint32_t uBufSize, uint32_t *puRead));
1881
1882 /**
1883 * Signals the backend that the host finished capturing for this iteration. Optional.
1884 *
1885 * @param pInterface Pointer to the interface structure containing the called function pointer.
1886 * @param pStream Pointer to audio stream.
1887 */
1888 DECLR3CALLBACKMEMBER(void, pfnStreamCaptureEnd, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1889
1890} PDMIHOSTAUDIO;
1891
1892/** PDMIHOSTAUDIO interface ID. */
1893#define PDMIHOSTAUDIO_IID "be34182b-d579-41e8-96e0-abb94900460f"
1894
1895/** @} */
1896
1897#endif /* !VBOX_INCLUDED_vmm_pdmaudioifs_h */
1898
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