VirtualBox

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

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

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