RSL: add doxygen documentation

3 files changed, 45 insertions, 13 deletions

diff --git a/Doxyfile.gsm b/Doxyfile.gsm
index 9fabac7d..e8aeb681 100644
--- a/Doxyfile.gsm
+++ b/Doxyfile.gsm
@@ -610,7 +610,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = include/osmocom/gsm src/gsm
+INPUT                  = include/osmocom/gsm include/osmocom/gsm/protocol src/gsm
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
diff --git a/include/osmocom/gsm/protocol/gsm_08_58.h b/include/osmocom/gsm/protocol/gsm_08_58.h
index 9b641b34..a7b68a79 100644
--- a/include/osmocom/gsm/protocol/gsm_08_58.h
+++ b/include/osmocom/gsm/protocol/gsm_08_58.h
@@ -25,13 +25,20 @@
 
 #include <stdint.h>
 
+/*! \addtogroup rsl
+ *  @{
+ */
+
+/*! \file gsm_08_58.h */
+
+/*! \brief RSL common header */
 struct abis_rsl_common_hdr {
 	uint8_t	msg_discr;
 	uint8_t	msg_type;
 	uint8_t	data[0];
 } __attribute__ ((packed));
 
-/* Chapter 8.3 */
+/* \brief RSL RLL header (Chapter 8.3) */
 struct abis_rsl_rll_hdr {
 	struct abis_rsl_common_hdr c;
 	uint8_t	ie_chan;
@@ -41,7 +48,7 @@ struct abis_rsl_rll_hdr {
 	uint8_t	data[0];
 } __attribute__ ((packed));
 
-/* Chapter 8.3 and 8.4 */
+/* \brief RSL Dedicated Channel header (Chapter 8.3 and 8.4) */
 struct abis_rsl_dchan_hdr {
 	struct abis_rsl_common_hdr c;
 	uint8_t	ie_chan;
@@ -49,7 +56,7 @@ struct abis_rsl_dchan_hdr {
 	uint8_t	data[0];
 } __attribute__ ((packed));
 
-/* Chapter 8.5 */
+/* \brief RSL Common Channel header (Chapter 8.5) */
 struct abis_rsl_cchan_hdr {
 	struct abis_rsl_common_hdr c;
 	uint8_t	ie_chan;
@@ -69,7 +76,7 @@ struct abis_rsl_cchan_hdr {
 
 #define ABIS_RSL_MDISC_IS_TRANSP(x)	(x & 0x01)
 
-/* Chapter 9.1 */
+/* \brief RSL Message Tyoe (Chapter 9.1) */
 enum abis_rsl_msgtype {
 	/* Radio Link Layer Management */
 	RSL_MT_DATA_REQ			= 0x01,
@@ -169,7 +176,7 @@ enum abis_rsl_msgtype {
 	RSL_MT_IPAC_DLCX_NACK,
 };
 
-/* Siemens vendor-specific */
+/*! \brief Siemens vendor-specific RSL message types */
 enum abis_rsl_msgtype_siemens {
 	RSL_MT_SIEMENS_MRPCI		= 0x41,
 	RSL_MT_SIEMENS_INTRAC_HO_COND_IND = 0x42,
@@ -189,7 +196,7 @@ enum abis_rsl_msgtype_siemens {
 	RSL_MT_SIEMENS_MODIF_COND_IND	= 0x50,
 };
 
-/* Chapter 9.3 */
+/*! \brief RSL Information Element Identifiers (Chapter 9.3) */
 enum abis_rsl_ie {
 	RSL_IE_CHAN_NR			= 0x01,
 	RSL_IE_LINK_IDENT,
@@ -302,7 +309,7 @@ enum abis_rsl_ie {
 #define RSL_ACT_SECOND_ADD	0x04
 #define RSL_ACT_SECOND_MULTI	0x05
 
-/* Chapter 9.3.6 */
+/*! \brief RSL Channel Mode IF (Chapter 9.3.6) */
 struct rsl_ie_chan_mode {
 	uint8_t dtx_dtu;
 	uint8_t spd_ind;
@@ -329,7 +336,7 @@ enum rsl_cmod_spd {
 #define RSL_CMOD_SP_NT_12k0	0x50
 #define RSL_CMOD_SP_NT_6k0	0x51
 
-/* Chapter 9.3.5 */
+/*! \brief RSL Channel Identification IE (Chapter 9.3.5) */
 struct rsl_ie_chan_ident {
 	/* GSM 04.08 10.5.2.5 */
 	struct {
@@ -441,7 +448,7 @@ struct rsl_ie_chan_ident {
 #define RSL_CHANNEED_TCH_F	0x02
 #define RSL_CHANNEED_TCH_ForH	0x03
 
-/* Chapter 9.3.45 */
+/*! \brief RSL Cell Broadcast Command (Chapter 9.3.45) */
 struct rsl_ie_cb_cmd_type {
 	uint8_t last_block:2;
 	uint8_t spare:1;
@@ -542,5 +549,6 @@ enum rsl_mrpci_phase {
 	RSL_MRPCI_PHASE_2PLUS	= 3,
 };
 
+/*! }@ */
 
 #endif /* PROTO_GSM_08_58_H */
diff --git a/src/gsm/rsl.c b/src/gsm/rsl.c
index c497ba95..1dafd6d8 100644
--- a/src/gsm/rsl.c
+++ b/src/gsm/rsl.c
@@ -28,9 +28,18 @@
 #include <osmocom/gsm/tlv.h>
 #include <osmocom/gsm/rsl.h>
 
+/*! \addtogroup rsl
+ *  @{
+ */
+
+/*! \file rsl.c */
+
+/*! \brief Size for RSL \ref msgb_alloc */
 #define RSL_ALLOC_SIZE		200
+/*! \brief Headroom size for RSL \ref msgb_alloc */
 #define RSL_ALLOC_HEADROOM	56
 
+/*! \brief Initialize a RSL RLL header */
 void rsl_init_rll_hdr(struct abis_rsl_rll_hdr *dh, uint8_t msg_type)
 {
 	dh->c.msg_discr = ABIS_RSL_MDISC_RLL;
@@ -39,6 +48,7 @@ void rsl_init_rll_hdr(struct abis_rsl_rll_hdr *dh, uint8_t msg_type)
 	dh->ie_link_id = RSL_IE_LINK_IDENT;
 }
 
+/*! \brief Initialize a RSL Common Channel header */
 void rsl_init_cchan_hdr(struct abis_rsl_cchan_hdr *ch, uint8_t msg_type)
 {
 	ch->c.msg_discr = ABIS_RSL_MDISC_COM_CHAN;
@@ -46,6 +56,7 @@ void rsl_init_cchan_hdr(struct abis_rsl_cchan_hdr *ch, uint8_t msg_type)
 	ch->ie_chan = RSL_IE_CHAN_NR;
 }
 
+/* \brief TLV parser definition for RSL */
 const struct tlv_definition rsl_att_tlvdef = {
 	.def = {
 		[RSL_IE_CHAN_NR]		= { TLV_TYPE_TV },
@@ -126,7 +137,7 @@ const struct tlv_definition rsl_att_tlvdef = {
 	},
 };
 
-/* encode channel number as per Section 9.3.1 */
+/*! \brief Encode channel number as per Section 9.3.1 */
 uint8_t rsl_enc_chan_nr(uint8_t type, uint8_t subch, uint8_t timeslot)
 {
 	uint8_t ret;
@@ -153,6 +164,12 @@ uint8_t rsl_enc_chan_nr(uint8_t type, uint8_t subch, uint8_t timeslot)
 	return ret;
 }
 
+/*! \brief Decode RSL channel number
+ *  \param[in] chan_nr Channel Number
+ *  \param[out] type Channel Type
+ *  \param[out] subch Sub-channel Number
+ *  \param[out] timeslot Timeslot
+ */
 int rsl_dec_chan_nr(uint8_t chan_nr, uint8_t *type, uint8_t *subch, uint8_t *timeslot)
 {
 	*timeslot = chan_nr & 0x7;
@@ -184,6 +201,7 @@ int rsl_dec_chan_nr(uint8_t chan_nr, uint8_t *type, uint8_t *subch, uint8_t *tim
 	return 0;
 }
 
+/*! \brief Get human-readable string for RSL channel number */
 const char *rsl_chan_nr_str(uint8_t chan_nr)
 {
 	static char str[20];
@@ -245,6 +263,7 @@ static const struct value_string rsl_err_vals[] = {
 	{ 0,				NULL }
 };
 
+/*! \brief Get human-readable name for RSL Error */
 const char *rsl_err_name(uint8_t err)
 {
 	return get_value_string(rsl_err_vals, err);
@@ -321,6 +340,7 @@ static const struct value_string rsl_msgt_names[] = {
 };
 
 
+/*! \brief Get human-readable string for RSL Message Type */
 const char *rsl_msg_name(uint8_t msg_type)
 {
 	return get_value_string(rsl_msgt_names, msg_type);
@@ -344,6 +364,7 @@ static const struct value_string rsl_rlm_cause_strs[] = {
 	{ 0,				NULL },
 };
 
+/*! \brief Get human-readable string for RLM cause */
 const char *rsl_rlm_cause_name(uint8_t err)
 {
 	return get_value_string(rsl_rlm_cause_strs, err);
@@ -387,7 +408,7 @@ int rsl_ccch_conf_to_bs_ccch_sdcch_comb(int ccch_conf)
 	}
 }
 
-/* Push a RSL RLL header */
+/*! \brief Push a RSL RLL header onto an existing msgb */
 void rsl_rll_push_hdr(struct msgb *msg, uint8_t msg_type, uint8_t chan_nr,
 		      uint8_t link_id, int transparent)
 {
@@ -404,7 +425,7 @@ void rsl_rll_push_hdr(struct msgb *msg, uint8_t msg_type, uint8_t chan_nr,
 	msg->l2h = (uint8_t *)rh;
 }
 
-/* Push a RSL RLL header with L3_INFO IE */
+/*! \brief Push a RSL RLL header with L3_INFO IE */
 void rsl_rll_push_l3(struct msgb *msg, uint8_t msg_type, uint8_t chan_nr,
 		     uint8_t link_id, int transparent)
 {
@@ -420,6 +441,7 @@ void rsl_rll_push_l3(struct msgb *msg, uint8_t msg_type, uint8_t chan_nr,
 	rsl_rll_push_hdr(msg, msg_type, chan_nr, link_id, transparent);
 }
 
+/*! \brief Create msgb with RSL RLL header */
 struct msgb *rsl_rll_simple(uint8_t msg_type, uint8_t chan_nr,
 			    uint8_t link_id, int transparent)
 {
@@ -445,3 +467,5 @@ struct msgb *rsl_rll_simple(uint8_t msg_type, uint8_t chan_nr,
 
 	return msg;
 }
+
+/*! }@ */