From 4e777c300ffc701a6c9239deaec1d8073b0ac2f2 Mon Sep 17 00:00:00 2001 From: Harald Welte Date: Wed, 17 Aug 2011 19:15:24 +0200 Subject: doxygen: Add documentation for Abis OML --- include/osmocom/gsm/abis_nm.h | 9 ++++ include/osmocom/gsm/protocol/gsm_12_21.h | 85 ++++++++++++++++++++++---------- src/gsm/abis_nm.c | 33 +++++++++++-- 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 #include #include +/*! \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 #include -/* 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 #include @@ -30,7 +36,7 @@ #include #include -/* 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; } + +/*! }@ */ -- cgit v1.2.3