Changeset 67907 in vbox

Timestamp:

Jul 11, 2017 2:00:07 PM (8 years ago)

Author:

vboxsync

Message:

Audio/DevHDA: More docs, cleanup.

Location:

trunk/src/VBox/Devices/Audio

Files:

• DevHDA.cpp (modified) (5 diffs)
• DevHDACommon.cpp (modified) (2 diffs)
• DevHDACommon.h (modified) (2 diffs)
• HDAStreamChannel.cpp (modified) (6 diffs)

trunk/src/VBox/Devices/Audio/DevHDA.cpp

@@ -137 +137 @@
 
 #ifdef HDA_USE_DMA_ACCESS_HANDLER
+/**
+ * Struct for keeping an HDA DMA access handler context.
+ */
 typedef struct HDADMAACCESSHANDLER
 {
@@ -207 +210 @@
 #ifndef VBOX_DEVICE_STRUCT_TESTCASE
 #ifdef IN_RING3
-static void hdaGctlReset(PHDASTATE pThis);
+static void hdaGCTLReset(PHDASTATE pThis);
 #endif
 
@@ -864 +867 @@
         HDA_REG(pThis, GCTL) &= ~HDA_GCTL_CRST;
 
-        hdaGctlReset(pThis);
+        hdaGCTLReset(pThis);
 #else
         return VINF_IOM_R3_MMIO_WRITE;
@@ -2522 +2525 @@
  *
  */
-static void hdaGctlReset(PHDASTATE pThis)
+static void hdaGCTLReset(PHDASTATE pThis)
 {
     LogFlowFuncEnter();
@@ -4059 +4062 @@
     HDA_REG(pThis, WAKEEN)  = 0x0;
 
-    hdaGctlReset(pThis);
+    hdaGCTLReset(pThis);
 
     /* Indicate that HDA is not in reset. The firmware is supposed to (un)reset HDA,

trunk/src/VBox/Devices/Audio/DevHDACommon.cpp

@@ -31 +31 @@
 #include "HDAStream.h"
 
-AssertCompileSize(HDABDLEDESC, 16); /* Always 16 byte. Also must be aligned on 128-byte boundary. */
-AssertCompile(HDA_MAX_SDI <= HDA_MAX_SDO);
 
 #ifndef DEBUG
@@ -501 +499 @@
 #endif /* IN_RING3 */
 
+/**
+ * Returns a new INTSTS value based on the current device state.
+ *
+ * @returns Determined INTSTS register value.
+ * @param   pThis               HDA state.
+ *
+ * @remark  This function does *not* set INTSTS!
+ */
 uint32_t hdaGetINTSTS(PHDASTATE pThis)
 {

trunk/src/VBox/Devices/Audio/DevHDACommon.h

@@ -70 +70 @@
 #define HDA_MAX_SDO                 4
 #define HDA_MAX_STREAMS             (HDA_MAX_SDI + HDA_MAX_SDO)
+AssertCompile(HDA_MAX_SDI <= HDA_MAX_SDO);
 
 /** Number of general registers. */
@@ -535 +536 @@
     uint32_t     fFlags;
 } HDABDLEDESC, *PHDABDLEDESC;
+AssertCompileSize(HDABDLEDESC, 16); /* Always 16 byte. Also must be aligned on 128-byte boundary. */
 
 /**

trunk/src/VBox/Devices/Audio/HDAStreamChannel.cpp

@@ -27 +27 @@
 #include "HDAStreamChannel.h"
 
+/**
+ * Initializes a stream channel data structure.
+ *
+ * @returns IPRT status code.
+ * @param   pChanData           Channel data to initialize.
+ * @param   fFlags
+ */
 int hdaStreamChannelDataInit(PPDMAUDIOSTREAMCHANNELDATA pChanData, uint32_t fFlags)
 {
@@ -39 +46 @@
 
 /**
- * Frees a stream channel data block again.
+ * Destroys a stream channel data structure.
  *
- * @param   pChanData           Pointer to channel data to free.
+ * @param   pChanData           Channel data to destroy.
  */
 void hdaStreamChannelDataDestroy(PPDMAUDIOSTREAMCHANNELDATA pChanData)
@@ -57 +64 @@
 }
 
+/**
+ * Extracts HDA audio stream data and stores it into the given stream channel data block.
+ *
+ * @returns IPRT status code.
+ * @param   pChan               Channel data to extract audio stream data into.
+ * @param   pvBuf               Buffer of audio data to extract.
+ * @param   cbBuf               Size (in bytes) of audio data to extract.
+ */
 int hdaStreamChannelExtract(PPDMAUDIOSTREAMCHANNEL pChan, const void *pvBuf, size_t cbBuf)
 {
@@ -105 +120 @@
 }
 
+/**
+ * Advances the current read / write pointer by a certain amount.
+ *
+ * @returns IPRT status code.
+ * @param   pChan               Channel data to advance read / write pointer for.
+ * @param   cbAdv               Amount (in bytes) to advance read / write pointer.
+ *
+ * @remark  Currently not used / implemented.
+ */
 int hdaStreamChannelAdvance(PPDMAUDIOSTREAMCHANNEL pChan, size_t cbAdv)
 {
@@ -115 +139 @@
 }
 
+/**
+ * Acquires (reads) audio channel data.
+ * Must be released when done with hdaStreamChannelReleaseData().
+ *
+ * @returns IPRT status code.
+ * @param   pChanData           Channel data to acquire audio channel data from.
+ * @param   pvData              Pointer to buffer where to store the acquired data.
+ * @param   pcbData             Size (in bytes) of acquired data.
+ */
 int hdaStreamChannelAcquireData(PPDMAUDIOSTREAMCHANNELDATA pChanData, void *pvData, size_t *pcbData)
 {
@@ -127 +160 @@
 }
 
+/**
+ * Releases formerly acquired data by hdaStreamChannelAcquireData().
+ *
+ * @returns IPRT status code.
+ * @param   pChanData           Channel data to release formerly acquired data for.
+ */
 int hdaStreamChannelReleaseData(PPDMAUDIOSTREAMCHANNELDATA pChanData)
 {