Index: /trunk/include/VBox/vmm/pdmaudioifs.h
===================================================================
--- /trunk/include/VBox/vmm/pdmaudioifs.h	(revision 62604)
+++ /trunk/include/VBox/vmm/pdmaudioifs.h	(revision 62605)
@@ -41,13 +41,12 @@
  */
 
-/** @todo r=bird: Don't be lazy with documentation! */
+/** PDM audio driver instance flags. */
 typedef uint32_t PDMAUDIODRVFLAGS;
 
 /** No flags set. */
-/** @todo r=bird: s/PDMAUDIODRVFLAG/PDMAUDIODRV_FLAGS/g */
-#define PDMAUDIODRVFLAG_NONE        0
+#define PDMAUDIODRVFLAGS_NONE       0
 /** Marks a primary audio driver which is critical
  *  when running the VM. */
-#define PDMAUDIODRVFLAG_PRIMARY     RT_BIT(0)
+#define PDMAUDIODRVFLAGS_PRIMARY    RT_BIT(0)
 
 /**
@@ -56,10 +55,17 @@
 typedef enum PDMAUDIOFMT
 {
+    /** Invalid format, do not use. */
     PDMAUDIOFMT_INVALID,
+    /** 8-bit, unsigned. */
     PDMAUDIOFMT_U8,
+    /** 8-bit, signed. */
     PDMAUDIOFMT_S8,
+    /** 16-bit, unsigned. */
     PDMAUDIOFMT_U16,
+    /** 16-bit, signed. */
     PDMAUDIOFMT_S16,
+    /** 32-bit, unsigned. */
     PDMAUDIOFMT_U32,
+    /** 32-bit, signed. */
     PDMAUDIOFMT_S32,
     /** Hack to blow the type up to 32-bit. */
@@ -93,5 +99,7 @@
 typedef struct PDMAUDIOSAMPLE
 {
+    /** Left channel. */
     int64_t i64LSample;
+    /** Right channel. */
     int64_t i64RSample;
 } PDMAUDIOSAMPLE;
@@ -122,6 +130,9 @@
 typedef enum PDMAUDIODIR
 {
+    /** Unknown direction. */
     PDMAUDIODIR_UNKNOWN = 0,
+    /** Input. */
     PDMAUDIODIR_IN      = 1,
+    /** Output. */
     PDMAUDIODIR_OUT     = 2,
     /** Duplex handling. */
@@ -136,7 +147,11 @@
 typedef enum PDMAUDIOPLAYBACKDEST
 {
+    /** Unknown destination. */
     PDMAUDIOPLAYBACKDEST_UNKNOWN = 0,
+    /** Front channel. */
     PDMAUDIOPLAYBACKDEST_FRONT,
+    /** Center / LFE (Subwoofer) channel. */
     PDMAUDIOPLAYBACKDEST_CENTER_LFE,
+    /** Rear channel. */
     PDMAUDIOPLAYBACKDEST_REAR,
     /** Hack to blow the type up to 32-bit. */
@@ -149,10 +164,17 @@
 typedef enum PDMAUDIORECSOURCE
 {
+    /** Unknown recording source. */
     PDMAUDIORECSOURCE_UNKNOWN = 0,
+    /** Microphone-In. */
     PDMAUDIORECSOURCE_MIC,
+    /** CD. */
     PDMAUDIORECSOURCE_CD,
+    /** Video-In. */
     PDMAUDIORECSOURCE_VIDEO,
+    /** AUX. */
     PDMAUDIORECSOURCE_AUX,
+    /** Line-In. */
     PDMAUDIORECSOURCE_LINE,
+    /** Phone-In. */
     PDMAUDIORECSOURCE_PHONE,
     /** Hack to blow the type up to 32-bit. */
@@ -255,10 +277,17 @@
 typedef enum PDMAUDIOMIXERCTL
 {
+    /** Unknown mixer control. */
     PDMAUDIOMIXERCTL_UNKNOWN = 0,
+    /** Master volume. */
     PDMAUDIOMIXERCTL_VOLUME_MASTER,
+    /** Front. */
     PDMAUDIOMIXERCTL_FRONT,
+    /** Center / LFE (Subwoofer). */
     PDMAUDIOMIXERCTL_CENTER_LFE,
+    /** Rear. */
     PDMAUDIOMIXERCTL_REAR,
+    /** Line-In. */
     PDMAUDIOMIXERCTL_LINE_IN,
+    /** Microphone-In. */
     PDMAUDIOMIXERCTL_MIC_IN,
     /** Hack to blow the type up to 32-bit. */
Index: /trunk/src/VBox/Devices/Audio/AudioMixer.cpp
===================================================================
--- /trunk/src/VBox/Devices/Audio/AudioMixer.cpp	(revision 62604)
+++ /trunk/src/VBox/Devices/Audio/AudioMixer.cpp	(revision 62605)
@@ -61,4 +61,13 @@
 
 
+/**
+ * Creates an audio sink and attaches it to the given mixer.
+ *
+ * @returns IPRT status code.
+ * @param   pMixer              Mixer to attach created sink to.
+ * @param   pszName             Name of the sink to create.
+ * @param   enmDir              Direction of the sink to create.
+ * @param   ppSink              Pointer which returns the created sink on success.
+ */
 int AudioMixerCreateSink(PAUDIOMIXER pMixer, const char *pszName, AUDMIXSINKDIR enmDir, PAUDMIXSINK *ppSink)
 {
@@ -110,8 +119,16 @@
 }
 
-int AudioMixerCreate(const char *pszName, uint32_t uFlags, PAUDIOMIXER *ppMixer)
+/**
+ * Creates an audio mixer.
+ *
+ * @returns IPRT status code.
+ * @param   pszName             Name of the audio mixer.
+ * @param   fFlags              Creation flags. Not used at the moment and must be 0.
+ * @param   ppMixer             Pointer which returns the created mixer object.
+ */
+int AudioMixerCreate(const char *pszName, uint32_t fFlags, PAUDIOMIXER *ppMixer)
 {
     AssertPtrReturn(pszName, VERR_INVALID_POINTER);
-    /** @todo Add flag validation. */
+    /** @todo Add fFlags validation. */
     AssertPtrReturn(ppMixer, VERR_INVALID_POINTER);
 
@@ -149,4 +166,12 @@
 }
 
+/**
+ * Helper function for the internal debugger to print the mixer's current
+ * state, along with the attached sinks.
+ *
+ * @param   pMixer              Mixer to print debug output for.
+ * @param   pHlp                Debug info helper to use.
+ * @param   pszArgs             Optional arguments. Not being used at the moment.
+ */
 void AudioMixerDebug(PAUDIOMIXER pMixer, PCDBGFINFOHLP pHlp, const char *pszArgs)
 {
@@ -165,4 +190,9 @@
 }
 
+/**
+ * Destroys an audio mixer.
+ *
+ * @param   pMixer              Audio mixer to destroy.
+ */
 void AudioMixerDestroy(PAUDIOMIXER pMixer)
 {
@@ -195,15 +225,10 @@
 }
 
-int AudioMixerGetDeviceFormat(PAUDIOMIXER pMixer, PPDMAUDIOSTREAMCFG pCfg)
-{
-    AssertPtrReturn(pMixer, VERR_INVALID_POINTER);
-    AssertPtrReturn(pCfg,   VERR_INVALID_POINTER);
-
-    /** @todo Perform a deep copy, if needed. */
-    *pCfg = pMixer->devFmt;
-
-    return VINF_SUCCESS;
-}
-
+/**
+ * Invalidates all internal data, internal version.
+ *
+ * @returns IPRT status code.
+ * @param   pMixer              Mixer to invalidate data for.
+ */
 int audioMixerInvalidateInternal(PAUDIOMIXER pMixer)
 {
@@ -223,4 +248,10 @@
 }
 
+/**
+ * Invalidates all internal data.
+ *
+ * @returns IPRT status code.
+ * @param   pMixer              Mixer to invalidate data for.
+ */
 void AudioMixerInvalidate(PAUDIOMIXER pMixer)
 {
@@ -233,4 +264,11 @@
 }
 
+/**
+ * Removes a formerly attached audio sink for an audio mixer, internal version.
+ *
+ * @returns IPRT status code.
+ * @param   pMixer              Mixer to remove sink from.
+ * @param   pSink               Sink to remove.
+ */
 static int audioMixerRemoveSinkInternal(PAUDIOMIXER pMixer, PAUDMIXSINK pSink)
 {
@@ -256,19 +294,16 @@
 }
 
+/**
+ * Removes a formerly attached audio sink for an audio mixer.
+ *
+ * @returns IPRT status code.
+ * @param   pMixer              Mixer to remove sink from.
+ * @param   pSink               Sink to remove.
+ */
+
 void AudioMixerRemoveSink(PAUDIOMIXER pMixer, PAUDMIXSINK pSink)
 {
     audioMixerSinkRemoveAllStreamsInternal(pSink);
     audioMixerRemoveSinkInternal(pMixer, pSink);
-}
-
-int AudioMixerSetDeviceFormat(PAUDIOMIXER pMixer, PPDMAUDIOSTREAMCFG pCfg)
-{
-    AssertPtrReturn(pMixer, VERR_INVALID_POINTER);
-    AssertPtrReturn(pCfg, VERR_INVALID_POINTER);
-
-    /** @todo Perform a deep copy, if needed. */
-    pMixer->devFmt = *pCfg;
-
-    return VINF_SUCCESS;
 }
 
@@ -298,4 +333,11 @@
  ********************************************************************************************************************************/
 
+/**
+ * Adds an audio stream to a specific audio sink.
+ *
+ * @returns IPRT status code.
+ * @param   pSink               Sink to add audio stream to.
+ * @param   pStream             Stream to add.
+ */
 int AudioMixerSinkAddStream(PAUDMIXSINK pSink, PAUDMIXSTREAM pStream)
 {
@@ -384,4 +426,14 @@
 }
 
+/**
+ * Creates an audio mixer stream.
+ *
+ * @returns IPRT status code.
+ * @param   pSink               Sink to use for creating the stream.
+ * @param   pConn               Audio connector interface to use.
+ * @param   pCfg                Audio stream configuration to use.
+ * @param   fFlags              Stream creation flags. Currently unused, set to 0.
+ * @param   ppStream            Pointer which receives the the newly created audio stream.
+ */
 int AudioMixerSinkCreateStream(PAUDMIXSINK pSink,
                                PPDMIAUDIOCONNECTOR pConn, PPDMAUDIOSTREAMCFG pCfg, uint32_t fFlags, PAUDMIXSTREAM *ppStream)
@@ -465,4 +517,11 @@
 }
 
+/**
+ * Static helper function to translate a sink command
+ * to a PDM audio stream command.
+ *
+ * @returns PDM audio stream command, or PDMAUDIOSTREAMCMD_UNKNOWN if not found.
+ * @param   enmCmd              Mixer sink command to translate.
+ */
 static PDMAUDIOSTREAMCMD audioMixerSinkToStreamCmd(AUDMIXSINKCMD enmCmd)
 {
@@ -480,4 +539,11 @@
 }
 
+/**
+ * Controls a mixer sink.
+ *
+ * @returns IPRT status code.
+ * @param   pSink               Mixer sink to control.
+ * @param   enmSinkCmd          Sink command to set.
+ */
 int AudioMixerSinkCtl(PAUDMIXSINK pSink, AUDMIXSINKCMD enmSinkCmd)
 {
@@ -518,4 +584,9 @@
 }
 
+/**
+ * Destroys a mixer sink and removes it from the attached mixer (if any).
+ *
+ * @param   pSink               Mixer sink to destroy.
+ */
 void AudioMixerSinkDestroy(PAUDMIXSINK pSink)
 {
@@ -538,4 +609,9 @@
 }
 
+/**
+ * Destroys a mixer sink.
+ *
+ * @param   pSink               Mixer sink to destroy.
+ */
 static void audioMixerSinkDestroyInternal(PAUDMIXSINK pSink)
 {
@@ -570,5 +646,5 @@
  *
  * @returns Amount of bytes ready to be read from the sink.
- * @param   pSink           Sink to return number of available samples for.
+ * @param   pSink               Sink to return number of available samples for.
  */
 uint32_t AudioMixerSinkGetReadable(PAUDMIXSINK pSink)
@@ -591,5 +667,5 @@
  *
  * @returns Amount of bytes ready to be written to the sink.
- * @param   pSink           Sink to return number of available samples for.
+ * @param   pSink               Sink to return number of available samples for.
  */
 uint32_t AudioMixerSinkGetWritable(PAUDMIXSINK pSink)
@@ -611,7 +687,5 @@
  *
  * @returns Mixing direction.
- * @param   pSink           Sink to return direction for.
- *
- * @remark
+ * @param   pSink               Sink to return direction for.
  */
 AUDMIXSINKDIR AudioMixerSinkGetDir(PAUDMIXSINK pSink)
@@ -621,4 +695,11 @@
 }
 
+/**
+ * Returns a specific mixer stream from a sink, based on its index.
+ *
+ * @returns Mixer stream if found, or NULL if not found.
+ * @param   pSink               Sink to retrieve mixer stream from.
+ * @param   uIndex              Index of the mixer stream to return.
+ */
 PAUDMIXSTREAM AudioMixerSinkGetStream(PAUDMIXSINK pSink, uint8_t uIndex)
 {
@@ -639,4 +720,10 @@
 }
 
+/**
+ * Returns the current status of a mixer sink.
+ *
+ * @returns IPRT status code.
+ * @param   pSink               Mixer sink to return status for.
+ */
 AUDMIXSINKSTS AudioMixerSinkGetStatus(PAUDMIXSINK pSink)
 {
@@ -650,4 +737,10 @@
 }
 
+/**
+ * Returns the number of attached mixer streams to a mixer sink.
+ *
+ * @returns IPRT status code.
+ * @param   pSink               Mixer sink to return number for.
+ */
 uint8_t AudioMixerSinkGetStreamCount(PAUDMIXSINK pSink)
 {
@@ -658,4 +751,14 @@
 }
 
+/**
+ * Reads audio data from a mixer sink.
+ *
+ * @returns IPRT status code.
+ * @param   pSink               Mixer sink to read data from.
+ * @param   enmOp               Mixer operation to use for reading the data.
+ * @param   pvBuf               Buffer where to store the read data.
+ * @param   cbBuf               Buffer size (in bytes) where to store the data.
+ * @param   pcbRead             Number of bytes read. Optional.
+ */
 int AudioMixerSinkRead(PAUDMIXSINK pSink, AUDMIXOP enmOp, void *pvBuf, uint32_t cbBuf, uint32_t *pcbRead)
 {
@@ -744,4 +847,11 @@
 }
 
+/**
+ * Removes a mixer stream from a mixer sink, internal version.
+ *
+ * @returns IPRT status code.
+ * @param   pSink               Sink to remove mixer stream from.
+ * @param   pStream             Stream to remove.
+ */
 static int audioMixerSinkRemoveStreamInternal(PAUDMIXSINK pSink, PAUDMIXSTREAM pStream)
 {
@@ -773,4 +883,10 @@
 }
 
+/**
+ * Removes a mixer stream from a mixer sink.
+ *
+ * @param   pSink               Sink to remove mixer stream from.
+ * @param   pStream             Stream to remove.
+ */
 void AudioMixerSinkRemoveStream(PAUDMIXSINK pSink, PAUDMIXSTREAM pStream)
 {
@@ -851,4 +967,11 @@
 }
 
+/**
+ * Sets the audio format of a mixer sink.
+ *
+ * @returns IPRT status code.
+ * @param   pSink               Sink to set audio format for.
+ * @param   pPCMProps           Audio format (PCM properties) to set.
+ */
 int AudioMixerSinkSetFormat(PAUDMIXSINK pSink, PPDMPCMPROPS pPCMProps)
 {
@@ -909,4 +1032,10 @@
 }
 
+/**
+ * Updates a mixer sink, internal version.
+ *
+ * @returns IPRT status code.
+ * @param   pSink               Mixer sink to update.
+ */
 static int audioMixerSinkUpdateInternal(PAUDMIXSINK pSink)
 {
@@ -1053,4 +1182,10 @@
 }
 
+/**
+ * Updates (invalidates) a mixer sink.
+ *
+ * @returns IPRT status code.
+ * @param   pSink               Mixer sink to update.
+ */
 int AudioMixerSinkUpdate(PAUDMIXSINK pSink)
 {
@@ -1069,4 +1204,11 @@
 }
 
+/**
+ * Updates the (master) volume of a mixer sink.
+ *
+ * @returns IPRT status code.
+ * @param   pSink               Mixer sink to update volume for.
+ * @param   pVolMaster          Master volume to set.
+ */
 static int audioMixerSinkUpdateVolume(PAUDMIXSINK pSink, const PPDMAUDIOVOLUME pVolMaster)
 {
@@ -1103,4 +1245,14 @@
 }
 
+/**
+ * Writes data to a mixer sink.
+ *
+ * @returns IPRT status code.
+ * @param   pSink               Sink to write data to.
+ * @param   enmOp               Mixer operation to use when writing data to the sink.
+ * @param   pvBuf               Buffer containing the audio data to write.
+ * @param   cbBuf               Size (in bytes) of the buffer containing the audio data.
+ * @param   pcbWritten          Number of bytes written. Optional.
+ */
 int AudioMixerSinkWrite(PAUDMIXSINK pSink, AUDMIXOP enmOp, const void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten)
 {
@@ -1158,4 +1310,12 @@
  ********************************************************************************************************************************/
 
+/**
+ * Controls a mixer stream.
+ *
+ * @returns IPRT status code.
+ * @param   pMixStream          Mixer stream to control.
+ * @param   enmCmd              Mixer stream command to use.
+ * @param   fCtl                Additional control flags. Pass 0.
+ */
 int AudioMixerStreamCtl(PAUDMIXSTREAM pMixStream, PDMAUDIOSTREAMCMD enmCmd, uint32_t fCtl)
 {
@@ -1168,4 +1328,9 @@
 }
 
+/**
+ * Destroys a mixer stream, internal version.
+ *
+ * @param   pMixStream          Mixer stream to destroy.
+ */
 static void audioMixerStreamDestroyInternal(PAUDMIXSTREAM pMixStream)
 {
@@ -1197,4 +1362,9 @@
 }
 
+/**
+ * Destroys a mixer stream.
+ *
+ * @param   pMixStream          Mixer stream to destroy.
+ */
 void AudioMixerStreamDestroy(PAUDMIXSTREAM pMixStream)
 {
@@ -1228,4 +1398,10 @@
 }
 
+/**
+ * Returns whether a mixer stream currently is active (playing/recording) or not.
+ *
+ * @returns @true if playing/recording, @false if not.
+ * @param   pMixStream          Mixer stream to return status for.
+ */
 bool AudioMixerStreamIsActive(PAUDMIXSTREAM pMixStream)
 {
@@ -1237,4 +1413,10 @@
 }
 
+/**
+ * Returns whether a mixer stream is valid (e.g. initialized and in a working state) or not.
+ *
+ * @returns @true if valid, @false if not.
+ * @param   pMixStream          Mixer stream to return status for.
+ */
 bool AudioMixerStreamIsValid(PAUDMIXSTREAM pMixStream)
 {
Index: /trunk/src/VBox/Devices/Audio/AudioMixer.h
===================================================================
--- /trunk/src/VBox/Devices/Audio/AudioMixer.h	(revision 62604)
+++ /trunk/src/VBox/Devices/Audio/AudioMixer.h	(revision 62605)
@@ -197,5 +197,7 @@
     /** Invalid operation, do not use. */
     AUDMIXOP_INVALID = 0,
+    /** Copy data from A to B, overwriting data in B. */
     AUDMIXOP_COPY,
+    /** Blend data from A with (existing) data in B. */
     AUDMIXOP_BLEND,
     /** The usual 32-bit hack. */
@@ -209,8 +211,6 @@
 int AudioMixerCreateSink(PAUDIOMIXER pMixer, const char *pszName, AUDMIXSINKDIR enmDir, PAUDMIXSINK *ppSink);
 void AudioMixerDestroy(PAUDIOMIXER pMixer);
-int AudioMixerGetDeviceFormat(PAUDIOMIXER pMixer, PPDMAUDIOSTREAMCFG pCfg);
 void AudioMixerInvalidate(PAUDIOMIXER pMixer);
 void AudioMixerRemoveSink(PAUDIOMIXER pMixer, PAUDMIXSINK pSink);
-int AudioMixerSetDeviceFormat(PAUDIOMIXER pMixer, PPDMAUDIOSTREAMCFG pCfg);
 int AudioMixerSetMasterVolume(PAUDIOMIXER pMixer, PPDMAUDIOVOLUME pVol);
 void AudioMixerDebug(PAUDIOMIXER pMixer, PCDBGFINFOHLP pHlp, const char *pszArgs);
Index: /trunk/src/VBox/Devices/Audio/DevIchAc97.cpp
===================================================================
--- /trunk/src/VBox/Devices/Audio/DevIchAc97.cpp	(revision 62604)
+++ /trunk/src/VBox/Devices/Audio/DevIchAc97.cpp	(revision 62605)
@@ -2432,5 +2432,5 @@
              */
             if (pDrv->uLUN == 0)
-                pDrv->Flags |= PDMAUDIODRVFLAG_PRIMARY;
+                pDrv->Flags |= PDMAUDIODRVFLAGS_PRIMARY;
 
             LogFunc(("LUN#%RU8: pCon=%p, drvFlags=0x%x\n", uLUN, pDrv->pConnector, pDrv->Flags));
@@ -2693,14 +2693,4 @@
         if (RT_SUCCESS(rc))
         {
-            /* Set a default audio format for our mixer. */
-            PDMAUDIOSTREAMCFG streamCfg;
-            streamCfg.uHz           = 44100;
-            streamCfg.cChannels     = 2;
-            streamCfg.enmFormat     = PDMAUDIOFMT_S16;
-            streamCfg.enmEndianness = PDMAUDIOHOSTENDIANNESS;
-
-            rc = AudioMixerSetDeviceFormat(pThis->pMixer, &streamCfg);
-            AssertRC(rc);
-
             /* Add all required audio sinks. */
             int rc2 = AudioMixerCreateSink(pThis->pMixer, "[Playback] PCM Output", AUDMIXSINKDIR_OUTPUT, &pThis->pSinkOutput);
@@ -2728,5 +2718,5 @@
              * might not worth showing an own error message box in the GUI.
              */
-            if (!(pDrv->Flags & PDMAUDIODRVFLAG_PRIMARY))
+            if (!(pDrv->Flags & PDMAUDIODRVFLAGS_PRIMARY))
                 continue;
 
@@ -2847,5 +2837,5 @@
             /* Only register primary driver.
              * The device emulation does the output multiplexing then. */
-            if (!(pDrv->Flags & PDMAUDIODRVFLAG_PRIMARY))
+            if (!(pDrv->Flags & PDMAUDIODRVFLAGS_PRIMARY))
                 continue;
 
Index: /trunk/src/VBox/Devices/Audio/DevIchHda.cpp
===================================================================
--- /trunk/src/VBox/Devices/Audio/DevIchHda.cpp	(revision 62604)
+++ /trunk/src/VBox/Devices/Audio/DevIchHda.cpp	(revision 62605)
@@ -2856,5 +2856,5 @@
 
             if (   RT_FAILURE(rc2)
-                && (pDrv->Flags & PDMAUDIODRVFLAG_PRIMARY)) /* We only care about primary drivers here, the rest may fail. */
+                && (pDrv->Flags & PDMAUDIODRVFLAGS_PRIMARY)) /* We only care about primary drivers here, the rest may fail. */
             {
                 if (RT_SUCCESS(rc))
@@ -5600,5 +5600,5 @@
              */
             if (pDrv->uLUN == 0)
-                pDrv->Flags |= PDMAUDIODRVFLAG_PRIMARY;
+                pDrv->Flags |= PDMAUDIODRVFLAGS_PRIMARY;
 
             LogFunc(("LUN#%u: pCon=%p, drvFlags=0x%x\n", uLUN, pDrv->pConnector, pDrv->Flags));
@@ -5916,14 +5916,4 @@
         if (RT_SUCCESS(rc))
         {
-            /* Set a default audio format for our mixer. */
-            PDMAUDIOSTREAMCFG streamCfg;
-            streamCfg.uHz           = 44100;
-            streamCfg.cChannels     = 2;
-            streamCfg.enmFormat     = PDMAUDIOFMT_S16;
-            streamCfg.enmEndianness = PDMAUDIOHOSTENDIANNESS;
-
-            rc = AudioMixerSetDeviceFormat(pThis->pMixer, &streamCfg);
-            AssertRC(rc);
-
             /*
              * Add mixer output sinks.
@@ -6012,5 +6002,5 @@
              * might not worth showing an own error message box in the GUI.
              */
-            if (!(pDrv->Flags & PDMAUDIODRVFLAG_PRIMARY))
+            if (!(pDrv->Flags & PDMAUDIODRVFLAGS_PRIMARY))
                 continue;
 
@@ -6221,5 +6211,5 @@
             /* Only register primary driver.
              * The device emulation does the output multiplexing then. */
-            if (pDrv->Flags != PDMAUDIODRVFLAG_PRIMARY)
+            if (pDrv->Flags != PDMAUDIODRVFLAGS_PRIMARY)
                 continue;
 
Index: /trunk/src/VBox/Devices/Audio/DevSB16.cpp
===================================================================
--- /trunk/src/VBox/Devices/Audio/DevSB16.cpp	(revision 62604)
+++ /trunk/src/VBox/Devices/Audio/DevSB16.cpp	(revision 62605)
@@ -258,5 +258,5 @@
              */
             if (pDrv->uLUN == 0)
-                pDrv->Flags |= PDMAUDIODRVFLAG_PRIMARY;
+                pDrv->Flags |= PDMAUDIODRVFLAGS_PRIMARY;
 
             LogFunc(("LUN#%RU8: pCon=%p, drvFlags=0x%x\n", uLUN, pDrv->pConnector, pDrv->Flags));
@@ -1851,5 +1851,5 @@
             }
 
-            if (pDrv->Flags & PDMAUDIODRVFLAG_PRIMARY)
+            if (pDrv->Flags & PDMAUDIODRVFLAGS_PRIMARY)
             {
                 /* Only do the next DMA transfer if we're able to write the entire
@@ -2421,5 +2421,5 @@
          * might not worth showing an own error message box in the GUI.
          */
-        if (!(pDrv->Flags & PDMAUDIODRVFLAG_PRIMARY))
+        if (!(pDrv->Flags & PDMAUDIODRVFLAGS_PRIMARY))
             continue;
 
@@ -2468,5 +2468,5 @@
             /* Only register primary driver.
              * The device emulation does the output multiplexing then. */
-            if (pDrv->Flags != PDMAUDIODRVFLAG_PRIMARY)
+            if (pDrv->Flags != PDMAUDIODRVFLAGS_PRIMARY)
                 continue;
 
Index: /trunk/src/VBox/Devices/Audio/DrvAudio.cpp
===================================================================
--- /trunk/src/VBox/Devices/Audio/DrvAudio.cpp	(revision 62604)
+++ /trunk/src/VBox/Devices/Audio/DrvAudio.cpp	(revision 62605)
@@ -246,5 +246,9 @@
 #endif /* !VBOX_AUDIO_TESTCASE */
 
-static DECLCALLBACK(int) drvAudioStreamControl(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd)
+/**
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamControl}
+ */
+static DECLCALLBACK(int) drvAudioStreamControl(PPDMIAUDIOCONNECTOR pInterface,
+                                               PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd)
 {
     AssertPtrReturn(pInterface, VERR_INVALID_POINTER);
@@ -270,4 +274,12 @@
 }
 
+/**
+ * Controls an audio stream.
+ *
+ * @returns IPRT status code.
+ * @param   pThis               Pointer to driver instance.
+ * @param   pStream             Stream to control.
+ * @param   enmStreamCmd        Control command.
+ */
 static int drvAudioStreamControlInternal(PDRVAUDIO pThis, PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd)
 {
@@ -363,4 +375,13 @@
 }
 
+/**
+ * Controls a stream's backend.
+ * If the stream has no backend available, VERR_NOT_FOUND is returned.
+ *
+ * @returns IPRT status code.
+ * @param   pThis               Pointer to driver instance.
+ * @param   pStream             Stream to control.
+ * @param   enmStreamCmd        Control command.
+ */
 static int drvAudioStreamControlInternalBackend(PDRVAUDIO pThis, PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd)
 {
@@ -369,5 +390,6 @@
 
     PPDMAUDIOSTREAM pHstStream = drvAudioGetHostStream(pStream);
-    AssertPtr(pHstStream);
+    if (!pHstStream) /* Stream does not have a host backend? Bail out. */
+        return VERR_NOT_FOUND;
 
     LogFlowFunc(("[%s] enmStreamCmd=%RU32, fStatus=0x%x\n", pHstStream->szName, enmStreamCmd, pHstStream->fStatus));
@@ -375,90 +397,87 @@
     AssertPtr(pThis->pHostDrvAudio);
 
-    int rc = VINF_SUCCESS;
-
-    if (RT_SUCCESS(rc))
-    {
-        switch (enmStreamCmd)
-        {
-            case PDMAUDIOSTREAMCMD_ENABLE:
-            {
-                if (!(pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_ENABLED))
+    int rc;
+
+    switch (enmStreamCmd)
+    {
+        case PDMAUDIOSTREAMCMD_ENABLE:
+        {
+            if (!(pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_ENABLED))
+            {
+                LogRel2(("Audio: Enabling stream '%s'\n", pHstStream->szName));
+                rc = pThis->pHostDrvAudio->pfnStreamControl(pThis->pHostDrvAudio, pHstStream, PDMAUDIOSTREAMCMD_ENABLE);
+                if (RT_SUCCESS(rc))
                 {
-                    LogRel2(("Audio: Enabling stream '%s'\n", pHstStream->szName));
-                    rc = pThis->pHostDrvAudio->pfnStreamControl(pThis->pHostDrvAudio, pHstStream, PDMAUDIOSTREAMCMD_ENABLE);
-                    if (RT_SUCCESS(rc))
-                    {
-                        pHstStream->fStatus |= PDMAUDIOSTRMSTS_FLAG_ENABLED;
-                    }
-                    else
-                        LogRel2(("Audio: Disabling stream '%s' failed with %Rrc\n", pHstStream->szName, rc));
+                    pHstStream->fStatus |= PDMAUDIOSTRMSTS_FLAG_ENABLED;
                 }
+                else
+                    LogRel2(("Audio: Disabling stream '%s' failed with %Rrc\n", pHstStream->szName, rc));
+            }
+            break;
+        }
+
+        case PDMAUDIOSTREAMCMD_DISABLE:
+        {
+            if (pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_ENABLED)
+            {
+                LogRel2(("Audio: Disabling stream '%s'\n", pHstStream->szName));
+                rc = pThis->pHostDrvAudio->pfnStreamControl(pThis->pHostDrvAudio, pHstStream, PDMAUDIOSTREAMCMD_DISABLE);
+                if (RT_SUCCESS(rc))
+                {
+                    pHstStream->fStatus &= ~PDMAUDIOSTRMSTS_FLAG_ENABLED;
+                    pHstStream->fStatus &= ~PDMAUDIOSTRMSTS_FLAG_PENDING_DISABLE;
+                    AudioMixBufReset(&pHstStream->MixBuf);
+                }
+                else
+                    LogRel2(("Audio: Disabling stream '%s' failed with %Rrc\n", pHstStream->szName, rc));
+            }
+            break;
+        }
+
+        case PDMAUDIOSTREAMCMD_PAUSE:
+        {
+            /* Only pause if the stream is enabled. */
+            if (!(pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_ENABLED))
                 break;
-            }
-
-            case PDMAUDIOSTREAMCMD_DISABLE:
-            {
-                if (pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_ENABLED)
+
+            if (!(pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_PAUSED))
+            {
+                LogRel2(("Audio: Pausing stream '%s'\n", pHstStream->szName));
+                rc = pThis->pHostDrvAudio->pfnStreamControl(pThis->pHostDrvAudio, pHstStream, PDMAUDIOSTREAMCMD_PAUSE);
+                if (RT_SUCCESS(rc))
                 {
-                    LogRel2(("Audio: Disabling stream '%s'\n", pHstStream->szName));
-                    rc = pThis->pHostDrvAudio->pfnStreamControl(pThis->pHostDrvAudio, pHstStream, PDMAUDIOSTREAMCMD_DISABLE);
-                    if (RT_SUCCESS(rc))
-                    {
-                        pHstStream->fStatus &= ~PDMAUDIOSTRMSTS_FLAG_ENABLED;
-                        pHstStream->fStatus &= ~PDMAUDIOSTRMSTS_FLAG_PENDING_DISABLE;
-                        AudioMixBufReset(&pHstStream->MixBuf);
-                    }
-                    else
-                        LogRel2(("Audio: Disabling stream '%s' failed with %Rrc\n", pHstStream->szName, rc));
+                    pHstStream->fStatus |= PDMAUDIOSTRMSTS_FLAG_PAUSED;
                 }
+                else
+                    LogRel2(("Audio: Pausing stream '%s' failed with %Rrc\n", pHstStream->szName, rc));
+            }
+            break;
+        }
+
+        case PDMAUDIOSTREAMCMD_RESUME:
+        {
+            /* Only need to resume if the stream is enabled. */
+            if (!(pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_ENABLED))
                 break;
-            }
-
-            case PDMAUDIOSTREAMCMD_PAUSE:
-            {
-                /* Only pause if the stream is enabled. */
-                if (!(pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_ENABLED))
-                    break;
-
-                if (!(pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_PAUSED))
+
+            if (pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_PAUSED)
+            {
+                LogRel2(("Audio: Resuming stream '%s'\n", pHstStream->szName));
+                rc = pThis->pHostDrvAudio->pfnStreamControl(pThis->pHostDrvAudio, pHstStream, PDMAUDIOSTREAMCMD_RESUME);
+                if (RT_SUCCESS(rc))
                 {
-                    LogRel2(("Audio: Pausing stream '%s'\n", pHstStream->szName));
-                    rc = pThis->pHostDrvAudio->pfnStreamControl(pThis->pHostDrvAudio, pHstStream, PDMAUDIOSTREAMCMD_PAUSE);
-                    if (RT_SUCCESS(rc))
-                    {
-                        pHstStream->fStatus |= PDMAUDIOSTRMSTS_FLAG_PAUSED;
-                    }
-                    else
-                        LogRel2(("Audio: Pausing stream '%s' failed with %Rrc\n", pHstStream->szName, rc));
+                    pHstStream->fStatus &= ~PDMAUDIOSTRMSTS_FLAG_PAUSED;
                 }
-                break;
-            }
-
-            case PDMAUDIOSTREAMCMD_RESUME:
-            {
-                /* Only need to resume if the stream is enabled. */
-                if (!(pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_ENABLED))
-                    break;
-
-                if (pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_PAUSED)
-                {
-                    LogRel2(("Audio: Resuming stream '%s'\n", pHstStream->szName));
-                    rc = pThis->pHostDrvAudio->pfnStreamControl(pThis->pHostDrvAudio, pHstStream, PDMAUDIOSTREAMCMD_RESUME);
-                    if (RT_SUCCESS(rc))
-                    {
-                        pHstStream->fStatus &= ~PDMAUDIOSTRMSTS_FLAG_PAUSED;
-                    }
-                    else
-                        LogRel2(("Audio: Resuming stream '%s' failed with %Rrc\n", pHstStream->szName, rc));
-                }
-                break;
-            }
-
-            default:
-            {
-                AssertMsgFailed(("Command %RU32 not implemented\n", enmStreamCmd));
-                rc = VERR_NOT_IMPLEMENTED;
-                break;
-            }
+                else
+                    LogRel2(("Audio: Resuming stream '%s' failed with %Rrc\n", pHstStream->szName, rc));
+            }
+            break;
+        }
+
+        default:
+        {
+            AssertMsgFailed(("Command %RU32 not implemented\n", enmStreamCmd));
+            rc = VERR_NOT_IMPLEMENTED;
+            break;
         }
     }
@@ -470,4 +489,13 @@
 }
 
+/**
+ * Initializes an audio stream with a given host and guest stream configuration.
+ *
+ * @returns IPRT status code.
+ * @param   pThis               Pointer to driver instance.
+ * @param   pStream             Stream to initialize.
+ * @param   pCfgHost            Stream configuration to use for the host side (backend).
+ * @param   pCfgGuest           Stream configuration to use for the guest side.
+ */
 static int drvAudioStreamInitInternal(PDRVAUDIO pThis,
                                       PPDMAUDIOSTREAM pStream, PPDMAUDIOSTREAMCFG pCfgHost, PPDMAUDIOSTREAMCFG pCfgGuest)
@@ -592,4 +620,11 @@
 }
 
+/**
+ * Re-initializes an audio stream with its existing host and guest stream configuration.
+ *
+ * @returns IPRT status code.
+ * @param   pThis               Pointer to driver instance.
+ * @param   pStream             Stream to re-initialize.
+ */
 static int drvAudioStreamReInitInternal(PDRVAUDIO pThis, PPDMAUDIOSTREAM pStream)
 {
@@ -657,15 +692,5 @@
 
 /**
- * Writes VM audio output data from the guest stream into the host stream.
- * The attached host driver backend then will play out the audio in a
- * later step then.
- *
- * @return  IPRT status code.
- * @return  int
- * @param   pThis
- * @param   pGstStrmOut
- * @param   pvBuf
- * @param   cbBuf
- * @param   pcbWritten
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamWrite}
  */
 static DECLCALLBACK(int) drvAudioStreamWrite(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
@@ -759,4 +784,7 @@
 }
 
+/**
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamAddRef}
+ */
 static DECLCALLBACK(uint32_t) drvAudioStreamAddRef(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream)
 {
@@ -769,4 +797,7 @@
 }
 
+/**
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamRelease}
+ */
 static DECLCALLBACK(uint32_t) drvAudioStreamRelease(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream)
 {
@@ -782,4 +813,7 @@
 }
 
+/**
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamIterate}
+ */
 static DECLCALLBACK(int) drvAudioStreamIterate(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream)
 {
@@ -806,4 +840,15 @@
 }
 
+/**
+ * Does one iteration of an audio stream.
+ * This function gives the backend the chance of iterating / altering data and
+ * does the actual mixing between the guest <-> host mixing buffers.
+ *
+ * @returns IPRT status code.
+ * @param   pThis               Pointer to driver instance.
+ * @param   pStream             Stream to iterate.
+ *
+ * @remark
+ */
 static int drvAudioStreamIterateInternal(PDRVAUDIO pThis, PPDMAUDIOSTREAM pStream)
 {
@@ -856,23 +901,17 @@
         else if (pHstStream->enmDir == PDMAUDIODIR_OUT)
         {
-            uint32_t cSamplesLive = AudioMixBufLive(&pGstStream->MixBuf);
-            if (!cSamplesLive) /* No live samples at the moment? */
-            {
-                /* When playing samples, the host is the parent while the guest is the child.
-                 * So try mixing not yet mixed guest-side samples to the host-side buffer. */
-                rc = AudioMixBufMixToParent(&pGstStream->MixBuf, AudioMixBufUsed(&pGstStream->MixBuf), &cSamplesMixed);
-                if (   RT_SUCCESS(rc)
-                    && cSamplesMixed)
-                {
-                    Log3Func(("[%s] %RU32 samples mixed\n", pHstStream->szName, cSamplesMixed));
-                }
-
-                if (RT_SUCCESS(rc))
-                    cSamplesLive = AudioMixBufLive(&pGstStream->MixBuf);
-            }
-
-            Log3Func(("[%s] %RU32 live samples\n", pHstStream->szName, cSamplesLive));
-
-            if (!cSamplesLive) /* No live samples (anymore)? */
+            /* When playing samples, the host is the parent while the guest is the child.
+             * So try mixing not yet mixed guest-side samples to the host-side buffer. */
+            rc = AudioMixBufMixToParent(&pGstStream->MixBuf, AudioMixBufUsed(&pGstStream->MixBuf), &cSamplesMixed);
+            if (   RT_SUCCESS(rc)
+                && cSamplesMixed)
+            {
+                Log3Func(("[%s] %RU32 samples mixed, guest has %RU32 samples left (%RU32 live)\n",
+                          pHstStream->szName, cSamplesMixed,
+                          AudioMixBufUsed(&pGstStream->MixBuf), AudioMixBufLive(&pGstStream->MixBuf)));
+            }
+
+            uint32_t cSamplesLeft = AudioMixBufUsed(&pGstStream->MixBuf);
+            if (!cSamplesLeft) /* No samples (anymore)? */
             {
                 fTryClosePending = true;
@@ -911,4 +950,7 @@
 }
 
+/**
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamPlay}
+ */
 static DECLCALLBACK(int) drvAudioStreamPlay(PPDMIAUDIOCONNECTOR pInterface,
                                             PPDMAUDIOSTREAM pStream, uint32_t *pcSamplesPlayed)
@@ -991,8 +1033,7 @@
                     STAM_COUNTER_ADD(&pHstStream->Out.StatSamplesPlayed, cSamplesPlayed);
 #endif
+                    cSamplesLive = AudioMixBufLive(&pGstStream->MixBuf);
                 }
             }
-
-            Log3Func(("[%s] strmSts=0x%x, cSamplesPlayed=%RU32, rc=%Rrc\n", pHstStream->szName, strmSts, cSamplesPlayed, rc));
         }
 
@@ -1032,4 +1073,7 @@
 }
 
+/**
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamCapture}
+ */
 static DECLCALLBACK(int) drvAudioStreamCapture(PPDMIAUDIOCONNECTOR pInterface,
                                                PPDMAUDIOSTREAM pStream, uint32_t *pcSamplesCaptured)
@@ -1120,6 +1164,14 @@
 
 #ifdef VBOX_WITH_AUDIO_CALLBACKS
+/**
+ * Duplicates an audio callback.
+ *
+ * @returns Pointer to duplicated callback, or NULL on failure.
+ * @param   pCB                 Callback to duplicate.
+ */
 static PPDMAUDIOCALLBACK drvAudioCallbackDuplicate(PPDMAUDIOCALLBACK pCB)
 {
+    AssertPtrReturn(pCB, VERR_INVALID_POINTER);
+
     PPDMAUDIOCALLBACK pCBCopy = (PPDMAUDIOCALLBACK)RTMemDup((void *)pCB, sizeof(PDMAUDIOCALLBACK));
     if (!pCBCopy)
@@ -1141,4 +1193,9 @@
 }
 
+/**
+ * Destroys a given callback.
+ *
+ * @param   pCB                 Callback to destroy.
+ */
 static void drvAudioCallbackDestroy(PPDMAUDIOCALLBACK pCB)
 {
@@ -1155,4 +1212,7 @@
 }
 
+/**
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnRegisterCallbacks}
+ */
 static DECLCALLBACK(int) drvAudioRegisterCallbacks(PPDMIAUDIOCONNECTOR pInterface,
                                                    PPDMAUDIOCALLBACK paCallbacks, size_t cCallbacks)
@@ -1202,4 +1262,7 @@
 }
 
+/**
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnCallback}
+ */
 static DECLCALLBACK(int) drvAudioCallback(PPDMIAUDIOCONNECTOR pInterface, PDMAUDIOCALLBACKTYPE enmType,
                                           void *pvUser, size_t cbUser)
@@ -1305,4 +1368,10 @@
 }
 
+/**
+ * Handles state changes for all audio streams.
+ *
+ * @param   pDrvIns             Pointer to driver instance.
+ * @param   enmCmd              Stream command to set for all streams.
+ */
 static void drvAudioStateHandler(PPDMDRVINS pDrvIns, PDMAUDIOSTREAMCMD enmCmd)
 {
@@ -1320,5 +1389,12 @@
 }
 
-static DECLCALLBACK(int) drvAudioInit(PCFGMNODE pCfgHandle, PPDMDRVINS pDrvIns)
+/**
+ * Intializes an audio driver instance.
+ *
+ * @returns IPRT status code.
+ * @param   pDrvIns             Pointer to driver instance.
+ * @param   pCfgHandle          CFGM handle to use for configuration.
+ */
+static int drvAudioInit(PPDMDRVINS pDrvIns, PCFGMNODE pCfgHandle)
 {
     AssertPtrReturn(pCfgHandle, VERR_INVALID_POINTER);
@@ -1342,4 +1418,7 @@
 }
 
+/**
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamRead}
+ */
 static DECLCALLBACK(int) drvAudioStreamRead(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
                                             void *pvBuf, uint32_t cbBuf, uint32_t *pcbRead)
@@ -1432,4 +1511,7 @@
 }
 
+/**
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamCreate}
+ */
 static DECLCALLBACK(int) drvAudioStreamCreate(PPDMIAUDIOCONNECTOR pInterface,
                                               PPDMAUDIOSTREAMCFG pCfgHost, PPDMAUDIOSTREAMCFG pCfgGuest,
@@ -1606,4 +1688,7 @@
 }
 
+/**
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnGetConfig}
+ */
 static DECLCALLBACK(int) drvAudioGetConfig(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOBACKENDCFG pCfg)
 {
@@ -1635,4 +1720,7 @@
 }
 
+/**
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnGetStatus}
+ */
 static DECLCALLBACK(PDMAUDIOBACKENDSTS) drvAudioGetStatus(PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir)
 {
@@ -1661,4 +1749,7 @@
 }
 
+/**
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamGetReadable}
+ */
 static DECLCALLBACK(uint32_t) drvAudioStreamGetReadable(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream)
 {
@@ -1688,5 +1779,6 @@
         cReadable = AudioMixBufLive(&pGstStream->MixBuf);
 
-    Log3Func(("[%s] cbReadable=%RU32\n", pHstStream->szName, cReadable));
+    Log3Func(("[%s] cbReadable=%RU32 (%zu bytes)\n", pHstStream->szName, cReadable,
+              AUDIOMIXBUF_S2B(&pGstStream->MixBuf, cReadable)));
 
     rc2 = RTCritSectLeave(&pThis->CritSect);
@@ -1697,4 +1789,7 @@
 }
 
+/**
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamGetWritable}
+ */
 static DECLCALLBACK(uint32_t) drvAudioStreamGetWritable(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream)
 {
@@ -1715,15 +1810,15 @@
         AssertRC(rc2);
 
+        AssertMsgFailed(("Guest stream '%s' does not have a host stream attached\n", pStream->szName));
         return 0;
     }
 
     PPDMAUDIOSTREAM pGstStream = pHstStream->pPair;
-
-    uint32_t cWritable = 0;
-
-    if (AudioMixBufLive(&pHstStream->MixBuf) == 0)
-        cWritable = AudioMixBufFreeBytes(&pGstStream->MixBuf);
-
-    Log3Func(("[%s] cWritable=%RU32\n", pHstStream->szName, cWritable));
+    AssertPtr(pGstStream);
+
+    uint32_t cWritable = AudioMixBufFree(&pGstStream->MixBuf);
+
+    Log3Func(("[%s] cWritable=%RU32 (%zu bytes)\n", pHstStream->szName, cWritable,
+              AUDIOMIXBUF_S2B(&pGstStream->MixBuf, cWritable)));
 
     rc2 = RTCritSectLeave(&pThis->CritSect);
@@ -1734,4 +1829,7 @@
 }
 
+/**
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamGetStatus}
+ */
 static DECLCALLBACK(PDMAUDIOSTRMSTS) drvAudioStreamGetStatus(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream)
 {
@@ -1761,4 +1859,7 @@
 }
 
+/**
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamSetVolume}
+ */
 static DECLCALLBACK(int) drvAudioStreamSetVolume(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOVOLUME pVol)
 {
@@ -1779,4 +1880,7 @@
 }
 
+/**
+ * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamDestroy}
+ */
 static DECLCALLBACK(int) drvAudioStreamDestroy(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream)
 {
@@ -1855,4 +1959,11 @@
 }
 
+/**
+ * Calls the backend to give it the chance to destroy its part of the audio stream.
+ *
+ * @returns IPRT status code.
+ * @param   pThis               Pointer to driver instance.
+ * @param   pHstStream          Host audio stream to call the backend destruction for.
+ */
 static int drvAudioStreamDestroyInternalBackend(PDRVAUDIO pThis, PPDMAUDIOSTREAM pHstStream)
 {
@@ -1881,4 +1992,12 @@
 }
 
+/**
+ * Destroys an audio stream.
+ *
+ * @returns IPRT status code.
+ * @param   pThis               Pointer to driver instance.
+ * @param   pStream             Pointer to audio stream to destroy.
+ *                              That pointer will be invalid after successful destruction.
+ */
 static int drvAudioStreamDestroyInternal(PDRVAUDIO pThis, PPDMAUDIOSTREAM pStream)
 {
@@ -2068,5 +2187,5 @@
     }
 
-    rc = drvAudioInit(pCfgHandle, pDrvIns);
+    rc = drvAudioInit(pDrvIns, pCfgHandle);
     if (RT_SUCCESS(rc))
     {
Index: /trunk/src/VBox/Devices/Audio/DrvAudioCommon.cpp
===================================================================
--- /trunk/src/VBox/Devices/Audio/DrvAudioCommon.cpp	(revision 62604)
+++ /trunk/src/VBox/Devices/Audio/DrvAudioCommon.cpp	(revision 62605)
@@ -202,4 +202,10 @@
 }
 
+/**
+ * Converts a recording source enumeration to a string.
+ *
+ * @returns Stringified recording source, or "Unknown", if not found.
+ * @param   enmRecSrc           Recording source to convert.
+ */
 const char *DrvAudioHlpRecSrcToStr(PDMAUDIORECSOURCE enmRecSrc)
 {
@@ -281,4 +287,10 @@
 }
 
+/**
+ * Converts an audio format to a string.
+ *
+ * @returns Stringified audio format, or "Unknown", if not found.
+ * @param   enmFmt              Audio format to convert.
+ */
 const char *DrvAudioHlpAudFmtToStr(PDMAUDIOFMT enmFmt)
 {
@@ -308,7 +320,13 @@
 
     AssertMsgFailed(("Bogus audio format %ld\n", enmFmt));
-    return "Invalid";
-}
-
+    return "Unknown";
+}
+
+/**
+ * Converts a given string to an audio format.
+ *
+ * @returns Audio format for the given string, or PDMAUDIOFMT_INVALID if not found.
+ * @param   pszFmt              String to convert to an audio format.
+ */
 PDMAUDIOFMT DrvAudioHlpStrToAudFmt(const char *pszFmt)
 {
@@ -332,4 +350,12 @@
 }
 
+/**
+ * Checks whether the given PCM properties are equal with the given
+ * stream configuration.
+ *
+ * @returns @true if equal, @false if not.
+ * @param   pProps              PCM properties to compare.
+ * @param   pCfg                Stream configuration to compare.
+ */
 bool DrvAudioHlpPCMPropsAreEqual(PPDMPCMPROPS pProps, PPDMAUDIOSTREAMCFG pCfg)
 {
@@ -372,4 +398,11 @@
 }
 
+/**
+ * Checks whether two given PCM properties are equal.
+ *
+ * @returns @true if equal, @false if not.
+ * @param   pProps1             First properties to compare.
+ * @param   pProps2             Second properties to compare.
+ */
 bool DrvAudioHlpPCMPropsAreEqual(PPDMPCMPROPS pProps1, PPDMPCMPROPS pProps2)
 {
@@ -377,5 +410,5 @@
     AssertPtrReturn(pProps2, false);
 
-    if (pProps1 == pProps2)
+    if (pProps1 == pProps2) /* If the pointers match, take a shortcut. */
         return true;
 
@@ -408,4 +441,10 @@
 }
 
+/**
+ * Checks whether a given stream configuration is valid or not.
+ *
+ * Returns @true if configuration is valid, @false if not.
+ * @param   pCfg                Stream configuration to check.
+ */
 bool DrvAudioHlpStreamCfgIsValid(PPDMAUDIOSTREAMCFG pCfg)
 {
@@ -500,4 +539,9 @@
 }
 
+/**
+ * Prints an audio stream configuration to the debug log.
+ *
+ * @param   pCfg                Stream configuration to log.
+ */
 void DrvAudioHlpStreamCfgPrint(PPDMAUDIOSTREAMCFG pCfg)
 {
@@ -546,4 +590,15 @@
 }
 
+/**
+ * Calculates the audio bit rate of the given bits per sample, the Hz and the number
+ * of audio channels.
+ *
+ * Divide the result by 8 to get the byte rate.
+ *
+ * @returns The calculated bit rate.
+ * @param   cBits               Number of bits per sample.
+ * @param   uHz                 Hz (Hertz) rate.
+ * @param   cChannels           Number of audio channels.
+ */
 uint32_t DrvAudioHlpCalcBitrate(uint8_t cBits, uint32_t uHz, uint8_t cChannels)
 {
@@ -551,4 +606,14 @@
 }
 
+/**
+ * Calculates the audio bit rate out of a given audio stream configuration.
+ *
+ * Divide the result by 8 to get the byte rate.
+ *
+ * @returns The calculated bit rate.
+ * @param   pCfg                Audio stream configuration to calculate bit rate for.
+ *
+ * @remark
+ */
 uint32_t DrvAudioHlpCalcBitrate(PPDMAUDIOSTREAMCFG pCfg)
 {
@@ -663,4 +728,14 @@
 }
 
+/**
+ * Opens or creates a wave (.WAV) file.
+ *
+ * @returns IPRT status code.
+ * @param   pFile               Pointer to audio file handle to use.
+ * @param   pszFile             File path of file to open or create.
+ * @param   fOpen               Open flags.
+ * @param   pProps              PCM properties to use.
+ * @param   fFlags              Audio file flags.
+ */
 int DrvAudioHlpWAVFileOpen(PPDMAUDIOFILE pFile, const char *pszFile, uint32_t fOpen, PPDMPCMPROPS pProps,
                            PDMAUDIOFILEFLAGS fFlags)
@@ -729,4 +804,10 @@
 }
 
+/**
+ * Closes a wave (.WAV) audio file.
+ *
+ * @returns IPRT status code.
+ * @param   pFile               Audio file handle to close.
+ */
 int DrvAudioHlpWAVFileClose(PPDMAUDIOFILE pFile)
 {
@@ -759,4 +840,12 @@
 }
 
+/**
+ * Returns the raw PCM audio data size of a wave file.
+ * This does *not* include file headers and other data which does
+ * not belong to the actual PCM audio data.
+ *
+ * @returns Size (in bytes) of the raw PCM audio data.
+ * @param   pFile               Audio file handle to retrieve the audio data size for.
+ */
 size_t DrvAudioHlpWAVFileGetDataSize(PPDMAUDIOFILE pFile)
 {
@@ -771,9 +860,21 @@
 }
 
+/**
+ * Write PCM data to a wave (.WAV) file.
+ *
+ * @returns IPRT status code.
+ * @param   pFile               Audio file handle to write PCM data to.
+ * @param   pvBuf               Audio data to write.
+ * @param   cbBuf               Size (in bytes) of audio data to write.
+ * @param   fFlags              Additional write flags. Not being used at the moment and must be 0.
+ *
+ * @remark
+ */
 int DrvAudioHlpWAVFileWrite(PPDMAUDIOFILE pFile, const void *pvBuf, size_t cbBuf, uint32_t fFlags)
 {
     AssertPtrReturn(pFile, VERR_INVALID_POINTER);
     AssertPtrReturn(pvBuf, VERR_INVALID_POINTER);
-    /** @todo Validate fFlags. */
+
+    AssertReturn(fFlags == 0, VERR_INVALID_PARAMETER); /** @todo fFlags are currently not implemented. */
 
     Assert(pFile->enmType == PDMAUDIOFILETYPE_WAV);
