[Sound-open-firmware] [PATCH 05/10] volume: add doxygen comments

21 Jun 2018

From: Tomasz Lauda tomasz.lauda@linux.intel.com
Adds doxygen comments to volume implementation.
Signed-off-by: Tomasz Lauda tomasz.lauda@linux.intel.com
---
 src/audio/volume.c         | 110 +++++++++++++++++++--
 src/audio/volume.h         |  69 +++++++++----
 src/audio/volume_generic.c | 192 ++++++++++++++++++++++++++++++-------
 src/audio/volume_hifi3.c   |  37 +++++++
 4 files changed, 347 insertions(+), 61 deletions(-)

diff --git a/src/audio/volume.c b/src/audio/volume.c
index 9e2968d..2ac3d64 100644
--- a/src/audio/volume.c
+++ b/src/audio/volume.c
@@ -30,6 +30,14 @@
  *         Tomasz Lauda tomasz.lauda@linux.intel.com
  */
+/**
+ * \file audio/volume.c
+ * \brief Volume component implementation
+ * \authors Liam Girdwood liam.r.girdwood@linux.intel.com\n
+ *          Keyon Jie yang.jie@linux.intel.com\n
+ *          Tomasz Lauda tomasz.lauda@linux.intel.com
+ */
+
 #include <stddef.h>
 #include <errno.h>
 #include <sof/sof.h>
@@ -41,7 +49,11 @@
 #include <sof/clock.h>
 #include "volume.h"
-/* synchronise host mmap() volume with real value */
+/**
+ * \brief Synchronize host mmap() volume with real value.
+ * \param[in,out] cd Volume component private data.
+ * \param[in] chan Channel number.
+ */
 static void vol_sync_host(struct comp_data *cd, uint32_t chan)
 {
    if (cd->hvol == NULL)
@@ -55,13 +67,23 @@ static void vol_sync_host(struct comp_data *cd, uint32_t chan)
    }
 }
+/**
+ * \brief Update volume with target value.
+ * \param[in,out] cd Volume component private data.
+ * \param[in] chan Channel number.
+ */
 static void vol_update(struct comp_data *cd, uint32_t chan)
 {
    cd->volume[chan] = cd->tvolume[chan];
    vol_sync_host(cd, chan);
 }
-/* this ramps volume changes over time */
+/**
+ * \brief Ramps volume changes over time.
+ * \param[in,out] data Volume base component device.
+ * \param[in] delay Update time.
+ * \return Time until next work.
+ */
 static uint64_t vol_work(void *data, uint64_t delay)
 {
    struct comp_dev *dev = (struct comp_dev *)data;
@@ -119,6 +141,12 @@ static uint64_t vol_work(void *data, uint64_t delay)
    	return 0;
 }
+/**
+ * \brief Creates volume component.
+ * \param[in,out] data Volume base component device.
+ * \param[in] delay Update time.
+ * \return Pointer to volume base component device.
+ */
 static struct comp_dev *volume_new(struct sof_ipc_comp *comp)
 {
    struct comp_dev *dev;
@@ -157,6 +185,10 @@ static struct comp_dev *volume_new(struct sof_ipc_comp *comp)
    return dev;
 }
+/**
+ * \brief Frees volume component.
+ * \param[in,out] dev Volume base component device.
+ */
 static void volume_free(struct comp_dev *dev)
 {
    struct comp_data *cd = comp_get_drvdata(dev);
@@ -167,9 +199,12 @@ static void volume_free(struct comp_dev *dev)
    rfree(dev);
 }
-/*
- * Set volume component audio stream parameters - All done in prepare() since
- * we need to know source and sink component params.
+/**
+ * \brief Sets volume component audio stream parameters.
+ * \param[in,out] dev Volume base component device.
+ * \return Error code.
+ *
+ * All done in prepare() since we need to know source and sink component params.
  */
 static int volume_params(struct comp_dev *dev)
 {
@@ -183,6 +218,12 @@ static int volume_params(struct comp_dev *dev)
    return 0;
 }
+/**
+ * \brief Sets channel target volume.
+ * \param[in,out] dev Volume base component device.
+ * \param[in] chan Channel number.
+ * \param[in] vol Target volume.
+ */
 static inline void volume_set_chan(struct comp_dev *dev, int chan, uint32_t vol)
 {
    struct comp_data *cd = comp_get_drvdata(dev);
@@ -202,6 +243,11 @@ static inline void volume_set_chan(struct comp_dev *dev, int chan, uint32_t vol)
    cd->tvolume[chan] = v;
 }
+/**
+ * \brief Mutes channel.
+ * \param[in,out] dev Volume base component device.
+ * \param[in] chan Channel number.
+ */
 static inline void volume_set_chan_mute(struct comp_dev *dev, int chan)
 {
    struct comp_data *cd = comp_get_drvdata(dev);
@@ -212,6 +258,11 @@ static inline void volume_set_chan_mute(struct comp_dev *dev, int chan)
    cd->tvolume[chan] = 0;
 }
+/**
+ * \brief Unmutes channel.
+ * \param[in,out] dev Volume base component device.
+ * \param[in] chan Channel number.
+ */
 static inline void volume_set_chan_unmute(struct comp_dev *dev, int chan)
 {
    struct comp_data *cd = comp_get_drvdata(dev);
@@ -221,6 +272,12 @@ static inline void volume_set_chan_unmute(struct comp_dev *dev, int chan)
    	cd->tvolume[chan] = cd->mvolume[chan];
 }
+/**
+ * \brief Sets volume control command.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] cdata Control command data.
+ * \return Error code.
+ */
 static int volume_ctrl_set_cmd(struct comp_dev *dev,
    		       struct sof_ipc_ctrl_data *cdata)
 {
@@ -280,6 +337,12 @@ static int volume_ctrl_set_cmd(struct comp_dev *dev,
    return 0;
 }
+/**
+ * \brief Gets volume control command.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] cdata Control command data.
+ * \return Error code.
+ */
 static int volume_ctrl_get_cmd(struct comp_dev *dev,
    		       struct sof_ipc_ctrl_data *cdata)
 {
@@ -311,7 +374,13 @@ static int volume_ctrl_get_cmd(struct comp_dev *dev,
    return 0;
 }
-/* used to pass standard and bespoke commands (with data) to component */
+/**
+ * \brief Used to pass standard and bespoke commands (with data) to component.
+ * \param[in,out] dev Volume base component device.
+ * \param[in] cmd Command type.
+ * \param[in,out] data Control command data.
+ * \return Error code.
+ */
 static int volume_cmd(struct comp_dev *dev, int cmd, void *data)
 {
    struct sof_ipc_ctrl_data *cdata = data;
@@ -328,6 +397,12 @@ static int volume_cmd(struct comp_dev *dev, int cmd, void *data)
    }
 }
+/**
+ * \brief Sets volume component state.
+ * \param[in,out] dev Volume base component device.
+ * \param[in] cmd Command type.
+ * \return Error code.
+ */
 static int volume_trigger(struct comp_dev *dev, int cmd)
 {
    trace_volume("trg");
@@ -335,7 +410,11 @@ static int volume_trigger(struct comp_dev *dev, int cmd)
    return comp_set_state(dev, cmd);
 }
-/* copy and process stream data from source to sink buffers */
+/**
+ * \brief Copies and processes stream data.
+ * \param[in,out] dev Volume base component device.
+ * \return Error code.
+ */
 static int volume_copy(struct comp_dev *dev)
 {
    struct comp_data *cd = comp_get_drvdata(dev);
@@ -375,9 +454,13 @@ static int volume_copy(struct comp_dev *dev)
    return dev->frames;
 }
-/*
+/**
+ * \brief Prepares volume component for processing.
+ * \param[in,out] dev Volume base component device.
+ * \return Error code.
+ *
  * Volume component is usually first and last in pipelines so it makes sense
- * to also do some type conversion too.
+ * to also do some type of conversion here.
  */
 static int volume_prepare(struct comp_dev *dev)
 {
@@ -489,6 +572,11 @@ err:
    return ret;
 }
+/**
+ * \brief Resets volume component.
+ * \param[in,out] dev Volume base component device.
+ * \return Error code.
+ */
 static int volume_reset(struct comp_dev *dev)
 {
    trace_volume("res");
@@ -497,6 +585,7 @@ static int volume_reset(struct comp_dev *dev)
    return 0;
 }
+/** \brief Volume component definition. */
 struct comp_driver comp_volume = {
    .type	= SOF_COMP_VOLUME,
    .ops	= {
@@ -511,6 +600,9 @@ struct comp_driver comp_volume = {
    },
 };
+/**
+ * \brief Initializes volume component.
+ */
 void sys_comp_volume_init(void)
 {
    comp_register(&comp_volume);
diff --git a/src/audio/volume.h b/src/audio/volume.h
index f7c9b43..d130fe4 100644
--- a/src/audio/volume.h
+++ b/src/audio/volume.h
@@ -28,6 +28,14 @@
  * Author: Tomasz Lauda tomasz.lauda@linux.intel.com
  */
+/**
+ * \file audio/volume.h
+ * \brief Volume component header file
+ * \authors Liam Girdwood liam.r.girdwood@linux.intel.com\n
+ *          Keyon Jie yang.jie@linux.intel.com\n
+ *          Tomasz Lauda tomasz.lauda@linux.intel.com
+ */
+
 #ifndef VOLUME_H
 #define VOLUME_H
@@ -47,49 +55,70 @@
#endif
+/** \brief Volume trace function. */
 #define trace_volume(__e)	trace_event(TRACE_CLASS_VOLUME, __e)
+
+/** \brief Volume trace value function. */
 #define tracev_volume(__e)	tracev_event(TRACE_CLASS_VOLUME, __e)
+
+/** \brief Volume trace error function. */
 #define trace_volume_error(__e)	trace_error(TRACE_CLASS_VOLUME, __e)
-/* this should ramp from 0dB to mute in 64ms.
- * i.e 2^16 -> 0 in 32 * 2048 steps each lasting 2ms
+/**
+ * \brief Volume ramp time in microseconds.
+ *
+ * This should ramp from 0dB to mute in 64ms.
+ * i.e. 2^16 -> 0 in 32 * 2048 steps each lasting 2ms.
  */
 #define VOL_RAMP_US	2000
+
+/** \brief Volume ramp step. */
 #define VOL_RAMP_STEP	(1 << 11)
+
+/** \brief Volume maximum value. */
 #define VOL_MAX		(1 << 16)
+
+/** \brief Volume minimum value. */
 #define VOL_MIN		0
-/* volume component private data */
+/**
+ * \brief Volume component private data.
+ *
+ * Gain amplitude value is between 0 (mute) ... 2^16 (0dB) ... 2^24 (~+48dB).
+ */
 struct comp_data {
-	uint32_t source_period_bytes;
-	uint32_t sink_period_bytes;
-	enum sof_ipc_frame source_format;
-	enum sof_ipc_frame sink_format;
-	uint32_t volume[SOF_IPC_MAX_CHANNELS];	/* current volume */
-	uint32_t tvolume[SOF_IPC_MAX_CHANNELS];	/* target volume */
-	uint32_t mvolume[SOF_IPC_MAX_CHANNELS];	/* mute volume */
+	uint32_t source_period_bytes;		/**< source number of period bytes */
+	uint32_t sink_period_bytes;		/**< sink number of period bytes */
+	enum sof_ipc_frame source_format;	/**< source frame format */
+	enum sof_ipc_frame sink_format;		/**< sink frame format */
+	uint32_t volume[SOF_IPC_MAX_CHANNELS];	/**< current volume */
+	uint32_t tvolume[SOF_IPC_MAX_CHANNELS];	/**< target volume */
+	uint32_t mvolume[SOF_IPC_MAX_CHANNELS];	/**< mute volume */
    void (*scale_vol)(struct comp_dev *dev, struct comp_buffer *sink,
-			  struct comp_buffer *source);
-	struct work volwork;
-
-	/* host volume readback */
-	struct sof_ipc_ctrl_value_chan *hvol;
+		struct comp_buffer *source);	/**< volume processing function */
+	struct work volwork;			/**< volume scheduled work function */
+	struct sof_ipc_ctrl_value_chan *hvol;	/**< host volume readback */
 };
+/** \brief Volume processing functions map. */
 struct comp_func_map {
-	uint16_t source;	/* source format */
-	uint16_t sink;		/* sink format */
-	uint16_t channels;	/* channel number for the stream */
+	uint16_t source;			/**< source frame format */
+	uint16_t sink;				/**< sink frame format */
+	uint16_t channels;			/**< number of stream channels */
    void (*func)(struct comp_dev *dev, struct comp_buffer *sink,
-		     struct comp_buffer *source);
+		struct comp_buffer *source);	/**< volume processing function */
 };
-/* map of source and sink buffer formats to volume function */
+/** \brief Map of formats with dedicated processing functions. */
 extern const struct comp_func_map func_map[];
typedef void (*scale_vol)(struct comp_dev *, struct comp_buffer *,
    		  struct comp_buffer *);
+/**
+ * \brief Retrievies volume processing function.
+ * \param[in,out] dev Volume base component device.
+ */
 scale_vol vol_get_processing_function(struct comp_dev *dev);
#endif /* VOLUME_H */
diff --git a/src/audio/volume_generic.c b/src/audio/volume_generic.c
index 200cf12..3b91ab5 100644
--- a/src/audio/volume_generic.c
+++ b/src/audio/volume_generic.c
@@ -30,13 +30,27 @@
  *         Tomasz Lauda tomasz.lauda@linux.intel.com
  */
+/**
+ * \file audio/volume_generic.c
+ * \brief Volume generic processing implementation
+ * \authors Liam Girdwood liam.r.girdwood@linux.intel.com\n
+ *          Keyon Jie yang.jie@linux.intel.com\n
+ *          Tomasz Lauda tomasz.lauda@linux.intel.com
+ */
+
 #include "volume.h"
#ifdef CONFIG_GENERIC
-/* volume scaling functions for stereo input */
-
-/* copy and scale volume from 16 bit source buffer to 32 bit dest buffer */
+/**
+ * \brief Volume processing from 16 bit to 32 bit in 2 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 16 bit source buffer
+ * to 32 bit destination buffer for 2 channels.
+ */
 static void vol_s16_to_s32_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
 {
@@ -53,7 +67,15 @@ static void vol_s16_to_s32_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
-/* copy and scale volume from 32 bit source buffer to 16 bit dest buffer */
+/**
+ * \brief Volume processing from 32 bit to 16 bit in 2 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 32 bit source buffer
+ * to 16 bit destination buffer for 2 channels.
+ */
 static void vol_s32_to_s16_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
 {
@@ -72,7 +94,15 @@ static void vol_s32_to_s16_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
-/* copy and scale volume from 32 bit source buffer to 32 bit dest buffer */
+/**
+ * \brief Volume processing from 32 bit to 32 bit in 2 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 32 bit source buffer
+ * to 32 bit destination buffer for 2 channels.
+ */
 static void vol_s32_to_s32_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
 {
@@ -91,7 +121,15 @@ static void vol_s32_to_s32_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
-/* copy and scale volume from 16 bit source buffer to 16 bit dest buffer */
+/**
+ * \brief Volume processing from 16 bit to 16 bit in 2 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 16 bit source buffer
+ * to 16 bit destination buffer for 2 channels.
+ */
 static void vol_s16_to_s16_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
 {
@@ -110,8 +148,14 @@ static void vol_s16_to_s16_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
-/* copy and scale volume from 16 bit source buffer to 24 bit
- * on 32 bit boundary dest buffer
+/**
+ * \brief Volume processing from 16 bit to 24/32 bit in 2 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 16 bit source buffer
+ * to 24/32 bit destination buffer for 2 channels.
  */
 static void vol_s16_to_s24_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
@@ -131,8 +175,14 @@ static void vol_s16_to_s24_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
-/* copy and scale volume from 16 bit source buffer to 24 bit
- * on 32 bit boundary dest buffer
+/**
+ * \brief Volume processing from 24/32 bit to 16 bit in 2 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 24/32 bit source buffer
+ * to 16 bit destination buffer for 2 channels.
  */
 static void vol_s24_to_s16_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
@@ -154,8 +204,14 @@ static void vol_s24_to_s16_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
-/* copy and scale volume from 32 bit source buffer to 24 bit
- * on 32 bit boundary dest buffer
+/**
+ * \brief Volume processing from 32 bit to 24/32 bit in 2 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 32 bit source buffer
+ * to 24/32 bit destination buffer for 2 channels.
  */
 static void vol_s32_to_s24_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
@@ -175,8 +231,14 @@ static void vol_s32_to_s24_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
-/* copy and scale volume from 16 bit source buffer to 24 bit
- * on 32 bit boundary dest buffer
+/**
+ * \brief Volume processing from 24/32 bit to 32 bit in 2 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 24/32 bit source buffer
+ * to 32 bit destination buffer for 2 channels.
  */
 static void vol_s24_to_s32_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
@@ -198,8 +260,14 @@ static void vol_s24_to_s32_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
-/* copy and scale volume from 24 bit source buffer to 24 bit on 32 bit boundary
- * dest buffer.
+/**
+ * \brief Volume processing from 24/32 bit to 24/32 bit in 2 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 24/32 bit source buffer
+ * to 24/32 bit destination buffer for 2 channels.
  */
 static void vol_s24_to_s24_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
@@ -220,9 +288,15 @@ static void vol_s24_to_s24_2ch(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
-/* volume scaling functions for 4-channel input */
-
-/* copy and scale volume from 16 bit source buffer to 32 bit dest buffer */
+/**
+ * \brief Volume processing from 16 bit to 32 bit in 4 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 16 bit source buffer
+ * to 32 bit destination buffer for 4 channels.
+ */
 static void vol_s16_to_s32_4ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
 {
@@ -241,7 +315,15 @@ static void vol_s16_to_s32_4ch(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
-/* copy and scale volume from 32 bit source buffer to 16 bit dest buffer */
+/**
+ * \brief Volume processing from 32 bit to 16 bit in 4 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 32 bit source buffer
+ * to 16 bit destination buffer for 4 channels.
+ */
 static void vol_s32_to_s16_4ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
 {
@@ -274,7 +356,15 @@ static void vol_s32_to_s16_4ch(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
-/* copy and scale volume from 32 bit source buffer to 32 bit dest buffer */
+/**
+ * \brief Volume processing from 32 bit to 32 bit in 4 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 32 bit source buffer
+ * to 32 bit destination buffer for 4 channels.
+ */
 static void vol_s32_to_s32_4ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
 {
@@ -297,7 +387,15 @@ static void vol_s32_to_s32_4ch(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
-/* copy and scale volume from 16 bit source buffer to 16 bit dest buffer */
+/**
+ * \brief Volume processing from 16 bit to 16 bit in 4 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 16 bit source buffer
+ * to 16 bit destination buffer for 4 channels.
+ */
 static void vol_s16_to_s16_4ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
 {
@@ -320,8 +418,14 @@ static void vol_s16_to_s16_4ch(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
-/* copy and scale volume from 16 bit source buffer to 24 bit
- * on 32 bit boundary buffer
+/**
+ * \brief Volume processing from 16 bit to 24/32 bit in 4 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 16 bit source buffer
+ * to 24/32 bit destination buffer for 4 channels.
  */
 static void vol_s16_to_s24_4ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
@@ -345,8 +449,14 @@ static void vol_s16_to_s24_4ch(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
-/* copy and scale volume from 16 bit source buffer to 24 bit
- * on 32 bit boundary dest buffer
+/**
+ * \brief Volume processing from 24/32 bit to 16 bit in 4 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 24/32 bit source buffer
+ * to 16 bit destination buffer for 4 channels.
  */
 static void vol_s24_to_s16_4ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
@@ -384,8 +494,14 @@ static void vol_s24_to_s16_4ch(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
-/* copy and scale volume from 32 bit source buffer to 24 bit
- * on 32 bit boundary dest buffer
+/**
+ * \brief Volume processing from 32 bit to 24/32 bit in 4 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 32 bit source buffer
+ * to 24/32 bit destination buffer for 4 channels.
  */
 static void vol_s32_to_s24_4ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
@@ -409,8 +525,14 @@ static void vol_s32_to_s24_4ch(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
-/* copy and scale volume from 16 bit source buffer to 24 bit
- * on 32 bit boundary dest buffer
+/**
+ * \brief Volume processing from 24/32 bit to 32 bit in 4 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 24/32 bit source buffer
+ * to 32 bit destination buffer for 4 channels.
  */
 static void vol_s24_to_s32_4ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
@@ -438,8 +560,14 @@ static void vol_s24_to_s32_4ch(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
-/* Copy and scale volume from 24 bit source buffer to 24 bit on 32 bit boundary
- * dest buffer.
+/**
+ * \brief Volume processing from 24/32 bit to 24/32 bit in 4 channels.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ *
+ * Copy and scale volume from 24/32 bit source buffer
+ * to 24/32 bit destination buffer for 4 channels.
  */
 static void vol_s24_to_s24_4ch(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
diff --git a/src/audio/volume_hifi3.c b/src/audio/volume_hifi3.c
index e410de3..48e164e 100644
--- a/src/audio/volume_hifi3.c
+++ b/src/audio/volume_hifi3.c
@@ -28,14 +28,27 @@
  * Author: Tomasz Lauda tomasz.lauda@linux.intel.com
  */
+/**
+ * \file audio/volume_hifi3.c
+ * \brief Volume HiFi3 processing implementation
+ * \authors Tomasz Lauda tomasz.lauda@linux.intel.com
+ */
+
 #include "volume.h"
#if defined(__XCC__) && XCHAL_HAVE_HIFI3
#include <xtensa/tie/xt_hifi3.h>
+/** \brief Volume scale ratio. */
 #define VOL_SCALE (uint32_t)((double)INT32_MAX / VOL_MAX)
+/**
+ * \brief HiFi3 enabled volume processing from 16 bit to 16 bit.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ */
 static void vol_s16_to_s16(struct comp_dev *dev, struct comp_buffer *sink,
    		   struct comp_buffer *source)
 {
@@ -78,6 +91,12 @@ static void vol_s16_to_s16(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
+/**
+ * \brief HiFi3 enabled volume processing from 16 bit to x bit.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ */
 static void vol_s16_to_sX(struct comp_dev *dev, struct comp_buffer *sink,
    		  struct comp_buffer *source)
 {
@@ -129,6 +148,12 @@ static void vol_s16_to_sX(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
+/**
+ * \brief HiFi3 enabled volume processing from x bit to 16 bit.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ */
 static void vol_sX_to_s16(struct comp_dev *dev, struct comp_buffer *sink,
    		  struct comp_buffer *source)
 {
@@ -179,6 +204,12 @@ static void vol_sX_to_s16(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
+/**
+ * \brief HiFi3 enabled volume processing from 24/32 bit to 24/32 or 32 bit.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ */
 static void vol_s24_to_s24_s32(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
 {
@@ -228,6 +259,12 @@ static void vol_s24_to_s24_s32(struct comp_dev *dev, struct comp_buffer *sink,
    }
 }
+/**
+ * \brief HiFi3 enabled volume processing from 32 bit to 24/32 or 32 bit.
+ * \param[in,out] dev Volume base component device.
+ * \param[in,out] sink Destination buffer.
+ * \param[in,out] source Source buffer.
+ */
 static void vol_s32_to_s24_s32(struct comp_dev *dev, struct comp_buffer *sink,
    		       struct comp_buffer *source)
 {
-- 
2.17.0


    