| 1 | /** @file
|
|---|
| 2 | * PDM - Pluggable Device Manager, Audio interfaces.
|
|---|
| 3 | */
|
|---|
| 4 |
|
|---|
| 5 | /*
|
|---|
| 6 | * Copyright (C) 2006-2020 Oracle Corporation
|
|---|
| 7 | *
|
|---|
| 8 | * This file is part of VirtualBox Open Source Edition (OSE), as
|
|---|
| 9 | * available from http://www.virtualbox.org. This file is free software;
|
|---|
| 10 | * you can redistribute it and/or modify it under the terms of the GNU
|
|---|
| 11 | * General Public License (GPL) as published by the Free Software
|
|---|
| 12 | * Foundation, in version 2 as it comes in the "COPYING" file of the
|
|---|
| 13 | * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
|---|
| 14 | * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
|---|
| 15 | *
|
|---|
| 16 | * The contents of this file may alternatively be used under the terms
|
|---|
| 17 | * of the Common Development and Distribution License Version 1.0
|
|---|
| 18 | * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
|
|---|
| 19 | * VirtualBox OSE distribution, in which case the provisions of the
|
|---|
| 20 | * CDDL are applicable instead of those of the GPL.
|
|---|
| 21 | *
|
|---|
| 22 | * You may elect to license modified versions of this file under the
|
|---|
| 23 | * terms and conditions of either the GPL or the CDDL or both.
|
|---|
| 24 | */
|
|---|
| 25 |
|
|---|
| 26 | /** @page pg_pdm_audio PDM Audio
|
|---|
| 27 | *
|
|---|
| 28 | * @section sec_pdm_audio_overview Audio architecture overview
|
|---|
| 29 | *
|
|---|
| 30 | * The audio architecture mainly consists of two PDM interfaces,
|
|---|
| 31 | * PDMIAUDIOCONNECTOR and PDMIHOSTAUDIO.
|
|---|
| 32 | *
|
|---|
| 33 | * The PDMIAUDIOCONNECTOR interface is responsible of connecting a device
|
|---|
| 34 | * emulation, such as SB16, AC'97 and HDA to one or multiple audio backend(s).
|
|---|
| 35 | * Its API abstracts audio stream handling and I/O functions, device enumeration
|
|---|
| 36 | * and so on.
|
|---|
| 37 | *
|
|---|
| 38 | * The PDMIHOSTAUDIO interface must be implemented by all audio backends to
|
|---|
| 39 | * provide an abstract and common way of accessing needed functions, such as
|
|---|
| 40 | * transferring output audio data for playing audio or recording input from the
|
|---|
| 41 | * host.
|
|---|
| 42 | *
|
|---|
| 43 | * A device emulation can have one or more LUNs attached to it, whereas these
|
|---|
| 44 | * LUNs in turn then all have their own PDMIAUDIOCONNECTOR, making it possible
|
|---|
| 45 | * to connect multiple backends to a certain device emulation stream
|
|---|
| 46 | * (multiplexing).
|
|---|
| 47 | *
|
|---|
| 48 | * An audio backend's job is to record and/or play audio data (depending on its
|
|---|
| 49 | * capabilities). It highly depends on the host it's running on and needs very
|
|---|
| 50 | * specific (host-OS-dependent) code. The backend itself only has very limited
|
|---|
| 51 | * ways of accessing and/or communicating with the PDMIAUDIOCONNECTOR interface
|
|---|
| 52 | * via callbacks, but never directly with the device emulation or other parts of
|
|---|
| 53 | * the audio sub system.
|
|---|
| 54 | *
|
|---|
| 55 | *
|
|---|
| 56 | * @section sec_pdm_audio_mixing Mixing
|
|---|
| 57 | *
|
|---|
| 58 | * The AUDIOMIXER API is optionally available to create and manage virtual audio
|
|---|
| 59 | * mixers. Such an audio mixer in turn then can be used by the device emulation
|
|---|
| 60 | * code to manage all the multiplexing to/from the connected LUN audio streams.
|
|---|
| 61 | *
|
|---|
| 62 | * Currently only input and output stream are supported. Duplex stream are not
|
|---|
| 63 | * supported yet.
|
|---|
| 64 | *
|
|---|
| 65 | * This also is handy if certain LUN audio streams should be added or removed
|
|---|
| 66 | * during runtime.
|
|---|
| 67 | *
|
|---|
| 68 | * To create a group of either input or output streams the AUDMIXSINK API can be
|
|---|
| 69 | * used.
|
|---|
| 70 | *
|
|---|
| 71 | * For example: The device emulation has one hardware output stream (HW0), and
|
|---|
| 72 | * that output stream shall be available to all connected LUN backends. For that
|
|---|
| 73 | * to happen, an AUDMIXSINK sink has to be created and attached to the device's
|
|---|
| 74 | * AUDIOMIXER object.
|
|---|
| 75 | *
|
|---|
| 76 | * As every LUN has its own AUDMIXSTREAM object, adding all those
|
|---|
| 77 | * objects to the just created audio mixer sink will do the job.
|
|---|
| 78 | *
|
|---|
| 79 | * @note The AUDIOMIXER API is purely optional and is not used by all currently
|
|---|
| 80 | * implemented device emulations (e.g. SB16).
|
|---|
| 81 | *
|
|---|
| 82 | *
|
|---|
| 83 | * @section sec_pdm_audio_data_processing Data processing
|
|---|
| 84 | *
|
|---|
| 85 | * Audio input / output data gets handed off to/from the device emulation in an
|
|---|
| 86 | * unmodified (raw) way. The actual audio frame / sample conversion is done via
|
|---|
| 87 | * the PDMAUDIOMIXBUF API.
|
|---|
| 88 | *
|
|---|
| 89 | * This concentrates the audio data processing in one place and makes it easier
|
|---|
| 90 | * to test / benchmark such code.
|
|---|
| 91 | *
|
|---|
| 92 | * A PDMAUDIOFRAME is the internal representation of a single audio frame, which
|
|---|
| 93 | * consists of a single left and right audio sample in time. Only mono (1) and
|
|---|
| 94 | * stereo (2) channel(s) currently are supported.
|
|---|
| 95 | *
|
|---|
| 96 | *
|
|---|
| 97 | * @section sec_pdm_audio_timing Timing
|
|---|
| 98 | *
|
|---|
| 99 | * Handling audio data in a virtual environment is hard, as the human perception
|
|---|
| 100 | * is very sensitive to the slightest cracks and stutters in the audible data.
|
|---|
| 101 | * This can happen if the VM's timing is lagging behind or not within the
|
|---|
| 102 | * expected time frame.
|
|---|
| 103 | *
|
|---|
| 104 | * The two main components which unfortunately contradict each other is a) the
|
|---|
| 105 | * audio device emulation and b) the audio backend(s) on the host. Those need to
|
|---|
| 106 | * be served in a timely manner to function correctly. To make e.g. the device
|
|---|
| 107 | * emulation rely on the pace the host backend(s) set - or vice versa - will not
|
|---|
| 108 | * work, as the guest's audio system / drivers then will not be able to
|
|---|
| 109 | * compensate this accordingly.
|
|---|
| 110 | *
|
|---|
| 111 | * So each component, the device emulation, the audio connector(s) and the
|
|---|
| 112 | * backend(s) must do its thing *when* it needs to do it, independently of the
|
|---|
| 113 | * others. For that we use various (small) ring buffers to (hopefully) serve all
|
|---|
| 114 | * components with the amount of data *when* they need it.
|
|---|
| 115 | *
|
|---|
| 116 | * Additionally, the device emulation can run with a different audio frame size,
|
|---|
| 117 | * while the backends(s) may require a different frame size (16 bit stereo
|
|---|
| 118 | * -> 8 bit mono, for example).
|
|---|
| 119 | *
|
|---|
| 120 | * The device emulation can give the audio connector(s) a scheduling hint
|
|---|
| 121 | * (optional), e.g. in which interval it expects any data processing.
|
|---|
| 122 | *
|
|---|
| 123 | * A data transfer for playing audio data from the guest on the host looks like
|
|---|
| 124 | * this: (RB = Ring Buffer, MB = Mixing Buffer)
|
|---|
| 125 | *
|
|---|
| 126 | * (A) Device DMA -> (B) Device RB -> (C) Audio Connector %Guest MB -> (D) Audio
|
|---|
| 127 | * Connector %Host MB -> (E) Backend RB (optional, up to the backend) -> (F)
|
|---|
| 128 | * Backend audio framework.
|
|---|
| 129 | *
|
|---|
| 130 | * When capturing audio data the chain is similar to the above one, just in a
|
|---|
| 131 | * different direction, of course.
|
|---|
| 132 | *
|
|---|
| 133 | * The audio connector hereby plays a key role when it comes to (pre-)buffering
|
|---|
| 134 | * data to minimize any audio stutters and/or cracks. The following values,
|
|---|
| 135 | * which also can be tweaked via CFGM / extra-data are available:
|
|---|
| 136 | *
|
|---|
| 137 | * - The pre-buffering time (in ms): Audio data which needs to be buffered
|
|---|
| 138 | * before any playback (or capturing) can happen.
|
|---|
| 139 | * - The actual buffer size (in ms): How big the mixing buffer (for C and D)
|
|---|
| 140 | * will be.
|
|---|
| 141 | * - The period size (in ms): How big a chunk of audio (often called period or
|
|---|
| 142 | * fragment) for F must be to get handled correctly.
|
|---|
| 143 | *
|
|---|
| 144 | * The above values can be set on a per-driver level, whereas input and output
|
|---|
| 145 | * streams for a driver also can be handled set independently. The verbose audio
|
|---|
| 146 | * (release) log will tell about the (final) state of each audio stream.
|
|---|
| 147 | *
|
|---|
| 148 | *
|
|---|
| 149 | * @section sec_pdm_audio_diagram Diagram
|
|---|
| 150 | *
|
|---|
| 151 | * @todo r=bird: Not quite able to make sense of this, esp. the
|
|---|
| 152 | * AUDMIXSINK/AUDIOMIXER bits crossing the LUN connections.
|
|---|
| 153 | *
|
|---|
| 154 | * @verbatim
|
|---|
| 155 | +----------------------------------+
|
|---|
| 156 | |Device (SB16 / AC'97 / HDA) |
|
|---|
| 157 | |----------------------------------|
|
|---|
| 158 | |AUDIOMIXER (Optional) |
|
|---|
| 159 | |AUDMIXSINK0 (Optional) |
|
|---|
| 160 | |AUDMIXSINK1 (Optional) |
|
|---|
| 161 | |AUDMIXSINKn (Optional) |
|
|---|
| 162 | | |
|
|---|
| 163 | | L L L |
|
|---|
| 164 | | U U U |
|
|---|
| 165 | | N N N |
|
|---|
| 166 | | 0 1 n |
|
|---|
| 167 | +-----+----+----+------------------+
|
|---|
| 168 | | | |
|
|---|
| 169 | | | |
|
|---|
| 170 | +--------------+ | | | +-------------+
|
|---|
| 171 | |AUDMIXSINK | | | | |AUDIOMIXER |
|
|---|
| 172 | |--------------| | | | |-------------|
|
|---|
| 173 | |AUDMIXSTREAM0 |+-|----|----|-->|AUDMIXSINK0 |
|
|---|
| 174 | |AUDMIXSTREAM1 |+-|----|----|-->|AUDMIXSINK1 |
|
|---|
| 175 | |AUDMIXSTREAMn |+-|----|----|-->|AUDMIXSINKn |
|
|---|
| 176 | +--------------+ | | | +-------------+
|
|---|
| 177 | | | |
|
|---|
| 178 | | | |
|
|---|
| 179 | +----+----+----+----+
|
|---|
| 180 | |LUN |
|
|---|
| 181 | |-------------------|
|
|---|
| 182 | |PDMIAUDIOCONNECTOR |
|
|---|
| 183 | |AUDMIXSTREAM |
|
|---|
| 184 | | +------+
|
|---|
| 185 | | | |
|
|---|
| 186 | | | |
|
|---|
| 187 | | | |
|
|---|
| 188 | +-------------------+ |
|
|---|
| 189 | |
|
|---|
| 190 | +-------------------------+ |
|
|---|
| 191 | +-------------------------+ +----+--------------------+
|
|---|
| 192 | |PDMAUDIOSTREAM | |PDMIAUDIOCONNECTOR |
|
|---|
| 193 | |-------------------------| |-------------------------|
|
|---|
| 194 | |PDMAUDIOMIXBUF |+------>|PDMAUDIOSTREAM Host |
|
|---|
| 195 | |PDMAUDIOSTREAMCFG |+------>|PDMAUDIOSTREAM Guest |
|
|---|
| 196 | | | |Device capabilities |
|
|---|
| 197 | | | |Device configuration |
|
|---|
| 198 | | | | |
|
|---|
| 199 | | | +--+|PDMIHOSTAUDIO |
|
|---|
| 200 | | | | |+-----------------------+|
|
|---|
| 201 | +-------------------------+ | ||Backend storage space ||
|
|---|
| 202 | | |+-----------------------+|
|
|---|
| 203 | | +-------------------------+
|
|---|
| 204 | |
|
|---|
| 205 | +---------------------+ |
|
|---|
| 206 | |PDMIHOSTAUDIO | |
|
|---|
| 207 | |+--------------+ | |
|
|---|
| 208 | ||DirectSound | | |
|
|---|
| 209 | |+--------------+ | |
|
|---|
| 210 | | | |
|
|---|
| 211 | |+--------------+ | |
|
|---|
| 212 | ||PulseAudio | | |
|
|---|
| 213 | |+--------------+ |+-------+
|
|---|
| 214 | | |
|
|---|
| 215 | |+--------------+ |
|
|---|
| 216 | ||Core Audio | |
|
|---|
| 217 | |+--------------+ |
|
|---|
| 218 | | |
|
|---|
| 219 | | |
|
|---|
| 220 | | |
|
|---|
| 221 | | |
|
|---|
| 222 | +---------------------+
|
|---|
| 223 | @endverbatim
|
|---|
| 224 | */
|
|---|
| 225 |
|
|---|
| 226 | #ifndef VBOX_INCLUDED_vmm_pdmaudioifs_h
|
|---|
| 227 | #define VBOX_INCLUDED_vmm_pdmaudioifs_h
|
|---|
| 228 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
|---|
| 229 | # pragma once
|
|---|
| 230 | #endif
|
|---|
| 231 |
|
|---|
| 232 | #include <iprt/assertcompile.h>
|
|---|
| 233 | #include <iprt/circbuf.h>
|
|---|
| 234 | #include <iprt/list.h>
|
|---|
| 235 | #include <iprt/path.h>
|
|---|
| 236 |
|
|---|
| 237 | #include <VBox/types.h>
|
|---|
| 238 | #include <VBox/vmm/pdmcommon.h>
|
|---|
| 239 | #include <VBox/vmm/stam.h>
|
|---|
| 240 |
|
|---|
| 241 | /** @defgroup grp_pdm_ifs_audio PDM Audio Interfaces
|
|---|
| 242 | * @ingroup grp_pdm_interfaces
|
|---|
| 243 | * @{
|
|---|
| 244 | */
|
|---|
| 245 |
|
|---|
| 246 | #ifndef VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH
|
|---|
| 247 | # if defined(RT_OS_WINDOWS) || defined(RT_OS_OS2)
|
|---|
| 248 | # define VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "c:\\temp\\"
|
|---|
| 249 | # else
|
|---|
| 250 | # define VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "/tmp/"
|
|---|
| 251 | # endif
|
|---|
| 252 | #endif
|
|---|
| 253 |
|
|---|
| 254 | /** PDM audio driver instance flags. */
|
|---|
| 255 | typedef uint32_t PDMAUDIODRVFLAGS;
|
|---|
| 256 |
|
|---|
| 257 | /** No flags set. */
|
|---|
| 258 | #define PDMAUDIODRVFLAGS_NONE 0
|
|---|
| 259 | /** Marks a primary audio driver which is critical
|
|---|
| 260 | * when running the VM. */
|
|---|
| 261 | #define PDMAUDIODRVFLAGS_PRIMARY RT_BIT(0)
|
|---|
| 262 |
|
|---|
| 263 | /**
|
|---|
| 264 | * Audio format in signed or unsigned variants.
|
|---|
| 265 | */
|
|---|
| 266 | typedef enum PDMAUDIOFMT
|
|---|
| 267 | {
|
|---|
| 268 | /** Invalid format, do not use. */
|
|---|
| 269 | PDMAUDIOFMT_INVALID = 0,
|
|---|
| 270 | /** 8-bit, unsigned. */
|
|---|
| 271 | PDMAUDIOFMT_U8,
|
|---|
| 272 | /** 8-bit, signed. */
|
|---|
| 273 | PDMAUDIOFMT_S8,
|
|---|
| 274 | /** 16-bit, unsigned. */
|
|---|
| 275 | PDMAUDIOFMT_U16,
|
|---|
| 276 | /** 16-bit, signed. */
|
|---|
| 277 | PDMAUDIOFMT_S16,
|
|---|
| 278 | /** 32-bit, unsigned. */
|
|---|
| 279 | PDMAUDIOFMT_U32,
|
|---|
| 280 | /** 32-bit, signed. */
|
|---|
| 281 | PDMAUDIOFMT_S32,
|
|---|
| 282 | /** End of valid values. */
|
|---|
| 283 | PDMAUDIOFMT_END,
|
|---|
| 284 | /** Hack to blow the type up to 32-bit. */
|
|---|
| 285 | PDMAUDIOFMT_32BIT_HACK = 0x7fffffff
|
|---|
| 286 | } PDMAUDIOFMT;
|
|---|
| 287 |
|
|---|
| 288 | /**
|
|---|
| 289 | * Audio direction.
|
|---|
| 290 | */
|
|---|
| 291 | typedef enum PDMAUDIODIR
|
|---|
| 292 | {
|
|---|
| 293 | /** Invalid zero value as per usual (guards against using unintialized values). */
|
|---|
| 294 | PDMAUDIODIR_INVALID = 0,
|
|---|
| 295 | /** Unknown direction. */
|
|---|
| 296 | PDMAUDIODIR_UNKNOWN,
|
|---|
| 297 | /** Input. */
|
|---|
| 298 | PDMAUDIODIR_IN,
|
|---|
| 299 | /** Output. */
|
|---|
| 300 | PDMAUDIODIR_OUT,
|
|---|
| 301 | /** Duplex handling. */
|
|---|
| 302 | PDMAUDIODIR_DUPLEX,
|
|---|
| 303 | /** End of valid values. */
|
|---|
| 304 | PDMAUDIODIR_END,
|
|---|
| 305 | /** Hack to blow the type up to 32-bit. */
|
|---|
| 306 | PDMAUDIODIR_32BIT_HACK = 0x7fffffff
|
|---|
| 307 | } PDMAUDIODIR;
|
|---|
| 308 |
|
|---|
| 309 | /** Device latency spec in milliseconds (ms). */
|
|---|
| 310 | typedef uint32_t PDMAUDIODEVLATSPECMS;
|
|---|
| 311 |
|
|---|
| 312 | /** Device latency spec in seconds (s). */
|
|---|
| 313 | typedef uint32_t PDMAUDIODEVLATSPECSEC;
|
|---|
| 314 |
|
|---|
| 315 | /** @name PDMAUDIOHOSTDEV_F_XXX
|
|---|
| 316 | * @{ */
|
|---|
| 317 | /** No flags set. */
|
|---|
| 318 | #define PDMAUDIOHOSTDEV_F_NONE UINT32_C(0)
|
|---|
| 319 | /** The device marks the default device within the host OS. */
|
|---|
| 320 | #define PDMAUDIOHOSTDEV_F_DEFAULT RT_BIT_32(0)
|
|---|
| 321 | /** The device can be removed at any time and we have to deal with it. */
|
|---|
| 322 | #define PDMAUDIOHOSTDEV_F_HOTPLUG RT_BIT_32(1)
|
|---|
| 323 | /** The device is known to be buggy and needs special treatment. */
|
|---|
| 324 | #define PDMAUDIOHOSTDEV_F_BUGGY RT_BIT_32(2)
|
|---|
| 325 | /** Ignore the device, no matter what. */
|
|---|
| 326 | #define PDMAUDIOHOSTDEV_F_IGNORE RT_BIT_32(3)
|
|---|
| 327 | /** The device is present but marked as locked by some other application. */
|
|---|
| 328 | #define PDMAUDIOHOSTDEV_F_LOCKED RT_BIT_32(4)
|
|---|
| 329 | /** The device is present but not in an alive state (dead). */
|
|---|
| 330 | #define PDMAUDIOHOSTDEV_F_DEAD RT_BIT_32(5)
|
|---|
| 331 | /** Set if the extra backend specific data cannot be duplicated. */
|
|---|
| 332 | #define PDMAUDIOHOSTDEV_F_NO_DUP RT_BIT_32(31)
|
|---|
| 333 | /** @} */
|
|---|
| 334 |
|
|---|
| 335 | /**
|
|---|
| 336 | * Audio device type.
|
|---|
| 337 | */
|
|---|
| 338 | typedef enum PDMAUDIODEVICETYPE
|
|---|
| 339 | {
|
|---|
| 340 | /** Invalid zero value as per usual (guards against using unintialized values). */
|
|---|
| 341 | PDMAUDIODEVICETYPE_INVALID = 0,
|
|---|
| 342 | /** Unknown device type. This is the default. */
|
|---|
| 343 | PDMAUDIODEVICETYPE_UNKNOWN,
|
|---|
| 344 | /** Dummy device; for backends which are not able to report
|
|---|
| 345 | * actual device information (yet). */
|
|---|
| 346 | PDMAUDIODEVICETYPE_DUMMY,
|
|---|
| 347 | /** The device is built into the host (non-removable). */
|
|---|
| 348 | PDMAUDIODEVICETYPE_BUILTIN,
|
|---|
| 349 | /** The device is an (external) USB device. */
|
|---|
| 350 | PDMAUDIODEVICETYPE_USB,
|
|---|
| 351 | /** End of valid values. */
|
|---|
| 352 | PDMAUDIODEVICETYPE_END,
|
|---|
| 353 | /** Hack to blow the type up to 32-bit. */
|
|---|
| 354 | PDMAUDIODEVICETYPE_32BIT_HACK = 0x7fffffff
|
|---|
| 355 | } PDMAUDIODEVICETYPE;
|
|---|
| 356 |
|
|---|
| 357 | /**
|
|---|
| 358 | * Host audio device info, part of enumeration result.
|
|---|
| 359 | *
|
|---|
| 360 | * @sa PDMAUDIOHOSTENUM, PDMIHOSTAUDIO::pfnGetDevices
|
|---|
| 361 | */
|
|---|
| 362 | typedef struct PDMAUDIOHOSTDEV
|
|---|
| 363 | {
|
|---|
| 364 | /** List entry (like PDMAUDIOHOSTENUM::LstDevices). */
|
|---|
| 365 | RTLISTNODE ListEntry;
|
|---|
| 366 | /** Magic value (PDMAUDIOHOSTDEV_MAGIC). */
|
|---|
| 367 | uint32_t uMagic;
|
|---|
| 368 | /** Size of this structure and whatever backend specific data that follows it. */
|
|---|
| 369 | uint32_t cbSelf;
|
|---|
| 370 | /** The device type. */
|
|---|
| 371 | PDMAUDIODEVICETYPE enmType;
|
|---|
| 372 | /** Usage of the device. */
|
|---|
| 373 | PDMAUDIODIR enmUsage;
|
|---|
| 374 | /** Device flags, PDMAUDIOHOSTDEV_F_XXX. */
|
|---|
| 375 | uint32_t fFlags;
|
|---|
| 376 | /** Reference count indicating how many audio streams currently are relying on this device. */
|
|---|
| 377 | uint8_t cRefCount;
|
|---|
| 378 | /** Maximum number of input audio channels the device supports. */
|
|---|
| 379 | uint8_t cMaxInputChannels;
|
|---|
| 380 | /** Maximum number of output audio channels the device supports. */
|
|---|
| 381 | uint8_t cMaxOutputChannels;
|
|---|
| 382 | uint8_t bAlignment;
|
|---|
| 383 | /** Device type union, based on enmType. */
|
|---|
| 384 | union
|
|---|
| 385 | {
|
|---|
| 386 | /** USB type specifics. */
|
|---|
| 387 | struct
|
|---|
| 388 | {
|
|---|
| 389 | /** Vendor ID. */
|
|---|
| 390 | uint16_t idVendor;
|
|---|
| 391 | /** Product ID. */
|
|---|
| 392 | uint16_t idProduct;
|
|---|
| 393 | } USB;
|
|---|
| 394 | uint64_t uPadding[ARCH_BITS >= 64 ? 3 : 4];
|
|---|
| 395 | } Type;
|
|---|
| 396 | /** Friendly name of the device, if any. Could be truncated. */
|
|---|
| 397 | char szName[64];
|
|---|
| 398 | } PDMAUDIOHOSTDEV;
|
|---|
| 399 | AssertCompileSizeAlignment(PDMAUDIOHOSTDEV, 16);
|
|---|
| 400 | /** Pointer to audio device info (enumeration result). */
|
|---|
| 401 | typedef PDMAUDIOHOSTDEV *PPDMAUDIOHOSTDEV;
|
|---|
| 402 | /** Pointer to a const audio device info (enumeration result). */
|
|---|
| 403 | typedef PDMAUDIOHOSTDEV const *PCPDMAUDIOHOSTDEV;
|
|---|
| 404 |
|
|---|
| 405 | /** Magic value for PDMAUDIOHOSTDEV. */
|
|---|
| 406 | #define PDMAUDIOHOSTDEV_MAGIC PDM_VERSION_MAKE(0xa0d0, 1, 0)
|
|---|
| 407 |
|
|---|
| 408 |
|
|---|
| 409 | /**
|
|---|
| 410 | * A host audio device enumeration result.
|
|---|
| 411 | *
|
|---|
| 412 | * @sa PDMIHOSTAUDIO::pfnGetDevices
|
|---|
| 413 | */
|
|---|
| 414 | typedef struct PDMAUDIOHOSTENUM
|
|---|
| 415 | {
|
|---|
| 416 | /** Magic value (PDMAUDIOHOSTENUM_MAGIC). */
|
|---|
| 417 | uint32_t uMagic;
|
|---|
| 418 | /** Number of audio devices in the list. */
|
|---|
| 419 | uint32_t cDevices;
|
|---|
| 420 | /** List of audio devices (PDMAUDIOHOSTDEV). */
|
|---|
| 421 | RTLISTANCHOR LstDevices;
|
|---|
| 422 | } PDMAUDIOHOSTENUM;
|
|---|
| 423 | /** Pointer to an audio device enumeration result. */
|
|---|
| 424 | typedef PDMAUDIOHOSTENUM *PPDMAUDIOHOSTENUM;
|
|---|
| 425 | /** Pointer to a const audio device enumeration result. */
|
|---|
| 426 | typedef PDMAUDIOHOSTENUM const *PCPDMAUDIOHOSTENUM;
|
|---|
| 427 |
|
|---|
| 428 | /** Magic for the host audio device enumeration. */
|
|---|
| 429 | #define PDMAUDIOHOSTENUM_MAGIC PDM_VERSION_MAKE(0xa0d1, 1, 0)
|
|---|
| 430 |
|
|---|
| 431 |
|
|---|
| 432 | /**
|
|---|
| 433 | * Audio configuration (static) of an audio host backend.
|
|---|
| 434 | */
|
|---|
| 435 | typedef struct PDMAUDIOBACKENDCFG
|
|---|
| 436 | {
|
|---|
| 437 | /** The backend's friendly name. */
|
|---|
| 438 | char szName[32];
|
|---|
| 439 | /** Size (in bytes) of the host backend's audio output stream structure. */
|
|---|
| 440 | size_t cbStreamOut;
|
|---|
| 441 | /** Size (in bytes) of the host backend's audio input stream structure. */
|
|---|
| 442 | size_t cbStreamIn;
|
|---|
| 443 | /** Number of concurrent output (playback) streams supported on the host.
|
|---|
| 444 | * UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
|
|---|
| 445 | uint32_t cMaxStreamsOut;
|
|---|
| 446 | /** Number of concurrent input (recording) streams supported on the host.
|
|---|
| 447 | * UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
|
|---|
| 448 | uint32_t cMaxStreamsIn;
|
|---|
| 449 | } PDMAUDIOBACKENDCFG;
|
|---|
| 450 | /** Pointer to a static host audio audio configuration. */
|
|---|
| 451 | typedef PDMAUDIOBACKENDCFG *PPDMAUDIOBACKENDCFG;
|
|---|
| 452 |
|
|---|
| 453 | /**
|
|---|
| 454 | * A single audio frame.
|
|---|
| 455 | *
|
|---|
| 456 | * Currently only two (2) channels, left and right, are supported.
|
|---|
| 457 | *
|
|---|
| 458 | * @note When changing this structure, make sure to also handle
|
|---|
| 459 | * VRDP's input / output processing in DrvAudioVRDE, as VRDP
|
|---|
| 460 | * expects audio data in st_sample_t format (historical reasons)
|
|---|
| 461 | * which happens to be the same as PDMAUDIOFRAME for now.
|
|---|
| 462 | */
|
|---|
| 463 | typedef struct PDMAUDIOFRAME
|
|---|
| 464 | {
|
|---|
| 465 | /** Left channel. */
|
|---|
| 466 | int64_t i64LSample;
|
|---|
| 467 | /** Right channel. */
|
|---|
| 468 | int64_t i64RSample;
|
|---|
| 469 | } PDMAUDIOFRAME;
|
|---|
| 470 | /** Pointer to a single (stereo) audio frame. */
|
|---|
| 471 | typedef PDMAUDIOFRAME *PPDMAUDIOFRAME;
|
|---|
| 472 | /** Pointer to a const single (stereo) audio frame. */
|
|---|
| 473 | typedef PDMAUDIOFRAME const *PCPDMAUDIOFRAME;
|
|---|
| 474 |
|
|---|
| 475 | typedef enum PDMAUDIOENDIANNESS
|
|---|
| 476 | {
|
|---|
| 477 | /** The usual invalid value. */
|
|---|
| 478 | PDMAUDIOENDIANNESS_INVALID = 0,
|
|---|
| 479 | /** Little endian. */
|
|---|
| 480 | PDMAUDIOENDIANNESS_LITTLE,
|
|---|
| 481 | /** Bit endian. */
|
|---|
| 482 | PDMAUDIOENDIANNESS_BIG,
|
|---|
| 483 | /** Endianness doesn't have a meaning in the context. */
|
|---|
| 484 | PDMAUDIOENDIANNESS_NA,
|
|---|
| 485 | /** The end of the valid endian values (exclusive). */
|
|---|
| 486 | PDMAUDIOENDIANNESS_END,
|
|---|
| 487 | /** Hack to blow the type up to 32-bit. */
|
|---|
| 488 | PDMAUDIOENDIANNESS_32BIT_HACK = 0x7fffffff
|
|---|
| 489 | } PDMAUDIOENDIANNESS;
|
|---|
| 490 |
|
|---|
| 491 | /** @def PDMAUDIOHOSTENDIANNESS
|
|---|
| 492 | * The PDMAUDIOENDIANNESS value for the host. */
|
|---|
| 493 | #if defined(RT_LITTLE_ENDIAN)
|
|---|
| 494 | # define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_LITTLE
|
|---|
| 495 | #elif defined(RT_BIG_ENDIAN)
|
|---|
| 496 | # define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_BIG
|
|---|
| 497 | #else
|
|---|
| 498 | # error "Port me!"
|
|---|
| 499 | #endif
|
|---|
| 500 |
|
|---|
| 501 | /**
|
|---|
| 502 | * Audio playback destinations.
|
|---|
| 503 | */
|
|---|
| 504 | typedef enum PDMAUDIOPLAYBACKDST
|
|---|
| 505 | {
|
|---|
| 506 | /** Invalid zero value as per usual (guards against using unintialized values). */
|
|---|
| 507 | PDMAUDIOPLAYBACKDST_INVALID = 0,
|
|---|
| 508 | /** Unknown destination. */
|
|---|
| 509 | PDMAUDIOPLAYBACKDST_UNKNOWN,
|
|---|
| 510 | /** Front channel. */
|
|---|
| 511 | PDMAUDIOPLAYBACKDST_FRONT,
|
|---|
| 512 | /** Center / LFE (Subwoofer) channel. */
|
|---|
| 513 | PDMAUDIOPLAYBACKDST_CENTER_LFE,
|
|---|
| 514 | /** Rear channel. */
|
|---|
| 515 | PDMAUDIOPLAYBACKDST_REAR,
|
|---|
| 516 | /** End of valid values. */
|
|---|
| 517 | PDMAUDIOPLAYBACKDST_END,
|
|---|
| 518 | /** Hack to blow the type up to 32-bit. */
|
|---|
| 519 | PDMAUDIOPLAYBACKDST_32BIT_HACK = 0x7fffffff
|
|---|
| 520 | } PDMAUDIOPLAYBACKDST;
|
|---|
| 521 |
|
|---|
| 522 | /**
|
|---|
| 523 | * Audio recording sources.
|
|---|
| 524 | *
|
|---|
| 525 | * @note Because this is almost exclusively used in PDMAUDIODSTSRCUNION where it
|
|---|
| 526 | * overlaps with PDMAUDIOPLAYBACKDST, the values starts at 64 instead of 0.
|
|---|
| 527 | */
|
|---|
| 528 | typedef enum PDMAUDIORECSRC
|
|---|
| 529 | {
|
|---|
| 530 | /** Unknown recording source. */
|
|---|
| 531 | PDMAUDIORECSRC_UNKNOWN = 64,
|
|---|
| 532 | /** Microphone-In. */
|
|---|
| 533 | PDMAUDIORECSRC_MIC,
|
|---|
| 534 | /** CD. */
|
|---|
| 535 | PDMAUDIORECSRC_CD,
|
|---|
| 536 | /** Video-In. */
|
|---|
| 537 | PDMAUDIORECSRC_VIDEO,
|
|---|
| 538 | /** AUX. */
|
|---|
| 539 | PDMAUDIORECSRC_AUX,
|
|---|
| 540 | /** Line-In. */
|
|---|
| 541 | PDMAUDIORECSRC_LINE,
|
|---|
| 542 | /** Phone-In. */
|
|---|
| 543 | PDMAUDIORECSRC_PHONE,
|
|---|
| 544 | /** End of valid values. */
|
|---|
| 545 | PDMAUDIORECSRC_END,
|
|---|
| 546 | /** Hack to blow the type up to 32-bit. */
|
|---|
| 547 | PDMAUDIORECSRC_32BIT_HACK = 0x7fffffff
|
|---|
| 548 | } PDMAUDIORECSRC;
|
|---|
| 549 |
|
|---|
| 550 | /**
|
|---|
| 551 | * Union for keeping an audio stream destination or source.
|
|---|
| 552 | */
|
|---|
| 553 | typedef union PDMAUDIODSTSRCUNION
|
|---|
| 554 | {
|
|---|
| 555 | /** Desired playback destination (for an output stream). */
|
|---|
| 556 | PDMAUDIOPLAYBACKDST enmDst;
|
|---|
| 557 | /** Desired recording source (for an input stream). */
|
|---|
| 558 | PDMAUDIORECSRC enmSrc;
|
|---|
| 559 | } PDMAUDIODSTSRCUNION;
|
|---|
| 560 | /** Pointer to an audio stream src/dst union. */
|
|---|
| 561 | typedef PDMAUDIODSTSRCUNION *PPDMAUDIODSTSRCUNION;
|
|---|
| 562 |
|
|---|
| 563 | /**
|
|---|
| 564 | * Audio stream (data) layout.
|
|---|
| 565 | */
|
|---|
| 566 | typedef enum PDMAUDIOSTREAMLAYOUT
|
|---|
| 567 | {
|
|---|
| 568 | /** Invalid zero value as per usual (guards against using unintialized values). */
|
|---|
| 569 | PDMAUDIOSTREAMLAYOUT_INVALID = 0,
|
|---|
| 570 | /** Unknown access type; do not use (hdaR3StreamMapReset uses it). */
|
|---|
| 571 | PDMAUDIOSTREAMLAYOUT_UNKNOWN,
|
|---|
| 572 | /** Non-interleaved access, that is, consecutive access to the data.
|
|---|
| 573 | * @todo r=bird: For plain stereo this is actually interleaves left/right. What
|
|---|
| 574 | * I guess non-interleaved means, is that there are no additional
|
|---|
| 575 | * information interleaved next to the interleaved stereo.
|
|---|
| 576 | * https://stackoverflow.com/questions/17879933/whats-the-interleaved-audio */
|
|---|
| 577 | PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED,
|
|---|
| 578 | /** Interleaved access, where the data can be mixed together with data of other audio streams. */
|
|---|
| 579 | PDMAUDIOSTREAMLAYOUT_INTERLEAVED,
|
|---|
| 580 | /** Complex layout, which does not fit into the interleaved / non-interleaved layouts. */
|
|---|
| 581 | PDMAUDIOSTREAMLAYOUT_COMPLEX,
|
|---|
| 582 | /** Raw (pass through) data, with no data layout processing done.
|
|---|
| 583 | *
|
|---|
| 584 | * This means that this stream will operate on PDMAUDIOFRAME data
|
|---|
| 585 | * directly. Don't use this if you don't have to.
|
|---|
| 586 | *
|
|---|
| 587 | * @deprecated Replaced by S64 (signed, 64-bit sample size). */
|
|---|
| 588 | PDMAUDIOSTREAMLAYOUT_RAW,
|
|---|
| 589 | /** End of valid values. */
|
|---|
| 590 | PDMAUDIOSTREAMLAYOUT_END,
|
|---|
| 591 | /** Hack to blow the type up to 32-bit. */
|
|---|
| 592 | PDMAUDIOSTREAMLAYOUT_32BIT_HACK = 0x7fffffff
|
|---|
| 593 | } PDMAUDIOSTREAMLAYOUT;
|
|---|
| 594 |
|
|---|
| 595 | /**
|
|---|
| 596 | * Stream channel data block.
|
|---|
| 597 | */
|
|---|
| 598 | typedef struct PDMAUDIOSTREAMCHANNELDATA
|
|---|
| 599 | {
|
|---|
| 600 | /** Circular buffer for the channel data. */
|
|---|
| 601 | PRTCIRCBUF pCircBuf;
|
|---|
| 602 | /** Amount of audio data (in bytes) acquired for reading. */
|
|---|
| 603 | size_t cbAcq;
|
|---|
| 604 | /** Channel data flags, PDMAUDIOSTREAMCHANNELDATA_FLAGS_XXX. */
|
|---|
| 605 | uint32_t fFlags;
|
|---|
| 606 | } PDMAUDIOSTREAMCHANNELDATA;
|
|---|
| 607 | /** Pointer to audio stream channel data buffer. */
|
|---|
| 608 | typedef PDMAUDIOSTREAMCHANNELDATA *PPDMAUDIOSTREAMCHANNELDATA;
|
|---|
| 609 |
|
|---|
| 610 | /** @name PDMAUDIOSTREAMCHANNELDATA_FLAGS_XXX
|
|---|
| 611 | * @{ */
|
|---|
| 612 | /** No stream channel data flags defined. */
|
|---|
| 613 | #define PDMAUDIOSTREAMCHANNELDATA_FLAGS_NONE UINT32_C(0)
|
|---|
| 614 | /** @} */
|
|---|
| 615 |
|
|---|
| 616 | /**
|
|---|
| 617 | * Standard speaker channel IDs.
|
|---|
| 618 | *
|
|---|
| 619 | * This can cover up to 11.0 surround sound.
|
|---|
| 620 | *
|
|---|
| 621 | * @note Any of those channels can be marked / used as the LFE channel (played
|
|---|
| 622 | * through the subwoofer).
|
|---|
| 623 | */
|
|---|
| 624 | typedef enum PDMAUDIOSTREAMCHANNELID
|
|---|
| 625 | {
|
|---|
| 626 | /** Invalid zero value as per usual (guards against using unintialized values). */
|
|---|
| 627 | PDMAUDIOSTREAMCHANNELID_INVALID = 0,
|
|---|
| 628 | /** Unknown / not set channel ID. */
|
|---|
| 629 | PDMAUDIOSTREAMCHANNELID_UNKNOWN,
|
|---|
| 630 | /** Front left channel. */
|
|---|
| 631 | PDMAUDIOSTREAMCHANNELID_FRONT_LEFT,
|
|---|
| 632 | /** Front right channel. */
|
|---|
| 633 | PDMAUDIOSTREAMCHANNELID_FRONT_RIGHT,
|
|---|
| 634 | /** Front center channel. */
|
|---|
| 635 | PDMAUDIOSTREAMCHANNELID_FRONT_CENTER,
|
|---|
| 636 | /** Low frequency effects (subwoofer) channel. */
|
|---|
| 637 | PDMAUDIOSTREAMCHANNELID_LFE,
|
|---|
| 638 | /** Rear left channel. */
|
|---|
| 639 | PDMAUDIOSTREAMCHANNELID_REAR_LEFT,
|
|---|
| 640 | /** Rear right channel. */
|
|---|
| 641 | PDMAUDIOSTREAMCHANNELID_REAR_RIGHT,
|
|---|
| 642 | /** Front left of center channel. */
|
|---|
| 643 | PDMAUDIOSTREAMCHANNELID_FRONT_LEFT_OF_CENTER,
|
|---|
| 644 | /** Front right of center channel. */
|
|---|
| 645 | PDMAUDIOSTREAMCHANNELID_FRONT_RIGHT_OF_CENTER,
|
|---|
| 646 | /** Rear center channel. */
|
|---|
| 647 | PDMAUDIOSTREAMCHANNELID_REAR_CENTER,
|
|---|
| 648 | /** Side left channel. */
|
|---|
| 649 | PDMAUDIOSTREAMCHANNELID_SIDE_LEFT,
|
|---|
| 650 | /** Side right channel. */
|
|---|
| 651 | PDMAUDIOSTREAMCHANNELID_SIDE_RIGHT,
|
|---|
| 652 | /** Left height channel. */
|
|---|
| 653 | PDMAUDIOSTREAMCHANNELID_LEFT_HEIGHT,
|
|---|
| 654 | /** Right height channel. */
|
|---|
| 655 | PDMAUDIOSTREAMCHANNELID_RIGHT_HEIGHT,
|
|---|
| 656 | /** End of valid values. */
|
|---|
| 657 | PDMAUDIOSTREAMCHANNELID_END,
|
|---|
| 658 | /** Hack to blow the type up to 32-bit. */
|
|---|
| 659 | PDMAUDIOSTREAMCHANNELID_32BIT_HACK = 0x7fffffff
|
|---|
| 660 | } PDMAUDIOSTREAMCHANNELID;
|
|---|
| 661 |
|
|---|
| 662 | /**
|
|---|
| 663 | * Mappings channels onto an audio stream.
|
|---|
| 664 | *
|
|---|
| 665 | * The mappings are either for a single (mono) or dual (stereo) channels onto an
|
|---|
| 666 | * audio stream (aka stream profile). An audio stream consists of one or
|
|---|
| 667 | * multiple channels (e.g. 1 for mono, 2 for stereo), depending on the
|
|---|
| 668 | * configuration.
|
|---|
| 669 | */
|
|---|
| 670 | typedef struct PDMAUDIOSTREAMMAP
|
|---|
| 671 | {
|
|---|
| 672 | /** Array of channel IDs being handled.
|
|---|
| 673 | * @note The first (zero-based) index specifies the leftmost channel. */
|
|---|
| 674 | PDMAUDIOSTREAMCHANNELID aenmIDs[2];
|
|---|
| 675 | /** Step size (in bytes) to the channel's next frame. */
|
|---|
| 676 | uint32_t cbStep;
|
|---|
| 677 | /** Frame size (in bytes) of this channel. */
|
|---|
| 678 | uint32_t cbFrame;
|
|---|
| 679 | /** Byte offset to the first frame in the data block. */
|
|---|
| 680 | uint32_t offFirst;
|
|---|
| 681 | /** Byte offset to the next frame in the data block. */
|
|---|
| 682 | uint32_t offNext;
|
|---|
| 683 | /** Associated data buffer. */
|
|---|
| 684 | PDMAUDIOSTREAMCHANNELDATA Data;
|
|---|
| 685 | } PDMAUDIOSTREAMMAP;
|
|---|
| 686 | /** Pointer to an audio stream channel mapping. */
|
|---|
| 687 | typedef PDMAUDIOSTREAMMAP *PPDMAUDIOSTREAMMAP;
|
|---|
| 688 |
|
|---|
| 689 | /**
|
|---|
| 690 | * Properties of audio streams for host/guest for in or out directions.
|
|---|
| 691 | */
|
|---|
| 692 | typedef struct PDMAUDIOPCMPROPS
|
|---|
| 693 | {
|
|---|
| 694 | /** The frame size. */
|
|---|
| 695 | uint8_t cbFrame;
|
|---|
| 696 | /** Shift count used with PDMAUDIOPCMPROPS_F2B and PDMAUDIOPCMPROPS_B2F.
|
|---|
| 697 | * Depends on number of stream channels and the stream format being used, calc
|
|---|
| 698 | * value using PDMAUDIOPCMPROPS_MAKE_SHIFT.
|
|---|
| 699 | * @sa PDMAUDIOSTREAMCFG_B2F, PDMAUDIOSTREAMCFG_F2B */
|
|---|
| 700 | uint8_t cShiftX;
|
|---|
| 701 | /** Sample width (in bytes). */
|
|---|
| 702 | RT_GCC_EXTENSION
|
|---|
| 703 | uint8_t cbSampleX : 4;
|
|---|
| 704 | /** Number of audio channels. */
|
|---|
| 705 | RT_GCC_EXTENSION
|
|---|
| 706 | uint8_t cChannelsX : 4;
|
|---|
| 707 | /** Signed or unsigned sample. */
|
|---|
| 708 | bool fSigned : 1;
|
|---|
| 709 | /** Whether the endianness is swapped or not. */
|
|---|
| 710 | bool fSwapEndian : 1;
|
|---|
| 711 | /** Raw mixer frames, only applicable for signed 64-bit samples. */
|
|---|
| 712 | bool fRaw : 1;
|
|---|
| 713 | /** Sample frequency in Hertz (Hz). */
|
|---|
| 714 | uint32_t uHz;
|
|---|
| 715 | } PDMAUDIOPCMPROPS;
|
|---|
| 716 | AssertCompileSize(PDMAUDIOPCMPROPS, 8);
|
|---|
| 717 | AssertCompileSizeAlignment(PDMAUDIOPCMPROPS, 8);
|
|---|
| 718 | /** Pointer to audio stream properties. */
|
|---|
| 719 | typedef PDMAUDIOPCMPROPS *PPDMAUDIOPCMPROPS;
|
|---|
| 720 | /** Pointer to const audio stream properties. */
|
|---|
| 721 | typedef PDMAUDIOPCMPROPS const *PCPDMAUDIOPCMPROPS;
|
|---|
| 722 |
|
|---|
| 723 | /** @name Macros for use with PDMAUDIOPCMPROPS
|
|---|
| 724 | * @{ */
|
|---|
| 725 | /** Initializer for PDMAUDIOPCMPROPS. */
|
|---|
| 726 | #define PDMAUDIOPCMPROPS_INITIALIZER(a_cbSample, a_fSigned, a_cChannels, a_uHz, a_fSwapEndian) \
|
|---|
| 727 | { (a_cbSample) * (a_cChannels), PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS(a_cbSample, a_cChannels), a_cbSample, a_cChannels, \
|
|---|
| 728 | a_fSigned, a_fSwapEndian, false /*fRaw*/, a_uHz }
|
|---|
| 729 | /** Calculates the cShift value of given sample bits and audio channels.
|
|---|
| 730 | * @note Does only support mono/stereo channels for now, for non-stereo/mono we
|
|---|
| 731 | * returns a special value which the two conversion functions detect
|
|---|
| 732 | * and make them fall back on cbSample * cChannels. */
|
|---|
| 733 | #define PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS(cbSample, cChannels) \
|
|---|
| 734 | ( RT_IS_POWER_OF_TWO((unsigned)((cChannels) * (cbSample))) \
|
|---|
| 735 | ? (uint8_t)(ASMBitFirstSetU32((unsigned)((cChannels) * (cbSample))) - 1) : (uint8_t)UINT8_MAX )
|
|---|
| 736 | /** Calculates the cShift value of a PDMAUDIOPCMPROPS structure. */
|
|---|
| 737 | #define PDMAUDIOPCMPROPS_MAKE_SHIFT(pProps) \
|
|---|
| 738 | PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS((pProps)->cbSampleX, (pProps)->cChannelsX)
|
|---|
| 739 | /** Converts (audio) frames to bytes.
|
|---|
| 740 | * @note Requires properly initialized properties, i.e. cbFrames correctly calculated
|
|---|
| 741 | * and cShift set using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
|
|---|
| 742 | #define PDMAUDIOPCMPROPS_F2B(pProps, cFrames) \
|
|---|
| 743 | ( (pProps)->cShiftX != UINT8_MAX ? (cFrames) << (pProps)->cShiftX : (cFrames) * (pProps)->cbFrame )
|
|---|
| 744 | /** Converts bytes to (audio) frames.
|
|---|
| 745 | * @note Requires properly initialized properties, i.e. cbFrames correctly calculated
|
|---|
| 746 | * and cShift set using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
|
|---|
| 747 | #define PDMAUDIOPCMPROPS_B2F(pProps, cb) \
|
|---|
| 748 | ( (pProps)->cShiftX != UINT8_MAX ? (cb) >> (pProps)->cShiftX : (cb) / (pProps)->cbFrame )
|
|---|
| 749 | /** @} */
|
|---|
| 750 |
|
|---|
| 751 | /**
|
|---|
| 752 | * An audio stream configuration.
|
|---|
| 753 | */
|
|---|
| 754 | typedef struct PDMAUDIOSTREAMCFG
|
|---|
| 755 | {
|
|---|
| 756 | /** Direction of the stream. */
|
|---|
| 757 | PDMAUDIODIR enmDir;
|
|---|
| 758 | /** Destination / source indicator, depending on enmDir. */
|
|---|
| 759 | PDMAUDIODSTSRCUNION u;
|
|---|
| 760 | /** The stream's PCM properties. */
|
|---|
| 761 | PDMAUDIOPCMPROPS Props;
|
|---|
| 762 | /** The stream's audio data layout.
|
|---|
| 763 | * This indicates how the audio data buffers to/from the backend is being layouted.
|
|---|
| 764 | *
|
|---|
| 765 | * Currently, the following layouts are supported by the audio connector:
|
|---|
| 766 | *
|
|---|
| 767 | * PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED:
|
|---|
| 768 | * One stream at once. The consecutive audio data is exactly in the format and frame width
|
|---|
| 769 | * like defined in the PCM properties. This is the default.
|
|---|
| 770 | *
|
|---|
| 771 | * PDMAUDIOSTREAMLAYOUT_RAW:
|
|---|
| 772 | * Can be one or many streams at once, depending on the stream's mixing buffer setup.
|
|---|
| 773 | * The audio data will get handled as PDMAUDIOFRAME frames without any modification done.
|
|---|
| 774 | *
|
|---|
| 775 | * @todo r=bird: See PDMAUDIOSTREAMLAYOUT comments. */
|
|---|
| 776 | PDMAUDIOSTREAMLAYOUT enmLayout;
|
|---|
| 777 | /** Device emulation-specific data needed for the audio connector. */
|
|---|
| 778 | struct
|
|---|
| 779 | {
|
|---|
| 780 | /** Scheduling hint set by the device emulation about when this stream is being served on average (in ms).
|
|---|
| 781 | * Can be 0 if not hint given or some other mechanism (e.g. callbacks) is being used. */
|
|---|
| 782 | uint32_t cMsSchedulingHint;
|
|---|
| 783 | } Device;
|
|---|
| 784 | /**
|
|---|
| 785 | * Backend-specific data for the stream.
|
|---|
| 786 | * On input (requested configuration) those values are set by the audio connector to let the backend know what we expect.
|
|---|
| 787 | * On output (acquired configuration) those values reflect the values set and used by the backend.
|
|---|
| 788 | * Set by the backend on return. Not all backends support all values / features.
|
|---|
| 789 | */
|
|---|
| 790 | struct
|
|---|
| 791 | {
|
|---|
| 792 | /** Period size of the stream (in audio frames).
|
|---|
| 793 | * This value reflects the number of audio frames in between each hardware interrupt on the
|
|---|
| 794 | * backend (host) side. 0 if not set / available by the backend. */
|
|---|
| 795 | uint32_t cFramesPeriod;
|
|---|
| 796 | /** (Ring) buffer size (in audio frames). Often is a multiple of cFramesPeriod.
|
|---|
| 797 | * 0 if not set / available by the backend. */
|
|---|
| 798 | uint32_t cFramesBufferSize;
|
|---|
| 799 | /** Pre-buffering size (in audio frames). Frames needed in buffer before the stream becomes active (pre buffering).
|
|---|
| 800 | * The bigger this value is, the more latency for the stream will occur.
|
|---|
| 801 | * 0 if not set / available by the backend. UINT32_MAX if not defined (yet). */
|
|---|
| 802 | uint32_t cFramesPreBuffering;
|
|---|
| 803 | } Backend;
|
|---|
| 804 | uint32_t u32Padding;
|
|---|
| 805 | /** Friendly name of the stream. */
|
|---|
| 806 | char szName[64];
|
|---|
| 807 | } PDMAUDIOSTREAMCFG;
|
|---|
| 808 | AssertCompileSizeAlignment(PDMAUDIOSTREAMCFG, 8);
|
|---|
| 809 | /** Pointer to audio stream configuration keeper. */
|
|---|
| 810 | typedef PDMAUDIOSTREAMCFG *PPDMAUDIOSTREAMCFG;
|
|---|
| 811 | /** Pointer to a const audio stream configuration keeper. */
|
|---|
| 812 | typedef PDMAUDIOSTREAMCFG const *PCPDMAUDIOSTREAMCFG;
|
|---|
| 813 |
|
|---|
| 814 | /** Converts (audio) frames to bytes. */
|
|---|
| 815 | #define PDMAUDIOSTREAMCFG_F2B(pCfg, frames) PDMAUDIOPCMPROPS_F2B(&(pCfg)->Props, (frames))
|
|---|
| 816 | /** Converts bytes to (audio) frames. */
|
|---|
| 817 | #define PDMAUDIOSTREAMCFG_B2F(pCfg, cb) PDMAUDIOPCMPROPS_B2F(&(pCfg)->Props, (cb))
|
|---|
| 818 |
|
|---|
| 819 | /**
|
|---|
| 820 | * Audio mixer controls.
|
|---|
| 821 | */
|
|---|
| 822 | typedef enum PDMAUDIOMIXERCTL
|
|---|
| 823 | {
|
|---|
| 824 | /** Invalid zero value as per usual (guards against using unintialized values). */
|
|---|
| 825 | PDMAUDIOMIXERCTL_INVALID = 0,
|
|---|
| 826 | /** Unknown mixer control. */
|
|---|
| 827 | PDMAUDIOMIXERCTL_UNKNOWN,
|
|---|
| 828 | /** Master volume. */
|
|---|
| 829 | PDMAUDIOMIXERCTL_VOLUME_MASTER,
|
|---|
| 830 | /** Front. */
|
|---|
| 831 | PDMAUDIOMIXERCTL_FRONT,
|
|---|
| 832 | /** Center / LFE (Subwoofer). */
|
|---|
| 833 | PDMAUDIOMIXERCTL_CENTER_LFE,
|
|---|
| 834 | /** Rear. */
|
|---|
| 835 | PDMAUDIOMIXERCTL_REAR,
|
|---|
| 836 | /** Line-In. */
|
|---|
| 837 | PDMAUDIOMIXERCTL_LINE_IN,
|
|---|
| 838 | /** Microphone-In. */
|
|---|
| 839 | PDMAUDIOMIXERCTL_MIC_IN,
|
|---|
| 840 | /** End of valid values. */
|
|---|
| 841 | PDMAUDIOMIXERCTL_END,
|
|---|
| 842 | /** Hack to blow the type up to 32-bit. */
|
|---|
| 843 | PDMAUDIOMIXERCTL_32BIT_HACK = 0x7fffffff
|
|---|
| 844 | } PDMAUDIOMIXERCTL;
|
|---|
| 845 |
|
|---|
| 846 | /**
|
|---|
| 847 | * Audio stream commands.
|
|---|
| 848 | *
|
|---|
| 849 | * Used in the audio connector as well as in the actual host backends.
|
|---|
| 850 | */
|
|---|
| 851 | typedef enum PDMAUDIOSTREAMCMD
|
|---|
| 852 | {
|
|---|
| 853 | /** Invalid zero value as per usual (guards against using unintialized values). */
|
|---|
| 854 | PDMAUDIOSTREAMCMD_INVALID = 0,
|
|---|
| 855 | /** Unknown command, do not use. */
|
|---|
| 856 | PDMAUDIOSTREAMCMD_UNKNOWN,
|
|---|
| 857 | /** Enables the stream. */
|
|---|
| 858 | PDMAUDIOSTREAMCMD_ENABLE,
|
|---|
| 859 | /** Disables the stream.
|
|---|
| 860 | * For output streams this stops the stream after playing the remaining (buffered) audio data.
|
|---|
| 861 | * For input streams this will deliver the remaining (captured) audio data and not accepting
|
|---|
| 862 | * any new audio input data afterwards. */
|
|---|
| 863 | PDMAUDIOSTREAMCMD_DISABLE,
|
|---|
| 864 | /** Pauses the stream. */
|
|---|
| 865 | PDMAUDIOSTREAMCMD_PAUSE,
|
|---|
| 866 | /** Resumes the stream. */
|
|---|
| 867 | PDMAUDIOSTREAMCMD_RESUME,
|
|---|
| 868 | /** Tells the stream to drain itself.
|
|---|
| 869 | * For output streams this plays all remaining (buffered) audio frames,
|
|---|
| 870 | * for input streams this permits receiving any new audio frames.
|
|---|
| 871 | * No supported by all backends. */
|
|---|
| 872 | PDMAUDIOSTREAMCMD_DRAIN,
|
|---|
| 873 | /** Tells the stream to drop all (buffered) audio data immediately.
|
|---|
| 874 | * No supported by all backends. */
|
|---|
| 875 | PDMAUDIOSTREAMCMD_DROP,
|
|---|
| 876 | /** End of valid values. */
|
|---|
| 877 | PDMAUDIOSTREAMCMD_END,
|
|---|
| 878 | /** Hack to blow the type up to 32-bit. */
|
|---|
| 879 | PDMAUDIOSTREAMCMD_32BIT_HACK = 0x7fffffff
|
|---|
| 880 | } PDMAUDIOSTREAMCMD;
|
|---|
| 881 |
|
|---|
| 882 | /**
|
|---|
| 883 | * Audio volume parameters.
|
|---|
| 884 | */
|
|---|
| 885 | typedef struct PDMAUDIOVOLUME
|
|---|
| 886 | {
|
|---|
| 887 | /** Set to @c true if this stream is muted, @c false if not. */
|
|---|
| 888 | bool fMuted;
|
|---|
| 889 | /** Left channel volume.
|
|---|
| 890 | * Range is from [0 ... 255], whereas 0 specifies
|
|---|
| 891 | * the most silent and 255 the loudest value. */
|
|---|
| 892 | uint8_t uLeft;
|
|---|
| 893 | /** Right channel volume.
|
|---|
| 894 | * Range is from [0 ... 255], whereas 0 specifies
|
|---|
| 895 | * the most silent and 255 the loudest value. */
|
|---|
| 896 | uint8_t uRight;
|
|---|
| 897 | } PDMAUDIOVOLUME;
|
|---|
| 898 | /** Pointer to audio volume settings. */
|
|---|
| 899 | typedef PDMAUDIOVOLUME *PPDMAUDIOVOLUME;
|
|---|
| 900 |
|
|---|
| 901 | /** Defines the minimum volume allowed. */
|
|---|
| 902 | #define PDMAUDIO_VOLUME_MIN (0)
|
|---|
| 903 | /** Defines the maximum volume allowed. */
|
|---|
| 904 | #define PDMAUDIO_VOLUME_MAX (255)
|
|---|
| 905 |
|
|---|
| 906 | /**
|
|---|
| 907 | * Rate processing information of a source & destination audio stream.
|
|---|
| 908 | *
|
|---|
| 909 | * This is needed because both streams can differ regarding their rates and
|
|---|
| 910 | * therefore need to be treated accordingly.
|
|---|
| 911 | */
|
|---|
| 912 | typedef struct PDMAUDIOSTREAMRATE
|
|---|
| 913 | {
|
|---|
| 914 | /** Current (absolute) offset in the output (destination) stream.
|
|---|
| 915 | * @todo r=bird: Please reveal which unit these members are given in. */
|
|---|
| 916 | uint64_t offDst;
|
|---|
| 917 | /** Increment for moving offDst for the destination stream.
|
|---|
| 918 | * This is needed because the source <-> destination rate might be different. */
|
|---|
| 919 | uint64_t uDstInc;
|
|---|
| 920 | /** Current (absolute) offset in the input stream. */
|
|---|
| 921 | uint32_t offSrc;
|
|---|
| 922 | /** Explicit alignment padding. */
|
|---|
| 923 | uint32_t u32AlignmentPadding;
|
|---|
| 924 | /** Last processed frame of the input stream.
|
|---|
| 925 | * Needed for interpolation. */
|
|---|
| 926 | PDMAUDIOFRAME SrcFrameLast;
|
|---|
| 927 | } PDMAUDIOSTREAMRATE;
|
|---|
| 928 | /** Pointer to rate processing information of a stream. */
|
|---|
| 929 | typedef PDMAUDIOSTREAMRATE *PPDMAUDIOSTREAMRATE;
|
|---|
| 930 |
|
|---|
| 931 | /**
|
|---|
| 932 | * Mixing buffer volume parameters.
|
|---|
| 933 | *
|
|---|
| 934 | * The volume values are in fixed point style and must be converted to/from
|
|---|
| 935 | * before using with e.g. PDMAUDIOVOLUME.
|
|---|
| 936 | */
|
|---|
| 937 | typedef struct PDMAUDMIXBUFVOL
|
|---|
| 938 | {
|
|---|
| 939 | /** Set to @c true if this stream is muted, @c false if not. */
|
|---|
| 940 | bool fMuted;
|
|---|
| 941 | /** Left volume to apply during conversion.
|
|---|
| 942 | * Pass 0 to convert the original values. May not apply to all conversion functions. */
|
|---|
| 943 | uint32_t uLeft;
|
|---|
| 944 | /** Right volume to apply during conversion.
|
|---|
| 945 | * Pass 0 to convert the original values. May not apply to all conversion functions. */
|
|---|
| 946 | uint32_t uRight;
|
|---|
| 947 | } PDMAUDMIXBUFVOL;
|
|---|
| 948 | /** Pointer to mixing buffer volument parameters. */
|
|---|
| 949 | typedef PDMAUDMIXBUFVOL *PPDMAUDMIXBUFVOL;
|
|---|
| 950 |
|
|---|
| 951 | /*
|
|---|
| 952 | * Frame conversion parameters for the audioMixBufConvFromXXX / audioMixBufConvToXXX functions.
|
|---|
| 953 | */
|
|---|
| 954 | typedef struct PDMAUDMIXBUFCONVOPTS
|
|---|
| 955 | {
|
|---|
| 956 | /** Number of audio frames to convert. */
|
|---|
| 957 | uint32_t cFrames;
|
|---|
| 958 | union
|
|---|
| 959 | {
|
|---|
| 960 | struct
|
|---|
| 961 | {
|
|---|
| 962 | /** Volume to use for conversion. */
|
|---|
| 963 | PDMAUDMIXBUFVOL Volume;
|
|---|
| 964 | } From;
|
|---|
| 965 | } RT_UNION_NM(u);
|
|---|
| 966 | } PDMAUDMIXBUFCONVOPTS;
|
|---|
| 967 | /** Pointer to conversion parameters for the audio mixer. */
|
|---|
| 968 | typedef PDMAUDMIXBUFCONVOPTS *PPDMAUDMIXBUFCONVOPTS;
|
|---|
| 969 | /** Pointer to const conversion parameters for the audio mixer. */
|
|---|
| 970 | typedef PDMAUDMIXBUFCONVOPTS const *PCPDMAUDMIXBUFCONVOPTS;
|
|---|
| 971 |
|
|---|
| 972 | /**
|
|---|
| 973 | * @note All internal handling is done in audio frames, not in bytes!
|
|---|
| 974 | * @todo r=bird: What does this node actually apply to?
|
|---|
| 975 | */
|
|---|
| 976 | typedef uint32_t PDMAUDIOMIXBUFFMT;
|
|---|
| 977 | typedef PDMAUDIOMIXBUFFMT *PPDMAUDIOMIXBUFFMT;
|
|---|
| 978 |
|
|---|
| 979 | /**
|
|---|
| 980 | * Convertion-from function used by the PDM audio buffer mixer.
|
|---|
| 981 | *
|
|---|
| 982 | * @returns Number of audio frames returned.
|
|---|
| 983 | * @param paDst Where to return the converted frames.
|
|---|
| 984 | * @param pvSrc The source frame bytes.
|
|---|
| 985 | * @param cbSrc Number of bytes to convert.
|
|---|
| 986 | * @param pOpts Conversion options.
|
|---|
| 987 | * @todo r=bird: The @a paDst size is presumable given in @a pOpts->cFrames?
|
|---|
| 988 | */
|
|---|
| 989 | typedef DECLCALLBACKTYPE(uint32_t, FNPDMAUDIOMIXBUFCONVFROM,(PPDMAUDIOFRAME paDst, const void *pvSrc, uint32_t cbSrc,
|
|---|
| 990 | PCPDMAUDMIXBUFCONVOPTS pOpts));
|
|---|
| 991 | /** Pointer to a convertion-from function used by the PDM audio buffer mixer. */
|
|---|
| 992 | typedef FNPDMAUDIOMIXBUFCONVFROM *PFNPDMAUDIOMIXBUFCONVFROM;
|
|---|
| 993 |
|
|---|
| 994 | /**
|
|---|
| 995 | * Convertion-to function used by the PDM audio buffer mixer.
|
|---|
| 996 | *
|
|---|
| 997 | * @param pvDst Output buffer.
|
|---|
| 998 | * @param paSrc The input frames.
|
|---|
| 999 | * @param pOpts Conversion options.
|
|---|
| 1000 | * @todo r=bird: The @a paSrc size is presumable given in @a pOpts->cFrames and
|
|---|
| 1001 | * this implicitly gives the pvDst size too, right?
|
|---|
| 1002 | */
|
|---|
| 1003 | typedef DECLCALLBACKTYPE(void, FNPDMAUDIOMIXBUFCONVTO,(void *pvDst, PCPDMAUDIOFRAME paSrc, PCPDMAUDMIXBUFCONVOPTS pOpts));
|
|---|
| 1004 | /** Pointer to a convertion-to function used by the PDM audio buffer mixer. */
|
|---|
| 1005 | typedef FNPDMAUDIOMIXBUFCONVTO *PFNPDMAUDIOMIXBUFCONVTO;
|
|---|
| 1006 |
|
|---|
| 1007 | /** Pointer to audio mixing buffer. */
|
|---|
| 1008 | typedef struct PDMAUDIOMIXBUF *PPDMAUDIOMIXBUF;
|
|---|
| 1009 |
|
|---|
| 1010 | /**
|
|---|
| 1011 | * Audio mixing buffer.
|
|---|
| 1012 | */
|
|---|
| 1013 | typedef struct PDMAUDIOMIXBUF
|
|---|
| 1014 | {
|
|---|
| 1015 | /** Magic value (PDMAUDIOMIXBUF_MAGIC). */
|
|---|
| 1016 | uint32_t uMagic;
|
|---|
| 1017 | uint8_t abPadding[4];
|
|---|
| 1018 | /* ???Undocumented??? */
|
|---|
| 1019 | RTLISTNODE Node;
|
|---|
| 1020 | /** Name of the buffer. */
|
|---|
| 1021 | char *pszName;
|
|---|
| 1022 | /** Frame buffer. */
|
|---|
| 1023 | PPDMAUDIOFRAME pFrames;
|
|---|
| 1024 | /** Size of the frame buffer (in audio frames). */
|
|---|
| 1025 | uint32_t cFrames;
|
|---|
| 1026 | /** The current read position (in frames). */
|
|---|
| 1027 | uint32_t offRead;
|
|---|
| 1028 | /** The current write position (in frames). */
|
|---|
| 1029 | uint32_t offWrite;
|
|---|
| 1030 | /** Total frames already mixed down to the parent buffer (if any).
|
|---|
| 1031 | *
|
|---|
| 1032 | * Always starting at the parent's offRead position.
|
|---|
| 1033 | * @note Count always is specified in parent frames, as the sample count can
|
|---|
| 1034 | * differ between parent and child. */
|
|---|
| 1035 | uint32_t cMixed;
|
|---|
| 1036 | /** How much audio frames are currently being used
|
|---|
| 1037 | * in this buffer.
|
|---|
| 1038 | * Note: This also is known as the distance in ring buffer terms. */
|
|---|
| 1039 | uint32_t cUsed;
|
|---|
| 1040 | /** Number of children mix buffers kept in lstChildren. */
|
|---|
| 1041 | uint32_t cChildren;
|
|---|
| 1042 | /** List of children mix buffers to keep in sync with (if being a parent buffer). */
|
|---|
| 1043 | RTLISTANCHOR lstChildren;
|
|---|
| 1044 | /** Pointer to parent buffer (if any). */
|
|---|
| 1045 | PPDMAUDIOMIXBUF pParent;
|
|---|
| 1046 | /** Intermediate structure for buffer conversion tasks. */
|
|---|
| 1047 | PPDMAUDIOSTREAMRATE pRate;
|
|---|
| 1048 | /** Internal representation of current volume used for mixing. */
|
|---|
| 1049 | PDMAUDMIXBUFVOL Volume;
|
|---|
| 1050 | /** This buffer's audio format.
|
|---|
| 1051 | * @todo r=bird: This seems to be a value created by AUDMIXBUF_AUDIO_FMT_MAKE(),
|
|---|
| 1052 | * which is not define here. Does this structure really belong here at
|
|---|
| 1053 | * all? */
|
|---|
| 1054 | PDMAUDIOMIXBUFFMT uAudioFmt;
|
|---|
| 1055 | /** Audio input properties.
|
|---|
| 1056 | * @note There is only one set of audio properties here because we have one
|
|---|
| 1057 | * mixer buffer for the guest side and a separate one for the host side.
|
|---|
| 1058 | * @todo r=bird: Why exactly do we need to use separate mixer buffers?
|
|---|
| 1059 | * Couldn't we just have different conversion fuctions and save the
|
|---|
| 1060 | * extra copying? */
|
|---|
| 1061 | PDMAUDIOPCMPROPS Props;
|
|---|
| 1062 | /** Standard conversion-to function for set uAudioFmt. */
|
|---|
| 1063 | PFNPDMAUDIOMIXBUFCONVTO pfnConvTo;
|
|---|
| 1064 | /** Standard conversion-from function for set uAudioFmt. */
|
|---|
| 1065 | PFNPDMAUDIOMIXBUFCONVFROM pfnConvFrom;
|
|---|
| 1066 |
|
|---|
| 1067 | /** Ratio of the associated parent stream's frequency by this stream's
|
|---|
| 1068 | * frequency (1<<32), represented as a signed 64 bit integer.
|
|---|
| 1069 | *
|
|---|
| 1070 | * For example, if the parent stream has a frequency of 44 khZ, and this
|
|---|
| 1071 | * stream has a frequency of 11 kHz, the ration then would be
|
|---|
| 1072 | * (44/11 * (1 << 32)).
|
|---|
| 1073 | *
|
|---|
| 1074 | * Currently this does not get changed once assigned. */
|
|---|
| 1075 | int64_t iFreqRatio;
|
|---|
| 1076 | } PDMAUDIOMIXBUF;
|
|---|
| 1077 |
|
|---|
| 1078 | /** Magic value for PDMAUDIOMIXBUF. */
|
|---|
| 1079 | #define PDMAUDIOMIXBUF_MAGIC PDM_VERSION_MAKE(0xa0d2, 1, 0)
|
|---|
| 1080 |
|
|---|
| 1081 | /** @name PDMAUDIOFILE_FLAGS_XXX
|
|---|
| 1082 | * @{ */
|
|---|
| 1083 | /** No flags defined. */
|
|---|
| 1084 | #define PDMAUDIOFILE_FLAGS_NONE UINT32_C(0)
|
|---|
| 1085 | /** Keep the audio file even if it contains no audio data. */
|
|---|
| 1086 | #define PDMAUDIOFILE_FLAGS_KEEP_IF_EMPTY RT_BIT_32(0)
|
|---|
| 1087 | /** Audio file flag validation mask. */
|
|---|
| 1088 | #define PDMAUDIOFILE_FLAGS_VALID_MASK UINT32_C(0x1)
|
|---|
| 1089 | /** @} */
|
|---|
| 1090 |
|
|---|
| 1091 | /** Audio file default open flags.
|
|---|
| 1092 | * @todo r=bird: What is the exact purpose of this? */
|
|---|
| 1093 | #define PDMAUDIOFILE_DEFAULT_OPEN_FLAGS (RTFILE_O_OPEN_CREATE | RTFILE_O_APPEND | RTFILE_O_WRITE | RTFILE_O_DENY_WRITE)
|
|---|
| 1094 |
|
|---|
| 1095 | /**
|
|---|
| 1096 | * Audio file types.
|
|---|
| 1097 | * @todo r=bird: This does not really belong here.
|
|---|
| 1098 | */
|
|---|
| 1099 | typedef enum PDMAUDIOFILETYPE
|
|---|
| 1100 | {
|
|---|
| 1101 | /** The customary invalid zero value. */
|
|---|
| 1102 | PDMAUDIOFILETYPE_INVALID = 0,
|
|---|
| 1103 | /** Unknown type, do not use. */
|
|---|
| 1104 | PDMAUDIOFILETYPE_UNKNOWN,
|
|---|
| 1105 | /** Raw (PCM) file. */
|
|---|
| 1106 | PDMAUDIOFILETYPE_RAW,
|
|---|
| 1107 | /** Wave (.WAV) file. */
|
|---|
| 1108 | PDMAUDIOFILETYPE_WAV,
|
|---|
| 1109 | /** Hack to blow the type up to 32-bit. */
|
|---|
| 1110 | PDMAUDIOFILETYPE_32BIT_HACK = 0x7fffffff
|
|---|
| 1111 | } PDMAUDIOFILETYPE;
|
|---|
| 1112 |
|
|---|
| 1113 | /** @name PDMAUDIOFILENAME_FLAGS_XXX
|
|---|
| 1114 | * @{ */
|
|---|
| 1115 | /** No flags defined. */
|
|---|
| 1116 | #define PDMAUDIOFILENAME_FLAGS_NONE UINT32_C(0)
|
|---|
| 1117 | /** Adds an ISO timestamp to the file name. */
|
|---|
| 1118 | #define PDMAUDIOFILENAME_FLAGS_TS RT_BIT(0)
|
|---|
| 1119 | /** @} */
|
|---|
| 1120 |
|
|---|
| 1121 | /**
|
|---|
| 1122 | * Audio file handle.
|
|---|
| 1123 | */
|
|---|
| 1124 | typedef struct PDMAUDIOFILE
|
|---|
| 1125 | {
|
|---|
| 1126 | /** Type of the audio file. */
|
|---|
| 1127 | PDMAUDIOFILETYPE enmType;
|
|---|
| 1128 | /** Audio file flags, PDMAUDIOFILE_FLAGS_XXX. */
|
|---|
| 1129 | uint32_t fFlags;
|
|---|
| 1130 | /** Actual file handle. */
|
|---|
| 1131 | RTFILE hFile;
|
|---|
| 1132 | /** Data needed for the specific audio file type implemented.
|
|---|
| 1133 | * Optional, can be NULL. */
|
|---|
| 1134 | void *pvData;
|
|---|
| 1135 | /** Data size (in bytes). */
|
|---|
| 1136 | size_t cbData;
|
|---|
| 1137 | /** File name and path. */
|
|---|
| 1138 | char szName[RTPATH_MAX];
|
|---|
| 1139 | } PDMAUDIOFILE;
|
|---|
| 1140 | /** Pointer to an audio file handle. */
|
|---|
| 1141 | typedef PDMAUDIOFILE *PPDMAUDIOFILE;
|
|---|
| 1142 |
|
|---|
| 1143 | /** @name PDMAUDIOSTREAMSTS_FLAGS_XXX
|
|---|
| 1144 | * @{ */
|
|---|
| 1145 | /** No flags being set. */
|
|---|
| 1146 | #define PDMAUDIOSTREAMSTS_FLAGS_NONE UINT32_C(0)
|
|---|
| 1147 | /** Whether this stream has been initialized by the
|
|---|
| 1148 | * backend or not. */
|
|---|
| 1149 | #define PDMAUDIOSTREAMSTS_FLAGS_INITIALIZED RT_BIT_32(0)
|
|---|
| 1150 | /** Whether this stream is enabled or disabled. */
|
|---|
| 1151 | #define PDMAUDIOSTREAMSTS_FLAGS_ENABLED RT_BIT_32(1)
|
|---|
| 1152 | /** Whether this stream has been paused or not. This also implies
|
|---|
| 1153 | * that this is an enabled stream! */
|
|---|
| 1154 | #define PDMAUDIOSTREAMSTS_FLAGS_PAUSED RT_BIT_32(2)
|
|---|
| 1155 | /** Whether this stream was marked as being disabled
|
|---|
| 1156 | * but there are still associated guest output streams
|
|---|
| 1157 | * which rely on its data. */
|
|---|
| 1158 | #define PDMAUDIOSTREAMSTS_FLAGS_PENDING_DISABLE RT_BIT_32(3)
|
|---|
| 1159 | /** Whether this stream is in re-initialization phase.
|
|---|
| 1160 | * All other bits remain untouched to be able to restore
|
|---|
| 1161 | * the stream's state after the re-initialization bas been
|
|---|
| 1162 | * finished. */
|
|---|
| 1163 | #define PDMAUDIOSTREAMSTS_FLAGS_PENDING_REINIT RT_BIT_32(4)
|
|---|
| 1164 | /** Validation mask. */
|
|---|
| 1165 | #define PDMAUDIOSTREAMSTS_VALID_MASK UINT32_C(0x0000001F)
|
|---|
| 1166 | /** Stream status flag, PDMAUDIOSTREAMSTS_FLAGS_XXX. */
|
|---|
| 1167 | typedef uint32_t PDMAUDIOSTREAMSTS;
|
|---|
| 1168 | /** @} */
|
|---|
| 1169 |
|
|---|
| 1170 | /**
|
|---|
| 1171 | * Backend status.
|
|---|
| 1172 | */
|
|---|
| 1173 | typedef enum PDMAUDIOBACKENDSTS
|
|---|
| 1174 | {
|
|---|
| 1175 | /** Unknown/invalid status. */
|
|---|
| 1176 | PDMAUDIOBACKENDSTS_UNKNOWN = 0,
|
|---|
| 1177 | /** No backend attached. */
|
|---|
| 1178 | PDMAUDIOBACKENDSTS_NOT_ATTACHED,
|
|---|
| 1179 | /** The backend is in its initialization phase.
|
|---|
| 1180 | * Not all backends support this status. */
|
|---|
| 1181 | PDMAUDIOBACKENDSTS_INITIALIZING,
|
|---|
| 1182 | /** The backend has stopped its operation. */
|
|---|
| 1183 | PDMAUDIOBACKENDSTS_STOPPED,
|
|---|
| 1184 | /** The backend is up and running. */
|
|---|
| 1185 | PDMAUDIOBACKENDSTS_RUNNING,
|
|---|
| 1186 | /** The backend ran into an error and is unable to recover.
|
|---|
| 1187 | * A manual re-initialization might help. */
|
|---|
| 1188 | PDMAUDIOBACKENDSTS_ERROR,
|
|---|
| 1189 | /** Hack to blow the type up to 32-bit. */
|
|---|
| 1190 | PDMAUDIOBACKENDSTS_32BIT_HACK = 0x7fffffff
|
|---|
| 1191 | } PDMAUDIOBACKENDSTS;
|
|---|
| 1192 |
|
|---|
| 1193 | /**
|
|---|
| 1194 | * The specifics for an audio input stream.
|
|---|
| 1195 | *
|
|---|
| 1196 | * Do not use directly, use PDMAUDIOSTREAM instead.
|
|---|
| 1197 | */
|
|---|
| 1198 | typedef struct PDMAUDIOSTREAMIN
|
|---|
| 1199 | {
|
|---|
| 1200 | struct
|
|---|
| 1201 | {
|
|---|
| 1202 | /** File for writing stream reads. */
|
|---|
| 1203 | PPDMAUDIOFILE pFileStreamRead;
|
|---|
| 1204 | /** File for writing non-interleaved captures. */
|
|---|
| 1205 | PPDMAUDIOFILE pFileCaptureNonInterleaved;
|
|---|
| 1206 | } Dbg;
|
|---|
| 1207 | struct
|
|---|
| 1208 | {
|
|---|
| 1209 | STAMCOUNTER TotalFramesCaptured;
|
|---|
| 1210 | STAMCOUNTER AvgFramesCaptured;
|
|---|
| 1211 | STAMCOUNTER TotalTimesCaptured;
|
|---|
| 1212 | STAMCOUNTER TotalFramesRead;
|
|---|
| 1213 | STAMCOUNTER AvgFramesRead;
|
|---|
| 1214 | STAMCOUNTER TotalTimesRead;
|
|---|
| 1215 | } Stats;
|
|---|
| 1216 | } PDMAUDIOSTREAMIN;
|
|---|
| 1217 | /** Pointer to the specifics for an audio input stream. */
|
|---|
| 1218 | typedef PDMAUDIOSTREAMIN *PPDMAUDIOSTREAMIN;
|
|---|
| 1219 |
|
|---|
| 1220 | /**
|
|---|
| 1221 | * The specifics for an audio output stream.
|
|---|
| 1222 | *
|
|---|
| 1223 | * Do not use directly, use PDMAUDIOSTREAM instead.
|
|---|
| 1224 | */
|
|---|
| 1225 | typedef struct PDMAUDIOSTREAMOUT
|
|---|
| 1226 | {
|
|---|
| 1227 | struct
|
|---|
| 1228 | {
|
|---|
| 1229 | /** File for writing stream writes. */
|
|---|
| 1230 | PPDMAUDIOFILE pFileStreamWrite;
|
|---|
| 1231 | /** File for writing stream playback. */
|
|---|
| 1232 | PPDMAUDIOFILE pFilePlayNonInterleaved;
|
|---|
| 1233 | } Dbg;
|
|---|
| 1234 | struct
|
|---|
| 1235 | {
|
|---|
| 1236 | STAMCOUNTER TotalFramesPlayed;
|
|---|
| 1237 | STAMCOUNTER AvgFramesPlayed;
|
|---|
| 1238 | STAMCOUNTER TotalTimesPlayed;
|
|---|
| 1239 | STAMCOUNTER TotalFramesWritten;
|
|---|
| 1240 | STAMCOUNTER AvgFramesWritten;
|
|---|
| 1241 | STAMCOUNTER TotalTimesWritten;
|
|---|
| 1242 | } Stats;
|
|---|
| 1243 | /** Hack alert: Max writable amount reported by the backend.
|
|---|
| 1244 | * This is used to aid buffer underrun detection in DrvAudio while playing.
|
|---|
| 1245 | * Ideally, the backend should have a method for querying number of buffered
|
|---|
| 1246 | * bytes instead. However this will do for now. */
|
|---|
| 1247 | uint32_t cbBackendMaxWritable;
|
|---|
| 1248 | } PDMAUDIOSTREAMOUT;
|
|---|
| 1249 | /** Pointer to the specifics for an audio output stream. */
|
|---|
| 1250 | typedef PDMAUDIOSTREAMOUT *PPDMAUDIOSTREAMOUT;
|
|---|
| 1251 |
|
|---|
| 1252 | /** Pointer to an audio stream. */
|
|---|
| 1253 | typedef struct PDMAUDIOSTREAM *PPDMAUDIOSTREAM;
|
|---|
| 1254 |
|
|---|
| 1255 | /**
|
|---|
| 1256 | * Audio stream context.
|
|---|
| 1257 | * Needed for separating data from the guest and host side (per stream).
|
|---|
| 1258 | */
|
|---|
| 1259 | typedef struct PDMAUDIOSTREAMCTX
|
|---|
| 1260 | {
|
|---|
| 1261 | /** The stream's audio configuration. */
|
|---|
| 1262 | PDMAUDIOSTREAMCFG Cfg;
|
|---|
| 1263 | /** This stream's mixing buffer. */
|
|---|
| 1264 | PDMAUDIOMIXBUF MixBuf;
|
|---|
| 1265 | } PDMAUDIOSTREAMCTX;
|
|---|
| 1266 |
|
|---|
| 1267 | /** Pointer to an audio stream context. */
|
|---|
| 1268 | typedef struct PDMAUDIOSTREAM *PPDMAUDIOSTREAMCTX;
|
|---|
| 1269 |
|
|---|
| 1270 | /** @name PDMAUDIOSTREAM_WARN_FLAGS_XXX
|
|---|
| 1271 | * @{ */
|
|---|
| 1272 | /** No stream warning flags set. */
|
|---|
| 1273 | #define PDMAUDIOSTREAM_WARN_FLAGS_NONE 0
|
|---|
| 1274 | /** Warned about a disabled stream. */
|
|---|
| 1275 | #define PDMAUDIOSTREAM_WARN_FLAGS_DISABLED RT_BIT(0)
|
|---|
| 1276 | /** @} */
|
|---|
| 1277 |
|
|---|
| 1278 | /**
|
|---|
| 1279 | * An input or output audio stream.
|
|---|
| 1280 | */
|
|---|
| 1281 | typedef struct PDMAUDIOSTREAM
|
|---|
| 1282 | {
|
|---|
| 1283 | /** Magic value (PDMAUDIOSTREAM_MAGIC). */
|
|---|
| 1284 | uint32_t uMagic;
|
|---|
| 1285 | /** Size (in bytes) of the backend-specific stream data. */
|
|---|
| 1286 | uint32_t cbBackend;
|
|---|
| 1287 | /** List entry (some DrvAudio internal list). */
|
|---|
| 1288 | RTLISTNODE ListEntry;
|
|---|
| 1289 | /** Number of references to this stream.
|
|---|
| 1290 | * Only can be destroyed when the reference count reaches 0. */
|
|---|
| 1291 | uint32_t cRefs;
|
|---|
| 1292 | /** Number of (re-)tries while re-initializing the stream. */
|
|---|
| 1293 | uint32_t cTriesReInit;
|
|---|
| 1294 | /** Warnings shown already in the release log.
|
|---|
| 1295 | * See PDMAUDIOSTREAM_WARN_FLAGS_XXX. */
|
|---|
| 1296 | uint32_t fWarningsShown;
|
|---|
| 1297 | /** Stream status flag. */
|
|---|
| 1298 | PDMAUDIOSTREAMSTS fStatus;
|
|---|
| 1299 | /** Audio direction of this stream. */
|
|---|
| 1300 | PDMAUDIODIR enmDir;
|
|---|
| 1301 | /** For output streams this indicates whether the stream has reached
|
|---|
| 1302 | * its playback threshold, e.g. is playing audio.
|
|---|
| 1303 | * For input streams this indicates whether the stream has enough input
|
|---|
| 1304 | * data to actually start reading audio. */
|
|---|
| 1305 | bool fThresholdReached;
|
|---|
| 1306 | bool afPadding[3];
|
|---|
| 1307 | /** The guest side of the stream. */
|
|---|
| 1308 | PDMAUDIOSTREAMCTX Guest;
|
|---|
| 1309 | /** The host side of the stream. */
|
|---|
| 1310 | PDMAUDIOSTREAMCTX Host;
|
|---|
| 1311 | /** Timestamp (in ns) since last trying to re-initialize.
|
|---|
| 1312 | * Might be 0 if has not been tried yet. */
|
|---|
| 1313 | uint64_t tsLastReInitNs;
|
|---|
| 1314 | /** Timestamp (in ns) since last iteration. */
|
|---|
| 1315 | uint64_t tsLastIteratedNs;
|
|---|
| 1316 | /** Timestamp (in ns) since last playback / capture. */
|
|---|
| 1317 | uint64_t tsLastPlayedCapturedNs;
|
|---|
| 1318 | /** Timestamp (in ns) since last read (input streams) or
|
|---|
| 1319 | * write (output streams). */
|
|---|
| 1320 | uint64_t tsLastReadWrittenNs;
|
|---|
| 1321 | /** Data to backend-specific stream data.
|
|---|
| 1322 | * This data block will be casted by the backend to access its backend-dependent data.
|
|---|
| 1323 | *
|
|---|
| 1324 | * That way the backends do not have access to the audio connector's data. */
|
|---|
| 1325 | void *pvBackend;
|
|---|
| 1326 |
|
|---|
| 1327 | /** Name of this stream. */
|
|---|
| 1328 | char szName[64];
|
|---|
| 1329 |
|
|---|
| 1330 | /** Union for input/output specifics depending on enmDir. */
|
|---|
| 1331 | union
|
|---|
| 1332 | {
|
|---|
| 1333 | PDMAUDIOSTREAMIN In;
|
|---|
| 1334 | PDMAUDIOSTREAMOUT Out;
|
|---|
| 1335 | } RT_UNION_NM(u);
|
|---|
| 1336 | } PDMAUDIOSTREAM;
|
|---|
| 1337 |
|
|---|
| 1338 | /** Magic value for PDMAUDIOSTREAM. */
|
|---|
| 1339 | #define PDMAUDIOSTREAM_MAGIC PDM_VERSION_MAKE(0xa0d3, 1, 1)
|
|---|
| 1340 |
|
|---|
| 1341 |
|
|---|
| 1342 | /**
|
|---|
| 1343 | * Audio callback source.
|
|---|
| 1344 | */
|
|---|
| 1345 | typedef enum PDMAUDIOCBSOURCE
|
|---|
| 1346 | {
|
|---|
| 1347 | /** Invalid, do not use. */
|
|---|
| 1348 | PDMAUDIOCBSOURCE_INVALID = 0,
|
|---|
| 1349 | /** Device emulation. */
|
|---|
| 1350 | PDMAUDIOCBSOURCE_DEVICE,
|
|---|
| 1351 | /** Audio connector interface. */
|
|---|
| 1352 | PDMAUDIOCBSOURCE_CONNECTOR,
|
|---|
| 1353 | /** Backend (lower). */
|
|---|
| 1354 | PDMAUDIOCBSOURCE_BACKEND,
|
|---|
| 1355 | /** Hack to blow the type up to 32-bit. */
|
|---|
| 1356 | PDMAUDIOCBSOURCE_32BIT_HACK = 0x7fffffff
|
|---|
| 1357 | } PDMAUDIOCBSOURCE;
|
|---|
| 1358 |
|
|---|
| 1359 | /**
|
|---|
| 1360 | * Audio device callback types.
|
|---|
| 1361 | * Those callbacks are being sent from the audio connector -> device emulation.
|
|---|
| 1362 | */
|
|---|
| 1363 | typedef enum PDMAUDIODEVICECBTYPE
|
|---|
| 1364 | {
|
|---|
| 1365 | /** Invalid, do not use. */
|
|---|
| 1366 | PDMAUDIODEVICECBTYPE_INVALID = 0,
|
|---|
| 1367 | /** Data is availabe as input for passing to the device emulation. */
|
|---|
| 1368 | PDMAUDIODEVICECBTYPE_DATA_INPUT,
|
|---|
| 1369 | /** Free data for the device emulation to write to the backend. */
|
|---|
| 1370 | PDMAUDIODEVICECBTYPE_DATA_OUTPUT,
|
|---|
| 1371 | /** Hack to blow the type up to 32-bit. */
|
|---|
| 1372 | PDMAUDIODEVICECBTYPE_32BIT_HACK = 0x7fffffff
|
|---|
| 1373 | } PDMAUDIODEVICECBTYPE;
|
|---|
| 1374 |
|
|---|
| 1375 | #if 0 /** @todo r=bird: Who needs this exactly? Fix the style or remove */
|
|---|
| 1376 | /**
|
|---|
| 1377 | * Device callback data for audio input.
|
|---|
| 1378 | */
|
|---|
| 1379 | typedef struct PDMAUDIODEVICECBDATA_DATA_INPUT
|
|---|
| 1380 | {
|
|---|
| 1381 | /** Input: How many bytes are availabe as input for passing
|
|---|
| 1382 | * to the device emulation. */
|
|---|
| 1383 | uint32_t cbInAvail;
|
|---|
| 1384 | /** Output: How many bytes have been read. */
|
|---|
| 1385 | uint32_t cbOutRead;
|
|---|
| 1386 | } PDMAUDIODEVICECBDATA_DATA_INPUT;
|
|---|
| 1387 | typedef PDMAUDIODEVICECBDATA_DATA_INPUT *PPDMAUDIODEVICECBDATA_DATA_INPUT;
|
|---|
| 1388 |
|
|---|
| 1389 | /**
|
|---|
| 1390 | * Device callback data for audio output.
|
|---|
| 1391 | */
|
|---|
| 1392 | typedef struct PDMAUDIODEVICECBDATA_DATA_OUTPUT
|
|---|
| 1393 | {
|
|---|
| 1394 | /** Input: How many bytes are free for the device emulation to write. */
|
|---|
| 1395 | uint32_t cbInFree;
|
|---|
| 1396 | /** Output: How many bytes were written by the device emulation. */
|
|---|
| 1397 | uint32_t cbOutWritten;
|
|---|
| 1398 | } PDMAUDIODEVICECBDATA_DATA_OUTPUT, *PPDMAUDIODEVICECBDATA_DATA_OUTPUT;
|
|---|
| 1399 | #endif
|
|---|
| 1400 |
|
|---|
| 1401 | /**
|
|---|
| 1402 | * Audio backend callback types.
|
|---|
| 1403 | * Those callbacks are being sent from the backend -> audio connector.
|
|---|
| 1404 | */
|
|---|
| 1405 | typedef enum PDMAUDIOBACKENDCBTYPE
|
|---|
| 1406 | {
|
|---|
| 1407 | /** Invalid, do not use. */
|
|---|
| 1408 | PDMAUDIOBACKENDCBTYPE_INVALID = 0,
|
|---|
| 1409 | /** The backend's status has changed. */
|
|---|
| 1410 | PDMAUDIOBACKENDCBTYPE_STATUS,
|
|---|
| 1411 | /** One or more host audio devices have changed. */
|
|---|
| 1412 | PDMAUDIOBACKENDCBTYPE_DEVICES_CHANGED,
|
|---|
| 1413 | /** Hack to blow the type up to 32-bit. */
|
|---|
| 1414 | PDMAUDIOBACKENDCBTYPE_32BIT_HACK = 0x7fffffff
|
|---|
| 1415 | } PDMAUDIOBACKENDCBTYPE;
|
|---|
| 1416 |
|
|---|
| 1417 | /** Pointer to a host audio interface. */
|
|---|
| 1418 | typedef struct PDMIHOSTAUDIO *PPDMIHOSTAUDIO;
|
|---|
| 1419 |
|
|---|
| 1420 | /**
|
|---|
| 1421 | * Host audio callback function.
|
|---|
| 1422 | *
|
|---|
| 1423 | * This function will be called from a backend to communicate with the host audio interface.
|
|---|
| 1424 | *
|
|---|
| 1425 | * @returns IPRT status code.
|
|---|
| 1426 | * @param pDrvIns Pointer to driver instance which called us.
|
|---|
| 1427 | * @param enmType Callback type.
|
|---|
| 1428 | * @param pvUser User argument.
|
|---|
| 1429 | * @param cbUser Size (in bytes) of user argument.
|
|---|
| 1430 | */
|
|---|
| 1431 | typedef DECLCALLBACKTYPE(int, FNPDMHOSTAUDIOCALLBACK,(PPDMDRVINS pDrvIns, PDMAUDIOBACKENDCBTYPE enmType,
|
|---|
| 1432 | void *pvUser, size_t cbUser));
|
|---|
| 1433 | /** Pointer to a FNPDMHOSTAUDIOCALLBACK(). */
|
|---|
| 1434 | typedef FNPDMHOSTAUDIOCALLBACK *PFNPDMHOSTAUDIOCALLBACK;
|
|---|
| 1435 |
|
|---|
| 1436 | /**
|
|---|
| 1437 | * Audio callback registration record.
|
|---|
| 1438 | */
|
|---|
| 1439 | typedef struct PDMAUDIOCBRECORD
|
|---|
| 1440 | {
|
|---|
| 1441 | /** List node. */
|
|---|
| 1442 | RTLISTANCHOR Node;
|
|---|
| 1443 | /** Callback source. */
|
|---|
| 1444 | PDMAUDIOCBSOURCE enmSource;
|
|---|
| 1445 | /** Callback type, based on the given source. */
|
|---|
| 1446 | union
|
|---|
| 1447 | {
|
|---|
| 1448 | /** Device callback stuff. */
|
|---|
| 1449 | struct
|
|---|
| 1450 | {
|
|---|
| 1451 | PDMAUDIODEVICECBTYPE enmType;
|
|---|
| 1452 | } Device;
|
|---|
| 1453 | } RT_UNION_NM(u);
|
|---|
| 1454 | /** Pointer to context data. Optional. */
|
|---|
| 1455 | void *pvCtx;
|
|---|
| 1456 | /** Size (in bytes) of context data.
|
|---|
| 1457 | * Must be 0 if pvCtx is NULL. */
|
|---|
| 1458 | size_t cbCtx;
|
|---|
| 1459 | } PDMAUDIOCBRECORD;
|
|---|
| 1460 | /** Pointer to an audio callback registration record. */
|
|---|
| 1461 | typedef PDMAUDIOCBRECORD *PPDMAUDIOCBRECORD;
|
|---|
| 1462 |
|
|---|
| 1463 | /** @todo r=bird: What is this exactly? */
|
|---|
| 1464 | #define PPDMAUDIOBACKENDSTREAM void *
|
|---|
| 1465 |
|
|---|
| 1466 | /** Pointer to a audio connector interface. */
|
|---|
| 1467 | typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
|
|---|
| 1468 |
|
|---|
| 1469 | /**
|
|---|
| 1470 | * Audio connector interface (up).
|
|---|
| 1471 | */
|
|---|
| 1472 | typedef struct PDMIAUDIOCONNECTOR
|
|---|
| 1473 | {
|
|---|
| 1474 | /**
|
|---|
| 1475 | * Enables or disables the given audio direction for this driver.
|
|---|
| 1476 | *
|
|---|
| 1477 | * When disabled, assiociated output streams consume written audio without passing them further down to the backends.
|
|---|
| 1478 | * Associated input streams then return silence when read from those.
|
|---|
| 1479 | *
|
|---|
| 1480 | * @returns VBox status code.
|
|---|
| 1481 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1482 | * @param enmDir Audio direction to enable or disable driver for.
|
|---|
| 1483 | * @param fEnable Whether to enable or disable the specified audio direction.
|
|---|
| 1484 | *
|
|---|
| 1485 | * @note Be very careful when using this function, as this could
|
|---|
| 1486 | * violate / run against the (global) VM settings. See @bugref{9882}.
|
|---|
| 1487 | */
|
|---|
| 1488 | DECLR3CALLBACKMEMBER(int, pfnEnable, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir, bool fEnable));
|
|---|
| 1489 |
|
|---|
| 1490 | /**
|
|---|
| 1491 | * Returns whether the given audio direction for this driver is enabled or not.
|
|---|
| 1492 | *
|
|---|
| 1493 | * @returns True if audio is enabled for the given direction, false if not.
|
|---|
| 1494 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1495 | * @param enmDir Audio direction to retrieve enabled status for.
|
|---|
| 1496 | */
|
|---|
| 1497 | DECLR3CALLBACKMEMBER(bool, pfnIsEnabled, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
|
|---|
| 1498 |
|
|---|
| 1499 | /**
|
|---|
| 1500 | * Retrieves the current configuration of the host audio backend.
|
|---|
| 1501 | *
|
|---|
| 1502 | * @returns VBox status code.
|
|---|
| 1503 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1504 | * @param pCfg Where to store the host audio backend configuration data.
|
|---|
| 1505 | */
|
|---|
| 1506 | DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOBACKENDCFG pCfg));
|
|---|
| 1507 |
|
|---|
| 1508 | /**
|
|---|
| 1509 | * Retrieves the current status of the host audio backend.
|
|---|
| 1510 | *
|
|---|
| 1511 | * @returns Status of the host audio backend.
|
|---|
| 1512 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1513 | * @param enmDir Audio direction to check host audio backend for. Specify PDMAUDIODIR_DUPLEX for the overall
|
|---|
| 1514 | * backend status.
|
|---|
| 1515 | */
|
|---|
| 1516 | DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
|
|---|
| 1517 |
|
|---|
| 1518 | /**
|
|---|
| 1519 | * Creates an audio stream.
|
|---|
| 1520 | *
|
|---|
| 1521 | * @returns VBox status code.
|
|---|
| 1522 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1523 | * @param pCfgHost Stream configuration for host side.
|
|---|
| 1524 | * @param pCfgGuest Stream configuration for guest side.
|
|---|
| 1525 | * @param ppStream Pointer where to return the created audio stream on success.
|
|---|
| 1526 | */
|
|---|
| 1527 | DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfgHost,
|
|---|
| 1528 | PPDMAUDIOSTREAMCFG pCfgGuest, PPDMAUDIOSTREAM *ppStream));
|
|---|
| 1529 |
|
|---|
| 1530 | /**
|
|---|
| 1531 | * Destroys an audio stream.
|
|---|
| 1532 | *
|
|---|
| 1533 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1534 | * @param pStream Pointer to audio stream.
|
|---|
| 1535 | */
|
|---|
| 1536 | DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
|
|---|
| 1537 |
|
|---|
| 1538 | /**
|
|---|
| 1539 | * Adds a reference to the specified audio stream.
|
|---|
| 1540 | *
|
|---|
| 1541 | * @returns New reference count. UINT32_MAX on error.
|
|---|
| 1542 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1543 | * @param pStream Pointer to audio stream adding the reference to.
|
|---|
| 1544 | */
|
|---|
| 1545 | DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRetain, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
|
|---|
| 1546 |
|
|---|
| 1547 | /**
|
|---|
| 1548 | * Releases a reference from the specified stream.
|
|---|
| 1549 | *
|
|---|
| 1550 | * @returns New reference count. UINT32_MAX on error.
|
|---|
| 1551 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1552 | * @param pStream Pointer to audio stream releasing a reference from.
|
|---|
| 1553 | */
|
|---|
| 1554 | DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRelease, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
|
|---|
| 1555 |
|
|---|
| 1556 | /**
|
|---|
| 1557 | * Reads PCM audio data from the host (input).
|
|---|
| 1558 | *
|
|---|
| 1559 | * @returns VBox status code.
|
|---|
| 1560 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1561 | * @param pStream Pointer to audio stream to write to.
|
|---|
| 1562 | * @param pvBuf Where to store the read data.
|
|---|
| 1563 | * @param cbBuf Number of bytes to read.
|
|---|
| 1564 | * @param pcbRead Bytes of audio data read. Optional.
|
|---|
| 1565 | */
|
|---|
| 1566 | DECLR3CALLBACKMEMBER(int, pfnStreamRead, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
|
|---|
| 1567 | void *pvBuf, uint32_t cbBuf, uint32_t *pcbRead));
|
|---|
| 1568 |
|
|---|
| 1569 | /**
|
|---|
| 1570 | * Writes PCM audio data to the host (output).
|
|---|
| 1571 | *
|
|---|
| 1572 | * @returns VBox status code.
|
|---|
| 1573 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1574 | * @param pStream Pointer to audio stream to read from.
|
|---|
| 1575 | * @param pvBuf Audio data to be written.
|
|---|
| 1576 | * @param cbBuf Number of bytes to be written.
|
|---|
| 1577 | * @param pcbWritten Bytes of audio data written. Optional.
|
|---|
| 1578 | */
|
|---|
| 1579 | DECLR3CALLBACKMEMBER(int, pfnStreamWrite, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
|
|---|
| 1580 | const void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten));
|
|---|
| 1581 |
|
|---|
| 1582 | /**
|
|---|
| 1583 | * Controls a specific audio stream.
|
|---|
| 1584 | *
|
|---|
| 1585 | * @returns VBox status code.
|
|---|
| 1586 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1587 | * @param pStream Pointer to audio stream.
|
|---|
| 1588 | * @param enmStreamCmd The stream command to issue.
|
|---|
| 1589 | */
|
|---|
| 1590 | DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
|
|---|
| 1591 | PDMAUDIOSTREAMCMD enmStreamCmd));
|
|---|
| 1592 |
|
|---|
| 1593 | /**
|
|---|
| 1594 | * Processes stream data.
|
|---|
| 1595 | *
|
|---|
| 1596 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1597 | * @param pStream Pointer to audio stream.
|
|---|
| 1598 | */
|
|---|
| 1599 | DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
|
|---|
| 1600 |
|
|---|
| 1601 | /**
|
|---|
| 1602 | * Returns the number of readable data (in bytes) of a specific audio input stream.
|
|---|
| 1603 | *
|
|---|
| 1604 | * @returns Number of bytes of readable data.
|
|---|
| 1605 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1606 | * @param pStream Pointer to audio stream.
|
|---|
| 1607 | */
|
|---|
| 1608 | DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
|
|---|
| 1609 |
|
|---|
| 1610 | /**
|
|---|
| 1611 | * Returns the number of writable data (in bytes) of a specific audio output stream.
|
|---|
| 1612 | *
|
|---|
| 1613 | * @returns Number of bytes writable data.
|
|---|
| 1614 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1615 | * @param pStream Pointer to audio stream.
|
|---|
| 1616 | */
|
|---|
| 1617 | DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
|
|---|
| 1618 |
|
|---|
| 1619 | /**
|
|---|
| 1620 | * Returns the status of a specific audio stream.
|
|---|
| 1621 | *
|
|---|
| 1622 | * @returns Audio stream status
|
|---|
| 1623 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1624 | * @param pStream Pointer to audio stream.
|
|---|
| 1625 | */
|
|---|
| 1626 | DECLR3CALLBACKMEMBER(PDMAUDIOSTREAMSTS, pfnStreamGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
|
|---|
| 1627 |
|
|---|
| 1628 | /**
|
|---|
| 1629 | * Sets the audio volume of a specific audio stream.
|
|---|
| 1630 | *
|
|---|
| 1631 | * @returns VBox status code.
|
|---|
| 1632 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1633 | * @param pStream Pointer to audio stream.
|
|---|
| 1634 | * @param pVol Pointer to audio volume structure to set the stream's audio volume to.
|
|---|
| 1635 | */
|
|---|
| 1636 | DECLR3CALLBACKMEMBER(int, pfnStreamSetVolume, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOVOLUME pVol));
|
|---|
| 1637 |
|
|---|
| 1638 | /**
|
|---|
| 1639 | * Plays (transfers) available audio frames to the host backend.
|
|---|
| 1640 | *
|
|---|
| 1641 | * Only works with output streams.
|
|---|
| 1642 | *
|
|---|
| 1643 | * @returns VBox status code.
|
|---|
| 1644 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1645 | * @param pStream Pointer to audio stream.
|
|---|
| 1646 | * @param pcFramesPlayed Number of frames played. Optional.
|
|---|
| 1647 | */
|
|---|
| 1648 | DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcFramesPlayed));
|
|---|
| 1649 |
|
|---|
| 1650 | /**
|
|---|
| 1651 | * Captures (transfers) available audio frames from the host backend.
|
|---|
| 1652 | *
|
|---|
| 1653 | * Only works with input streams.
|
|---|
| 1654 | *
|
|---|
| 1655 | * @returns VBox status code.
|
|---|
| 1656 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1657 | * @param pStream Pointer to audio stream.
|
|---|
| 1658 | * @param pcFramesCaptured Number of frames captured. Optional.
|
|---|
| 1659 | */
|
|---|
| 1660 | DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
|
|---|
| 1661 | uint32_t *pcFramesCaptured));
|
|---|
| 1662 |
|
|---|
| 1663 | /**
|
|---|
| 1664 | * Registers (device) callbacks.
|
|---|
| 1665 | * This is handy for letting the device emulation know of certain events, e.g. processing input / output data
|
|---|
| 1666 | * or configuration changes.
|
|---|
| 1667 | *
|
|---|
| 1668 | * @returns VBox status code.
|
|---|
| 1669 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1670 | * @param paCallbacks Pointer to array of callbacks to register.
|
|---|
| 1671 | * @param cCallbacks Number of callbacks to register.
|
|---|
| 1672 | */
|
|---|
| 1673 | DECLR3CALLBACKMEMBER(int, pfnRegisterCallbacks, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOCBRECORD paCallbacks,
|
|---|
| 1674 | size_t cCallbacks));
|
|---|
| 1675 |
|
|---|
| 1676 | } PDMIAUDIOCONNECTOR;
|
|---|
| 1677 |
|
|---|
| 1678 | /** PDMIAUDIOCONNECTOR interface ID. */
|
|---|
| 1679 | #define PDMIAUDIOCONNECTOR_IID "00e704ef-0078-4bb6-0005-a5fd000ded9f"
|
|---|
| 1680 |
|
|---|
| 1681 |
|
|---|
| 1682 | /**
|
|---|
| 1683 | * PDM host audio interface.
|
|---|
| 1684 | */
|
|---|
| 1685 | typedef struct PDMIHOSTAUDIO
|
|---|
| 1686 | {
|
|---|
| 1687 | /**
|
|---|
| 1688 | * Initializes the host backend (driver).
|
|---|
| 1689 | *
|
|---|
| 1690 | * @returns VBox status code.
|
|---|
| 1691 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1692 | */
|
|---|
| 1693 | DECLR3CALLBACKMEMBER(int, pfnInit, (PPDMIHOSTAUDIO pInterface));
|
|---|
| 1694 |
|
|---|
| 1695 | /**
|
|---|
| 1696 | * Shuts down the host backend (driver).
|
|---|
| 1697 | *
|
|---|
| 1698 | * @returns VBox status code.
|
|---|
| 1699 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1700 | */
|
|---|
| 1701 | DECLR3CALLBACKMEMBER(void, pfnShutdown, (PPDMIHOSTAUDIO pInterface));
|
|---|
| 1702 |
|
|---|
| 1703 | /**
|
|---|
| 1704 | * Returns the host backend's configuration (backend).
|
|---|
| 1705 | *
|
|---|
| 1706 | * @returns VBox status code.
|
|---|
| 1707 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1708 | * @param pBackendCfg Where to store the backend audio configuration to.
|
|---|
| 1709 | */
|
|---|
| 1710 | DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg));
|
|---|
| 1711 |
|
|---|
| 1712 | /**
|
|---|
| 1713 | * Returns (enumerates) host audio device information.
|
|---|
| 1714 | *
|
|---|
| 1715 | * @returns VBox status code.
|
|---|
| 1716 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1717 | * @param pDeviceEnum Where to return the enumerated audio devices.
|
|---|
| 1718 | */
|
|---|
| 1719 | DECLR3CALLBACKMEMBER(int, pfnGetDevices, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHOSTENUM pDeviceEnum));
|
|---|
| 1720 |
|
|---|
| 1721 | /**
|
|---|
| 1722 | * Returns the current status from the audio backend.
|
|---|
| 1723 | *
|
|---|
| 1724 | * @returns PDMAUDIOBACKENDSTS enum.
|
|---|
| 1725 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1726 | * @param enmDir Audio direction to get status for. Pass PDMAUDIODIR_DUPLEX for overall status.
|
|---|
| 1727 | */
|
|---|
| 1728 | DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir));
|
|---|
| 1729 |
|
|---|
| 1730 | /**
|
|---|
| 1731 | * Sets a callback the audio backend can call. Optional.
|
|---|
| 1732 | *
|
|---|
| 1733 | * @returns VBox status code.
|
|---|
| 1734 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1735 | * @param pfnCallback The callback function to use, or NULL when unregistering.
|
|---|
| 1736 | */
|
|---|
| 1737 | DECLR3CALLBACKMEMBER(int, pfnSetCallback, (PPDMIHOSTAUDIO pInterface, PFNPDMHOSTAUDIOCALLBACK pfnCallback));
|
|---|
| 1738 |
|
|---|
| 1739 | /**
|
|---|
| 1740 | * Creates an audio stream using the requested stream configuration.
|
|---|
| 1741 | *
|
|---|
| 1742 | * If a backend is not able to create this configuration, it will return its
|
|---|
| 1743 | * best match in the acquired configuration structure on success.
|
|---|
| 1744 | *
|
|---|
| 1745 | * @returns VBox status code.
|
|---|
| 1746 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1747 | * @param pStream Pointer to audio stream.
|
|---|
| 1748 | * @param pCfgReq Pointer to requested stream configuration.
|
|---|
| 1749 | * @param pCfgAcq Pointer to acquired stream configuration.
|
|---|
| 1750 | * @todo r=bird: Implementation (at least Alsa) seems to make undocumented
|
|---|
| 1751 | * assumptions about the content of @a pCfgAcq.
|
|---|
| 1752 | */
|
|---|
| 1753 | DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
|
|---|
| 1754 | PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq));
|
|---|
| 1755 |
|
|---|
| 1756 | /**
|
|---|
| 1757 | * Destroys an audio stream.
|
|---|
| 1758 | *
|
|---|
| 1759 | * @returns VBox status code.
|
|---|
| 1760 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1761 | * @param pStream Pointer to audio stream.
|
|---|
| 1762 | */
|
|---|
| 1763 | DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
|
|---|
| 1764 |
|
|---|
| 1765 | /**
|
|---|
| 1766 | * Controls an audio stream.
|
|---|
| 1767 | *
|
|---|
| 1768 | * @returns VBox status code.
|
|---|
| 1769 | * @retval VERR_AUDIO_STREAM_NOT_READY if stream is not ready for required operation (yet).
|
|---|
| 1770 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1771 | * @param pStream Pointer to audio stream.
|
|---|
| 1772 | * @param enmStreamCmd The stream command to issue.
|
|---|
| 1773 | */
|
|---|
| 1774 | DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
|
|---|
| 1775 | PDMAUDIOSTREAMCMD enmStreamCmd));
|
|---|
| 1776 |
|
|---|
| 1777 | /**
|
|---|
| 1778 | * Returns the amount which is readable from the audio (input) stream.
|
|---|
| 1779 | *
|
|---|
| 1780 | * @returns For non-raw layout streams: Number of readable bytes.
|
|---|
| 1781 | * for raw layout streams : Number of readable audio frames.
|
|---|
| 1782 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1783 | * @param pStream Pointer to audio stream.
|
|---|
| 1784 | */
|
|---|
| 1785 | DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
|
|---|
| 1786 |
|
|---|
| 1787 | /**
|
|---|
| 1788 | * Returns the amount which is writable to the audio (output) stream.
|
|---|
| 1789 | *
|
|---|
| 1790 | * @returns Number of writable bytes.
|
|---|
| 1791 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1792 | * @param pStream Pointer to audio stream.
|
|---|
| 1793 | */
|
|---|
| 1794 | DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
|
|---|
| 1795 |
|
|---|
| 1796 | /**
|
|---|
| 1797 | * Returns the amount which is pending (in other words has not yet been processed) by/from the backend yet.
|
|---|
| 1798 | * Optional.
|
|---|
| 1799 | *
|
|---|
| 1800 | * For input streams this is read audio data by the backend which has not been processed by the host yet.
|
|---|
| 1801 | * For output streams this is written audio data to the backend which has not been processed by the backend yet.
|
|---|
| 1802 | *
|
|---|
| 1803 | * @returns For non-raw layout streams: Number of pending bytes.
|
|---|
| 1804 | * for raw layout streams : Number of pending audio frames.
|
|---|
| 1805 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1806 | * @param pStream Pointer to audio stream.
|
|---|
| 1807 | */
|
|---|
| 1808 | DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetPending, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
|
|---|
| 1809 |
|
|---|
| 1810 | /**
|
|---|
| 1811 | * Returns the current status of the given backend stream.
|
|---|
| 1812 | *
|
|---|
| 1813 | * @returns PDMAUDIOSTREAMSTS
|
|---|
| 1814 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1815 | * @param pStream Pointer to audio stream.
|
|---|
| 1816 | */
|
|---|
| 1817 | DECLR3CALLBACKMEMBER(PDMAUDIOSTREAMSTS, pfnStreamGetStatus, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
|
|---|
| 1818 |
|
|---|
| 1819 | /**
|
|---|
| 1820 | * Gives the host backend the chance to do some (necessary) iteration work.
|
|---|
| 1821 | *
|
|---|
| 1822 | * @returns VBox status code.
|
|---|
| 1823 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1824 | * @param pStream Pointer to audio stream.
|
|---|
| 1825 | */
|
|---|
| 1826 | DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
|
|---|
| 1827 |
|
|---|
| 1828 | /**
|
|---|
| 1829 | * Signals the backend that the host wants to begin playing for this iteration. Optional.
|
|---|
| 1830 | *
|
|---|
| 1831 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1832 | * @param pStream Pointer to audio stream.
|
|---|
| 1833 | */
|
|---|
| 1834 | DECLR3CALLBACKMEMBER(void, pfnStreamPlayBegin, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
|
|---|
| 1835 |
|
|---|
| 1836 | /**
|
|---|
| 1837 | * Plays (writes to) an audio (output) stream.
|
|---|
| 1838 | *
|
|---|
| 1839 | * @returns VBox status code.
|
|---|
| 1840 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1841 | * @param pStream Pointer to audio stream.
|
|---|
| 1842 | * @param pvBuf Pointer to audio data buffer to play.
|
|---|
| 1843 | * @param cbBuf The number of bytes of audio data to play.
|
|---|
| 1844 | * @param pcbWritten Where to return the actual number of bytes played.
|
|---|
| 1845 | */
|
|---|
| 1846 | DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
|
|---|
| 1847 | const void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten));
|
|---|
| 1848 |
|
|---|
| 1849 | /**
|
|---|
| 1850 | * Signals the backend that the host finished playing for this iteration. Optional.
|
|---|
| 1851 | *
|
|---|
| 1852 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1853 | * @param pStream Pointer to audio stream.
|
|---|
| 1854 | */
|
|---|
| 1855 | DECLR3CALLBACKMEMBER(void, pfnStreamPlayEnd, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
|
|---|
| 1856 |
|
|---|
| 1857 | /**
|
|---|
| 1858 | * Signals the backend that the host wants to begin capturing for this iteration. Optional.
|
|---|
| 1859 | *
|
|---|
| 1860 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1861 | * @param pStream Pointer to audio stream.
|
|---|
| 1862 | */
|
|---|
| 1863 | DECLR3CALLBACKMEMBER(void, pfnStreamCaptureBegin, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
|
|---|
| 1864 |
|
|---|
| 1865 | /**
|
|---|
| 1866 | * Captures (reads from) an audio (input) stream.
|
|---|
| 1867 | *
|
|---|
| 1868 | * @returns VBox status code.
|
|---|
| 1869 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1870 | * @param pStream Pointer to audio stream.
|
|---|
| 1871 | * @param pvBuf Buffer where to store read audio data.
|
|---|
| 1872 | * @param uBufSize Size of the audio data buffer (see note below for unit).
|
|---|
| 1873 | * @param puRead Returns number of units read.
|
|---|
| 1874 | * @note The @a uBufSize and @a puRead values are in bytes for non-raw
|
|---|
| 1875 | * layout streams and in frames for raw layout ones.
|
|---|
| 1876 | */
|
|---|
| 1877 | DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
|
|---|
| 1878 | void *pvBuf, uint32_t uBufSize, uint32_t *puRead));
|
|---|
| 1879 |
|
|---|
| 1880 | /**
|
|---|
| 1881 | * Signals the backend that the host finished capturing for this iteration. Optional.
|
|---|
| 1882 | *
|
|---|
| 1883 | * @param pInterface Pointer to the interface structure containing the called function pointer.
|
|---|
| 1884 | * @param pStream Pointer to audio stream.
|
|---|
| 1885 | */
|
|---|
| 1886 | DECLR3CALLBACKMEMBER(void, pfnStreamCaptureEnd, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
|
|---|
| 1887 |
|
|---|
| 1888 | } PDMIHOSTAUDIO;
|
|---|
| 1889 |
|
|---|
| 1890 | /** PDMIHOSTAUDIO interface ID. */
|
|---|
| 1891 | #define PDMIHOSTAUDIO_IID "be34182b-d579-41e8-96e0-abb94900460f"
|
|---|
| 1892 |
|
|---|
| 1893 | /** @} */
|
|---|
| 1894 |
|
|---|
| 1895 | #endif /* !VBOX_INCLUDED_vmm_pdmaudioifs_h */
|
|---|
| 1896 |
|
|---|
