VirtualBox

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

最後變更 在這個檔案從69956是 69956,由 vboxsync 提交於 7 年 前

Audio: Implemented support for dumping raw PCM data if debug mode is enabled.
  • 屬性 svn:eol-style 設為 native
  • 屬性 svn:keywords 設為 Author Date Id Revision
檔案大小: 59.3 KB
行 
1/** @file
2 * PDM - Pluggable Device Manager, audio interfaces.
3 */
4
5/*
6 * Copyright (C) 2006-2017 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.alldomusa.eu.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/**
27 * == Audio architecture overview
28 *
29 * The audio architecture mainly consists of two PDM interfaces, PDMAUDIOCONNECTOR
30 * and PDMIHOSTAUDIO.
31 *
32 * The PDMAUDIOCONNECTOR interface is responsible of connecting a device emulation, such
33 * as SB16, AC'97 and HDA to one or multiple audio backend(s). Its API abstracts audio
34 * stream handling and I/O functions, device enumeration and so on.
35 *
36 * The PDMIHOSTAUDIO interface must be implemented by all audio backends to provide an
37 * abstract and common way of accessing needed functions, such as transferring output audio
38 * data for playing audio or recording input from the host.
39 *
40 * A device emulation can have one or more LUNs attached to it, whereas these LUNs in turn
41 * then all have their own PDMIAUDIOCONNECTOR, making it possible to connect multiple backends
42 * to a certain device emulation stream (multiplexing).
43 *
44 * An audio backend's job is to record and/or play audio data (depending on its capabilities).
45 * It highly depends on the host it's running on and needs very specific (host-OS-dependent) code.
46 * The backend itself only has very limited ways of accessing and/or communicating with the
47 * PDMIAUDIOCONNECTOR interface via callbacks, but never directly with the device emulation or
48 * other parts of the audio sub system.
49 *
50 *
51 * == Mixing
52 *
53 * The AUDIOMIXER API is optionally available to create and manage virtual audio mixers.
54 * Such an audio mixer in turn then can be used by the device emulation code to manage all
55 * the multiplexing to/from the connected LUN audio streams.
56 *
57 * Currently only input and output stream are supported. Duplex stream are not supported yet.
58 *
59 * This also is handy if certain LUN audio streams should be added or removed during runtime.
60 *
61 * To create a group of either input or output streams the AUDMIXSINK API can be used.
62 *
63 * For example: The device emulation has one hardware output stream (HW0), and that output
64 * stream shall be available to all connected LUN backends. For that to happen,
65 * an AUDMIXSINK sink has to be created and attached to the device's AUDIOMIXER object.
66 *
67 * As every LUN has its own AUDMIXSTREAM object, adding all those objects to the
68 * just created audio mixer sink will do the job.
69 *
70 * Note: The AUDIOMIXER API is purely optional and is not used by all currently implemented
71 * device emulations (e.g. SB16).
72 *
73 *
74 * == Data processing
75 *
76 * Audio input / output data gets handed-off to/from the device emulation in an unmodified
77 * - that is, raw - way. The actual audio frame / sample conversion is done via the PDMAUDIOMIXBUF API.
78 *
79 * This concentrates the audio data processing in one place and makes it easier to test / benchmark
80 * such code.
81 *
82 * A PDMAUDIOFRAME is the internal representation of a single audio frame, which consists of a single left
83 * and right audio sample in time. Only mono (1) and stereo (2) channel(s) currently are supported.
84 *
85 *
86 * == Diagram
87 *
88 * +-------------------------+
89 * +-------------------------+ +-------------------------+ +-------------------+
90 * |PDMAUDIOSTREAM | |PDMAUDIOCONNECTOR | + ++|LUN |
91 * |-------------------------| |-------------------------| | |||-------------------|
92 * |PDMAUDIOMIXBUF |+------>|PDMAUDIOSTREAM Host |+---|-|||PDMIAUDIOCONNECTOR |
93 * |PDMAUDIOSTREAMCFG |+------>|PDMAUDIOSTREAM Guest | | |||AUDMIXSTREAM |
94 * | | |Device capabilities | | ||| |
95 * | | |Device configuration | | ||| |
96 * | | | | | ||| |
97 * | | +|PDMIHOSTAUDIO | | ||| |
98 * | | ||+-----------------------+| | ||+-------------------+
99 * +-------------------------+ |||Backend storage space || | ||
100 * ||+-----------------------+| | ||
101 * |+-------------------------+ | ||
102 * | | ||
103 * +---------------------+ | | ||
104 * |PDMIHOSTAUDIO | | | ||
105 * |+--------------+ | | +-------------------+ | || +-------------+
106 * ||DirectSound | | | |AUDMIXSINK | | || |AUDIOMIXER |
107 * |+--------------+ | | |-------------------| | || |-------------|
108 * | | | |AUDMIXSTREAM0 |+---|-||----->|AUDMIXSINK0 |
109 * |+--------------+ | | |AUDMIXSTREAM1 |+---|-||----->|AUDMIXSINK1 |
110 * ||PulseAudio | | | |AUDMIXSTREAMn |+---|-||----->|AUDMIXSINKn |
111 * |+--------------+ |+----------+ +-------------------+ | || +-------------+
112 * | | | ||
113 * |+--------------+ | | ||
114 * ||Core Audio | | | ||
115 * |+--------------+ | | ||
116 * | | | ||
117 * | | | ||+----------------------------------+
118 * | | | |||Device (SB16 / AC'97 / HDA) |
119 * | | | |||----------------------------------|
120 * +---------------------+ | |||AUDIOMIXER (Optional) |
121 * | |||AUDMIXSINK0 (Optional) |
122 * | |||AUDMIXSINK1 (Optional) |
123 * | |||AUDMIXSINKn (Optional) |
124 * | ||| |
125 * | |+|LUN0 |
126 * | ++|LUN1 |
127 * +--+|LUNn |
128 * | |
129 * | |
130 * | |
131 * +----------------------------------+
132 */
133
134#ifndef ___VBox_vmm_pdmaudioifs_h
135#define ___VBox_vmm_pdmaudioifs_h
136
137#include <iprt/circbuf.h>
138#include <iprt/list.h>
139
140#include <VBox/types.h>
141#ifdef VBOX_WITH_STATISTICS
142# include <VBox/vmm/stam.h>
143#endif
144
145/** @defgroup grp_pdm_ifs_audio PDM Audio Interfaces
146 * @ingroup grp_pdm_interfaces
147 * @{
148 */
149
150#ifndef VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH
151# ifdef RT_OS_WINDOWS
152# define VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "c:\\temp\\"
153# else
154# define VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "/tmp/"
155# endif
156#endif
157
158/** PDM audio driver instance flags. */
159typedef uint32_t PDMAUDIODRVFLAGS;
160
161/** No flags set. */
162#define PDMAUDIODRVFLAGS_NONE 0
163/** Marks a primary audio driver which is critical
164 * when running the VM. */
165#define PDMAUDIODRVFLAGS_PRIMARY RT_BIT(0)
166
167/**
168 * Audio format in signed or unsigned variants.
169 */
170typedef enum PDMAUDIOFMT
171{
172 /** Invalid format, do not use. */
173 PDMAUDIOFMT_INVALID,
174 /** 8-bit, unsigned. */
175 PDMAUDIOFMT_U8,
176 /** 8-bit, signed. */
177 PDMAUDIOFMT_S8,
178 /** 16-bit, unsigned. */
179 PDMAUDIOFMT_U16,
180 /** 16-bit, signed. */
181 PDMAUDIOFMT_S16,
182 /** 32-bit, unsigned. */
183 PDMAUDIOFMT_U32,
184 /** 32-bit, signed. */
185 PDMAUDIOFMT_S32,
186 /** Hack to blow the type up to 32-bit. */
187 PDMAUDIOFMT_32BIT_HACK = 0x7fffffff
188} PDMAUDIOFMT;
189
190/**
191 * Audio direction.
192 */
193typedef enum PDMAUDIODIR
194{
195 /** Unknown direction. */
196 PDMAUDIODIR_UNKNOWN = 0,
197 /** Input. */
198 PDMAUDIODIR_IN = 1,
199 /** Output. */
200 PDMAUDIODIR_OUT = 2,
201 /** Duplex handling. */
202 PDMAUDIODIR_ANY = 3,
203 /** Hack to blow the type up to 32-bit. */
204 PDMAUDIODIR_32BIT_HACK = 0x7fffffff
205} PDMAUDIODIR;
206
207/** Device latency spec in milliseconds (ms). */
208typedef uint32_t PDMAUDIODEVLATSPECMS;
209
210/** Device latency spec in seconds (s). */
211typedef uint32_t PDMAUDIODEVLATSPECSEC;
212
213/** Audio device flags. Use with PDMAUDIODEV_FLAG_ flags. */
214typedef uint32_t PDMAUDIODEVFLAG;
215
216/** No flags set. */
217#define PDMAUDIODEV_FLAGS_NONE 0
218/** The device marks the default device within the host OS. */
219#define PDMAUDIODEV_FLAGS_DEFAULT RT_BIT(0)
220/** The device can be removed at any time and we have to deal with it. */
221#define PDMAUDIODEV_FLAGS_HOTPLUG RT_BIT(1)
222/** The device is known to be buggy and needs special treatment. */
223#define PDMAUDIODEV_FLAGS_BUGGY RT_BIT(2)
224/** Ignore the device, no matter what. */
225#define PDMAUDIODEV_FLAGS_IGNORE RT_BIT(3)
226/** The device is present but marked as locked by some other application. */
227#define PDMAUDIODEV_FLAGS_LOCKED RT_BIT(4)
228/** The device is present but not in an alive state (dead). */
229#define PDMAUDIODEV_FLAGS_DEAD RT_BIT(5)
230
231/**
232 * Audio device type.
233 */
234typedef enum PDMAUDIODEVICETYPE
235{
236 /** Unknown device type. This is the default. */
237 PDMAUDIODEVICETYPE_UNKNOWN = 0,
238 /** Dummy device; for backends which are not able to report
239 * actual device information (yet). */
240 PDMAUDIODEVICETYPE_DUMMY,
241 /** The device is built into the host (non-removable). */
242 PDMAUDIODEVICETYPE_BUILTIN,
243 /** The device is an (external) USB device. */
244 PDMAUDIODEVICETYPE_USB,
245 /** Hack to blow the type up to 32-bit. */
246 PDMAUDIODEVICETYPE_32BIT_HACK = 0x7fffffff
247} PDMAUDIODEVICETYPE;
248
249/**
250 * Audio device instance data.
251 */
252typedef struct PDMAUDIODEVICE
253{
254 /** List node. */
255 RTLISTNODE Node;
256 /** Friendly name of the device, if any. */
257 char szName[64];
258 /** The device type. */
259 PDMAUDIODEVICETYPE enmType;
260 /** Reference count indicating how many audio streams currently are relying on this device. */
261 uint8_t cRefCount;
262 /** Usage of the device. */
263 PDMAUDIODIR enmUsage;
264 /** Device flags. */
265 PDMAUDIODEVFLAG fFlags;
266 /** Maximum number of input audio channels the device supports. */
267 uint8_t cMaxInputChannels;
268 /** Maximum number of output audio channels the device supports. */
269 uint8_t cMaxOutputChannels;
270 /** Additional data which might be relevant for the current context. */
271 void *pvData;
272 /** Size of the additional data. */
273 size_t cbData;
274 /** Device type union, based on enmType. */
275 union
276 {
277 /** USB type specifics. */
278 struct
279 {
280 /** Vendor ID. */
281 int16_t VID;
282 /** Product ID. */
283 int16_t PID;
284 } USB;
285 } Type;
286} PDMAUDIODEVICE, *PPDMAUDIODEVICE;
287
288/**
289 * Structure for keeping an audio device enumeration.
290 */
291typedef struct PDMAUDIODEVICEENUM
292{
293 /** Number of audio devices in the list. */
294 uint16_t cDevices;
295 /** List of audio devices. */
296 RTLISTANCHOR lstDevices;
297} PDMAUDIODEVICEENUM, *PPDMAUDIODEVICEENUM;
298
299/**
300 * Audio (static) configuration of an audio host backend.
301 */
302typedef struct PDMAUDIOBACKENDCFG
303{
304 /** Size (in bytes) of the host backend's audio output stream structure. */
305 size_t cbStreamOut;
306 /** Size (in bytes) of the host backend's audio input stream structure. */
307 size_t cbStreamIn;
308 /** Number of concurrent output streams supported on the host.
309 * UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
310 uint32_t cMaxStreamsOut;
311 /** Number of concurrent input streams supported on the host.
312 * UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
313 uint32_t cMaxStreamsIn;
314} PDMAUDIOBACKENDCFG, *PPDMAUDIOBACKENDCFG;
315
316/**
317 * A single audio frame.
318 *
319 * Currently only two (2) channels, left and right, are supported.
320 *
321 * Note: When changing this structure, make sure to also handle
322 * VRDP's input / output processing in DrvAudioVRDE, as VRDP
323 * expects audio data in st_sample_t format (historical reasons)
324 * which happens to be the same as PDMAUDIOFRAME for now.
325 */
326typedef struct PDMAUDIOFRAME
327{
328 /** Left channel. */
329 int64_t i64LSample;
330 /** Right channel. */
331 int64_t i64RSample;
332} PDMAUDIOFRAME;
333/** Pointer to a single (stereo) audio frame. */
334typedef PDMAUDIOFRAME *PPDMAUDIOFRAME;
335/** Pointer to a const single (stereo) audio frame. */
336typedef PDMAUDIOFRAME const *PCPDMAUDIOFRAME;
337
338typedef enum PDMAUDIOENDIANNESS
339{
340 /** The usual invalid endian. */
341 PDMAUDIOENDIANNESS_INVALID,
342 /** Little endian. */
343 PDMAUDIOENDIANNESS_LITTLE,
344 /** Bit endian. */
345 PDMAUDIOENDIANNESS_BIG,
346 /** Endianness doesn't have a meaning in the context. */
347 PDMAUDIOENDIANNESS_NA,
348 /** The end of the valid endian values (exclusive). */
349 PDMAUDIOENDIANNESS_END,
350 /** Hack to blow the type up to 32-bit. */
351 PDMAUDIOENDIANNESS_32BIT_HACK = 0x7fffffff
352} PDMAUDIOENDIANNESS;
353
354/**
355 * Audio playback destinations.
356 */
357typedef enum PDMAUDIOPLAYBACKDEST
358{
359 /** Unknown destination. */
360 PDMAUDIOPLAYBACKDEST_UNKNOWN = 0,
361 /** Front channel. */
362 PDMAUDIOPLAYBACKDEST_FRONT,
363 /** Center / LFE (Subwoofer) channel. */
364 PDMAUDIOPLAYBACKDEST_CENTER_LFE,
365 /** Rear channel. */
366 PDMAUDIOPLAYBACKDEST_REAR,
367 /** Hack to blow the type up to 32-bit. */
368 PDMAUDIOPLAYBACKDEST_32BIT_HACK = 0x7fffffff
369} PDMAUDIOPLAYBACKDEST;
370
371/**
372 * Audio recording sources.
373 */
374typedef enum PDMAUDIORECSOURCE
375{
376 /** Unknown recording source. */
377 PDMAUDIORECSOURCE_UNKNOWN = 0,
378 /** Microphone-In. */
379 PDMAUDIORECSOURCE_MIC,
380 /** CD. */
381 PDMAUDIORECSOURCE_CD,
382 /** Video-In. */
383 PDMAUDIORECSOURCE_VIDEO,
384 /** AUX. */
385 PDMAUDIORECSOURCE_AUX,
386 /** Line-In. */
387 PDMAUDIORECSOURCE_LINE,
388 /** Phone-In. */
389 PDMAUDIORECSOURCE_PHONE,
390 /** Hack to blow the type up to 32-bit. */
391 PDMAUDIORECSOURCE_32BIT_HACK = 0x7fffffff
392} PDMAUDIORECSOURCE;
393
394/**
395 * Audio stream (data) layout.
396 */
397typedef enum PDMAUDIOSTREAMLAYOUT
398{
399 /** Unknown access type; do not use. */
400 PDMAUDIOSTREAMLAYOUT_UNKNOWN = 0,
401 /** Non-interleaved access, that is, consecutive
402 * access to the data. */
403 PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED,
404 /** Interleaved access, where the data can be
405 * mixed together with data of other audio streams. */
406 PDMAUDIOSTREAMLAYOUT_INTERLEAVED,
407 /** Complex layout, which does not fit into the
408 * interleaved / non-interleaved layouts. */
409 PDMAUDIOSTREAMLAYOUT_COMPLEX,
410 /** Raw (pass through) data, with no data layout processing done.
411 *
412 * This means that this stream will operate on PDMAUDIOFRAME data
413 * directly. Don't use this if you don't have to. */
414 PDMAUDIOSTREAMLAYOUT_RAW,
415 /** Hack to blow the type up to 32-bit. */
416 PDMAUDIOSTREAMLAYOUT_32BIT_HACK = 0x7fffffff
417} PDMAUDIOSTREAMLAYOUT, *PPDMAUDIOSTREAMLAYOUT;
418
419/** No stream channel data flags defined. */
420#define PDMAUDIOSTREAMCHANNELDATA_FLAG_NONE 0
421
422/**
423 * Structure for keeping a stream channel data block around.
424 */
425typedef struct PDMAUDIOSTREAMCHANNELDATA
426{
427 /** Circular buffer for the channel data. */
428 PRTCIRCBUF pCircBuf;
429 size_t cbAcq;
430 /** Channel data flags. */
431 uint32_t fFlags;
432} PDMAUDIOSTREAMCHANNELDATA, *PPDMAUDIOSTREAMCHANNELDATA;
433
434/**
435 * Structure for a single channel of an audio stream.
436 * An audio stream consists of one or multiple channels,
437 * depending on the configuration.
438 */
439typedef struct PDMAUDIOSTREAMCHANNEL
440{
441 /** Channel ID. */
442 uint8_t uChannel;
443 /** Step size (in bytes) to the channel's next frame. */
444 size_t cbStep;
445 /** Frame size (in bytes) of this channel. */
446 size_t cbFrame;
447 /** Offset (in bytes) to first frame in the data block. */
448 size_t cbFirst;
449 /** Currente offset (in bytes) in the data stream. */
450 size_t cbOff;
451 /** Associated data buffer. */
452 PDMAUDIOSTREAMCHANNELDATA Data;
453} PDMAUDIOSTREAMCHANNEL, *PPDMAUDIOSTREAMCHANNEL;
454
455/**
456 * Union for keeping an audio stream destination or source.
457 */
458typedef union PDMAUDIODESTSOURCE
459{
460 /** Desired playback destination (for an output stream). */
461 PDMAUDIOPLAYBACKDEST Dest;
462 /** Desired recording source (for an input stream). */
463 PDMAUDIORECSOURCE Source;
464} PDMAUDIODESTSOURCE, *PPDMAUDIODESTSOURCE;
465
466/**
467 * Properties of audio streams for host/guest
468 * for in or out directions.
469 */
470typedef struct PDMAUDIOPCMPROPS
471{
472 /** Sample width. Bits per sample. */
473 uint8_t cBits;
474 /** Signed or unsigned sample. */
475 bool fSigned;
476 /** Number of audio channels. */
477 uint8_t cChannels;
478 /** Sample frequency in Hertz (Hz). */
479 uint32_t uHz;
480 /** Shift count used for faster calculation of various
481 * values, such as the alignment, bytes to frames and so on.
482 * Depends on number of stream channels and the stream format
483 * being used.
484 *
485 ** @todo Use some RTAsmXXX functions instead?
486 */
487 uint8_t cShift;
488 /** Whether the endianness is swapped or not. */
489 bool fSwapEndian;
490} PDMAUDIOPCMPROPS, *PPDMAUDIOPCMPROPS;
491
492/** Calculates the cShift value of given sample bits and audio channels.
493 * Note: Does only support mono/stereo channels for now. */
494#define PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS(cBits, cChannels) ((cChannels == 2) + (cBits / 16))
495/** Calculates the cShift value of a PDMAUDIOPCMPROPS structure.
496 * Note: Does only support mono/stereo channels for now. */
497#define PDMAUDIOPCMPROPS_MAKE_SHIFT(pProps) PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS((pProps)->cChannels == 2) + (pProps)->cBits / 16)
498/** Converts (audio) frames to bytes.
499 * Needs the cShift value set correctly, using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
500#define PDMAUDIOPCMPROPS_F2B(pProps, frames) ((frames) << (pProps)->cShift)
501/** Converts bytes to (audio) frames.
502 * Needs the cShift value set correctly, using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
503#define PDMAUDIOPCMPROPS_B2F(pProps, cb) (cb >> (pProps)->cShift)
504
505/**
506 * Structure for keeping an audio stream configuration.
507 */
508typedef struct PDMAUDIOSTREAMCFG
509{
510 /** Friendly name of the stream. */
511 char szName[64];
512 /** Direction of the stream. */
513 PDMAUDIODIR enmDir;
514 /** Destination / source indicator, depending on enmDir. */
515 PDMAUDIODESTSOURCE DestSource;
516 /** The stream's PCM properties. */
517 PDMAUDIOPCMPROPS Props;
518 /** The stream's audio data layout.
519 * This indicates how the audio data buffers to/from the backend is being layouted.
520 *
521 * Currently, the following layouts are supported by the audio connector:
522 *
523 * PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED:
524 * One stream at once. The consecutive audio data is exactly in the format and frame width
525 * like defined in the PCM properties. This is the default.
526 *
527 * PDMAUDIOSTREAMLAYOUT_RAW:
528 * Can be one or many streams at once, depending on the stream's mixing buffer setup.
529 * The audio data will get handled as PDMAUDIOFRAME frames without any modification done. */
530 PDMAUDIOSTREAMLAYOUT enmLayout;
531 /** Hint about the optimal frame buffer size (in audio frames).
532 * 0 if no hint is given. */
533 uint32_t cFrameBufferHint;
534} PDMAUDIOSTREAMCFG, *PPDMAUDIOSTREAMCFG;
535
536/** Converts (audio) frames to bytes. */
537#define PDMAUDIOSTREAMCFG_F2B(pCfg, frames) ((frames) << (pCfg->Props).cShift)
538/** Converts bytes to (audio) frames. */
539#define PDMAUDIOSTREAMCFG_B2F(pCfg, cb) (cb >> (pCfg->Props).cShift)
540
541#if defined(RT_LITTLE_ENDIAN)
542# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_LITTLE
543#elif defined(RT_BIG_ENDIAN)
544# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_BIG
545#else
546# error "Port me!"
547#endif
548
549/**
550 * Audio mixer controls.
551 */
552typedef enum PDMAUDIOMIXERCTL
553{
554 /** Unknown mixer control. */
555 PDMAUDIOMIXERCTL_UNKNOWN = 0,
556 /** Master volume. */
557 PDMAUDIOMIXERCTL_VOLUME_MASTER,
558 /** Front. */
559 PDMAUDIOMIXERCTL_FRONT,
560 /** Center / LFE (Subwoofer). */
561 PDMAUDIOMIXERCTL_CENTER_LFE,
562 /** Rear. */
563 PDMAUDIOMIXERCTL_REAR,
564 /** Line-In. */
565 PDMAUDIOMIXERCTL_LINE_IN,
566 /** Microphone-In. */
567 PDMAUDIOMIXERCTL_MIC_IN,
568 /** Hack to blow the type up to 32-bit. */
569 PDMAUDIOMIXERCTL_32BIT_HACK = 0x7fffffff
570} PDMAUDIOMIXERCTL;
571
572/**
573 * Audio stream commands. Used in the audio connector
574 * as well as in the actual host backends.
575 */
576typedef enum PDMAUDIOSTREAMCMD
577{
578 /** Unknown command, do not use. */
579 PDMAUDIOSTREAMCMD_UNKNOWN = 0,
580 /** Enables the stream. */
581 PDMAUDIOSTREAMCMD_ENABLE,
582 /** Disables the stream. */
583 PDMAUDIOSTREAMCMD_DISABLE,
584 /** Pauses the stream. */
585 PDMAUDIOSTREAMCMD_PAUSE,
586 /** Resumes the stream. */
587 PDMAUDIOSTREAMCMD_RESUME,
588 /** Hack to blow the type up to 32-bit. */
589 PDMAUDIOSTREAMCMD_32BIT_HACK = 0x7fffffff
590} PDMAUDIOSTREAMCMD;
591
592/**
593 * Audio volume parameters.
594 */
595typedef struct PDMAUDIOVOLUME
596{
597 /** Set to @c true if this stream is muted, @c false if not. */
598 bool fMuted;
599 /** Left channel volume.
600 * Range is from [0 ... 255], whereas 0 specifies
601 * the most silent and 255 the loudest value. */
602 uint8_t uLeft;
603 /** Right channel volume.
604 * Range is from [0 ... 255], whereas 0 specifies
605 * the most silent and 255 the loudest value. */
606 uint8_t uRight;
607} PDMAUDIOVOLUME, *PPDMAUDIOVOLUME;
608
609/** Defines the minimum volume allowed. */
610#define PDMAUDIO_VOLUME_MIN (0)
611/** Defines the maximum volume allowed. */
612#define PDMAUDIO_VOLUME_MAX (255)
613
614/**
615 * Structure for holding rate processing information
616 * of a source + destination audio stream. This is needed
617 * because both streams can differ regarding their rates
618 * and therefore need to be treated accordingly.
619 */
620typedef struct PDMAUDIOSTREAMRATE
621{
622 /** Current (absolute) offset in the output
623 * (destination) stream. */
624 uint64_t dstOffset;
625 /** Increment for moving dstOffset for the
626 * destination stream. This is needed because the
627 * source <-> destination rate might be different. */
628 uint64_t dstInc;
629 /** Current (absolute) offset in the input
630 * stream. */
631 uint32_t srcOffset;
632 /** Last processed frame of the input stream.
633 * Needed for interpolation. */
634 PDMAUDIOFRAME srcFrameLast;
635} PDMAUDIOSTREAMRATE, *PPDMAUDIOSTREAMRATE;
636
637/**
638 * Structure for holding mixing buffer volume parameters.
639 * The volume values are in fixed point style and must
640 * be converted to/from before using with e.g. PDMAUDIOVOLUME.
641 */
642typedef struct PDMAUDMIXBUFVOL
643{
644 /** Set to @c true if this stream is muted, @c false if not. */
645 bool fMuted;
646 /** Left volume to apply during conversion. Pass 0
647 * to convert the original values. May not apply to
648 * all conversion functions. */
649 uint32_t uLeft;
650 /** Right volume to apply during conversion. Pass 0
651 * to convert the original values. May not apply to
652 * all conversion functions. */
653 uint32_t uRight;
654} PDMAUDMIXBUFVOL, *PPDMAUDMIXBUFVOL;
655
656/**
657 * Structure for holding frame conversion parameters for
658 * the audioMixBufConvFromXXX / audioMixBufConvToXXX macros.
659 */
660typedef struct PDMAUDMIXBUFCONVOPTS
661{
662 /** Number of audio frames to convert. */
663 uint32_t cFrames;
664 union
665 {
666 struct
667 {
668 /** Volume to use for conversion. */
669 PDMAUDMIXBUFVOL Volume;
670 } From;
671 } RT_UNION_NM(u);
672} PDMAUDMIXBUFCONVOPTS;
673/** Pointer to conversion parameters for the audio mixer. */
674typedef PDMAUDMIXBUFCONVOPTS *PPDMAUDMIXBUFCONVOPTS;
675/** Pointer to const conversion parameters for the audio mixer. */
676typedef PDMAUDMIXBUFCONVOPTS const *PCPDMAUDMIXBUFCONVOPTS;
677
678/**
679 * Note: All internal handling is done in audio frames,
680 * not in bytes!
681 */
682typedef uint32_t PDMAUDIOMIXBUFFMT;
683typedef PDMAUDIOMIXBUFFMT *PPDMAUDIOMIXBUFFMT;
684
685/**
686 * Convertion-from function used by the PDM audio buffer mixer.
687 *
688 * @returns Number of audio frames returned.
689 * @param paDst Where to return the converted frames.
690 * @param pvSrc The source frame bytes.
691 * @param cbSrc Number of bytes to convert.
692 * @param pOpts Conversion options.
693 */
694typedef DECLCALLBACK(uint32_t) FNPDMAUDIOMIXBUFCONVFROM(PPDMAUDIOFRAME paDst, const void *pvSrc, uint32_t cbSrc,
695 PCPDMAUDMIXBUFCONVOPTS pOpts);
696/** Pointer to a convertion-from function used by the PDM audio buffer mixer. */
697typedef FNPDMAUDIOMIXBUFCONVFROM *PFNPDMAUDIOMIXBUFCONVFROM;
698
699/**
700 * Convertion-to function used by the PDM audio buffer mixer.
701 *
702 * @param pvDst Output buffer.
703 * @param paSrc The input frames.
704 * @param pOpts Conversion options.
705 */
706typedef DECLCALLBACK(void) FNPDMAUDIOMIXBUFCONVTO(void *pvDst, PCPDMAUDIOFRAME paSrc, PCPDMAUDMIXBUFCONVOPTS pOpts);
707/** Pointer to a convertion-to function used by the PDM audio buffer mixer. */
708typedef FNPDMAUDIOMIXBUFCONVTO *PFNPDMAUDIOMIXBUFCONVTO;
709
710typedef struct PDMAUDIOMIXBUF *PPDMAUDIOMIXBUF;
711typedef struct PDMAUDIOMIXBUF
712{
713 RTLISTNODE Node;
714 /** Name of the buffer. */
715 char *pszName;
716 /** Frame buffer. */
717 PPDMAUDIOFRAME pFrames;
718 /** Size of the frame buffer (in audio frames). */
719 uint32_t cFrames;
720 /** The current read position (in frames). */
721 uint32_t offRead;
722 /** The current write position (in frames). */
723 uint32_t offWrite;
724 /**
725 * Total frames already mixed down to the parent buffer (if any). Always starting at
726 * the parent's offRead position.
727 *
728 * Note: Count always is specified in parent frames, as the sample count can differ between parent
729 * and child.
730 */
731 uint32_t cMixed;
732 /** How much audio frames are currently being used
733 * in this buffer.
734 * Note: This also is known as the distance in ring buffer terms. */
735 uint32_t cUsed;
736 /** Pointer to parent buffer (if any). */
737 PPDMAUDIOMIXBUF pParent;
738 /** List of children mix buffers to keep in sync with (if being a parent buffer). */
739 RTLISTANCHOR lstChildren;
740 /** Number of children mix buffers kept in lstChildren. */
741 uint32_t cChildren;
742 /** Intermediate structure for buffer conversion tasks. */
743 PPDMAUDIOSTREAMRATE pRate;
744 /** Internal representation of current volume used for mixing. */
745 PDMAUDMIXBUFVOL Volume;
746 /** This buffer's audio format. */
747 PDMAUDIOMIXBUFFMT AudioFmt;
748 /** Standard conversion-to function for set AudioFmt. */
749 PFNPDMAUDIOMIXBUFCONVTO pfnConvTo;
750 /** Standard conversion-from function for set AudioFmt. */
751 PFNPDMAUDIOMIXBUFCONVFROM pfnConvFrom;
752 /**
753 * Ratio of the associated parent stream's frequency by this stream's
754 * frequency (1<<32), represented as a signed 64 bit integer.
755 *
756 * For example, if the parent stream has a frequency of 44 khZ, and this
757 * stream has a frequency of 11 kHz, the ration then would be
758 * (44/11 * (1 << 32)).
759 *
760 * Currently this does not get changed once assigned.
761 */
762 int64_t iFreqRatio;
763 /** For quickly converting frames <-> bytes and vice versa. */
764 uint8_t cShift;
765} PDMAUDIOMIXBUF;
766
767typedef uint32_t PDMAUDIOFILEFLAGS;
768
769/* No flags defined. */
770#define PDMAUDIOFILEFLAG_NONE 0
771
772/**
773 * Audio file types.
774 */
775typedef enum PDMAUDIOFILETYPE
776{
777 /** Unknown type, do not use. */
778 PDMAUDIOFILETYPE_UNKNOWN = 0,
779 /** Wave (.WAV) file. */
780 PDMAUDIOFILETYPE_WAV,
781 /** Hack to blow the type up to 32-bit. */
782 PDMAUDIOFILETYPE_32BIT_HACK = 0x7fffffff
783} PDMAUDIOFILETYPE;
784
785/**
786 * Structure for an audio file handle.
787 */
788typedef struct PDMAUDIOFILE
789{
790 /** Type of the audio file. */
791 PDMAUDIOFILETYPE enmType;
792 /** File name. */
793 char szName[255];
794 /** Actual file handle. */
795 RTFILE hFile;
796 /** Data needed for the specific audio file type implemented.
797 * Optional, can be NULL. */
798 void *pvData;
799 /** Data size (in bytes). */
800 size_t cbData;
801} PDMAUDIOFILE, *PPDMAUDIOFILE;
802
803/** Stream status flag. To be used with PDMAUDIOSTRMSTS_FLAG_ flags. */
804typedef uint32_t PDMAUDIOSTREAMSTS;
805
806/** No flags being set. */
807#define PDMAUDIOSTREAMSTS_FLAG_NONE 0
808/** Whether this stream has been initialized by the
809 * backend or not. */
810#define PDMAUDIOSTREAMSTS_FLAG_INITIALIZED RT_BIT_32(0)
811/** Whether this stream is enabled or disabled. */
812#define PDMAUDIOSTREAMSTS_FLAG_ENABLED RT_BIT_32(1)
813/** Whether this stream has been paused or not. This also implies
814 * that this is an enabled stream! */
815#define PDMAUDIOSTREAMSTS_FLAG_PAUSED RT_BIT_32(2)
816/** Whether this stream was marked as being disabled
817 * but there are still associated guest output streams
818 * which rely on its data. */
819#define PDMAUDIOSTREAMSTS_FLAG_PENDING_DISABLE RT_BIT_32(3)
820/** Whether this stream is in re-initialization phase.
821 * All other bits remain untouched to be able to restore
822 * the stream's state after the re-initialization bas been
823 * finished. */
824#define PDMAUDIOSTREAMSTS_FLAG_PENDING_REINIT RT_BIT_32(4)
825/** Validation mask. */
826#define PDMAUDIOSTREAMSTS_VALID_MASK UINT32_C(0x0000001F)
827
828/**
829 * Enumeration presenting a backend's current status.
830 */
831typedef enum PDMAUDIOBACKENDSTS
832{
833 /** Unknown/invalid status. */
834 PDMAUDIOBACKENDSTS_UNKNOWN = 0,
835 /** The backend is in its initialization phase.
836 * Not all backends support this status. */
837 PDMAUDIOBACKENDSTS_INITIALIZING,
838 /** The backend has stopped its operation. */
839 PDMAUDIOBACKENDSTS_STOPPED,
840 /** The backend is up and running. */
841 PDMAUDIOBACKENDSTS_RUNNING,
842 /** The backend ran into an error and is unable to recover.
843 * A manual re-initialization might help. */
844 PDMAUDIOBACKENDSTS_ERROR,
845 /** Hack to blow the type up to 32-bit. */
846 PDMAUDIOBACKENDSTS_32BIT_HACK = 0x7fffffff
847} PDMAUDIOBACKENDSTS;
848
849/**
850 * Audio stream context.
851 */
852typedef enum PDMAUDIOSTREAMCTX
853{
854 /** No context set / invalid. */
855 PDMAUDIOSTREAMCTX_UNKNOWN = 0,
856 /** Host stream, connected to a backend. */
857 PDMAUDIOSTREAMCTX_HOST,
858 /** Guest stream, connected to the device emulation. */
859 PDMAUDIOSTREAMCTX_GUEST,
860 /** Hack to blow the type up to 32-bit. */
861 PDMAUDIOSTREAMCTX_32BIT_HACK = 0x7fffffff
862} PDMAUDIOSTREAMCTX;
863
864/**
865 * Structure for keeping audio input stream specifics.
866 * Do not use directly. Instead, use PDMAUDIOSTREAM.
867 */
868typedef struct PDMAUDIOSTREAMIN
869{
870 /** Timestamp (in ms) since last read. */
871 uint64_t tsLastReadMS;
872#ifdef VBOX_WITH_STATISTICS
873 STAMCOUNTER StatBytesElapsed;
874 STAMCOUNTER StatBytesTotalRead;
875 STAMCOUNTER StatFramesCaptured;
876#endif
877} PDMAUDIOSTREAMIN, *PPDMAUDIOSTREAMIN;
878
879/**
880 * Structure for keeping audio output stream specifics.
881 * Do not use directly. Instead, use PDMAUDIOSTREAM.
882 */
883typedef struct PDMAUDIOSTREAMOUT
884{
885 /** Timestamp (in ms) since last write. */
886 uint64_t tsLastWriteMS;
887#ifdef VBOX_WITH_STATISTICS
888 STAMCOUNTER StatBytesElapsed;
889 STAMCOUNTER StatBytesTotalWritten;
890 STAMCOUNTER StatFramesPlayed;
891#endif
892} PDMAUDIOSTREAMOUT, *PPDMAUDIOSTREAMOUT;
893
894typedef struct PDMAUDIOSTREAM *PPDMAUDIOSTREAM;
895
896/**
897 * Structure for maintaining an nput/output audio stream.
898 */
899typedef struct PDMAUDIOSTREAM
900{
901 /** List node. */
902 RTLISTNODE Node;
903 /** Pointer to the other pair of this stream.
904 * This might be the host or guest side. */
905 PPDMAUDIOSTREAM pPair;
906 /** Name of this stream. */
907 char szName[64];
908 /** Number of references to this stream. Only can be
909 * destroyed if the reference count is reaching 0. */
910 uint32_t cRefs;
911 /** The stream's audio configuration. */
912 PDMAUDIOSTREAMCFG Cfg;
913 /** Stream status flag. */
914 PDMAUDIOSTREAMSTS fStatus;
915 /** This stream's mixing buffer. */
916 PDMAUDIOMIXBUF MixBuf;
917 /** Audio direction of this stream. */
918 PDMAUDIODIR enmDir;
919 /** Context of this stream. */
920 PDMAUDIOSTREAMCTX enmCtx;
921 /** Timestamp (in ms) since last iteration. */
922 uint64_t tsLastIterateMS;
923 /** Union for input/output specifics. */
924 union
925 {
926 PDMAUDIOSTREAMIN In;
927 PDMAUDIOSTREAMOUT Out;
928 } RT_UNION_NM(u);
929 /** Data to backend-specific stream data.
930 * This data block will be casted by the backend to access its backend-dependent data.
931 *
932 * That way the backends do not have access to the audio connector's data. */
933 void *pvBackend;
934 /** Size (in bytes) of the backend-specific stream data. */
935 size_t cbBackend;
936} PDMAUDIOSTREAM;
937
938/** Pointer to a audio connector interface. */
939typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
940
941/**
942 * Enumeration for an audio callback source.
943 */
944typedef enum PDMAUDIOCBSOURCE
945{
946 /** Invalid, do not use. */
947 PDMAUDIOCBSOURCE_INVALID = 0,
948 /** Device emulation. */
949 PDMAUDIOCBSOURCE_DEVICE = 1,
950 /** Audio connector interface. */
951 PDMAUDIOCBSOURCE_CONNECTOR = 2,
952 /** Backend (lower). */
953 PDMAUDIOCBSOURCE_BACKEND = 3,
954 /** Hack to blow the type up to 32-bit. */
955 PDMAUDIOCBSOURCE_32BIT_HACK = 0x7fffffff
956} PDMAUDIOCBSOURCE;
957
958/**
959 * Audio device callback types.
960 * Those callbacks are being sent from the audio connector -> device emulation.
961 */
962typedef enum PDMAUDIODEVICECBTYPE
963{
964 /** Invalid, do not use. */
965 PDMAUDIODEVICECBTYPE_INVALID = 0,
966 /** Data is availabe as input for passing to the device emulation. */
967 PDMAUDIODEVICECBTYPE_DATA_INPUT,
968 /** Free data for the device emulation to write to the backend. */
969 PDMAUDIODEVICECBTYPE_DATA_OUTPUT,
970 /** Hack to blow the type up to 32-bit. */
971 PDMAUDIODEVICECBTYPE_32BIT_HACK = 0x7fffffff
972} PDMAUDIODEVICECBTYPE;
973
974/**
975 * Device callback data for audio input.
976 */
977typedef struct PDMAUDIODEVICECBDATA_DATA_INPUT
978{
979 /** Input: How many bytes are availabe as input for passing
980 * to the device emulation. */
981 uint32_t cbInAvail;
982 /** Output: How many bytes have been read. */
983 uint32_t cbOutRead;
984} PDMAUDIODEVICECBDATA_DATA_INPUT, *PPDMAUDIODEVICECBDATA_DATA_INPUT;
985
986/**
987 * Device callback data for audio output.
988 */
989typedef struct PDMAUDIODEVICECBDATA_DATA_OUTPUT
990{
991 /** Input: How many bytes are free for the device emulation to write. */
992 uint32_t cbInFree;
993 /** Output: How many bytes were written by the device emulation. */
994 uint32_t cbOutWritten;
995} PDMAUDIODEVICECBDATA_DATA_OUTPUT, *PPDMAUDIODEVICECBDATA_DATA_OUTPUT;
996
997/**
998 * Audio backend callback types.
999 * Those callbacks are being sent from the backend -> audio connector.
1000 */
1001typedef enum PDMAUDIOBACKENDCBTYPE
1002{
1003 /** Invalid, do not use. */
1004 PDMAUDIOBACKENDCBTYPE_INVALID = 0,
1005 /** The backend's status has changed. */
1006 PDMAUDIOBACKENDCBTYPE_STATUS,
1007 /** One or more host audio devices have changed. */
1008 PDMAUDIOBACKENDCBTYPE_DEVICES_CHANGED,
1009 /** Hack to blow the type up to 32-bit. */
1010 PDMAUDIOBACKENDCBTYPE_32BIT_HACK = 0x7fffffff
1011} PDMAUDIOBACKENDCBTYPE;
1012
1013/** Pointer to a host audio interface. */
1014typedef struct PDMIHOSTAUDIO *PPDMIHOSTAUDIO;
1015
1016/**
1017 * Host audio callback function.
1018 * This function will be called from a backend to communicate with the host audio interface.
1019 *
1020 * @returns IPRT status code.
1021 * @param pDrvIns Pointer to driver instance which called us.
1022 * @param enmType Callback type.
1023 * @param pvUser User argument.
1024 * @param cbUser Size (in bytes) of user argument.
1025 */
1026typedef DECLCALLBACK(int) FNPDMHOSTAUDIOCALLBACK(PPDMDRVINS pDrvIns, PDMAUDIOBACKENDCBTYPE enmType, void *pvUser, size_t cbUser);
1027/** Pointer to a FNPDMHOSTAUDIOCALLBACK(). */
1028typedef FNPDMHOSTAUDIOCALLBACK *PFNPDMHOSTAUDIOCALLBACK;
1029
1030/**
1031 * Audio callback registration record.
1032 */
1033typedef struct PDMAUDIOCBRECORD
1034{
1035 /** List node. */
1036 RTLISTANCHOR Node;
1037 /** Callback source. */
1038 PDMAUDIOCBSOURCE enmSource;
1039 /** Callback type, based on the given source. */
1040 union
1041 {
1042 /** Device callback stuff. */
1043 struct
1044 {
1045 PDMAUDIODEVICECBTYPE enmType;
1046 } Device;
1047 } RT_UNION_NM(u);
1048 /** Pointer to context data. Optional. */
1049 void *pvCtx;
1050 /** Size (in bytes) of context data.
1051 * Must be 0 if pvCtx is NULL. */
1052 size_t cbCtx;
1053} PDMAUDIOCBRECORD, *PPDMAUDIOCBRECORD;
1054
1055#define PPDMAUDIOBACKENDSTREAM void *
1056
1057/**
1058 * Audio connector interface (up).
1059 */
1060typedef struct PDMIAUDIOCONNECTOR
1061{
1062 /**
1063 * Enables or disables the given audio direction for this driver.
1064 *
1065 * When disabled, assiociated output streams consume written audio without passing them further down to the backends.
1066 * Associated input streams then return silence when read from those.
1067 *
1068 * @returns VBox status code.
1069 * @param pInterface Pointer to the interface structure containing the called function pointer.
1070 * @param enmDir Audio direction to enable or disable driver for.
1071 * @param fEnable Whether to enable or disable the specified audio direction.
1072 */
1073 DECLR3CALLBACKMEMBER(int, pfnEnable, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir, bool fEnable));
1074
1075 /**
1076 * Returns whether the given audio direction for this driver is enabled or not.
1077 *
1078 * @returns True if audio is enabled for the given direction, false if not.
1079 * @param pInterface Pointer to the interface structure containing the called function pointer.
1080 * @param enmDir Audio direction to retrieve enabled status for.
1081 */
1082 DECLR3CALLBACKMEMBER(bool, pfnIsEnabled, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
1083
1084 /**
1085 * Retrieves the current configuration of the host audio backend.
1086 *
1087 * @returns VBox status code.
1088 * @param pInterface Pointer to the interface structure containing the called function pointer.
1089 * @param pCfg Where to store the host audio backend configuration data.
1090 */
1091 DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOBACKENDCFG pCfg));
1092
1093 /**
1094 * Retrieves the current status of the host audio backend.
1095 *
1096 * @returns Status of the host audio backend.
1097 * @param pInterface Pointer to the interface structure containing the called function pointer.
1098 * @param enmDir Audio direction to check host audio backend for. Specify PDMAUDIODIR_ANY for the overall
1099 * backend status.
1100 */
1101 DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
1102
1103 /**
1104 * Creates an audio stream.
1105 *
1106 * @returns VBox status code.
1107 * @param pInterface Pointer to the interface structure containing the called function pointer.
1108 * @param pCfgHost Stream configuration for host side.
1109 * @param pCfgGuest Stream configuration for guest side.
1110 * @param ppStream Pointer where to return the created audio stream on success.
1111 */
1112 DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfgHost, PPDMAUDIOSTREAMCFG pCfgGuest, PPDMAUDIOSTREAM *ppStream));
1113
1114 /**
1115 * Destroys an audio stream.
1116 *
1117 * @param pInterface Pointer to the interface structure containing the called function pointer.
1118 * @param pStream Pointer to audio stream.
1119 */
1120 DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1121
1122 /**
1123 * Adds a reference to the specified audio stream.
1124 *
1125 * @returns New reference count. UINT32_MAX on error.
1126 * @param pInterface Pointer to the interface structure containing the called function pointer.
1127 * @param pStream Pointer to audio stream adding the reference to.
1128 */
1129 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRetain, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1130
1131 /**
1132 * Releases a reference from the specified stream.
1133 *
1134 * @returns New reference count. UINT32_MAX on error.
1135 * @param pInterface Pointer to the interface structure containing the called function pointer.
1136 * @param pStream Pointer to audio stream releasing a reference from.
1137 */
1138 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRelease, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1139
1140 /**
1141 * Reads PCM audio data from the host (input).
1142 *
1143 * @returns VBox status code.
1144 * @param pInterface Pointer to the interface structure containing the called function pointer.
1145 * @param pStream Pointer to audio stream to write to.
1146 * @param pvBuf Where to store the read data.
1147 * @param cbBuf Number of bytes to read.
1148 * @param pcbRead Bytes of audio data read. Optional.
1149 */
1150 DECLR3CALLBACKMEMBER(int, pfnStreamRead, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, void *pvBuf, uint32_t cbBuf, uint32_t *pcbRead));
1151
1152 /**
1153 * Writes PCM audio data to the host (output).
1154 *
1155 * @returns VBox status code.
1156 * @param pInterface Pointer to the interface structure containing the called function pointer.
1157 * @param pStream Pointer to audio stream to read from.
1158 * @param pvBuf Audio data to be written.
1159 * @param cbBuf Number of bytes to be written.
1160 * @param pcbWritten Bytes of audio data written. Optional.
1161 */
1162 DECLR3CALLBACKMEMBER(int, pfnStreamWrite, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, const void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten));
1163
1164 /**
1165 * Controls a specific audio stream.
1166 *
1167 * @returns VBox status code.
1168 * @param pInterface Pointer to the interface structure containing the called function pointer.
1169 * @param pStream Pointer to audio stream.
1170 * @param enmStreamCmd The stream command to issue.
1171 */
1172 DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd));
1173
1174 /**
1175 * Processes stream data.
1176 *
1177 * @param pInterface Pointer to the interface structure containing the called function pointer.
1178 * @param pStream Pointer to audio stream.
1179 */
1180 DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1181
1182 /**
1183 * Returns the number of readable data (in bytes) of a specific audio input stream.
1184 *
1185 * @returns Number of readable data (in bytes).
1186 * @param pInterface Pointer to the interface structure containing the called function pointer.
1187 * @param pStream Pointer to audio stream.
1188 */
1189 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1190
1191 /**
1192 * Returns the number of writable data (in bytes) of a specific audio output stream.
1193 *
1194 * @returns Number of writable data (in bytes).
1195 * @param pInterface Pointer to the interface structure containing the called function pointer.
1196 * @param pStream Pointer to audio stream.
1197 */
1198 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1199
1200 /**
1201 * Returns the status of a specific audio stream.
1202 *
1203 * @returns Audio stream status
1204 * @param pInterface Pointer to the interface structure containing the called function pointer.
1205 * @param pStream Pointer to audio stream.
1206 */
1207 DECLR3CALLBACKMEMBER(PDMAUDIOSTREAMSTS, pfnStreamGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1208
1209 /**
1210 * Sets the audio volume of a specific audio stream.
1211 *
1212 * @returns VBox status code.
1213 * @param pInterface Pointer to the interface structure containing the called function pointer.
1214 * @param pStream Pointer to audio stream.
1215 * @param pVol Pointer to audio volume structure to set the stream's audio volume to.
1216 */
1217 DECLR3CALLBACKMEMBER(int, pfnStreamSetVolume, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOVOLUME pVol));
1218
1219 /**
1220 * Plays (transfers) available audio frames via the host backend. Only works with output streams.
1221 *
1222 * @returns VBox status code.
1223 * @param pInterface Pointer to the interface structure containing the called function pointer.
1224 * @param pStream Pointer to audio stream.
1225 * @param pcFramesPlayed Number of frames played. Optional.
1226 */
1227 DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcFramesPlayed));
1228
1229 /**
1230 * Captures (transfers) available audio frames from the host backend. Only works with input streams.
1231 *
1232 * @returns VBox status code.
1233 * @param pInterface Pointer to the interface structure containing the called function pointer.
1234 * @param pStream Pointer to audio stream.
1235 * @param pcFramesCaptured Number of frames captured. Optional.
1236 */
1237 DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcFramesCaptured));
1238
1239 /**
1240 * Registers (device) callbacks.
1241 * This is handy for letting the device emulation know of certain events, e.g. processing input / output data
1242 * or configuration changes.
1243 *
1244 * @returns VBox status code.
1245 * @param pInterface Pointer to the interface structure containing the called function pointer.
1246 * @param paCallbacks Pointer to array of callbacks to register.
1247 * @param cCallbacks Number of callbacks to register.
1248 */
1249 DECLR3CALLBACKMEMBER(int, pfnRegisterCallbacks, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOCBRECORD paCallbacks, size_t cCallbacks));
1250
1251} PDMIAUDIOCONNECTOR;
1252
1253/** PDMIAUDIOCONNECTOR interface ID. */
1254#define PDMIAUDIOCONNECTOR_IID "A643B40C-733F-4307-9549-070AF0EE0ED6"
1255
1256/**
1257 * Assigns all needed interface callbacks for an audio backend.
1258 *
1259 * @param a_Prefix The function name prefix.
1260 */
1261#define PDMAUDIO_IHOSTAUDIO_CALLBACKS(a_Prefix) \
1262 do { \
1263 pThis->IHostAudio.pfnInit = RT_CONCAT(a_Prefix,Init); \
1264 pThis->IHostAudio.pfnShutdown = RT_CONCAT(a_Prefix,Shutdown); \
1265 pThis->IHostAudio.pfnGetConfig = RT_CONCAT(a_Prefix,GetConfig); \
1266 /** @todo Add pfnGetDevices here as soon as supported by all backends. */ \
1267 pThis->IHostAudio.pfnGetStatus = RT_CONCAT(a_Prefix,GetStatus); \
1268 /** @todo Ditto for pfnSetCallback. */ \
1269 pThis->IHostAudio.pfnStreamCreate = RT_CONCAT(a_Prefix,StreamCreate); \
1270 pThis->IHostAudio.pfnStreamDestroy = RT_CONCAT(a_Prefix,StreamDestroy); \
1271 pThis->IHostAudio.pfnStreamControl = RT_CONCAT(a_Prefix,StreamControl); \
1272 pThis->IHostAudio.pfnStreamGetReadable = RT_CONCAT(a_Prefix,StreamGetReadable); \
1273 pThis->IHostAudio.pfnStreamGetWritable = RT_CONCAT(a_Prefix,StreamGetWritable); \
1274 pThis->IHostAudio.pfnStreamGetStatus = RT_CONCAT(a_Prefix,StreamGetStatus); \
1275 pThis->IHostAudio.pfnStreamIterate = RT_CONCAT(a_Prefix,StreamIterate); \
1276 pThis->IHostAudio.pfnStreamPlay = RT_CONCAT(a_Prefix,StreamPlay); \
1277 pThis->IHostAudio.pfnStreamCapture = RT_CONCAT(a_Prefix,StreamCapture); \
1278 } while (0)
1279
1280/**
1281 * PDM host audio interface.
1282 */
1283typedef struct PDMIHOSTAUDIO
1284{
1285 /**
1286 * Initializes the host backend (driver).
1287 *
1288 * @returns VBox status code.
1289 * @param pInterface Pointer to the interface structure containing the called function pointer.
1290 */
1291 DECLR3CALLBACKMEMBER(int, pfnInit, (PPDMIHOSTAUDIO pInterface));
1292
1293 /**
1294 * Shuts down the host backend (driver).
1295 *
1296 * @returns VBox status code.
1297 * @param pInterface Pointer to the interface structure containing the called function pointer.
1298 */
1299 DECLR3CALLBACKMEMBER(void, pfnShutdown, (PPDMIHOSTAUDIO pInterface));
1300
1301 /**
1302 * Returns the host backend's configuration (backend).
1303 *
1304 * @returns VBox status code.
1305 * @param pInterface Pointer to the interface structure containing the called function pointer.
1306 * @param pBackendCfg Where to store the backend audio configuration to.
1307 */
1308 DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg));
1309
1310 /**
1311 * Returns (enumerates) host audio device information.
1312 *
1313 * @returns VBox status code.
1314 * @param pInterface Pointer to the interface structure containing the called function pointer.
1315 * @param pDeviceEnum Where to return the enumerated audio devices.
1316 */
1317 DECLR3CALLBACKMEMBER(int, pfnGetDevices, (PPDMIHOSTAUDIO pInterface, PPDMAUDIODEVICEENUM pDeviceEnum));
1318
1319 /**
1320 * Returns the current status from the audio backend.
1321 *
1322 * @returns PDMAUDIOBACKENDSTS enum.
1323 * @param pInterface Pointer to the interface structure containing the called function pointer.
1324 * @param enmDir Audio direction to get status for. Pass PDMAUDIODIR_ANY for overall status.
1325 */
1326 DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir));
1327
1328 /**
1329 * Sets a callback the audio backend can call. Optional.
1330 *
1331 * @returns VBox status code.
1332 * @param pInterface Pointer to the interface structure containing the called function pointer.
1333 * @param pfnCallback The callback function to use, or NULL when unregistering.
1334 */
1335 DECLR3CALLBACKMEMBER(int, pfnSetCallback, (PPDMIHOSTAUDIO pInterface, PFNPDMHOSTAUDIOCALLBACK pfnCallback));
1336
1337 /**
1338 * Creates an audio stream using the requested stream configuration.
1339 * If a backend is not able to create this configuration, it will return its best match in the acquired configuration
1340 * structure on success.
1341 *
1342 * @returns VBox status code.
1343 * @param pInterface Pointer to the interface structure containing the called function pointer.
1344 * @param pStream Pointer to audio stream.
1345 * @param pCfgReq Pointer to requested stream configuration.
1346 * @param pCfgAcq Pointer to acquired stream configuration.
1347 */
1348 DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq));
1349
1350 /**
1351 * Destroys an audio stream.
1352 *
1353 * @returns VBox status code.
1354 * @param pInterface Pointer to the interface structure containing the called function pointer.
1355 * @param pStream Pointer to audio stream.
1356 */
1357 DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1358
1359 /**
1360 * Controls an audio stream.
1361 *
1362 * @returns VBox status code.
1363 * @param pInterface Pointer to the interface structure containing the called function pointer.
1364 * @param pStream Pointer to audio stream.
1365 * @param enmStreamCmd The stream command to issue.
1366 */
1367 DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd));
1368
1369 /**
1370 * Returns the amount which is readable from the audio (input) stream.
1371 *
1372 * @returns For non-raw layout streams: Number of readable bytes.
1373 * for raw layout streams : Number of readable audio frames.
1374 * @param pInterface Pointer to the interface structure containing the called function pointer.
1375 * @param pStream Pointer to audio stream.
1376 */
1377 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1378
1379 /**
1380 * Returns the amount which is writable to the audio (output) stream.
1381 *
1382 * @returns For non-raw layout streams: Number of writable bytes.
1383 * for raw layout streams : Number of writable audio frames.
1384 * @param pInterface Pointer to the interface structure containing the called function pointer.
1385 * @param pStream Pointer to audio stream.
1386 */
1387 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1388
1389 /**
1390 * Returns the amount which is pending (in other words has not yet been processed) by/from the backend yet.
1391 * Optional.
1392 *
1393 * For input streams this is read audio data by the backend which has not been processed by the host yet.
1394 * For output streams this is written audio data to the backend which has not been processed by the backend yet.
1395 *
1396 * @returns For non-raw layout streams: Number of pending bytes.
1397 * for raw layout streams : Number of pending audio frames.
1398 * @param pInterface Pointer to the interface structure containing the called function pointer.
1399 * @param pStream Pointer to audio stream.
1400 */
1401 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetPending, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1402
1403 /**
1404 * Returns the current status of the given backend stream.
1405 *
1406 * @returns PDMAUDIOSTREAMSTS
1407 * @param pInterface Pointer to the interface structure containing the called function pointer.
1408 * @param pStream Pointer to audio stream.
1409 */
1410 DECLR3CALLBACKMEMBER(PDMAUDIOSTREAMSTS, pfnStreamGetStatus, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1411
1412 /**
1413 * Gives the host backend the chance to do some (necessary) iteration work.
1414 *
1415 * @returns VBox status code.
1416 * @param pInterface Pointer to the interface structure containing the called function pointer.
1417 * @param pStream Pointer to audio stream.
1418 */
1419 DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1420
1421 /**
1422 * Signals the backend that the host wants to begin playing for this iteration. Optional.
1423 *
1424 * @param pInterface Pointer to the interface structure containing the called function pointer.
1425 * @param pStream Pointer to audio stream.
1426 */
1427 DECLR3CALLBACKMEMBER(void, pfnStreamPlayBegin, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1428
1429 /**
1430 * Plays (writes to) an audio (output) stream.
1431 *
1432 * @returns VBox status code.
1433 * @param pInterface Pointer to the interface structure containing the called function pointer.
1434 * @param pStream Pointer to audio stream.
1435 * @param pvBuf Pointer to audio data buffer to play.
1436 * @param cxBuf For non-raw layout streams: Size (in bytes) of audio data buffer,
1437 * for raw layout streams : Size (in audio frames) of audio data buffer.
1438 * @param pcxWritten For non-raw layout streams: Returns number of bytes written. Optional.
1439 * for raw layout streams : Returns number of frames written. Optional.
1440 */
1441 DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, const void *pvBuf, uint32_t cxBuf, uint32_t *pcxWritten));
1442
1443 /**
1444 * Signals the backend that the host finished playing for this iteration. Optional.
1445 *
1446 * @param pInterface Pointer to the interface structure containing the called function pointer.
1447 * @param pStream Pointer to audio stream.
1448 */
1449 DECLR3CALLBACKMEMBER(void, pfnStreamPlayEnd, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1450
1451 /**
1452 * Signals the backend that the host wants to begin capturing for this iteration. Optional.
1453 *
1454 * @param pInterface Pointer to the interface structure containing the called function pointer.
1455 * @param pStream Pointer to audio stream.
1456 */
1457 DECLR3CALLBACKMEMBER(void, pfnStreamCaptureBegin, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1458
1459 /**
1460 * Captures (reads from) an audio (input) stream.
1461 *
1462 * @returns VBox status code.
1463 * @param pInterface Pointer to the interface structure containing the called function pointer.
1464 * @param pStream Pointer to audio stream.
1465 * @param pvBuf Buffer where to store read audio data.
1466 * @param cxBuf For non-raw layout streams: Size (in bytes) of audio data buffer,
1467 * for raw layout streams : Size (in audio frames) of audio data buffer.
1468 * @param pcxRead For non-raw layout streams: Returns number of bytes read. Optional.
1469 * for raw layout streams : Returns number of frames read. Optional.
1470 */
1471 DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, void *pvBuf, uint32_t cxBuf, uint32_t *pcxRead));
1472
1473 /**
1474 * Signals the backend that the host finished capturing for this iteration. Optional.
1475 *
1476 * @param pInterface Pointer to the interface structure containing the called function pointer.
1477 * @param pStream Pointer to audio stream.
1478 */
1479 DECLR3CALLBACKMEMBER(void, pfnStreamCaptureEnd, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1480
1481} PDMIHOSTAUDIO;
1482
1483/** PDMIHOSTAUDIO interface ID. */
1484#define PDMIHOSTAUDIO_IID "640F5A31-8245-491C-538F-29A0F9D08881"
1485
1486/** @} */
1487
1488#endif /* !___VBox_vmm_pdmaudioifs_h */
1489
注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

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