VirtualBox

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

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

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

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