doxygen: Add documentation for Abis OML

3 files changed, 98 insertions, 29 deletions

diff --git a/include/osmocom/gsm/abis_nm.h b/include/osmocom/gsm/abis_nm.h
index 3f5335e2..5b5bff0e 100644
--- a/include/osmocom/gsm/abis_nm.h
+++ b/include/osmocom/gsm/abis_nm.h
@@ -1,10 +1,16 @@
 #ifndef _OSMO_GSM_ABIS_NM_H
 #define _OSMO_GSM_ABIS_NM_H
 
+/*! \defgroup oml A-bis OML
+ *  @{
+ */
+
 #include <osmocom/gsm/tlv.h>
 #include <osmocom/gsm/gsm_utils.h>
 #include <osmocom/gsm/protocol/gsm_12_21.h>
 
+/*! \file abis_nm.h */
+
 enum abis_nm_msgtype;
 enum gsm_phys_chan_config;
 
@@ -28,4 +34,7 @@ void abis_nm_debugp_foh(int ss, struct abis_om_fom_hdr *foh);
 
 int abis_nm_chcomb4pchan(enum gsm_phys_chan_config pchan);
 enum abis_nm_chan_comb abis_nm_pchan4chcomb(uint8_t chcomb);
+
+/*! }@ */
+
 #endif /* _OSMO_GSM_ABIS_NM_H */
diff --git a/include/osmocom/gsm/protocol/gsm_12_21.h b/include/osmocom/gsm/protocol/gsm_12_21.h
index b8b00f3f..061dcb63 100644
--- a/include/osmocom/gsm/protocol/gsm_12_21.h
+++ b/include/osmocom/gsm/protocol/gsm_12_21.h
@@ -23,43 +23,66 @@
  *
  */
 
+/*! \addtogroup oml
+ *  @{
+ */
+
+/*! \file gsm_12_21.h */
+
 #include <stdint.h>
 #include <osmocom/gsm/tlv.h>
 
-/* generic header in front of every OML message according to TS 08.59 */
+/*! \brief generic header in front of every OML message according to TS 08.59 */
 struct abis_om_hdr {
+	/*! \brief Message Discriminator \ref abis_oml_mdisc */
 	uint8_t	mdisc;
+	/*! \brief Placement (like \ref ABIS_OM_PLACEMENT_ONLY) */
 	uint8_t	placement;
+	/*! \brief Sequence Number (if \ref ABIS_OM_PLACEMENT_MIDDLE) */
 	uint8_t	sequence;
+	/*! \brief Length in octets */
 	uint8_t	length;
+	/*! \brief actual payload data */
 	uint8_t	data[0];
 } __attribute__ ((packed));
 
+/*! \brief Message Discriminator for Formatted Object Messages */
 #define ABIS_OM_MDISC_FOM		0x80
+/*! \brief Message Discriminator for Man Machine Interface */
 #define ABIS_OM_MDISC_MMI		0x40
+/*! \brief Message Discriminator for TRAU management */
 #define ABIS_OM_MDISC_TRAU		0x20
+/*! \brief Message Discriminator for Manufacturer Specific Messages */
 #define ABIS_OM_MDISC_MANUF		0x10
+
+/*! \brief Entire OML message is in the L2 frame */
 #define ABIS_OM_PLACEMENT_ONLY		0x80
+/*! \brief First fragment of OML message is in this L2 frame */
 #define ABIS_OM_PLACEMENT_FIRST 	0x40
+/*! \brief Middle fragment of OML message is in this L2 frame */
 #define ABIS_OM_PLACEMENT_MIDDLE	0x20
+/*! \brief Last fragment of OML message is in this L2 frame */
 #define ABIS_OM_PLACEMENT_LAST		0x10
 
+/*! \brief OML Object Instance */
 struct abis_om_obj_inst {
-	uint8_t	bts_nr;
-	uint8_t	trx_nr;
-	uint8_t	ts_nr;
+	uint8_t	bts_nr;	/*!< \brief BTS Number */
+	uint8_t	trx_nr;	/*!< \brief TRX Number */
+	uint8_t	ts_nr;	/*!< \brief Timeslot Number */
 } __attribute__ ((packed));
 
+/*! \brief OML Object Instance */
 struct abis_om_fom_hdr {
-	uint8_t	msg_type;
-	uint8_t	obj_class;
-	struct abis_om_obj_inst	obj_inst;
-	uint8_t	data[0];
+	uint8_t	msg_type;	/*!< \brief Message Type (\ref abis_nm_msgtype) */
+	uint8_t	obj_class;	/*!< \brief Object Class (\ref abis_nm_obj_class) */
+	struct abis_om_obj_inst	obj_inst; /*!< \brief Object Instance */
+	uint8_t	data[0];	/*!< \brief Data */
 } __attribute__ ((packed));
 
+/*! \brief Size of the OML FOM header in octets */
 #define ABIS_OM_FOM_HDR_SIZE	(sizeof(struct abis_om_hdr) + sizeof(struct abis_om_fom_hdr))
 
-/* Section 9.1: Message Types */
+/*! \brief OML Message Type (Section 9.1) */
 enum abis_nm_msgtype {
 	/* SW Download Management Messages */
 	NM_MT_LOAD_INIT			= 0x01,
@@ -170,6 +193,7 @@ enum abis_nm_msgtype {
 	NM_MT_SET_ALARM_THRES_NACK,
 };
 
+/*! \brief Siemens specific OML Message Types */
 enum abis_nm_msgtype_bs11 {
 	NM_MT_BS11_RESET_RESOURCE	= 0x74,
 
@@ -205,6 +229,7 @@ enum abis_nm_msgtype_bs11 {
 	NM_MT_BS11_RECONNECT_ACK,
 };
 
+/*! \brief ip.access specific OML Message Types */
 enum abis_nm_msgtype_ipacc {
 	NM_MT_IPACC_RESTART		= 0x87,
 	NM_MT_IPACC_RESTART_ACK,
@@ -237,7 +262,7 @@ enum abis_nm_bs11_cell_alloc {
 	NM_BS11_CANR_DCS1800	= 0x01,
 };
 
-/* Section 9.2: Object Class */
+/*! \brief OML Object Class (Section 9.2) */
 enum abis_nm_obj_class {
 	NM_OC_SITE_MANAGER		= 0x00,
 	NM_OC_BTS,
@@ -268,7 +293,7 @@ enum abis_nm_obj_class {
 	NM_OC_NULL			= 0xff,
 };
 
-/* Section 9.4: Attributes */
+/*! \brief OML Attributes / IEs (Section 9.4) */
 enum abis_nm_attr {
 	NM_ATT_ABIS_CHANNEL	= 0x01,
 	NM_ATT_ADD_INFO,
@@ -464,7 +489,7 @@ enum abis_nm_attr {
 };
 #define NM_ATT_BS11_FILE_DATA	NM_ATT_EVENT_TYPE
 
-/* Section 9.4.4: Administrative State */
+/*! \brief OML Administrative State (Section 9.4.4) */
 enum abis_nm_adm_state {
 	NM_STATE_LOCKED		= 0x01,
 	NM_STATE_UNLOCKED	= 0x02,
@@ -472,7 +497,7 @@ enum abis_nm_adm_state {
 	NM_STATE_NULL		= 0xff,
 };
 
-/* Section 9.4.7: Administrative State */
+/*! \brief OML Availability State (Section 9.4.7) */
 enum abis_nm_avail_state {
 	NM_AVSTATE_IN_TEST	= 1,
 	NM_AVSTATE_POWER_OFF	= 2,
@@ -483,13 +508,14 @@ enum abis_nm_avail_state {
 	NM_AVSTATE_OK		= 0xff,
 };
 
+/*! \brief OML Operational State */
 enum abis_nm_op_state {
 	NM_OPSTATE_DISABLED	= 1,
 	NM_OPSTATE_ENABLED	= 2,
 	NM_OPSTATE_NULL		= 0xff,
 };
 
-/* Section 9.4.13: Channel Combination */
+/* \brief Channel Combination (Section 9.4.13) */
 enum abis_nm_chan_comb {
 	NM_CHANC_TCHFull	= 0x00,	/* TCH/F + TCH/H + SACCH/TF */
 	NM_CHANC_TCHHalf	= 0x01, /* TCH/H(0,1) + FACCH/H(0,1) +
@@ -512,7 +538,7 @@ enum abis_nm_chan_comb {
 	NM_CHANC_IPAC_TCHFull_TCHHalf = 0x81,
 };
 
-/* Section 9.4.16: Event Type */
+/*! \brief Event Type (Section 9.4.16) */
 enum abis_nm_event_type {
 	NM_EVT_COMM_FAIL	= 0x00,
 	NM_EVT_QOS_FAIL		= 0x01,
@@ -521,7 +547,7 @@ enum abis_nm_event_type {
 	NM_EVT_ENV_FAIL		= 0x04,
 };
 
-/* Section: 9.4.63: Perceived Severity */
+/*! \brief Perceived Severity (Section: 9.4.63) */
 enum abis_nm_severity {
 	NM_SEVER_CEASED		= 0x00,
 	NM_SEVER_CRITICAL	= 0x01,
@@ -531,14 +557,14 @@ enum abis_nm_severity {
 	NM_SEVER_INDETERMINATE	= 0x05,
 };
 
-/* Section 9.4.43: Probable Cause Type */
+/*! \brief Probable Cause Type (Section 9.4.43) */
 enum abis_nm_pcause_type {
 	NM_PCAUSE_T_X721	= 0x01,
 	NM_PCAUSE_T_GSM		= 0x02,
 	NM_PCAUSE_T_MANUF	= 0x03,
 };
 
-/* Section 9.4.36: NACK Causes */
+/*! \brief NACK causes (Section 9.4.36) */
 enum abis_nm_nack_cause {
 	/* General Nack Causes */
 	NM_NACK_INCORR_STRUCT		= 0x01,
@@ -576,15 +602,15 @@ enum abis_nm_nack_cause {
 	NM_NACK_MEAS_NOTSTART		= 0x2c,
 };
 
-/* Section 9.4.1 */
+/*! \brief Abis OML Channel (Section 9.4.1) */
 struct abis_nm_channel {
 	uint8_t	attrib;
-	uint8_t	bts_port;
-	uint8_t	timeslot;
-	uint8_t	subslot;
+	uint8_t	bts_port;	/*!< \brief BTS port number */
+	uint8_t	timeslot;	/*!< \brief E1 timeslot */
+	uint8_t	subslot;	/*!< \brief E1 sub-slot */
 } __attribute__ ((packed));
 
-/* Siemens BS-11 specific objects in the SienemsHW (0xA5) object class */
+/*! \brief Siemens BS-11 specific objects in the SienemsHW (0xA5) object class */
 enum abis_bs11_objtype {
 	BS11_OBJ_ALCO		= 0x01,
 	BS11_OBJ_BBSIG		= 0x02,	/* obj_class: 0,1 */
@@ -595,6 +621,7 @@ enum abis_bs11_objtype {
 	BS11_OBJ_PA		= 0x09,	/* obj_class: 0, 1*/
 };
 
+/*! \brief Siemens BS11 TRX power */
 enum abis_bs11_trx_power {
 	BS11_TRX_POWER_GSM_2W	= 0x06,
 	BS11_TRX_POWER_GSM_250mW= 0x07,
@@ -606,17 +633,20 @@ enum abis_bs11_trx_power {
 	BS11_TRX_POWER_DCS_160mW= 0x0d,
 };
 
+/*! \brief Siemens BS11 PLL mode */
 enum abis_bs11_li_pll_mode {
 	BS11_LI_PLL_LOCKED	= 2,
 	BS11_LI_PLL_STANDALONE	= 3,
 };
 
+/*! \brief Siemens BS11 E1 line configuration */
 enum abis_bs11_line_cfg {
 	BS11_LINE_CFG_STAR	= 0x00,
 	BS11_LINE_CFG_MULTIDROP	= 0x01,
 	BS11_LINE_CFG_LOOP	= 0x02,
 };
 
+/*! \brief Siemens BS11 boot phase */
 enum abis_bs11_phase {
 	BS11_STATE_SOFTWARE_RQD		= 0x01,
 	BS11_STATE_LOAD_SMU_INTENDED	= 0x11,
@@ -633,6 +663,7 @@ enum abis_bs11_phase {
 	BS11_STATE_ABIS_LOAD		= 0x13,
 };
 
+/*! \brief ip.access test number */
 enum abis_nm_ipacc_test_no {
 	NM_IPACC_TESTNO_RLOOP_ANT	= 0x01,
 	NM_IPACC_TESTNO_RLOOP_XCVR	= 0x02,
@@ -646,7 +677,7 @@ enum abis_nm_ipacc_test_no {
 	NM_IPACC_TESTNO_BCCCH_MONITOR	= 0x46,
 };
 
-/* first byte after length inside NM_ATT_TEST_REPORT */
+/*! \brief first byte after length inside NM_ATT_TEST_REPORT */
 enum abis_nm_ipacc_test_res {
 	NM_IPACC_TESTRES_SUCCESS	= 0,
 	NM_IPACC_TESTRES_TIMEOUT	= 1,
@@ -655,7 +686,7 @@ enum abis_nm_ipacc_test_res {
 	NM_IPACC_TESTRES_STOPPED	= 4,
 };
 
-/* internal IE inside NM_ATT_TEST_REPORT */
+/*! \brief internal IE inside NM_ATT_TEST_REPORT */
 enum abis_nm_ipacc_testres_ie {
 	NM_IPACC_TR_IE_FREQ_ERR_LIST	= 3,
 	NM_IPACC_TR_IE_CHAN_USAGE	= 4,
@@ -664,6 +695,7 @@ enum abis_nm_ipacc_testres_ie {
 	NM_IPACC_TR_IE_FREQ_ERR		= 18,
 };
 
+/*! \brief ip.access IEI */
 enum ipac_eie {
 	NM_IPAC_EIE_ARFCN_WHITE		= 0x01,
 	NM_IPAC_EIE_ARFCH_BLACK		= 0x02,
@@ -696,6 +728,7 @@ enum ipac_eie {
 	NM_IPAC_EIE_BTS_ID		= 0x25,
 };
 
+/*! \brief ip.access NWL BCCH information type */
 enum ipac_bcch_info_type {
 	IPAC_BINF_RXLEV			= (1 << 8),
 	IPAC_BINF_RXQUAL		= (1 << 9),
@@ -710,4 +743,6 @@ enum ipac_bcch_info_type {
 	IPAC_BINF_CELL_ALLOC		= (1 << 2),
 };
 
+/*! }@ */
+
 #endif /* PROTO_GSM_12_21_H */
diff --git a/src/gsm/abis_nm.c b/src/gsm/abis_nm.c
index b54657d6..5c3647ca 100644
--- a/src/gsm/abis_nm.c
+++ b/src/gsm/abis_nm.c
@@ -20,6 +20,12 @@
  *
  */
 
+/*! \addtogroup oml
+ *  @{
+ */
+
+/*! \file abis_nm.c */
+
 #include <stdint.h>
 #include <errno.h>
 
@@ -30,7 +36,7 @@
 #include <osmocom/gsm/protocol/gsm_12_21.h>
 #include <osmocom/gsm/abis_nm.h>
 
-/* unidirectional messages from BTS to BSC */
+/*! \brief unidirectional messages from BTS to BSC */
 const enum abis_nm_msgtype abis_nm_reports[4] = {
 	NM_MT_SW_ACTIVATED_REP,
 	NM_MT_TEST_REP,
@@ -38,14 +44,14 @@ const enum abis_nm_msgtype abis_nm_reports[4] = {
 	NM_MT_FAILURE_EVENT_REP,
 };
 
-/* messages without ACK/NACK */
+/*! \brief messages without ACK/NACK */
 const enum abis_nm_msgtype abis_nm_no_ack_nack[3] = {
 	NM_MT_MEAS_RES_REQ,
 	NM_MT_STOP_MEAS,
 	NM_MT_START_MEAS,
 };
 
-/* Messages related to software load */
+/*! \brief messages related to software load */
 const enum abis_nm_msgtype abis_nm_sw_load_msgs[9] = {
 	NM_MT_LOAD_INIT_ACK,
 	NM_MT_LOAD_INIT_NACK,
@@ -59,6 +65,7 @@ const enum abis_nm_msgtype abis_nm_sw_load_msgs[9] = {
 	NM_MT_SW_ACTIVATED_REP,
 };
 
+/*! \brief All NACKs (negative acknowledgements */
 const enum abis_nm_msgtype abis_nm_nacks[33] = {
 	NM_MT_LOAD_INIT_NACK,
 	NM_MT_LOAD_END_NACK,
@@ -133,6 +140,7 @@ static const struct value_string nack_names[] = {
 	{ 0,				NULL }
 };
 
+/*! \brief Get human-readable string for OML NACK message type */
 const char *abis_nm_nack_name(uint8_t nack)
 {
 	return get_value_string(nack_names, nack);
@@ -177,6 +185,7 @@ static const struct value_string nack_cause_names[] = {
 	{ 0,				NULL }
 };
 
+/*! \brief Get human-readable string for NACK cause */
 const char *abis_nm_nack_cause_name(uint8_t cause)
 {
 	return get_value_string(nack_cause_names, cause);
@@ -192,6 +201,7 @@ static const struct value_string event_type_names[] = {
 	{ 0,				NULL }
 };
 
+/*! \brief Get human-readable string for OML event type */
 const char *abis_nm_event_type_name(uint8_t cause)
 {
 	return get_value_string(event_type_names, cause);
@@ -208,12 +218,13 @@ static const struct value_string severity_names[] = {
 	{ 0,				NULL }
 };
 
+/*! \brief Get human-readable string for perceived OML severity */
 const char *abis_nm_severity_name(uint8_t cause)
 {
 	return get_value_string(severity_names, cause);
 }
 
-/* Attributes that the BSC can set, not only get, according to Section 9.4 */
+/*! \brief Attributes that the BSC can set, not only get, according to Section 9.4 */
 const enum abis_nm_attr abis_nm_att_settable[] = {
 	NM_ATT_ADD_INFO,
 	NM_ATT_ADD_TEXT,
@@ -242,6 +253,7 @@ const enum abis_nm_attr abis_nm_att_settable[] = {
 	NM_ATT_MEAS_TYPE,
 };
 
+/*! \brief GSM A-bis OML TLV parser definition */
 const struct tlv_definition abis_nm_att_tlvdef = {
 	.def = {
 		[NM_ATT_ABIS_CHANNEL] =		{ TLV_TYPE_FIXED, 3 },
@@ -311,6 +323,7 @@ const struct tlv_definition abis_nm_att_tlvdef = {
 	},
 };
 
+/*! \brief Human-readable strings for A-bis OML Object Class */
 const struct value_string abis_nm_obj_class_names[] = {
 	{ NM_OC_SITE_MANAGER,	"SITE-MANAGER" },
 	{ NM_OC_BTS,		"BTS" },
@@ -332,6 +345,7 @@ const struct value_string abis_nm_obj_class_names[] = {
 	{ 0,			NULL }
 };
 
+/*! \brief Get human-readable string for OML Operational State */
 const char *abis_nm_opstate_name(uint8_t os)
 {
 	switch (os) {
@@ -360,6 +374,7 @@ static const struct value_string avail_names[] = {
 	{ 0,	NULL }
 };
 
+/*! \brief Get human-readable string for OML Availability State */
 const char *abis_nm_avail_name(uint8_t avail)
 {
 	return get_value_string(avail_names, avail);
@@ -377,11 +392,13 @@ static struct value_string test_names[] = {
 	{ 0, NULL }
 };
 
+/*! \brief Get human-readable string for OML test */
 const char *abis_nm_test_name(uint8_t test)
 {
 	return get_value_string(test_names, test);
 }
 
+/*! \brief Human-readable names for OML administrative state */
 const struct value_string abis_nm_adm_state_names[] = {
 	{ NM_STATE_LOCKED,	"Locked" },
 	{ NM_STATE_UNLOCKED,	"Unlocked" },
@@ -390,6 +407,10 @@ const struct value_string abis_nm_adm_state_names[] = {
 	{ 0, NULL }
 };
 
+/*! \brief write a human-readable OML header to the debug log
+ *  \param[in] ss Logging sub-system
+ *  \param[in] foh A-bis OML FOM header
+ */
 void abis_nm_debugp_foh(int ss, struct abis_om_fom_hdr *foh)
 {
 	DEBUGP(ss, "OC=%s(%02x) INST=(%02x,%02x,%02x) ",
@@ -411,6 +432,7 @@ static const enum abis_nm_chan_comb chcomb4pchan[] = {
 	/* FIXME: bounds check */
 };
 
+/*! \brief Obtain OML Channel Combination for phnsical channel config */
 int abis_nm_chcomb4pchan(enum gsm_phys_chan_config pchan)
 {
 	if (pchan < ARRAY_SIZE(chcomb4pchan))
@@ -419,6 +441,7 @@ int abis_nm_chcomb4pchan(enum gsm_phys_chan_config pchan)
 	return -EINVAL;
 }
 
+/*! \brief Obtain physical channel config for OML Channel Combination */
 enum abis_nm_chan_comb abis_nm_pchan4chcomb(uint8_t chcomb)
 {
 	int i;
@@ -428,3 +451,5 @@ enum abis_nm_chan_comb abis_nm_pchan4chcomb(uint8_t chcomb)
 	}
 	return GSM_PCHAN_NONE;
 }
+
+/*! }@ */