VirtualBox

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

Last change on this file since 68485 was 68485, checked in by vboxsync, 7 years ago

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

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