subchan_demux: add doxygen documentation

2 files changed, 84 insertions, 29 deletions

diff --git a/include/osmocom/abis/subchan_demux.h b/include/osmocom/abis/subchan_demux.h
index b71c856..4e2f464 100644
--- a/include/osmocom/abis/subchan_demux.h
+++ b/include/osmocom/abis/subchan_demux.h
@@ -23,79 +23,87 @@
 #include <stdint.h>
 #include <osmocom/core/linuxlist.h>
 
+/*! \defgroup subchan_demux
+ *  \brief E1 sub-channel multiplexer/demultiplexer
+ *  @{
+ *
+ *  \file subchan_demux.h
+ */
+
+/*! \brief number of 16k sub-channels inside one 64k E1 timeslot */
 #define NR_SUBCH	4
+/*! \brief size of TRAU frames in bytes */
 #define TRAU_FRAME_SIZE	40
+/*! \brief size of TRAU farmes in bits */
 #define TRAU_FRAME_BITS	(TRAU_FRAME_SIZE*8)
 
 /***********************************************************************/
 /* DEMULTIPLEXER */
 /***********************************************************************/
 
+/*! \brief one subchannel inside the demultplexer */
 struct demux_subch {
+	/*! \brief bit-buffer for output bits */
 	uint8_t out_bitbuf[TRAU_FRAME_BITS];
-	uint16_t out_idx; /* next bit to be written in out_bitbuf */
-	/* number of consecutive zeros that we have received (for sync) */
+	/*! \brief next bit to be written in out_bitbuf */
+	uint16_t out_idx;
+	/*! \brief number of consecutive zeros that we have received (for sync) */
 	unsigned int consecutive_zeros;
-	/* are we in TRAU frame sync or not? */
+	/*! \brief  are we in TRAU frame sync or not? */
 	unsigned int in_sync;
 };
 
+/*! \brief one instance of a subchannel demultiplexer */
 struct subch_demux {
-	/* bitmask of currently active subchannels */
+	/*! \brief bitmask of currently active subchannels */
 	uint8_t chan_activ;
-	/* one demux_subch struct for every subchannel */
+	/*! \brief one demux_subch struct for every subchannel */
 	struct demux_subch subch[NR_SUBCH];
-	/* callback to be called once we have received a complete
-	 * frame on a given subchannel */
+	/*! \brief callback to be called once we have received a
+	 *  complete frame on a given subchannel */
 	int (*out_cb)(struct subch_demux *dmx, int ch, uint8_t *data, int len,
 		      void *);
-	/* user-provided data, transparently passed to out_cb() */
+	/*! \brief user-provided data, transparently passed to out_cb() */
 	void *data;
 };
 
-/* initialize one demultiplexer instance */
 int subch_demux_init(struct subch_demux *dmx);
-
-/* feed 'len' number of muxed bytes into the demultiplexer */
 int subch_demux_in(struct subch_demux *dmx, uint8_t *data, int len);
-
-/* activate decoding/processing for one subchannel */
 int subch_demux_activate(struct subch_demux *dmx, int subch);
-
-/* deactivate decoding/processing for one subchannel */
 int subch_demux_deactivate(struct subch_demux *dmx, int subch);
 
 /***********************************************************************/
 /* MULTIPLEXER */
 /***********************************************************************/
 
-/* one element in the tx_queue of a muxer sub-channel */
+/*! \brief one element in the tx_queue of a muxer sub-channel */
 struct subch_txq_entry {
+	/*! \brief internal linked list header */
 	struct llist_head list;
 
-	unsigned int bit_len;	/* total number of bits in 'bits' */
-	unsigned int next_bit;	/* next bit to be transmitted */
+	unsigned int bit_len;	/*!< \brief total number of bits in 'bits' */
+	unsigned int next_bit;	/*!< \brief next bit to be transmitted */
 
-	uint8_t bits[0];	/* one bit per byte */
+	uint8_t bits[0];	/*!< \brief one bit per byte */
 };
 
+/*! \brief one sub-channel inside a multiplexer */
 struct mux_subch {
+	/*! \brief linked list of \ref subch_txq_entry */
 	struct llist_head tx_queue;
 };
 
-/* structure representing one instance of the subchannel muxer */
+/*! \brief one instance of the subchannel multiplexer */
 struct subch_mux {
+	/*! \brief array of sub-channels inside the multiplexer */
 	struct mux_subch subch[NR_SUBCH];
 };
 
-/* initialize a subchannel muxer instance */
 int subchan_mux_init(struct subch_mux *mx);
-
-/* request the output of 'len' multiplexed bytes */
 int subchan_mux_out(struct subch_mux *mx, uint8_t *data, int len);
-
-/* enqueue some data into one sub-channel of the muxer */
 int subchan_mux_enqueue(struct subch_mux *mx, int s_nr, const uint8_t *data,
 			int len);
 
+/* }@ */
+
 #endif /* _SUBCH_DEMUX_H */
diff --git a/src/subchan_demux.c b/src/subchan_demux.c
index eaf2c83..41fe1d2 100644
--- a/src/subchan_demux.c
+++ b/src/subchan_demux.c
@@ -30,6 +30,12 @@
 #include <osmocom/abis/trau_frame.h>
 #include <osmocom/core/talloc.h>
 
+/*! \addtogroup subchan_demux
+ *  @{
+ *
+ *  \file subchan_demux.c
+ */
+
 void *tall_tqe_ctx;
 
 static inline void append_bit(struct demux_subch *sch, uint8_t bit)
@@ -68,6 +74,9 @@ static void resync_to_here(struct demux_subch *sch)
 	sch->in_sync = 1;
 }
 
+/*! \brief initialize subchannel demuxer structure
+ *  \param[in,out] dmx subchannel demuxer
+ */
 int subch_demux_init(struct subch_demux *dmx)
 {
 	int i;
@@ -81,7 +90,13 @@ int subch_demux_init(struct subch_demux *dmx)
 	return 0;
 }
 
-/* input some arbitrary (modulo 4) number of bytes of a 64k E1 channel,
+/*! \brief Input some data from the 64k full-slot into subchannel demux
+ *  \param[in] dmx subchannel demuxer
+ *  \param[in] data pointer to buffer containing input data
+ *  \param[in] len length of \a data in bytes
+ *  \returns 0 in case of success, <0 otherwise.
+ *
+ * Input some arbitrary (modulo 4) number of bytes of a 64k E1 channel,
  * split it into the 16k subchannels */
 int subch_demux_in(struct subch_demux *dmx, uint8_t *data, int len)
 {
@@ -142,6 +157,14 @@ int subch_demux_in(struct subch_demux *dmx, uint8_t *data, int len)
 	return i;
 }
 
+/*! \brief activate a given sub-channel
+ *  \param[in] dmx subchannel demuxer
+ *  \param[in] subch sub-channel number
+ *  \returns 0 in case of success, <0 otherwise
+ *
+ * Activating a sub-channel will casuse the \ref subch_demux::out_cb
+ * callback to be called for any incoming data from the full slot
+ */
 int subch_demux_activate(struct subch_demux *dmx, int subch)
 {
 	if (subch >= NR_SUBCH)
@@ -151,6 +174,14 @@ int subch_demux_activate(struct subch_demux *dmx, int subch)
 	return 0;
 }
 
+/*! \brief deactivate a given sub-channel
+ *  \param[in] dmx subchannel demuxer
+ *  \param[in] subch sub-channel number
+ *  \returns 0 in case of success, <0 otherwise
+ *
+ * Deactivating a sub-channel will casuse the \ref subch_demux::out_cb
+ * callback no longer to be called.
+ */
 int subch_demux_deactivate(struct subch_demux *dmx, int subch)
 {
 	if (subch >= NR_SUBCH)
@@ -243,7 +274,12 @@ static int mux_output_byte(struct subch_mux *mx, uint8_t *byte)
 	return rc;
 }
 
-/* Request the output of some muxed bytes from the subchan muxer */
+/*! \brief Request the output of some muxed bytes from the subchan muxer
+ *  \param[in] mx subchannel muxer
+ *  \param[out] data caller-allocated buffer for data
+ *  \param[in] len number of bytes to be filled into \a data
+ *  \returns actual number of bytes filled into \a data
+ */
 int subchan_mux_out(struct subch_mux *mx, uint8_t *data, int len)
 {
 	int i;
@@ -284,7 +320,13 @@ static void tx_queue_evict(struct mux_subch *sch, int num_evict)
 	}
 }
 
-/* enqueue some data into the tx_queue of a given subchannel */
+/*! \brief enqueue some data into the tx_queue of a given subchannel
+ *  \param[in] mx subchannel muxer instance
+ *  \param[in] s_nr subchannel number
+ *  \param[in] data pointer to buffer with data
+ *  \param[in] len length of \a data
+ *  \returns 0 in case of success, <0 in case of error
+ */
 int subchan_mux_enqueue(struct subch_mux *mx, int s_nr, const uint8_t *data,
 			int len)
 {
@@ -306,7 +348,10 @@ int subchan_mux_enqueue(struct subch_mux *mx, int s_nr, const uint8_t *data,
 	return 0;
 }
 
-/* initialize one subchannel muxer instance */
+/*! \brief initialize one subchannel muxer instance
+ *  \param[in,out] mx subchannel muxer instance, caller-allocated
+ *  \returns 0 in success, < 0 in case of error
+ */
 int subchan_mux_init(struct subch_mux *mx)
 {
 	int i;
@@ -319,3 +364,5 @@ int subchan_mux_init(struct subch_mux *mx)
 
 	return 0;
 }
+
+/* }@ */