Changeset 65020 in vbox for trunk/src/VBox/Devices/Audio

Timestamp:

Dec 29, 2016 9:23:50 AM (8 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

112515

Message:

Documentation.

File:

• trunk/src/VBox/Devices/Audio/DevIchAc97.cpp (modified) (20 diffs)

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

@@ -509 +509 @@
 }
 
+/**
+ * Retrieves the audio mixer sink of a corresponding AC'97 stream index.
+ *
+ * @returns Pointer to audio mixer sink if found, or NULL if not found / invalid.
+ * @param   pThis               AC'97 state.
+ * @param   uIndex              Stream index to get audio mixer sink for.
+ */
 DECLINLINE(PAUDMIXSINK) ichac97IndexToSink(PAC97STATE pThis, uint8_t uIndex)
 {
@@ -525 +532 @@
 }
 
-/** Fetches the buffer descriptor at _CIV. */
+/**
+ * Fetches the current BDLE (Buffer Descriptor List Entry) of an AC'97 audio stream.
+ *
+ * @returns IPRT status code.
+ * @param   pThis               AC'97 state.
+ * @param   pStream             AC'97 stream to fetch BDLE for.
+ *
+ * @remark  Uses CIV as BDLE index.
+ */
 static void ichac97StreamFetchBDLE(PAC97STATE pThis, PAC97STREAM pStream)
 {
@@ -549 +564 @@
 
 /**
- * Update the BM status register
+ * Updates the status register (SR) of an AC'97 audio stream.
+ *
+ * @param   pThis               AC'97 state.
+ * @param   pStream             AC'97 stream to update SR for.
+ * @param   new_sr              New value for status register (SR).
  */
 static void ichac97StreamUpdateSR(PAC97STATE pThis, PAC97STREAM pStream, uint32_t new_sr)
@@ -620 +639 @@
 }
 
+/**
+ * Enables or disables an AC'97 audio stream.
+ *
+ * @returns IPRT status code.
+ * @param   pThis               AC'97 state.
+ * @param   pStream             AC'97 stream to enable or disable.
+ * @param   fEnable             Whether to enable or disble the stream.
+ */
 static int ichac97StreamEnable(PAC97STATE pThis, PAC97STREAM pStream, bool fEnable)
 {
@@ -713 +740 @@
 
 /**
- * Creates an AC'97 stream.
+ * Creates an AC'97 audio stream.
  *
  * @returns IPRT status code.
@@ -738 +765 @@
 
 /**
- * Destroys an AC'97 stream.
+ * Destroys an AC'97 audio stream.
  *
  * @returns IPRT status code.
@@ -768 +795 @@
 
 /**
- * Creates all AC'97 streams for the device.
+ * Creates all AC'97 audio streams of the device.
  *
  * @returns IPRT status code.
@@ -822 +849 @@
 }
 
+/**
+ * Destroys all AC'97 audio streams of the device.
+ *
+ * @param   pThis               AC'97 state.
+ */
 static void ichac97StreamsDestroy(PAC97STATE pThis)
 {
@@ -1704 +1736 @@
 }
 
+/**
+ * Sets the volume of a specific AC'97 mixer control.
+ *
+ * This currently only supports attenuation -- gain support is currently not implemented.
+ *
+ * @returns IPRT status code.
+ * @param   pThis               AC'97 state.
+ * @param   index               AC'97 mixer index to set volume for.
+ * @param   enmMixerCtl         Corresponding audio mixer sink.
+ * @param   uVal                Volume value to set.
+ */
 static int ichac97MixerSetVolume(PAC97STATE pThis, int index, PDMAUDIOMIXERCTL enmMixerCtl, uint32_t uVal)
 {
@@ -1798 +1841 @@
 }
 
+/**
+ * Converts an AC'97 recording source index to a PDM audio recording source.
+ *
+ * @returns PDM audio recording source.
+ * @param   i                   AC'97 index to convert.
+ */
 static PDMAUDIORECSOURCE ichac97IndextoRecSource(uint8_t i)
 {
@@ -1816 +1865 @@
 }
 
+/**
+ * Converts a PDM audio recording source to an AC'97 recording source index.
+ *
+ * @returns AC'97 recording source index.
+ * @param   rs                  PDM audio recording source to convert.
+ */
 static uint8_t ichac97RecSourceToIndex(PDMAUDIORECSOURCE rs)
 {
@@ -1834 +1889 @@
 }
 
+/**
+ * Performs an AC'97 mixer record select to switch to a different recording
+ * source.
+ *
+ * @param   pThis               AC'97 state.
+ * @param   val                 AC'97 recording source index to set.
+ */
 static void ichac97RecordSelect(PAC97STATE pThis, uint32_t val)
 {
@@ -1845 +1907 @@
 }
 
+/**
+ * Resets the AC'97 mixer.
+ *
+ * @returns IPRT status code.
+ * @param   pThis               AC'97 state.
+ */
 static int ichac97MixerReset(PAC97STATE pThis)
 {
@@ -1949 +2017 @@
 
 #ifndef VBOX_WITH_AUDIO_AC97_CALLBACKS
+/**
+ * Starts the internal audio device timer (if not started yet).
+ *
+ * @param   pThis               AC'97 state.
+ */
 static void ichac97TimerMaybeStart(PAC97STATE pThis)
 {
@@ -1972 +2045 @@
 }
 
+/**
+ * Stops the internal audio device timer (if not stopped yet).
+ *
+ * @param   pThis               AC'97 state.
+ */
 static void ichac97TimerMaybeStop(PAC97STATE pThis)
 {
@@ -1989 +2067 @@
 }
 
+/**
+ * Main routine to perform the actual audio data transfers from the AC'97 streams
+ * to the backend(s) and vice versa.
+ *
+ * @param   pThis               AC'97 state.
+ */
 static void ichac97DoTransfers(PAC97STATE pThis)
 {
@@ -2030 +2114 @@
 #endif /* !VBOX_WITH_AUDIO_AC97_CALLBACKS */
 
+/**
+ * Timer callback which handles the audio data transfers on a periodic basis.
+ *
+ * @param   pDevIns             Device instance.
+ * @param   pTimer              Timer which was used when calling this.
+ * @param   pvUser              User argument as PAC97STATE.
+ */
 static DECLCALLBACK(void) ichac97Timer(PPDMDEVINS pDevIns, PTMTIMER pTimer, void *pvUser)
 {
@@ -2817 +2908 @@
 }
 
+/**
+ * Retrieves an AC'97 audio stream from an AC'97 stream index.
+ *
+ * @returns Pointer to AC'97 audio stream if found, or NULL if not found / invalid.
+ * @param                       AC'97 state.
+ */
 DECLINLINE(PAC97STREAM) ichac97GetStreamFromID(PAC97STATE pThis, uint32_t uID)
 {
@@ -2831 +2928 @@
 
 #ifdef IN_RING3
+/**
+ * Saves (serializes) an AC'97 stream using SSM.
+ *
+ * @returns IPRT status code.
+ * @param   pDevIns             Device instance.
+ * @param   pSSM                Saved state manager (SSM) handle to use.
+ * @param   pStream             AC'97 stream to save.
+ */
 static int ichac97SaveStream(PPDMDEVINS pDevIns, PSSMHANDLE pSSM, PAC97STREAM pStream)
 {
@@ -2886 +2991 @@
 }
 
+/**
+ * Loads an AC'97 stream from SSM.
+ *
+ * @returns IPRT status code.
+ * @param   pDevIns             Device instance.
+ * @param   pSSM                Saved state manager (SSM) handle to use.
+ * @param   pStream             AC'97 stream to load.
+ */
 static int ichac97LoadStream(PPDMDEVINS pDevIns, PSSMHANDLE pSSM, PAC97STREAM pStream)
 {