diff options
| author | Harald Welte <laforge@gnumonks.org> | 2017-06-12 21:44:18 +0200 |
|---|---|---|
| committer | Harald Welte <laforge@gnumonks.org> | 2017-06-12 21:55:54 +0000 |
| commit | 96e2a00d7a9044d0b1a83909c11d8f24955bc7c8 (patch) | |
| tree | 4bbe6cb49a766df4cdefa9fffd56bb953d51da75 | |
| parent | 7165880ac279a9d2d7403749f171eb9c60e70657 (diff) | |
update/extend doxygen documentation
It's a pity that even with this patch we still are fare away from having
the whole API documented. However, at least we have a more solid
foundation. Updates not only extend the documentation, but also make
sure it is rendered properly in the doxygen HTML.
Change-Id: I1344bd1a6869fb00de7c1899a8db93bba9bafce3
63 files changed, 827 insertions, 157 deletions
diff --git a/include/osmocom/core/msgb.h b/include/osmocom/core/msgb.h index afb887c0..f5dd323b 100644 --- a/include/osmocom/core/msgb.h +++ b/include/osmocom/core/msgb.h @@ -29,13 +29,7 @@ * @{ */ -/*! \file msgb.h - * \brief Osmocom message buffers - * The Osmocom message buffers are modelled after the 'struct skb' - * inside the Linux kernel network stack. As they exist in userspace, - * they are much simplified. However, terminology such as headroom, - * tailroom, push/pull/put etc. remains the same. - */ +/*! \file msgb.h */ #define MSGB_DEBUG @@ -26,12 +26,11 @@ /*! \addtogroup bits * @{ - */ - -/*! \file bits.c * \brief Osmocom bit level support code */ +/*! \file bits.c */ + /*! \brief convert unpacked bits to packed bits, return length in bytes * \param[out] out output buffer of packed bits diff --git a/src/bitvec.c b/src/bitvec.c index c895cffa..41e4f64c 100644 --- a/src/bitvec.c +++ b/src/bitvec.c @@ -24,12 +24,11 @@ /*! \addtogroup bitvec * @{ - */ - -/*! \file bitvec.c * \brief Osmocom bit vector abstraction */ +/*! \file bitvec.c */ + #include <errno.h> #include <stdint.h> #include <string.h> @@ -24,11 +24,10 @@ /*! \addtogroup conv * @{ + * \brief Osmocom convolutional encoder and decoder */ -/*! \file conv.c - * Osmocom convolutional encoder and decoder - */ +/*! \file conv.c */ #include "config.h" #ifdef HAVE_ALLOCA_H #include <alloca.h> diff --git a/src/crcXXgen.c.tpl b/src/crcXXgen.c.tpl index 7e45c111..1a69e852 100644 --- a/src/crcXXgen.c.tpl +++ b/src/crcXXgen.c.tpl @@ -24,6 +24,7 @@ /*! \addtogroup crcgen * @{ + * \brief Osmocom generic CRC routines */ /*! \file crcXXgen.c @@ -29,9 +29,6 @@ /*! \addtogroup fsm * @{ - */ - -/*! \file fsm.c * \brief Finite State Machine abstraction * * This is a generic C-language abstraction for implementing finite @@ -84,9 +81,10 @@ * * In order to attach private state to the \ref osmo_fsm_inst, it * offers an opaque priv pointer. - * */ +/*! \file fsm.c */ + LLIST_HEAD(osmo_g_fsms); static bool fsm_log_addr = true; diff --git a/src/gb/gprs_ns.c b/src/gb/gprs_ns.c index 23c0be88..17933ed1 100644 --- a/src/gb/gprs_ns.c +++ b/src/gb/gprs_ns.c @@ -1648,4 +1648,4 @@ void gprs_ns_set_log_ss(int ss) DNS = ss; } -/*! }@ */ +/*! @} */ diff --git a/src/gsm/a5.c b/src/gsm/a5.c index dbba0f20..23cbe0c9 100644 --- a/src/gsm/a5.c +++ b/src/gsm/a5.c @@ -26,13 +26,12 @@ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. */ -/*! \addtogroup a5 +/*! \addtogroup crypto * @{ + * \brief Osmocom GSM/GPRS ciphering algorithm implementation */ -/*! \file gsm/a5.c - * \brief Osmocom GSM A5 ciphering algorithm implementation - */ +/*! \file gsm/a5.c */ #include <errno.h> #include <string.h> diff --git a/src/gsm/abis_nm.c b/src/gsm/abis_nm.c index 73759cbd..c9549027 100644 --- a/src/gsm/abis_nm.c +++ b/src/gsm/abis_nm.c @@ -22,6 +22,8 @@ /*! \addtogroup oml * @{ + * \brief GSM Network Management (OML) messages on the A-bis interface + * 3GPP TS 12.21 version 8.0.0 Release 1999 / ETSI TS 100 623 V8.0.0 */ /*! \file abis_nm.c */ diff --git a/src/gsm/auth_comp128v1.c b/src/gsm/auth_comp128v1.c index c40027ee..3b645d2a 100644 --- a/src/gsm/auth_comp128v1.c +++ b/src/gsm/auth_comp128v1.c @@ -24,6 +24,10 @@ #include <osmocom/crypt/auth.h> #include <osmocom/gsm/comp128.h> +/*! \addtogroup auth + * @{ + */ + static int c128v1_gen_vec(struct osmo_auth_vector *vec, struct osmo_sub_auth_data *aud, const uint8_t *_rand) @@ -45,3 +49,5 @@ static __attribute__((constructor)) void on_dso_load_c128(void) { osmo_auth_register(&c128v1_alg); } + +/*! @} */ diff --git a/src/gsm/auth_comp128v23.c b/src/gsm/auth_comp128v23.c index 168f8865..b0900af2 100644 --- a/src/gsm/auth_comp128v23.c +++ b/src/gsm/auth_comp128v23.c @@ -27,6 +27,10 @@ #include <osmocom/crypt/auth.h> #include <osmocom/gsm/comp128v23.h> +/*! \addtogroup auth + * @{ + */ + static int c128v2_gen_vec(struct osmo_auth_vector *vec, struct osmo_sub_auth_data *aud, const uint8_t *_rand) @@ -66,3 +70,5 @@ static __attribute__((constructor)) void on_dso_load_c128(void) osmo_auth_register(&c128v2_alg); osmo_auth_register(&c128v3_alg); } + +/*! @} */ diff --git a/src/gsm/auth_core.c b/src/gsm/auth_core.c index 9ca5d93b..c9e403c5 100644 --- a/src/gsm/auth_core.c +++ b/src/gsm/auth_core.c @@ -32,10 +32,10 @@ /*! \addtogroup auth * @{ + * \brief GSM/GPRS/3G authentication core infrastructure */ -/* \file auth_core.c - */ +/* \file auth_core.c */ static LLIST_HEAD(osmo_auths); diff --git a/src/gsm/auth_milenage.c b/src/gsm/auth_milenage.c index c1331b5b..41e538d2 100644 --- a/src/gsm/auth_milenage.c +++ b/src/gsm/auth_milenage.c @@ -25,6 +25,10 @@ #include "milenage/common.h" #include "milenage/milenage.h" +/*! \addtogroup auth + * @{ + */ + static int milenage_gen_vec(struct osmo_auth_vector *vec, struct osmo_sub_auth_data *aud, const uint8_t *_rand) @@ -160,3 +164,5 @@ static __attribute__((constructor)) void on_dso_load_milenage(void) { osmo_auth_register(&milenage_alg); } + +/*! @} */ diff --git a/src/gsm/comp128.c b/src/gsm/comp128.c index abb49179..cb3a3092 100644 --- a/src/gsm/comp128.c +++ b/src/gsm/comp128.c @@ -68,6 +68,14 @@ #include <string.h> #include <stdint.h> +/*! \addtogroup auth + * @{ + */ + +/*! \file comp128.c + * \brief COMP128 v1; common/old GSM Authentication Algorithm (A3/A8) + */ + /* The compression tables (just copied ...) */ static const uint8_t table_0[512] = { 102, 177, 186, 162, 2, 156, 112, 75, 55, 25, 8, 12, 251, 193, 246, 188, @@ -184,6 +192,11 @@ _comp128_permutation(uint8_t *x, uint8_t *bits) x[(i>>3)+16] |= bits[(i*17) & 127] << (7-(i&7)); } +/*! \brief Perform COMP128v1 algorithm + * \param[in] ki Secret Key K(i) of subscriber + * \param[in] rand Random Challenge + * \param[out] sres user-supplied buffer for storing computed SRES value + * \param[out] kc user-supplied buffer for storing computed Kc value */ void comp128v1(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc) { @@ -228,8 +241,16 @@ comp128v1(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc) kc[7] = 0; } + +/*! \brief Perform COMP128v1 algorithm + * \param[in] ki Secret Key K(i) of subscriber + * \param[in] rand Random Challenge + * \param[out] sres user-supplied buffer for storing computed SRES value + * \param[out] kc user-supplied buffer for storing computed Kc value */ void comp128(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc) { comp128v1(ki, rand, sres, kc); } + +/*! @} */ diff --git a/src/gsm/comp128v23.c b/src/gsm/comp128v23.c index e21b718e..bfb4a0ee 100644 --- a/src/gsm/comp128v23.c +++ b/src/gsm/comp128v23.c @@ -28,6 +28,14 @@ #include <stdint.h> #include <string.h> +/*! \addtogroup auth + * @{ + */ + +/*! \file comp128v23.c + * \brief COMP128 v2 / v3; Common Algorithm used for GSM Authentication (A3/A8) + */ + static const uint8_t table0[256] = { 197, 235, 60, 151, 98, 96, 3, 100, 248, 118, 42, 117, 172, 211, 181, 203, 61, 126, 156, 87, 149, 224, 55, 132, 186, 63, 238, 255, 85, 83, 152, 33, 160, @@ -101,6 +109,12 @@ _comp128v23_internal(uint8_t *output, const uint8_t *kxor, const uint8_t *rand) } } +/*! \brief Perform COMP128v3 algorithm + * \param[in] ki Secret Key K(i) of subscriber + * \param[in] rand Random Challenge + * \param[out] sres user-supplied buffer for storing computed SRES value + * \param[out] kc user-supplied buffer for storing computed Kc value + * \returns 0 */ int comp128v3(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc) { @@ -147,6 +161,12 @@ comp128v3(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc) return 0; } +/*! \brief Perform COMP128v2 algorithm + * \param[in] ki Secret Key K(i) of subscriber + * \param[in] rand Random Challenge + * \param[out] sres user-supplied buffer for storing computed SRES value + * \param[out] kc user-supplied buffer for storing computed Kc value + * \returns 0 */ int comp128v2(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc) { @@ -155,3 +175,5 @@ comp128v2(const uint8_t *ki, const uint8_t *rand, uint8_t *sres, uint8_t *kc) kc[6] &= 0xfc; return r; } + +/*! @} */ diff --git a/src/gsm/gan.c b/src/gsm/gan.c index 0bcaa175..1d98b38b 100644 --- a/src/gsm/gan.c +++ b/src/gsm/gan.c @@ -21,6 +21,10 @@ #include <osmocom/gsm/protocol/gsm_44_318.h> +/*! \file gan.c + * \brief Generic Access Network (GAN) / UMA according to TS 44.318 + */ + const struct value_string gan_msgt_vals[] = { { GA_MT_RC_DISCOVERY_REQUEST, "GA-RC DISCOVERY REQUEST" }, diff --git a/src/gsm/gea.c b/src/gsm/gea.c index b8f6768a..8d026a29 100644 --- a/src/gsm/gea.c +++ b/src/gsm/gea.c @@ -30,6 +30,13 @@ #include <stdint.h> #include <string.h> +/*! \addtogroup crypto + * @{ + */ + +/*! \file gsm/gea.c */ + + /*! \brief Performs the GEA4 algorithm as in 3GPP TS 55.226 V9.0.0 * \param[in,out] out Buffer for gamma for encrypted/decrypted * \param[in] len Length of out, in bytes @@ -58,3 +65,5 @@ int gea3(uint8_t *out, uint16_t len, uint8_t *kc, uint32_t iv, osmo_c4(ck, kc); return gea4(out, len, ck, iv, direction); } + +/*! @} */ diff --git a/src/gsm/gprs_cipher_core.c b/src/gsm/gprs_cipher_core.c index da6e0a83..a0cf1851 100644 --- a/src/gsm/gprs_cipher_core.c +++ b/src/gsm/gprs_cipher_core.c @@ -29,6 +29,10 @@ #include <osmocom/crypt/gprs_cipher.h> +/*! \addtogroup crypto + * @{ + */ + static LLIST_HEAD(gprs_ciphers); static struct gprs_cipher_impl *selected_ciphers[_GPRS_ALGO_NUM]; @@ -125,3 +129,4 @@ uint32_t gprs_cipher_gen_input_i(uint32_t iov_i, uint32_t lfn, uint32_t oc) { return iov_i + lfn + oc; } +/*! @} */ diff --git a/src/gsm/gprs_gea.c b/src/gsm/gprs_gea.c index 8ff16484..836ee68c 100644 --- a/src/gsm/gprs_gea.c +++ b/src/gsm/gprs_gea.c @@ -27,6 +27,10 @@ #include <stdint.h> +/*! \addtogroup crypto + * @{ + */ + static struct gprs_cipher_impl gea3_impl = { .algo = GPRS_ALGO_GEA3, .name = "GEA3 (libosmogsm built-in)", @@ -46,3 +50,5 @@ static __attribute__((constructor)) void on_dso_load_gea(void) gprs_cipher_register(&gea3_impl); gprs_cipher_register(&gea4_impl); } + +/*! @} */ diff --git a/src/gsm/gprs_rlc.c b/src/gsm/gprs_rlc.c index a4053ef6..d1247be6 100644 --- a/src/gsm/gprs_rlc.c +++ b/src/gsm/gprs_rlc.c @@ -5,6 +5,10 @@ #include <osmocom/coding/gsm0503_coding.h> #include <osmocom/gprs/protocol/gsm_04_60.h> +/*! \file gsm/gprs_rlc.c + * \brief helper functions for (E)GPRS RLC according to 3GPP TS 44.060 + */ + #define EGPRS_CPS_TYPE1_TBL_SZ 29 #define EGPRS_CPS_TYPE2_TBL_SZ 8 #define EGPRS_CPS_TYPE3_TBL_SZ 16 diff --git a/src/gsm/gsm0341.c b/src/gsm/gsm0341.c index 1c14d3ed..2592b54e 100644 --- a/src/gsm/gsm0341.c +++ b/src/gsm/gsm0341.c @@ -27,6 +27,22 @@ #include <osmocom/core/talloc.h> #include <osmocom/gsm/protocol/gsm_03_41.h> +/*! \addtogroup sms + * @{ + */ + +/*! \brief Encode a 3GPP TS 03.41 SMS-CB message + * \param[in] ctx talloc allocation context + * \param[in] geo_scope Geographic Scope + * \param[in] msg_code Message Code + * \param[in] update Is this an update? + * \param[in] msg_id Message ID + * \param[in] dcs Data Coding Scheme + * \param[in] page_total Total number of pages + * \param[in] page_cur Current Page (up to \a page_total) + * \param[in] data Message data (copied 1:1) + * \param[in] len Length of \a data in bytes (up to 88) + * \returns callee-allocated TS 03.41 message with encoded data */ struct gsm341_ms_message * gsm0341_build_msg(void *ctx, uint8_t geo_scope, uint8_t msg_code, uint8_t update, uint16_t msg_id, uint8_t dcs, @@ -57,3 +73,5 @@ gsm0341_build_msg(void *ctx, uint8_t geo_scope, uint8_t msg_code, return cbmsg; } + +/*! @} */ diff --git a/src/gsm/gsm0411_smc.c b/src/gsm/gsm0411_smc.c index 4c083659..03016b92 100644 --- a/src/gsm/gsm0411_smc.c +++ b/src/gsm/gsm0411_smc.c @@ -60,6 +60,11 @@ #include <osmocom/gsm/gsm0411_smc.h> #include <osmocom/gsm/protocol/gsm_04_08.h> +/*! \addtogroup sms + * @{ + * \brief Point-to-Point (PP) Short Message Service (SMS) as per TS 04.11 + */ + static void cp_timer_expired(void *data); #define MAX_SMS_RETRY 2 @@ -569,3 +574,5 @@ int gsm411_smc_recv(struct gsm411_smc_inst *inst, int msg_type, return rc; } + +/*! @} */ diff --git a/src/gsm/gsm0411_smr.c b/src/gsm/gsm0411_smr.c index eb8aec0d..d120f2df 100644 --- a/src/gsm/gsm0411_smr.c +++ b/src/gsm/gsm0411_smr.c @@ -62,6 +62,10 @@ #define SMR_LOG_STR "SMR(%" PRIu64 ") " +/*! \addtogroup sms + * @{ + */ + static void rp_timer_expired(void *data); /* init a new instance */ @@ -484,3 +488,5 @@ int gsm411_smr_recv(struct gsm411_smr_inst *inst, int msg_type, return rc; } + +/*! @} */ diff --git a/src/gsm/gsm0411_utils.c b/src/gsm/gsm0411_utils.c index b84c9f25..543775cc 100644 --- a/src/gsm/gsm0411_utils.c +++ b/src/gsm/gsm0411_utils.c @@ -38,16 +38,24 @@ #include <osmocom/gsm/protocol/gsm_03_40.h> #include <osmocom/gsm/protocol/gsm_04_11.h> +/*! \addtogroup sms + * @{ + */ + #define GSM411_ALLOC_SIZE 1024 #define GSM411_ALLOC_HEADROOM 128 +/*! \brief Allocate a message buffer for use as TS 04.11 message + * \returns allocated message buffer */ struct msgb *gsm411_msgb_alloc(void) { return msgb_alloc_headroom(GSM411_ALLOC_SIZE, GSM411_ALLOC_HEADROOM, "GSM 04.11"); } -/* Turn int into semi-octet representation: 98 => 0x89 */ +/*! \brief Turn int into semi-octet representation: 98 => 0x89 + * \param[in] integer value representing decimal number 0..99 + * \returns BSC encoded as nibbles, swapped */ uint8_t gsm411_bcdify(uint8_t value) { uint8_t ret; @@ -58,7 +66,9 @@ uint8_t gsm411_bcdify(uint8_t value) return ret; } -/* Turn semi-octet representation into int: 0x89 => 98 */ +/*! \brief Turn semi-octet representation into int: 0x89 => 98 + * \param[in] value byte containing two BCD nibbles in revere order + * \returns integer representing decoded, re-ordered nibbles */ uint8_t gsm411_unbcdify(uint8_t value) { uint8_t ret; @@ -73,7 +83,9 @@ uint8_t gsm411_unbcdify(uint8_t value) return ret; } -/* Generate 03.40 TP-SCTS */ +/*! \brief Generate 03.40 TP-SCTS + * \param[out] scts Caller-provided buffer to store SCTS (7 octets) + * \param[in] time to encode */ void gsm340_gen_scts(uint8_t *scts, time_t time) { struct tm *tm = gmtime(&time); @@ -92,7 +104,9 @@ void gsm340_gen_scts(uint8_t *scts, time_t time) #endif } -/* Decode 03.40 TP-SCTS (into utc/gmt timestamp) */ +/*! \brief Decode 03.40 TP-SCTS (into utc/gmt timestamp) + * \param[in] scts SMS Center Time Stamp + * \return time in UTC time_t format */ time_t gsm340_scts(uint8_t *scts) { struct tm tm; @@ -190,7 +204,10 @@ static unsigned long gsm340_vp_relative_semioctet(uint8_t *sms_vp) return minutes; } -/* decode validity period. return minutes */ +/*! \brief decode validity period. return minutes + * \param[in] sms_vpf Validity Period Format in 03.40 encoding + * \param[in] sms_vp Validity Period Information Element + * \returns validity period in minutes */ unsigned long gsm340_validity_period(uint8_t sms_vpf, uint8_t *sms_vp) { uint8_t fi; /* functionality indicator */ @@ -228,7 +245,9 @@ unsigned long gsm340_validity_period(uint8_t sms_vpf, uint8_t *sms_vp) } } -/* determine coding alphabet dependent on GSM 03.38 Section 4 DCS */ +/*! \brief determine coding alphabet dependent on GSM 03.38 Section 4 DCS + * \param[in] dcs Data Coding Scheme in 03.38 encoding + * \returns libosmogsm internal enum \ref sms_alphabet */ enum sms_alphabet gsm338_get_sms_alphabet(uint8_t dcs) { uint8_t cgbits = dcs >> 4; @@ -266,7 +285,13 @@ enum sms_alphabet gsm338_get_sms_alphabet(uint8_t dcs) return alpha; } -/* generate a TPDU address field compliant with 03.40 sec. 9.1.2.5 */ +/*! \brief generate a TPDU address field compliant with 03.40 sec. 9.1.2.5 + * \param[out] oa caller-provided output buffer + * \param[in] oa_len caller-specified length of \a oa in bytes + * \param[in] type GSM340_TYPE_* + * \param[in] plan Numbering Plan + * \param[in] number string containing number + * \reurns number of bytes of \a oa that have been used */ int gsm340_gen_oa(uint8_t *oa, unsigned int oa_len, uint8_t type, uint8_t plan, const char *number) { @@ -296,7 +321,11 @@ int gsm340_gen_oa(uint8_t *oa, unsigned int oa_len, uint8_t type, return len_in_bytes; } -/* Prefix msg with a RP header */ +/*! \brief Prefix \ref msgb with a RP header + * \param msg Message Buffer containing message + * \param[in] rp_msg_type RP Message Type + * \param[in] rp_msg_ref RP Message Reference + * \returns 0 */ int gsm411_push_rp_header(struct msgb *msg, uint8_t rp_msg_type, uint8_t rp_msg_ref) { @@ -312,7 +341,12 @@ int gsm411_push_rp_header(struct msgb *msg, uint8_t rp_msg_type, return 0; } -/* Prefix msg with a 04.08/04.11 CP header */ +/*! \brief Prefix \ref msgb with a 04.08/04.11 CP header + * \param msg Message Buffer containing message + * \param[in] proto Protocol + * \param[in] trans Transaction + * \param[in] msg_type Message Type + * \retrns 0 */ int gsm411_push_cp_header(struct msgb *msg, uint8_t proto, uint8_t trans, uint8_t msg_type) { @@ -320,3 +354,5 @@ int gsm411_push_cp_header(struct msgb *msg, uint8_t proto, uint8_t trans, gsm0480_l3hdr_push(msg, proto | (trans << 4), msg_type); return 0; } + +/*! @} */ diff --git a/src/gsm/gsm0808.c b/src/gsm/gsm0808.c index 04c2f018..c96dc779 100644 --- a/src/gsm/gsm0808.c +++ b/src/gsm/gsm0808.c @@ -24,9 +24,22 @@ #include <osmocom/gsm/protocol/gsm_08_08.h> #include <osmocom/gsm/gsm48.h> +/*! \addtogroup gsm0808 + * @{ + * \brief Helper functions regarding the TS 08.08 / 48.008 A interface + */ + #define BSSMAP_MSG_SIZE 512 #define BSSMAP_MSG_HEADROOM 128 +/*! \brief Create "Complete L3 Info" for AoIP + * \param[in] msg_l3 msgb containing Layer 3 Message + * \param[in] nc Mobile Network Code + * \param[in] cc Mobile Country Code + * \param[in] lac Location Area Code + * \param[in] _ci Cell Identity + * \param[in] scl Speech Codec List + * \returns callee-allocated msgb with Complete L3 Info message */ struct msgb *gsm0808_create_layer3_aoip(const struct msgb *msg_l3, uint16_t nc, uint16_t cc, int lac, uint16_t _ci, const struct gsm0808_speech_codec_list @@ -68,12 +81,21 @@ struct msgb *gsm0808_create_layer3_aoip(const struct msgb *msg_l3, uint16_t nc, return msg; } +/*! \brief Create "Complete L3 Info" for A + * \param[in] msg_l3 msgb containing Layer 3 Message + * \param[in] nc Mobile Network Code + * \param[in] cc Mobile Country Code + * \param[in] lac Location Area Code + * \param[in] _ci Cell Identity + * \returns callee-allocated msgb with Complete L3 Info message */ struct msgb *gsm0808_create_layer3(struct msgb *msg_l3, uint16_t nc, uint16_t cc, int lac, uint16_t _ci) { return gsm0808_create_layer3_aoip(msg_l3, nc, cc, lac, _ci, NULL); } +/*! \brief Create BSSMAP RESET message + * \returns callee-allocated msgb with BSSMAP Reset message */ struct msgb *gsm0808_create_reset(void) { uint8_t cause = GSM0808_CAUSE_EQUIPMENT_FAILURE; @@ -89,6 +111,8 @@ struct msgb *gsm0808_create_reset(void) return msg; } +/*! \brief Create BSSMAP RESET ACK message + * \returns callee-allocated msgb with BSSMAP Reset ACK message */ struct msgb *gsm0808_create_reset_ack(void) { struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM, @@ -102,6 +126,8 @@ struct msgb *gsm0808_create_reset_ack(void) return msg; } +/*! \brief Create BSSMAP Clear Complete message + * \returns callee-allocated msgb with BSSMAP Clear Complete message */ struct msgb *gsm0808_create_clear_complete(void) { struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM, @@ -116,6 +142,9 @@ struct msgb *gsm0808_create_clear_complete(void) return msg; } +/*! \brief Create BSSMAP Clear Command message + * \param[in] reason TS 08.08 cause value + * \returns callee-allocated msgb with BSSMAP Clear Command message */ struct msgb *gsm0808_create_clear_command(uint8_t reason) { struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM, @@ -130,6 +159,10 @@ struct msgb *gsm0808_create_clear_command(uint8_t reason) return msg; } +/*! \brief Create BSSMAP Cipher Mode Command message + * \param[in] ei Mandatory Encryption Information + * \param[in] cipher_response_mode optional 1-byte Cipher Response Mode + * \returns callee-allocated msgb with BSSMAP Cipher Mode Command message */ struct msgb *gsm0808_create_cipher(const struct gsm0808_encrypt_info *ei, const uint8_t *cipher_response_mode) { @@ -163,6 +196,10 @@ struct msgb *gsm0808_create_cipher(const struct gsm0808_encrypt_info *ei, return msg; } +/*! \brief Create BSSMAP Cipher Mode Complete message + * \param[in] layer3 L3 Message to be included + * \param[in] alg_id Chosen Encrpytion Algorithm + * \returns callee-allocated msgb with BSSMAP Cipher Mode Complete message */ struct msgb *gsm0808_create_cipher_complete(struct msgb *layer3, uint8_t alg_id) { struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM, @@ -188,6 +225,9 @@ struct msgb *gsm0808_create_cipher_complete(struct msgb *layer3, uint8_t alg_id) return msg; } +/*! \brief Create BSSMAP Cipher Mode Reject message + * \param[in] reason TS 08.08 cause value + * \returns callee-allocated msgb with BSSMAP Cipher Mode Reject message */ struct msgb *gsm0808_create_cipher_reject(uint8_t cause) { struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM, @@ -202,6 +242,12 @@ struct msgb *gsm0808_create_cipher_reject(uint8_t cause) return msg; } +/*! \brief Create BSSMAP Classmark Update message + * \param[in] cm2 Classmark 2 + * \param[in] cm2_len length (in octets) of \a cm2 + * \param[in] cm3 Classmark 3 + * \param[in] cm3_len length (in octets) of \a cm3 + * \returns callee-allocated msgb with BSSMAP Classmark Update message */ struct msgb *gsm0808_create_classmark_update(const uint8_t *cm2, uint8_t cm2_len, const uint8_t *cm3, uint8_t cm3_len) { @@ -221,6 +267,9 @@ struct msgb *gsm0808_create_classmark_update(const uint8_t *cm2, uint8_t cm2_len return msg; } +/*! \brief Create BSSMAP SAPI N Reject message + * \param[in] link_id Link Identifier + * \returns callee-allocated msgb with BSSMAP SAPI N Reject message */ struct msgb *gsm0808_create_sapi_reject(uint8_t link_id) { struct msgb *msg = msgb_alloc_headroom(BSSMAP_MSG_SIZE, BSSMAP_MSG_HEADROOM, @@ -237,6 +286,13 @@ struct msgb *gsm0808_create_sapi_reject(uint8_t link_id) return msg; } +/*! \brief Create BSSMAP Assignment Request message + * \param[in] ct Channel Type + * \param[in] cic Circuit Identity Code (Classic A only) + * \param[in] ss Socket Address of MSC-side RTP socket (AoIP only) + * \param[in] scl Speech Codec List (AoIP only) + * \param[in] ci Call Identifier (Optional, LCLS) + * \returns callee-allocated msgb with BSSMAP Assignment Request message */ struct msgb *gsm0808_create_ass(const struct gsm0808_channel_type *ct, const uint16_t *cic, const struct sockaddr_storage *ss, @@ -293,6 +349,15 @@ struct msgb *gsm0808_create_ass(const struct gsm0808_channel_type *ct, return msg; } +/*! \brief Create BSSMAP Assignment Completed message + * \param[in] rr_cause GSM 04.08 RR Cause value + * \param[in] chosen_channel Chosen Channel + * \param[in] encr_alg_id Encryption Algorithm ID + * \param[in] speech_mode Speech Mode + * \param[in] ss Socket Address of BSS-side RTP socket + * \param[in] sc Speech Codec (current) + * \param[in] scl Speech Codec List (permitted) + * \returns callee-allocated msgb with BSSMAP Assignment Complete message */ struct msgb *gsm0808_create_ass_compl(uint8_t rr_cause, uint8_t chosen_channel, uint8_t encr_alg_id, uint8_t speech_mode, const struct sockaddr_storage *ss, @@ -342,6 +407,12 @@ struct msgb *gsm0808_create_ass_compl(uint8_t rr_cause, uint8_t chosen_channel, return msg; } +/*! \brief Create BSSMAP Assignment Completed message + * \param[in] rr_cause GSM 04.08 RR Cause value + * \param[in] chosen_channel Chosen Channel + * \param[in] encr_alg_id Encryption Algorithm ID + * \param[in] speech_mode Speech Mode + * \returns callee-allocated msgb with BSSMAP Assignment Complete message */ struct msgb *gsm0808_create_assignment_completed(uint8_t rr_cause, uint8_t chosen_channel, uint8_t encr_alg_id, @@ -351,6 +422,11 @@ struct msgb *gsm0808_create_assignment_completed(uint8_t rr_cause, speech_mode, NULL, NULL, NULL); } +/*! \brief Create BSSMAP Assignment Failure message + * \param[in] cause BSSMAP Cause value + * \param[in] rr_cause GSM 04.08 RR Cause value + * \param[in] scl Optional Speech Cdec List (AoIP) + * \returns callee-allocated msgb with BSSMAP Assignment Failure message */ struct msgb *gsm0808_create_ass_fail(uint8_t cause, const uint8_t *rr_cause, const struct gsm0808_speech_codec_list *scl) @@ -380,12 +456,19 @@ struct msgb *gsm0808_create_ass_fail(uint8_t cause, const uint8_t *rr_cause, return msg; } +/*! \brief Create BSSMAP Assignment Failure message + * \param[in] cause BSSMAP Cause value + * \param[in] rr_cause GSM 04.08 RR Cause value + * \returns callee-allocated msgb with BSSMAP Assignment Failure message */ struct msgb *gsm0808_create_assignment_failure(uint8_t cause, uint8_t *rr_cause) { return gsm0808_create_ass_fail(cause, rr_cause, NULL); } +/*! \brief Create BSSMAP Clear Request message + * \param[in] cause BSSMAP Cause value + * \returns callee-allocated msgb with BSSMAP Clear Request message */ struct msgb *gsm0808_create_clear_rqst(uint8_t cause) { struct msgb *msg; @@ -402,6 +485,12 @@ struct msgb *gsm0808_create_clear_rqst(uint8_t cause) return msg; } +/*! \brief Create BSSMAP PAGING message + * \param[in] imsi Mandatory paged IMSI in string representation + * \param[in] tmsi Optional paged TMSI + * \param[in] cil Cell Identity List (where to page) + * \param[in] chan_needed Channel Type needed + * \returns callee-allocated msgb with BSSMAP PAGING message */ struct msgb *gsm0808_create_paging(const char *imsi, const uint32_t *tmsi, const struct gsm0808_cell_id_list *cil, const uint8_t *chan_needed) @@ -454,6 +543,9 @@ struct msgb *gsm0808_create_paging(const char *imsi, const uint32_t *tmsi, return msg; } +/*! \brief Prepend a DTAP header to given Message Buffer + * \param[in] msgb Message Buffer + * \param[in] link_id Link Identifier */ void gsm0808_prepend_dtap_header(struct msgb *msg, uint8_t link_id) { uint8_t *hh = msgb_push(msg, 3); @@ -462,6 +554,10 @@ void gsm0808_prepend_dtap_header(struct msgb *msg, uint8_t link_id) hh[2] = msg->len - 3; } +/*! \brief Create BSSMAP DTAP message + * \param[in] msg_l3 Messge Buffer containing Layer3 message + * \param[in] link_id Link Identifier + * \returns callee-allocated msgb with BSSMAP DTAP message */ struct msgb *gsm0808_create_dtap(struct msgb *msg_l3, uint8_t link_id) { struct dtap_header *header; @@ -722,6 +818,7 @@ static const struct value_string gsm0808_msgt_names[] = { { 0, NULL } }; +/*! \brief Return string name of BSSMAP Message Type */ const char *gsm0808_bssmap_name(uint8_t msg_type) { return get_value_string(gsm0808_msgt_names, msg_type); @@ -733,7 +830,10 @@ static const struct value_string gsm0808_bssap_names[] = { { 0, NULL } }; +/*! \brief Return string name of BSSAP Message Type */ const char *gsm0808_bssap_name(uint8_t msg_type) { return get_value_string(gsm0808_bssap_names, msg_type); } + +/*! @} */ diff --git a/src/gsm/gsm0808_utils.c b/src/gsm/gsm0808_utils.c index ff97b2d2..bdd02e56 100644 --- a/src/gsm/gsm0808_utils.c +++ b/src/gsm/gsm0808_utils.c @@ -39,7 +39,15 @@ #include <sys/socket.h> #include <netinet/in.h> -/* Encode AoIP transport address element */ + +/*! \addtogroup gsm0808 + * @{ + */ + +/*! \brief Encode TS 08.08 AoIP transport address IE + * \param[out] msg Message Buffer to which to append IE + * \param[in] ss Socket Address to be used in IE + * \returns number of bytes added to \a msg */ uint8_t gsm0808_enc_aoip_trasp_addr(struct msgb *msg, const struct sockaddr_storage *ss) { @@ -80,7 +88,11 @@ uint8_t gsm0808_enc_aoip_trasp_addr(struct msgb *msg, return *tlv_len + 2; } -/* Decode AoIP transport address element */ +/*! \brief Decode TS 08.08 AoIP transport address IE + * \param[out] ss Caller-provided memory where decoded socket addr is stored + * \param[in] elem pointer to IE value + * \param[in] len length of \a elem in bytes + * \returns number of bytes parsed */ int gsm0808_dec_aoip_trasp_addr(struct sockaddr_storage *ss, const uint8_t *elem, uint8_t len) { @@ -168,7 +180,10 @@ static uint8_t enc_speech_codec(struct msgb *msg, return (uint8_t) (msg->tail - old_tail); } -/* Encode Speech Codec element */ +/*! \brief Encode TS 08.08 Speech Codec IE + * \param[out] msg Message Buffer to which IE will be appended + * \param[in] sc Speech Codec to be encoded into IE + * \returns number of bytes appended to \a msg */ uint8_t gsm0808_enc_speech_codec(struct msgb *msg, const struct gsm0808_speech_codec *sc) { @@ -188,7 +203,11 @@ uint8_t gsm0808_enc_speech_codec(struct msgb *msg, return *tlv_len + 2; } -/* Decode Speech Codec element */ +/*! \brief Decode TS 08.08 Speech Codec IE + * \param[out] sc Caller-allocated memory for Speech Codec + * \param[in] elem IE value to be decoded + * \param[in] len Length of \a elem in bytes + * \returns number of bytes parsed; negative on error */ int gsm0808_dec_speech_codec(struct gsm0808_speech_codec *sc, const uint8_t *elem, uint8_t len) { @@ -244,7 +263,10 @@ int gsm0808_dec_speech_codec(struct gsm0808_speech_codec *sc, return (int)(elem - old_elem); } -/* Encode Speech Codec list */ +/*! \brief Encode TS 08.08 Speech Codec list + * \param[out] msg Message Buffer to which IE is to be appended + * \param[in] scl Speech Codec List to be encoded into IE + * \returns number of bytes added to \a msg */ uint8_t gsm0808_enc_speech_codec_list(struct msgb *msg, const struct gsm0808_speech_codec_list *scl) { @@ -275,7 +297,11 @@ uint8_t gsm0808_enc_speech_codec_list(struct msgb *msg, return *tlv_len + 2; } -/* Decode Speech Codec list */ +/*! \brief Decode TS 08.08 Speech Codec list IE + * \param[out] scl Caller-provided memory to store codec list + * \param[in] elem IE value to be decoded + * \param[in] len Length of \a elem in bytes + * \returns number of bytes parsed; negative on error */ int gsm0808_dec_speech_codec_list(struct gsm0808_speech_codec_list *scl, const uint8_t *elem, uint8_t len) { @@ -315,7 +341,10 @@ int gsm0808_dec_speech_codec_list(struct gsm0808_speech_codec_list *scl, return (int)(elem - old_elem); } -/* Encode Channel Type element */ +/*! \brief Encode TS 08.08 Channel Type IE + * \param[out] msg Message Buffer to which IE is to be appended + * \param[in] ct Channel Type to be encoded + * \returns number of bytes added to \a msg */ uint8_t gsm0808_enc_channel_type(struct msgb *msg, const struct gsm0808_channel_type *ct) { @@ -353,7 +382,11 @@ uint8_t gsm0808_enc_channel_type(struct msgb *msg, return *tlv_len + 2; } -/* Decode Channel Type element */ +/*! \brief Decode TS 08.08 Channel Type IE + * \param[out] ct Caller-provided memory to store channel type + * \param[in] elem IE Value to be decoded + * \param[in] len Length of \a elem in bytes + * \returns number of bytes parsed; negative on error */ int gsm0808_dec_channel_type(struct gsm0808_channel_type *ct, const uint8_t *elem, uint8_t len) { @@ -386,7 +419,10 @@ int gsm0808_dec_channel_type(struct gsm0808_channel_type *ct, return (int)(elem - old_elem); } -/* Encode Encryption Information element */ +/*! \brief Encode TS 08.08 Encryption Information IE + * \param[out] msg Message Buffer to which IE is to be appended + * \param[in] ei Encryption Information to be encoded + * \returns number of bytes appended to \a msg */ uint8_t gsm0808_enc_encrypt_info(struct msgb *msg, const struct gsm0808_encrypt_info *ei) { @@ -421,7 +457,11 @@ uint8_t gsm0808_enc_encrypt_info(struct msgb *msg, return *tlv_len + 2; } -/* Decode Encryption Information element */ +/*! \brief Decode TS 08.08 Encryption Information IE + * \param[out] ei Caller-provided memory to store encryption information + * \param[in] elem IE value to be decoded + * \param[in] len Length of \a elem in bytes + * \returns number of bytes parsed; negative on error */ int gsm0808_dec_encrypt_info(struct gsm0808_encrypt_info *ei, const uint8_t *elem, uint8_t len) { @@ -456,7 +496,10 @@ int gsm0808_dec_encrypt_info(struct gsm0808_encrypt_info *ei, return (int)(elem - old_elem); } -/* Encode Cell Identifier List element */ +/*! \brief Encode TS 08.08 Cell Identifier List IE + * \param[out] msg Message Buffer to which IE is to be appended + * \param[in] cil Cell ID List to be encoded + * \returns number of bytes appended to \a msg */ uint8_t gsm0808_enc_cell_id_list(struct msgb *msg, const struct gsm0808_cell_id_list *cil) { @@ -492,7 +535,11 @@ uint8_t gsm0808_enc_cell_id_list(struct msgb *msg, return *tlv_len + 2; } -/* Decode Cell Identifier List element */ +/*! \brief Decode Cell Identifier List IE + * \param[out] cil Caller-provided memory to store Cell ID list + * \param[in] elem IE value to be decoded + * \param[in] len Length of \a elem in bytes + * \returns number of bytes parsed; negative on error */ int gsm0808_dec_cell_id_list(struct gsm0808_cell_id_list *cil, const uint8_t *elem, uint8_t len) { @@ -533,3 +580,5 @@ int gsm0808_dec_cell_id_list(struct gsm0808_cell_id_list *cil, cil->id_list_len = item_count; return (int)(elem - old_elem); } + +/*! @} */ diff --git a/src/gsm/gsm48.c b/src/gsm/gsm48.c index 543c9c00..1b255385 100644 --- a/src/gsm/gsm48.c +++ b/src/gsm/gsm48.c @@ -39,6 +39,12 @@ #include <osmocom/gsm/protocol/gsm_08_58.h> #include <osmocom/gsm/protocol/gsm_04_08_gprs.h> +/*! \addtogroup gsm0408 + * @{ + * \brief GSM Mobile Radion Interface L3 messages / TS 04.08 + */ + +/*! \brief TLV parser definitions for TS 04.08 CC */ const struct tlv_definition gsm48_att_tlvdef = { .def = { [GSM48_IE_MOBILE_ID] = { TLV_TYPE_TLV }, @@ -80,7 +86,7 @@ const struct tlv_definition gsm48_att_tlvdef = { }, }; -/* RR elements */ +/*! \brief TLV parser definitions for TS 04.08 RR */ const struct tlv_definition gsm48_rr_att_tlvdef = { .def = { /* NOTE: Don't add IE 17 = MOBILE_ID here, it already used. */ @@ -125,7 +131,7 @@ const struct tlv_definition gsm48_rr_att_tlvdef = { }, }; -/* MM elements */ +/*! \brief TLV parser definitions for TS 04.08 MM */ const struct tlv_definition gsm48_mm_att_tlvdef = { .def = { [GSM48_IE_MOBILE_ID] = { TLV_TYPE_TLV }, @@ -164,6 +170,7 @@ static const struct value_string rr_cause_names[] = { { 0, NULL }, }; +/*! \brief return string representation of RR Cause value */ const char *rr_cause_name(uint8_t cause) { return get_value_string(rr_cause_names, cause); @@ -205,6 +212,7 @@ static const char *cc_state_names[32] = { "illegal state 31", }; +/*! \brief return string representation of CC State */ const char *gsm48_cc_state_name(uint8_t state) { if (state < ARRAY_SIZE(cc_state_names)) @@ -252,6 +260,7 @@ static const struct value_string cc_msg_names[] = { { 0, NULL } }; +/*! \brief return string representation of CC Message Type */ const char *gsm48_cc_msg_name(uint8_t msgtype) { return get_value_string(cc_msg_names, msgtype); @@ -359,6 +368,7 @@ static const struct value_string rr_msg_names[] = { { 0, NULL } }; +/*! \brief return string representation of RR Message Type */ const char *gsm48_rr_msg_name(uint8_t msgtype) { return get_value_string(rr_msg_names, msgtype); @@ -398,6 +408,7 @@ static const struct value_string mi_type_names[] = { { 0, NULL } }; +/*! \brief return string representation of Mobile Identity Type */ const char *gsm48_mi_type_name(uint8_t mi) { return get_value_string(mi_type_names, mi); @@ -437,7 +448,12 @@ bool gsm48_hdr_gmm_cipherable(const struct gsm48_hdr *hdr) } } -/* Convert given mcc and mnc to BCD and write to *bcd_dst, which must be an +/* \brief Convert MCC + MNC to BCD representation + * \param[out] bcd_dst caller-allocated memory for output + * \param[in] mcc Mobile Country Code + * \param[in] mnc Mobile Network Code + * + * Convert given mcc and mnc to BCD and write to *bcd_dst, which must be an * allocated buffer of (at least) 3 bytes length. */ void gsm48_mcc_mnc_to_bcd(uint8_t *bcd_dst, uint16_t mcc, uint16_t mnc) { @@ -477,6 +493,11 @@ void gsm48_mcc_mnc_from_bcd(uint8_t *bcd_src, uint16_t *mcc, uint16_t *mnc) } } +/*! \brief Encode TS 04.08 Location Area Identifier + * \param[out] caller-provided memory for output + * \param[in] mcc Mobile Country Code + * \param[in] mnc Mobile Network Code + * \param[in] lac Location Area Code */ void gsm48_generate_lai(struct gsm48_loc_area_id *lai48, uint16_t mcc, uint16_t mnc, uint16_t lac) { @@ -484,7 +505,14 @@ void gsm48_generate_lai(struct gsm48_loc_area_id *lai48, uint16_t mcc, lai48->lac = osmo_htons(lac); } -/* Attention: this function returns true integers, not hex! */ +/*! \brief Decode TS 04.08 Location Area Identifier + * \param[in] Location Area Identifier (encoded) + * \param[out] mcc Mobile Country Code + * \param[out] mnc Mobile Network Code + * \param[out] lac Location Area Code + * \returns 0 + * + * Attention: this function returns true integers, not hex! */ int gsm48_decode_lai(struct gsm48_loc_area_id *lai, uint16_t *mcc, uint16_t *mnc, uint16_t *lac) { @@ -537,6 +565,10 @@ void gsm48_set_dtx(struct gsm48_cell_options *op, enum gsm48_dtx_mode full, } } +/*! \brief Generate TS 04.08 Mobile ID from TMSI + * \param[out] buf Caller-provided output buffer (7 bytes) + * \param[in] tmsi TMSI to be encoded + * \returns number of byes encoded (always 7) */ int gsm48_generate_mid_from_tmsi(uint8_t *buf, uint32_t tmsi) { uint32_t tmsi_be = osmo_htonl(tmsi); @@ -549,6 +581,10 @@ int gsm48_generate_mid_from_tmsi(uint8_t *buf, uint32_t tmsi) return 7; } +/*! \brief Generate TS 04.08 Mobile ID from IMSI + * \param[out] buf Caller-provided output buffer + * \param[in] imsi IMSI to be encoded + * \returns number of bytes used in \a buf */ int gsm48_generate_mid_from_imsi(uint8_t *buf, const char *imsi) { unsigned int length = strlen(imsi), i, off = 0; @@ -578,7 +614,12 @@ int gsm48_generate_mid_from_imsi(uint8_t *buf, const char *imsi) return 2 + buf[1]; } -/* Convert Mobile Identity (10.5.1.4) to string */ +/*! \brief Convert TS 04.08 Mobile Identity (10.5.1.4) to string + * \param[out] string Caller-provided buffer for output + * \param[in] str_len Length of \a string in bytes + * \param[in] mi Mobile Identity to be stringified + * \param[in] mi_len Length of \a mi in bytes + * \returns length of string written to \a string */ int gsm48_mi_to_string(char *string, const int str_len, const uint8_t *mi, const int mi_len) { @@ -621,6 +662,9 @@ int gsm48_mi_to_string(char *string, const int str_len, const uint8_t *mi, return str_cur - string; } +/*! \brief Parse TS 04.08 Routing Area Identifier + * \param[out] Caller-provided memory for decoded RA ID + * \param[in] buf Input buffer pointing to RAI IE value */ void gsm48_parse_ra(struct gprs_ra_id *raid, const uint8_t *buf) { raid->mcc = (buf[0] & 0xf) * 100; @@ -642,6 +686,10 @@ void gsm48_parse_ra(struct gprs_ra_id *raid, const uint8_t *buf) raid->rac = buf[5]; } +/*! \brief Encode a TS 04.08 Routing Area Identifier + * \param[out] buf Caller-provided output buffer of 6 bytes + * \param[in] raid Routing Area ID to be encoded + * \returns number of bytes used in \a buf */ int gsm48_construct_ra(uint8_t *buf, const struct gprs_ra_id *raid) { uint16_t mcc = raid->mcc; @@ -669,7 +717,13 @@ int gsm48_construct_ra(uint8_t *buf, const struct gprs_ra_id *raid) return 6; } -/* From Table 10.5.33 of GSM 04.08 */ +/*! \brief Determine number of paging sub-channels + * \param[in] chan_desc Control Channel Description + * \returns number of paging sub-channels + * + * Uses From Table 10.5.33 of GSM 04.08 to determine the number of + * paging sub-channels in the given control channel configuration + */ int gsm48_number_of_paging_subchannels(struct gsm48_control_channel_descr *chan_desc) { unsigned int n_pag_blocks = gsm0502_get_n_pag_blocks(chan_desc); @@ -680,6 +734,7 @@ int gsm48_number_of_paging_subchannels(struct gsm48_control_channel_descr *chan_ return n_pag_blocks * (chan_desc->bs_pa_mfrms + 2); } +/*! \brief TS 04.08 Protocol Descriptor names */ const struct value_string gsm48_pdisc_names[] = { OSMO_VALUE_STRING(GSM48_PDISC_GROUP_CC), OSMO_VALUE_STRING(GSM48_PDISC_BCAST_CC), @@ -699,6 +754,7 @@ const struct value_string gsm48_pdisc_names[] = { { 0, NULL } }; +/*! \brief TS 04.08 RR Message Type names */ const struct value_string gsm48_rr_msgtype_names[] = { OSMO_VALUE_STRING(GSM48_MT_RR_INIT_REQ), OSMO_VALUE_STRING(GSM48_MT_RR_ADD_ASS), @@ -791,6 +847,7 @@ const struct value_string gsm48_rr_msgtype_names[] = { { 0, NULL } }; +/*! \brief TS 04.08 MM Message Type names */ const struct value_string gsm48_mm_msgtype_names[] = { OSMO_VALUE_STRING(GSM48_MT_MM_IMSI_DETACH_IND), OSMO_VALUE_STRING(GSM48_MT_MM_LOC_UPD_ACCEPT), @@ -820,6 +877,7 @@ const struct value_string gsm48_mm_msgtype_names[] = { { 0, NULL } }; +/*! \brief TS 04.08 CC Message Type names */ const struct value_string gsm48_cc_msgtype_names[] = { OSMO_VALUE_STRING(GSM48_MT_CC_ALERTING), OSMO_VALUE_STRING(GSM48_MT_CC_CALL_CONF), @@ -862,12 +920,12 @@ const struct value_string gsm48_cc_msgtype_names[] = { { 0, NULL } }; -/*! /brief Compose a string naming the message type for given protocol. +/*! \brief Compose a string naming the message type for given protocol. * If the message type string is known, return the message type name, otherwise * return "<protocol discriminator name>:<message type in hex>". - * /param pdisc[in] protocol discriminator like GSM48_PDISC_MM - * /param msg_type[in] message type like GSM48_MT_MM_LOC_UPD_REQUEST - * /returns statically allocated string or string constant. + * \param[in] pdisc protocol discriminator like GSM48_PDISC_MM + * \param[in] msg_type message type like GSM48_MT_MM_LOC_UPD_REQUEST + * \returns statically allocated string or string constant. */ const char *gsm48_pdisc_msgtype_name(uint8_t pdisc, uint8_t msg_type) { @@ -896,3 +954,5 @@ const char *gsm48_pdisc_msgtype_name(uint8_t pdisc, uint8_t msg_type) gsm48_pdisc_name(pdisc), msg_type); return namebuf; } + +/*! @} */ diff --git a/src/gsm/gsm48_ie.c b/src/gsm/gsm48_ie.c index 2cc0645d..20d0075d 100644 --- a/src/gsm/gsm48_ie.c +++ b/src/gsm/gsm48_ie.c @@ -34,12 +34,20 @@ #include <osmocom/gsm/protocol/gsm_04_08.h> #include <osmocom/gsm/gsm48_ie.h> +/*! \addtogroup gsm0408 + * @{ + */ + static const char bcd_num_digits[] = { '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '*', '#', 'a', 'b', 'c', '\0' }; -/* decode a 'called/calling/connect party BCD number' as in 10.5.4.7 */ +/*! \brief decode a 'called/calling/connect party BCD number' as in 10.5.4.7 + * \param[out] Caller-provided output buffer + * \param[in] bcd_lv Length-Value portion of to-be-decoded IE + * \param[in] h_len Length of an optional heder between L and V portion + * \returns - in case of success; negative on error */ int gsm48_decode_bcd_number(char *output, int output_len, const uint8_t *bcd_lv, int h_len) { @@ -65,7 +73,7 @@ int gsm48_decode_bcd_number(char *output, int output_len, return 0; } -/* convert a single ASCII character to call-control BCD */ +/*! \brief convert a single ASCII character to call-control BCD */ static int asc_to_bcd(const char asc) { int i; @@ -77,7 +85,12 @@ static int asc_to_bcd(const char asc) return -EINVAL; } -/* convert a ASCII phone number to 'called/calling/connect party BCD number' */ +/*! \brief convert a ASCII phone number to 'called/calling/connect party BCD number' + * \param[out] bcd_lv Caller-provided output buffer + * \param[in] max_len Maximum Length of \a bcd_lv + * \param[in] h_len Length of an optional heder between L and V portion + * \param[in] input phone number as 0-terminated ASCII + * \returns number of bytes used in \a bcd_lv */ int gsm48_encode_bcd_number(uint8_t *bcd_lv, uint8_t max_len, int h_len, const char *input) { @@ -110,7 +123,10 @@ int gsm48_encode_bcd_number(uint8_t *bcd_lv, uint8_t max_len, return (bcd_cur - bcd_lv); } -/* TS 04.08 10.5.4.5: decode 'bearer capability' */ +/*! \brief Decode TS 04.08 Bearer Capability IE (10.5.4.5) + * \param[out] Caller-provided memory for decoded output + * \[aram[in] LV portion of TS 04.08 Bearer Capability + * \returns 0 on success; negative on error */ int gsm48_decode_bearer_cap(struct gsm_mncc_bearer_cap *bcap, const uint8_t *lv) { @@ -219,7 +235,11 @@ int gsm48_decode_bearer_cap(struct gsm_mncc_bearer_cap *bcap, return 0; } -/* TS 04.08 10.5.4.5: encode 'bearer capability' */ +/*! \brief Encode TS 04.08 Bearer Capability IE (10.5.4.5) + * \param[out] msg Message Buffer to which IE is to be appended + * \param[in] lv_only Write only LV portion (1) or TLV (0) + * \param[in] bcap Decoded Bearer Capability to be encoded + * \returns 0 on success; negative on error */ int gsm48_encode_bearer_cap(struct msgb *msg, int lv_only, const struct gsm_mncc_bearer_cap *bcap) { @@ -274,7 +294,10 @@ int gsm48_encode_bearer_cap(struct msgb *msg, int lv_only, return 0; } -/* TS 04.08 10.5.4.5a: decode 'call control cap' */ +/*! \brief Decode TS 04.08 Call Control Capabilities IE (10.5.4.5a) + * \param[out] Caller-provided memory for decoded CC capabilities + * \param[in] lv Length-Value of IE + * \retursns 0 on success; negative on error */ int gsm48_decode_cccap(struct gsm_mncc_cccap *ccap, const uint8_t *lv) { uint8_t in_len = lv[0]; @@ -289,7 +312,10 @@ int gsm48_decode_cccap(struct gsm_mncc_cccap *ccap, const uint8_t *lv) return 0; } -/* TS 04.08 10.5.4.5a: encode 'call control cap' */ +/*! \brief Encodoe TS 04.08 Call Control Capabilities (10.5.4.5a) + * \param[out] msg Message Buffer to which to append IE (as TLV) + * \param[in] ccap Decoded CC Capabilities to be encoded + * \returns 0 on success; negative on error */ int gsm48_encode_cccap(struct msgb *msg, const struct gsm_mncc_cccap *ccap) { @@ -307,7 +333,10 @@ int gsm48_encode_cccap(struct msgb *msg, return 0; } -/* TS 04.08 10.5.4.7: decode 'called party BCD number' */ +/*! \brief Decode TS 04.08 Called Party BCD Number IE (10.5.4.7) + * \param[out] called Caller-provided memory for decoded number + * \param[in] lv Length-Value portion of IE + * \returns 0 on success; negative on error */ int gsm48_decode_called(struct gsm_mncc_number *called, const uint8_t *lv) { @@ -326,7 +355,10 @@ int gsm48_decode_called(struct gsm_mncc_number *called, return 0; } -/* TS 04.08 10.5.4.7: encode 'called party BCD number' */ +/*! \brief Encode TS 04.08 Called Party IE (10.5.4.7) + * \param[out] msg Mesage Buffer to which to append IE (as TLV) + * \param[in] called MNCC Number to encode/append + * \returns 0 on success; negative on error */ int gsm48_encode_called(struct msgb *msg, const struct gsm_mncc_number *called) { @@ -348,7 +380,10 @@ int gsm48_encode_called(struct msgb *msg, return 0; } -/* decode callerid of various IEs */ +/*! \brief Decode TS 04.08 Caller ID + * \param[out] called Caller-provided memory for decoded number + * \param[in] lv Length-Value portion of IE + * \returns 0 on success; negative on error */ int gsm48_decode_callerid(struct gsm_mncc_number *callerid, const uint8_t *lv) { @@ -375,7 +410,12 @@ int gsm48_decode_callerid(struct gsm_mncc_number *callerid, return 0; } -/* encode callerid of various IEs */ +/*! \brief Encode TS 04.08 Caller ID IE + * \param[out] msg Mesage Buffer to which to append IE (as TLV) + * \param[in] ie IE Identifier (tag) + * \param[in] max_len maximum generated output in bytes + * \param[in] callerid MNCC Number to encode/append + * \returns 0 on success; negative on error */ int gsm48_encode_callerid(struct msgb *msg, int ie, int max_len, const struct gsm_mncc_number *callerid) { @@ -406,7 +446,10 @@ int gsm48_encode_callerid(struct msgb *msg, int ie, int max_len, return 0; } -/* TS 04.08 10.5.4.11: decode 'cause' */ +/*! \brief Decode TS 04.08 Cause IE (10.5.4.11) + * \param[out] cause Caller-provided memory for output + * \param[in] lv LV portion of Cause IE + * \returns 0 on success; negative on error */ int gsm48_decode_cause(struct gsm_mncc_cause *cause, const uint8_t *lv) { @@ -449,7 +492,11 @@ int gsm48_decode_cause(struct gsm_mncc_cause *cause, return 0; } -/* TS 04.08 10.5.4.11: encode 'cause' */ +/*! \brief Encode TS 04.08 Cause IE (10.5.4.11) + * \param[out] msg Message Buffer to which to append IE + * \param[in] lv_only Encode as LV (1) or TLV (0) + * \param[in] cause Cause value to be encoded + * \returns 0 on success; negative on error */ int gsm48_encode_cause(struct msgb *msg, int lv_only, const struct gsm_mncc_cause *cause) { @@ -489,49 +536,49 @@ int gsm48_encode_cause(struct msgb *msg, int lv_only, return 0; } -/* TS 04.08 10.5.4.9: decode 'calling number' */ +/*! \brief Decode TS 04.08 Calling Number IE (10.5.4.9) */ int gsm48_decode_calling(struct gsm_mncc_number *calling, const uint8_t *lv) { return gsm48_decode_callerid(calling, lv); } -/* TS 04.08 10.5.4.9: encode 'calling number' */ +/*! \brief Encode TS 04.08 Calling Number IE (10.5.4.9) */ int gsm48_encode_calling(struct msgb *msg, const struct gsm_mncc_number *calling) { return gsm48_encode_callerid(msg, GSM48_IE_CALLING_BCD, 14, calling); } -/* TS 04.08 10.5.4.13: decode 'connected number' */ +/*! \brief Decode TS 04.08 Connected Number IE (10.5.4.13) */ int gsm48_decode_connected(struct gsm_mncc_number *connected, const uint8_t *lv) { return gsm48_decode_callerid(connected, lv); } -/* TS 04.08 10.5.4.13: encode 'connected number' */ +/*! \brief Encode TS 04.08 Connected Number IE (10.5.4.13) */ int gsm48_encode_connected(struct msgb *msg, const struct gsm_mncc_number *connected) { return gsm48_encode_callerid(msg, GSM48_IE_CONN_BCD, 14, connected); } -/* TS 04.08 10.5.4.21b: decode 'redirecting number' */ +/*! \brief Decode TS 04.08 Redirecting Number IE (10.5.4.21b) */ int gsm48_decode_redirecting(struct gsm_mncc_number *redirecting, const uint8_t *lv) { return gsm48_decode_callerid(redirecting, lv); } -/* TS 04.08 10.5.4.21b: encode 'redirecting number' */ +/*! \brief Encode TS 04.08 Redirecting Number IE (10.5.4.21b) */ int gsm48_encode_redirecting(struct msgb *msg, const struct gsm_mncc_number *redirecting) { return gsm48_encode_callerid(msg, GSM48_IE_REDIR_BCD, 19, redirecting); } -/* TS 04.08 10.5.4.15: decode 'facility' */ +/*! \brief Decode TS 04.08 Facility IE (10.5.4.15) */ int gsm48_decode_facility(struct gsm_mncc_facility *facility, const uint8_t *lv) { @@ -549,7 +596,7 @@ int gsm48_decode_facility(struct gsm_mncc_facility *facility, return 0; } -/* TS 04.08 10.5.4.15: encode 'facility' */ +/*! \brief Encode TS 04.08 Facility IE (10.5.4.15) */ int gsm48_encode_facility(struct msgb *msg, int lv_only, const struct gsm_mncc_facility *facility) { @@ -568,7 +615,7 @@ int gsm48_encode_facility(struct msgb *msg, int lv_only, return 0; } -/* TS 04.08 10.5.4.20: decode 'notify' */ +/*! \brief Decode TS 04.08 Notify IE (10.5.4.20) */ int gsm48_decode_notify(int *notify, const uint8_t *v) { *notify = v[0] & 0x7f; @@ -576,7 +623,7 @@ int gsm48_decode_notify(int *notify, const uint8_t *v) return 0; } -/* TS 04.08 10.5.4.20: encode 'notify' */ +/*! \brief Encode TS 04.08 Notify IE (10.5.4.20) */ int gsm48_encode_notify(struct msgb *msg, int notify) { msgb_v_put(msg, notify | 0x80); @@ -584,7 +631,7 @@ int gsm48_encode_notify(struct msgb *msg, int notify) return 0; } -/* TS 04.08 10.5.4.23: decode 'signal' */ +/*! \brief Decode TS 04.08 Signal IE (10.5.4.23) */ int gsm48_decode_signal(int *signal, const uint8_t *v) { *signal = v[0]; @@ -592,7 +639,7 @@ int gsm48_decode_signal(int *signal, const uint8_t *v) return 0; } -/* TS 04.08 10.5.4.23: encode 'signal' */ +/*! \brief Encode TS 04.08 Signal IE (10.5.4.23) */ int gsm48_encode_signal(struct msgb *msg, int signal) { msgb_tv_put(msg, GSM48_IE_SIGNAL, signal); @@ -600,7 +647,7 @@ int gsm48_encode_signal(struct msgb *msg, int signal) return 0; } -/* TS 04.08 10.5.4.17: decode 'keypad' */ +/*! \brief Decode TS 04.08 Keypad IE (10.5.4.17) */ int gsm48_decode_keypad(int *keypad, const uint8_t *lv) { uint8_t in_len = lv[0]; @@ -613,7 +660,7 @@ int gsm48_decode_keypad(int *keypad, const uint8_t *lv) return 0; } -/* TS 04.08 10.5.4.17: encode 'keypad' */ +/*! \brief Encode TS 04.08 Keypad IE (10.5.4.17) */ int gsm48_encode_keypad(struct msgb *msg, int keypad) { msgb_tv_put(msg, GSM48_IE_KPD_FACILITY, keypad); @@ -621,7 +668,7 @@ int gsm48_encode_keypad(struct msgb *msg, int keypad) return 0; } -/* TS 04.08 10.5.4.21: decode 'progress' */ +/*! \brief Decode TS 04.08 Progress IE (10.5.4.21) */ int gsm48_decode_progress(struct gsm_mncc_progress *progress, const uint8_t *lv) { @@ -637,7 +684,7 @@ int gsm48_decode_progress(struct gsm_mncc_progress *progress, return 0; } -/* TS 04.08 10.5.4.21: encode 'progress' */ +/*! \brief Encode TS 04.08 Progress IE (10.5.4.21) */ int gsm48_encode_progress(struct msgb *msg, int lv_only, const struct gsm_mncc_progress *p) { @@ -654,7 +701,7 @@ int gsm48_encode_progress(struct msgb *msg, int lv_only, return 0; } -/* TS 04.08 10.5.4.25: decode 'user-user' */ +/*! \brief Decode TS 04.08 User-User IE (10.5.4.25) */ int gsm48_decode_useruser(struct gsm_mncc_useruser *uu, const uint8_t *lv) { @@ -680,7 +727,7 @@ int gsm48_decode_useruser(struct gsm_mncc_useruser *uu, return 0; } -/* TS 04.08 10.5.4.25: encode 'useruser' */ +/*! \brief Encode TS 04.08 User-User IE (10.5.4.25) */ int gsm48_encode_useruser(struct msgb *msg, int lv_only, const struct gsm_mncc_useruser *uu) { @@ -700,7 +747,7 @@ int gsm48_encode_useruser(struct msgb *msg, int lv_only, return 0; } -/* TS 04.08 10.5.4.24: decode 'ss version' */ +/*! \brief Decode TS 04.08 SS Version IE (10.5.4.24) */ int gsm48_decode_ssversion(struct gsm_mncc_ssversion *ssv, const uint8_t *lv) { @@ -715,7 +762,7 @@ int gsm48_decode_ssversion(struct gsm_mncc_ssversion *ssv, return 0; } -/* TS 04.08 10.5.4.24: encode 'ss version' */ +/*! \brief Encode TS 04.08 SS Version IE (10.5.4.24) */ int gsm48_encode_ssversion(struct msgb *msg, const struct gsm_mncc_ssversion *ssv) { @@ -733,7 +780,7 @@ int gsm48_encode_ssversion(struct msgb *msg, /* decode 'more data' does not require a function, because it has no value */ -/* TS 04.08 10.5.4.19: encode 'more data' */ +/*! \brief Encode TS 04.08 More Data IE (10.5.4.19) */ int gsm48_encode_more(struct msgb *msg) { uint8_t *ie; @@ -756,7 +803,11 @@ static int32_t smod(int32_t n, int32_t m) return res; } -/* decode "Cell Channel Description" (10.5.2.1b) and other frequency lists */ +/*! \brief Decode TS 04.08 Cell Channel Description IE (10.5.2.1b) and other frequency lists + * \param[out] f Caller-provided output memory + * \param[in] cd Cell Channel Description IE + * \param[in] len Length of \a cd in bytes + * \returns 0 on success; negative on error */ int gsm48_decode_freq_list(struct gsm_sysinfo_freq *f, uint8_t *cd, uint8_t len, uint8_t mask, uint8_t frqt) { @@ -1190,3 +1241,4 @@ int gsm48_decode_freq_list(struct gsm_sysinfo_freq *f, uint8_t *cd, return 0; } +/*! @} */ diff --git a/src/gsm/gsm_04_08_gprs.c b/src/gsm/gsm_04_08_gprs.c index 5fef208a..bd986d73 100644 --- a/src/gsm/gsm_04_08_gprs.c +++ b/src/gsm/gsm_04_08_gprs.c @@ -26,9 +26,11 @@ #include <stdbool.h> -/* Protocol related stuff, should go into libosmocore */ +/*! \addtogroup gsm0408 + * @{ + */ -/* 10.5.5.14 GPRS MM Cause / Table 10.5.147 */ +/*! \brief 10.5.5.14 GPRS MM Cause / Table 10.5.147 */ const struct value_string gsm48_gmm_cause_names_[] = { { GMM_CAUSE_IMSI_UNKNOWN, "IMSI unknown in HLR" }, { GMM_CAUSE_ILLEGAL_MS, "Illegal MS" }, @@ -73,7 +75,7 @@ const struct value_string gsm48_gmm_cause_names_[] = { const struct value_string *gsm48_gmm_cause_names = gsm48_gmm_cause_names_; -/* 10.5.6.6 SM Cause / Table 10.5.157 */ +/*! \brief 10.5.6.6 SM Cause / Table 10.5.157 */ const struct value_string gsm48_gsm_cause_names_[] = { { GSM_CAUSE_OPER_DET_BARR, "Operator Determined Barring" }, { GSM_CAUSE_MBMS_CAP_INSUF, "MBMS bearer capabilities insufficient for the service" }, @@ -140,6 +142,7 @@ bool gprs_ms_net_cap_gea_supported(const uint8_t *ms_net_cap, uint8_t cap_len, } } +/*! \brief String names of GMM message types */ const struct value_string gprs_msgt_gmm_names[] = { { GSM48_MT_GMM_ATTACH_REQ, "ATTACH REQUEST" }, { GSM48_MT_GMM_ATTACH_ACK, "ATTACH ACK" }, @@ -164,7 +167,7 @@ const struct value_string gprs_msgt_gmm_names[] = { { 0, NULL } }; -/* 10.5.5.2 */ +/*! \brief String names of GPRS Attach types according to 10.5.5.2 */ const struct value_string gprs_att_t_strs_[] = { { GPRS_ATT_T_ATTACH, "GPRS attach" }, { GPRS_ATT_T_ATT_WHILE_IMSI, "GPRS attach while IMSI attached" }, @@ -174,6 +177,7 @@ const struct value_string gprs_att_t_strs_[] = { const struct value_string *gprs_att_t_strs = gprs_att_t_strs_; +/*! \brief String names of GPRS Location Update Types */ const struct value_string gprs_upd_t_strs_[] = { { GPRS_UPD_T_RA, "RA updating" }, { GPRS_UPD_T_RA_LA, "combined RA/LA updating" }, @@ -184,7 +188,7 @@ const struct value_string gprs_upd_t_strs_[] = { const struct value_string *gprs_upd_t_strs = gprs_upd_t_strs_; -/* 10.5.5.5 */ +/*! \brief String names of GMM MO Detach Types according to 10.5.5.5 */ const struct value_string gprs_det_t_mo_strs_[] = { { GPRS_DET_T_MO_GPRS, "GPRS detach" }, { GPRS_DET_T_MO_IMSI, "IMSI detach" }, @@ -194,6 +198,7 @@ const struct value_string gprs_det_t_mo_strs_[] = { const struct value_string *gprs_det_t_mo_strs = gprs_det_t_mo_strs_; +/*! \brief String names of GMM MT Detach Types according to 10.5.5.5 */ const struct value_string gprs_det_t_mt_strs_[] = { { GPRS_DET_T_MT_REATT_REQ, "re-attach required" }, { GPRS_DET_T_MT_REATT_NOTREQ, "re-attach not required" }, @@ -203,6 +208,7 @@ const struct value_string gprs_det_t_mt_strs_[] = { const struct value_string *gprs_det_t_mt_strs = gprs_det_t_mt_strs_; +/*! \brief String names of GMM Service Types */ const struct value_string gprs_service_t_strs_[] = { { GPRS_SERVICE_T_SIGNALLING, "signalling" }, { GPRS_SERVICE_T_DATA, "data" }, @@ -213,3 +219,5 @@ const struct value_string gprs_service_t_strs_[] = { }; const struct value_string *gprs_service_t_strs = gprs_service_t_strs_; + +/*! @} */ diff --git a/src/gsm/gsm_utils.c b/src/gsm/gsm_utils.c index d16adf73..9cb5df62 100644 --- a/src/gsm/gsm_utils.c +++ b/src/gsm/gsm_utils.c @@ -134,7 +134,10 @@ static int gsm_septet_lookup(uint8_t ch) return -1; } -/* Compute the number of octets from the number of septets, for instance: 47 septets needs 41,125 = 42 octets */ +/*! \brife Compute number of octets from number of septets, + * for instance: 47 septets needs 41,125 = 42 octets + * \param[in sept_len Number of Septets + * \returns Number of octets required */ uint8_t gsm_get_octet_len(const uint8_t sept_len){ int octet_len = (sept_len * 7) / 8; if ((sept_len * 7) % 8 != 0) @@ -143,7 +146,13 @@ uint8_t gsm_get_octet_len(const uint8_t sept_len){ return octet_len; } -/* GSM 03.38 6.2.1 Character unpacking */ +/*! \brief TS 03.38 7-bit Character unpacking (6.2.1) + * \param[out] text Caller-provided output text buffer + * \param[in] n Length of \a text + * \param[in] user_data Input Data (septets) + * \param[in] septet_l Number of septets in \a user_data + * \param[in] ud_hdr_ind User Data Header present in data + * \returns number of bytes written to \a text */ int gsm_7bit_decode_n_hdr(char *text, size_t n, const uint8_t *user_data, uint8_t septet_l, uint8_t ud_hdr_ind) { unsigned shift = 0; @@ -201,11 +210,13 @@ int gsm_7bit_decode_n_hdr(char *text, size_t n, const uint8_t *user_data, uint8_ return text - text_buf_begin; } +/*! \brief Decode 7bit GSM Alphabet */ int gsm_7bit_decode_n(char *text, size_t n, const uint8_t *user_data, uint8_t septet_l) { return gsm_7bit_decode_n_hdr(text, n, user_data, septet_l, 0); } +/*! \brief Decode 7bit GSM Alphabet (USSD) */ int gsm_7bit_decode_n_ussd(char *text, size_t n, const uint8_t *user_data, uint8_t length) { int nchars; @@ -218,7 +229,15 @@ int gsm_7bit_decode_n_ussd(char *text, size_t n, const uint8_t *user_data, uint8 return nchars; } -/* GSM 03.38 6.2.1 Prepare character packing */ +/*! \brief Encode a ASCII characterrs as 7-bit GSM alphabet (TS 03.38) + * + * This function converts a zero-terminated input string \a data from + * ASCII into octet-aligned 7-bit GSM characters. No packing is + * performed. + * + * \param[out] result caller-allocated output buffer + * \param[in] data input data, ASCII + * \returns number of octets used in \a result */ int gsm_septet_encode(uint8_t *result, const char *data) { int i, y = 0; @@ -247,7 +266,12 @@ int gsm_septet_encode(uint8_t *result, const char *data) return y; } -/* 7bit to octet packing */ +/*! \brief GSM Default Alphabet 7bit to octet packing + * \param[out] result Caller-provided output buffer + * \param[in] rdata Input data septets + * \param[in] septet_len Length of \a rdata + * \param[in] padding padding bits at start + * \returns number of bytes used in \a result */ int gsm_septets2octets(uint8_t *result, const uint8_t *rdata, uint8_t septet_len, uint8_t padding) { int i = 0, z = 0; @@ -293,7 +317,12 @@ int gsm_septets2octets(uint8_t *result, const uint8_t *rdata, uint8_t septet_len return z; } -/* GSM 03.38 6.2.1 Character packing */ +/*! \brief GSM 7-bit alphabet TS 03.38 6.2.1 Character packing + * \param[out] result Caller-provided output buffer + * \param[in] n Maximum length of \a result in bytes + * \param[in] data octet-aligned string + * \param[out] octets Number of octets encoded + * \returns number of septets encoded */ int gsm_7bit_encode_n(uint8_t *result, size_t n, const char *data, int *octets) { int y = 0; @@ -332,6 +361,12 @@ int gsm_7bit_encode_n(uint8_t *result, size_t n, const char *data, int *octets) return y; } +/*! \brief Encode according to GSM 7-bit alphabet (TS 03.38 6.2.1) for USSD + * \param[out] result Caller-provided output buffer + * \param[in] n Maximum length of \a result in bytes + * \param[in] data octet-aligned string + * \param[out] octets Number of octets encoded + * \returns number of septets encoded */ int gsm_7bit_encode_n_ussd(uint8_t *result, size_t n, const char *data, int *octets) { int y; @@ -368,7 +403,10 @@ size_t gsm0858_rsl_ul_meas_enc(struct gsm_meas_rep_unidir *mru, bool dtxd_used, return 3; } -/* convert power class to dBm according to GSM TS 05.05 */ +/*! \brief Convert power class to dBm according to GSM TS 05.05 + * \param[in] band GSM frequency band + * \param[in] class GSM power class + * \returns maximum transmit power of power class in dBm */ unsigned int ms_class_gmsk_dbm(enum gsm_band band, int class) { switch (band) { @@ -409,8 +447,11 @@ unsigned int ms_class_gmsk_dbm(enum gsm_band band, int class) return -EINVAL; } -/* determine power control level for given dBm value, as indicated - * by the tables in chapter 4.1.1 of GSM TS 05.05 */ +/*! \brief determine power control level for given dBm value, as indicated + * by the tables in chapter 4.1.1 of GSM TS 05.05 + * \param[in] GSM frequency band + * \param[in] dbm RF power value in dBm + * \returns TS 05.05 power control level */ int ms_pwr_ctl_lvl(enum gsm_band band, unsigned int dbm) { switch (band) { @@ -459,6 +500,10 @@ int ms_pwr_ctl_lvl(enum gsm_band band, unsigned int dbm) return -EINVAL; } +/*! \brief Convert TS 05.05 power level to absolute dBm value + * \param[in] band GSM frequency band + * \param[in] lvl TS 05.05 power control level + * \returns RF power level in dBm */ int ms_pwr_dbm(enum gsm_band band, uint8_t lvl) { lvl &= 0x1f; @@ -497,7 +542,9 @@ int ms_pwr_dbm(enum gsm_band band, uint8_t lvl) return -EINVAL; } -/* According to TS 05.08 Chapter 8.1.4 */ +/*! \brief Convert TS 05.08 RxLev to dBm (TS 05.08 Chapter 8.1.4) + * \param[in] rxlev TS 05.08 RxLev value + * \returns Received RF power in dBm */ int rxlev2dbm(uint8_t rxlev) { if (rxlev > 63) @@ -506,7 +553,9 @@ int rxlev2dbm(uint8_t rxlev) return -110 + rxlev; } -/* According to TS 05.08 Chapter 8.1.4 */ +/*! \brief Convert RF signal level in dBm to TS 05.08 RxLev (TS 05.08 Chapter 8.1.4) + * \param[in] dbm RF signal level in dBm + * \returns TS 05.08 RxLev value */ uint8_t dbm2rxlev(int dbm) { int rxlev = dbm + 110; @@ -519,6 +568,7 @@ uint8_t dbm2rxlev(int dbm) return rxlev; } +/*! \brief Return string name of a given GSM Band */ const char *gsm_band_name(enum gsm_band band) { switch (band) { @@ -542,6 +592,7 @@ const char *gsm_band_name(enum gsm_band band) return "invalid"; } +/*! \brief Parse string name of a GSM band */ enum gsm_band gsm_band_parse(const char* mhz) { while (*mhz && !isdigit(*mhz)) @@ -572,6 +623,10 @@ enum gsm_band gsm_band_parse(const char* mhz) } } +/*! \brief Resolve GSM band from ARFCN + * In Osmocom, we use the highest bit of the \a arfcn to indicate PCS + * \param[in] arfcn Osmocom ARFCN, highest bit determines PCS mode + * \returns GSM Band */ enum gsm_band gsm_arfcn2band(uint16_t arfcn) { int is_pcs = arfcn & ARFCN_PCS; @@ -621,7 +676,10 @@ static struct gsm_freq_range gsm_ranges[] = { { /* Guard */ } }; -/* Convert an ARFCN to the frequency in MHz * 10 */ +/*! \brief Convert an ARFCN to the frequency in MHz * 10 + * \param[in] arfcn GSM ARFCN to convert + * \param[in] uplink Uplink (1) or Downlink (0) frequency + * \returns Frequency in units of 1/10ths of MHz (100kHz) */ uint16_t gsm_arfcn2freq10(uint16_t arfcn, int uplink) { struct gsm_freq_range *r; @@ -645,7 +703,10 @@ uint16_t gsm_arfcn2freq10(uint16_t arfcn, int uplink) return uplink ? freq10_ul : freq10_dl; } -/* Convert a Frequency in MHz * 10 to ARFCN */ +/*! \brief Convert a Frequency in MHz * 10 to ARFCN + * \param[in] freq10 Frequency in units of 1/10ths of MHz (100kHz) + * \param[in] uplink Frequency is Uplink (1) or Downlink (0) + * \returns ARFCN in case of success; 0xffff on error */ uint16_t gsm_freq102arfcn(uint16_t freq10, int uplink) { struct gsm_freq_range *r; @@ -675,6 +736,9 @@ uint16_t gsm_freq102arfcn(uint16_t freq10, int uplink) return arfcn; } +/*! \brief Parse GSM Frame Number into struct \ref gsm_time + * \param[out] time Caller-provided memory for \ref gsm_time + * \param[in] fn GSM Frame Number */ void gsm_fn2gsmtime(struct gsm_time *time, uint32_t fn) { time->fn = fn; @@ -684,13 +748,18 @@ void gsm_fn2gsmtime(struct gsm_time *time, uint32_t fn) time->tc = (time->fn / 51) % 8; } +/*! \brief Encode decoded \ref gsm_time to Frame Number + * \param[in] time GSM Time in decoded structure + * \returns GSM Frame Number */ uint32_t gsm_gsmtime2fn(struct gsm_time *time) { /* TS 05.02 Chapter 4.3.3 TDMA frame number */ return (51 * ((time->t3 - time->t2 + 26) % 26) + time->t3 + (26 * 51 * time->t1)); } -/*! \brief append range1024 encoded data to bit vector */ +/*! \brief append range1024 encoded data to bit vector + * \param[out] bv Caller-provided output bit-vector + * \param[in] r Input Range1024 sructure */ void bitvec_add_range1024(struct bitvec *bv, const struct gsm48_range_1024 *r) { bitvec_set_uint(bv, r->w1_hi, 2); @@ -724,7 +793,7 @@ void bitvec_add_range1024(struct bitvec *bv, const struct gsm48_range_1024 *r) bitvec_set_uint(bv, r->w16, 6); } -/* TS 23.003 Chapter 2.6 */ +/*! \brief Determine GPRS TLLI Type (TS 23.003 Chapter 2.6) */ int gprs_tlli_type(uint32_t tlli) { if ((tlli & 0xc0000000) == 0xc0000000) @@ -743,6 +812,10 @@ int gprs_tlli_type(uint32_t tlli) return TLLI_RESERVED; } +/*! \brief Determine TLLI from P-TMSI + * \param[in] p_tmsi P-TMSI + * \param[in] type TLLI Type we want to derive from \a p_tmsi + * \returns TLLI of given type */ uint32_t gprs_tmsi2tlli(uint32_t p_tmsi, enum gprs_tlli_type type) { uint32_t tlli; diff --git a/src/gsm/gsup.c b/src/gsm/gsup.c index a813ed8a..3cac2018 100644 --- a/src/gsm/gsup.c +++ b/src/gsm/gsup.c @@ -31,6 +31,11 @@ #include <stdint.h> +/*! \addtogroup gsup + * @{ + * \brief Osmocom Generic Subscriber Update Protocol + */ + const struct value_string osmo_gsup_message_type_names[] = { OSMO_VALUE_STRING(OSMO_GSUP_MSGT_UPDATE_LOCATION_REQUEST), OSMO_VALUE_STRING(OSMO_GSUP_MSGT_UPDATE_LOCATION_ERROR), @@ -536,3 +541,5 @@ void osmo_gsup_encode(struct msgb *msg, const struct osmo_gsup_message *gsup_msg msgb_tlv_put(msg, OSMO_GSUP_CN_DOMAIN_IE, 1, &dn); } } + +/*! @} */ diff --git a/src/gsm/ipa.c b/src/gsm/ipa.c index fa6a8b0d..5c37d643 100644 --- a/src/gsm/ipa.c +++ b/src/gsm/ipa.c @@ -41,6 +41,11 @@ #include <osmocom/gsm/protocol/ipaccess.h> #include <osmocom/gsm/ipa.h> +/*! \addtogroup ipa + * @{ + * \brief IPA Multiplex utility routines + */ + #define IPA_ALLOC_SIZE 1200 /* @@ -581,3 +586,5 @@ struct msgb *ipa_msg_alloc(int headroom) return NULL; return nmsg; } + +/*! @} */ diff --git a/src/gsm/lapd_core.c b/src/gsm/lapd_core.c index 310df653..b7a95399 100644 --- a/src/gsm/lapd_core.c +++ b/src/gsm/lapd_core.c @@ -23,6 +23,7 @@ /*! \addtogroup lapd * @{ + * \brief Osmocom LAPD core, used for Q.921, LAPDm and others */ /*! \file lapd_core.c */ diff --git a/src/gsm/lapdm.c b/src/gsm/lapdm.c index 99099d19..8ec942f4 100644 --- a/src/gsm/lapdm.c +++ b/src/gsm/lapdm.c @@ -23,6 +23,7 @@ /*! \addtogroup lapdm * @{ + * \brief GSM LAPDm (TS 04.06) implementation */ /*! \file lapdm.c */ diff --git a/src/gsm/oap.c b/src/gsm/oap.c index 1494a6a6..5706e8ff 100644 --- a/src/gsm/oap.c +++ b/src/gsm/oap.c @@ -28,6 +28,11 @@ #include <stdint.h> +/*! \addtogroup oap + * @{ + * \brief Osmocom Authentication Protocol + */ + /*! \brief Decode OAP message data. * \param[out] oap_msg Parsed data is written to this instance. * \param[in] data Pointer to the data buffer containing the OAP message. @@ -182,3 +187,5 @@ void osmo_oap_encode(struct msgb *msg, const struct osmo_oap_message *oap_msg) msg->l2h = msg->data; } + +/*! @} */ diff --git a/src/gsm/rsl.c b/src/gsm/rsl.c index 910e8481..5bdb0063 100644 --- a/src/gsm/rsl.c +++ b/src/gsm/rsl.c @@ -30,6 +30,7 @@ /*! \addtogroup rsl * @{ + * \brief GSM Radio Signalling Link (TS 08.58) */ /*! \file rsl.c */ @@ -39,7 +40,9 @@ /*! \brief Headroom size for RSL \ref msgb_alloc */ #define RSL_ALLOC_HEADROOM 56 -/*! \brief Initialize a RSL RLL header */ +/*! \brief Initialize a RSL RLL header + * \param[out] dh Caller-allocated RSL RLL header + * \param[in] msg_type Message Type */ void rsl_init_rll_hdr(struct abis_rsl_rll_hdr *dh, uint8_t msg_type) { dh->c.msg_discr = ABIS_RSL_MDISC_RLL; @@ -48,7 +51,9 @@ 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 */ +/*! \brief Initialize a RSL Common Channel header + * \param[out] ch Caller-allocated RSL Common Channel Header + * \param[in] msg_type Message Type */ void rsl_init_cchan_hdr(struct abis_rsl_cchan_hdr *ch, uint8_t msg_type) { ch->c.msg_discr = ABIS_RSL_MDISC_COM_CHAN; @@ -137,7 +142,11 @@ const struct tlv_definition rsl_att_tlvdef = { }, }; -/*! \brief Encode channel number as per Section 9.3.1 */ +/*! \brief Encode channel number as per Section 9.3.1 + * \param[in] Channel Type (RSL_CHAN_...) + * \param[in] subch Sub-Channel within Channel + * \param[in] timeslot Air interface timeslot + * \returns RSL Channel Number (TS 08.58 9.3.1) */ uint8_t rsl_enc_chan_nr(uint8_t type, uint8_t subch, uint8_t timeslot) { uint8_t ret; @@ -455,7 +464,12 @@ int rsl_ccch_conf_to_bs_ccch_sdcch_comb(int ccch_conf) } } -/*! \brief Push a RSL RLL header onto an existing msgb */ +/*! \brief Push a RSL RLL header onto an existing msgb + * \param msg Message Buffer to which RLL header shall be pushed + * \param[in] msg_type RSL Message Type + * \param[in] chan_nr RSL Channel Number + * \param[in] link_id RSL Link Identifier + * \param[in] transparent Transparent to BTS (1) or not (0) */ void rsl_rll_push_hdr(struct msgb *msg, uint8_t msg_type, uint8_t chan_nr, uint8_t link_id, int transparent) { @@ -472,7 +486,12 @@ void rsl_rll_push_hdr(struct msgb *msg, uint8_t msg_type, uint8_t chan_nr, msg->l2h = (uint8_t *)rh; } -/*! \brief Push a RSL RLL header with L3_INFO IE */ +/*! \brief Wrap msgb in L3 Info IE and push a RSL RLL header + * \param[in] msg Message Buffer to which L3 Header shall be appended + * \param[in] msg_type RSL Message Type + * \param[in] chan_hr RSL Channel Number + * \param[in] link_id Link Identififer + * \param[in] transparent Transparent to BTS (1) or not (0) */ void rsl_rll_push_l3(struct msgb *msg, uint8_t msg_type, uint8_t chan_nr, uint8_t link_id, int transparent) { @@ -488,7 +507,12 @@ 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 */ +/*! \brief Create msgb with RSL RLL header + * \param[in] msg_type RSL Message Type + * \param[in] chan_nr RSL Channel Number + * \param[in] link_id RSL Link Identifier + * \param[in] transparent Transparent to BTS (1) or not (0) + * \returns callee-allocated msgb; NULL on error */ struct msgb *rsl_rll_simple(uint8_t msg_type, uint8_t chan_nr, uint8_t link_id, int transparent) { @@ -515,6 +539,7 @@ struct msgb *rsl_rll_simple(uint8_t msg_type, uint8_t chan_nr, return msg; } +/*! \brief TLV parser definitions for IPA embedded IEs */ const struct tlv_definition rsl_ipac_eie_tlvdef = { .def = { [RSL_IPAC_EIE_RXLEV] = { TLV_TYPE_TV }, @@ -541,6 +566,7 @@ const struct tlv_definition rsl_ipac_eie_tlvdef = { }, }; +/*! \brief String names of RSL Channel Activation Types */ const struct value_string rsl_act_type_names[] = { { RSL_ACT_TYPE_INITIAL, "INITIAL" }, { RSL_ACT_TYPE_REACT, "REACT" }, diff --git a/src/gsm/tlv_parser.c b/src/gsm/tlv_parser.c index 4cc43f67..d7604c6d 100644 --- a/src/gsm/tlv_parser.c +++ b/src/gsm/tlv_parser.c @@ -25,7 +25,22 @@ /*! \addtogroup tlv * @{ + * \brief Osmocom TLV Parser + * + * The Osmocom TLV parser is intended to operate as a low-level C + * implementation without dynamic memory allocations. Basically, it + * iterates over the IE (Information Elements) of the message and fills + * an array of pointers, indexed by the IEI (IE Identifier). The + * parser output is thus an array of pointers to the start of the + * respective IE inside the message. + * + * The TLV parser is configured by a TLV parser definition, which + * determines which if the IEIs for a given protocol are of which + * particular type. Types are e.g. TV (Tag + single byte value), Tag + + * fixed-length value, TLV with 8bit length, TLV with 16bit length, TLV + * with variable-length length field, etc. */ + /*! \file tlv_parser.c */ struct tlv_definition tvlv_att_def; @@ -262,7 +277,9 @@ int tlv_parse(struct tlv_parsed *dec, const struct tlv_definition *def, return num_parsed; } -/*! \brief take a master (src) tlvdev and fill up all empty slots in 'dst' */ +/*! \brief take a master (src) tlvdev and fill up all empty slots in 'dst' + * \param dst TLV parser definition that is to be patched + * \param[in] src TLV parser definition whose content is patched into \a dst */ void tlv_def_patch(struct tlv_definition *dst, const struct tlv_definition *src) { int i; diff --git a/src/gsmtap_util.c b/src/gsmtap_util.c index 74f3b48d..64b54f38 100644 --- a/src/gsmtap_util.c +++ b/src/gsmtap_util.c @@ -43,6 +43,7 @@ /*! \addtogroup gsmtap * @{ + * \brief GSMTAP utility routines. Encapsulates GSM messages over UDP */ /*! \file gsmtap_util.c */ diff --git a/src/logging.c b/src/logging.c index 0d2b6daf..3b3dd052 100644 --- a/src/logging.c +++ b/src/logging.c @@ -22,6 +22,7 @@ /* \addtogroup logging * @{ + * \brief libosmocore Logging sub-system */ /* \file logging.c */ diff --git a/src/logging_gsmtap.c b/src/logging_gsmtap.c index f37f8e7d..7358bf68 100644 --- a/src/logging_gsmtap.c +++ b/src/logging_gsmtap.c @@ -23,7 +23,13 @@ * @{ */ -/*! \file logging_gsmtap.c */ +/*! \file logging_gsmtap.c + * \brief libosmocore log output encapsulated in GSMTAP + * + * Encapsulating the log output inside GSMTAP frames allows us to + * observer protocol traces (of Um, Abis, A or any other interface in + * the Osmocom world) with synchronous interspersed log messages. + */ #include "../config.h" diff --git a/src/logging_syslog.c b/src/logging_syslog.c index 5b0ae5ff..6fe3c719 100644 --- a/src/logging_syslog.c +++ b/src/logging_syslog.c @@ -23,7 +23,9 @@ * @{ */ -/*! \file logging_syslog.c */ +/*! \file logging_syslog.c + * \brief libosmocore logging output via syslog + */ #include "../config.h" diff --git a/src/loggingrb.c b/src/loggingrb.c index bd093b70..3fb38ca1 100644 --- a/src/loggingrb.c +++ b/src/loggingrb.c @@ -23,7 +23,9 @@ * @{ */ -/*! \file loggingrb.c */ +/*! \file loggingrb.c + * \brief libosmocore logging backend for a ring-buffer of last log messages + */ #include <osmocom/core/strrb.h> #include <osmocom/core/logging.h> diff --git a/src/macaddr.c b/src/macaddr.c index ceb1e0a3..e5db8cf0 100644 --- a/src/macaddr.c +++ b/src/macaddr.c @@ -24,7 +24,9 @@ * @{ */ -/*! \file loggingrb.c */ +/*! \file macaddr.c + * \brief MAC address utility routines + */ #include "config.h" @@ -20,10 +20,35 @@ /*! \addtogroup msgb * @{ + * \brief libosmocore message buffers, inspired by Linux kernel skbuff + * + * Inspired by the 'struct skbuff' of the Linux kernel, we implement a + * 'struct msgb' which we use for handling network + * packets aka messages aka PDUs. + * + * A msgb consists of + * * a header with some metadata, such as + * * a linked list header for message queues or the like + * * pointers to the headers of various protocol layers inside + * the packet + * * a data section consisting of + * * headroom, i.e. space in front of the message, to allow + * for additional headers being pushed in front of the current + * data + * * the curently occupied data for the message + * * tailroom, i.e. space at the end of the message, to + * allow more data to be added after the end of the current + * data + * + * We have plenty of utility functions around the \ref msgb: + * * allocation / release + * * enqueue / dequeue from/to message queues + * * prepending (pushing) and appending (putting) data + * * copying / resizing + * * hex-dumping to a string for debug purposes */ -/*! \file msgb.c - */ +/*! \file msgb.c */ #include <unistd.h> #include <string.h> diff --git a/src/plugin.c b/src/plugin.c index 52887acf..71df88be 100644 --- a/src/plugin.c +++ b/src/plugin.c @@ -20,6 +20,10 @@ * */ +/*! \addtogroup utils + * @{ + */ + /*! \file plugin.c * \brief Routines for loading and managing shared library plug-ins. */ @@ -69,3 +73,5 @@ int osmo_plugin_load_all(const char *directory) return 0; } #endif /* HAVE_DLFCN_H */ + +/*! @} */ diff --git a/src/rate_ctr.c b/src/rate_ctr.c index 3ccd065f..47067fb1 100644 --- a/src/rate_ctr.c +++ b/src/rate_ctr.c @@ -22,6 +22,7 @@ /*! \addtogroup rate_ctr * @{ + * \brief conters about events and their event rates */ /*! \file rate_ctr.c */ diff --git a/src/select.c b/src/select.c index afc8198e..bdd53b29 100644 --- a/src/select.c +++ b/src/select.c @@ -36,11 +36,10 @@ /*! \addtogroup select * @{ + * \brief select() loop abstraction */ -/*! \file select.c - * \brief select loop abstraction - */ +/*! \file select.c */ static int maxfd = 0; static LLIST_HEAD(osmo_fds); diff --git a/src/sercomm.c b/src/sercomm.c index 2f693ef4..33d48531 100644 --- a/src/sercomm.c +++ b/src/sercomm.c @@ -22,6 +22,7 @@ /*! \addtogroup sercomm * @{ + * \brief Serial communications layer, based on HDLC */ /*! \file sercomm.c diff --git a/src/serial.c b/src/serial.c index 05bdc86e..51a32bbc 100644 --- a/src/serial.c +++ b/src/serial.c @@ -24,11 +24,10 @@ /*! \addtogroup serial * @{ + * \brief Osmocom serial port helpers */ -/*! \file serial.c - * Osmocom serial port helpers - */ +/*! \file serial.c */ #include <errno.h> #include <fcntl.h> diff --git a/src/signal.c b/src/signal.c index 84025915..1d11617a 100644 --- a/src/signal.c +++ b/src/signal.c @@ -27,7 +27,9 @@ /*! \addtogroup signal * @{ + * \brief Generic signalling/notification infrastructure */ + /*! \file signal.c */ diff --git a/src/socket.c b/src/socket.c index 9d22d61d..6fa05a84 100644 --- a/src/socket.c +++ b/src/socket.c @@ -23,12 +23,11 @@ /*! \addtogroup socket * @{ - */ - -/*! \file socket.c * \brief Osmocom socket convenience functions */ +/*! \file socket.c */ + #ifdef HAVE_SYS_SOCKET_H #include <osmocom/core/logging.h> diff --git a/src/strrb.c b/src/strrb.c index 069a6993..69c4ddae 100644 --- a/src/strrb.c +++ b/src/strrb.c @@ -21,6 +21,10 @@ * */ +/*! \addtogroup utils + * @{ + */ + /*! \file strrb.c * \brief Lossy string ringbuffer for logging; keeps newest messages. */ @@ -170,3 +174,5 @@ int osmo_strrb_add(struct osmo_strrb *rb, const char *data) } return ret; } + +/*! @} */ diff --git a/src/timer.c b/src/timer.c index a8cd42b8..72176b8e 100644 --- a/src/timer.c +++ b/src/timer.c @@ -26,10 +26,10 @@ /*! \addtogroup timer * @{ + * \brief Osmocom timer abstraction; modelled after linux kernel timers */ -/*! \file timer.c - */ +/*! \file timer.c */ #include <assert.h> #include <string.h> diff --git a/src/utils.c b/src/utils.c index 1a4aab4b..e7c6bcfb 100644 --- a/src/utils.c +++ b/src/utils.c @@ -33,6 +33,7 @@ /*! \addtogroup utils * @{ + * \brief various utility routines */ /*! \file utils.c */ diff --git a/src/vty/command.c b/src/vty/command.c index 587bd626..e50706e8 100644 --- a/src/vty/command.c +++ b/src/vty/command.c @@ -42,7 +42,8 @@ Boston, MA 02110-1301, USA. */ #include <osmocom/core/utils.h> /*! \addtogroup command - * @{ + * @{ + * \brief VTY command handling */ /*! \file command.c */ diff --git a/src/vty/fsm_vty.c b/src/vty/fsm_vty.c index 422de9d9..3824fe8c 100644 --- a/src/vty/fsm_vty.c +++ b/src/vty/fsm_vty.c @@ -33,6 +33,16 @@ #include <osmocom/core/logging.h> #include <osmocom/core/linuxlist.h> +/*! \addtogroup fsm + * @{ + * \brief VTY interface for Osmocom FSM + * + * This is code implementing generic VTY access to Osmocom FSMs from + * libosmocore. This means that any application can expose all state + * of all instances of all registered FSM classes by calling a single + * command during startup: \ref osmo_fsm_vty_add_cmds + */ + /* we don't want to add this to a public header file; this is simply * exported by libosmocore and used by libmsomvty but not for public * consumption. */ @@ -175,3 +185,5 @@ void osmo_fsm_vty_add_cmds(void) install_element_ve(&show_fsm_inst_cmd); install_element_ve(&show_fsm_insts_cmd); } + +/*! @} */ diff --git a/src/vty/logging_vty.c b/src/vty/logging_vty.c index 7ec212e7..8c8a3235 100644 --- a/src/vty/logging_vty.c +++ b/src/vty/logging_vty.c @@ -39,6 +39,16 @@ #define LOG_STR "Configure logging sub-system\n" +/*! \addtogroup logging + * @{ + * \brief Configuration of logging from VTY + * + * This module implements functions that permit configuration of + * the libosmocore logging framework from VTY commands. This applies + * both to logging to the VTY (telnet sessions), as well as logging to + * other targets, such as sysslog, file, gsmtap, ... + */ + extern const struct log_info *osmo_log_info; static void _vty_output(struct log_target *tgt, @@ -778,3 +788,5 @@ void logging_vty_add_cmds() #endif install_element(CONFIG_NODE, &cfg_log_gsmtap_cmd); } + +/* @} */ diff --git a/src/vty/stats_vty.c b/src/vty/stats_vty.c index c03546b8..af69289f 100644 --- a/src/vty/stats_vty.c +++ b/src/vty/stats_vty.c @@ -41,6 +41,11 @@ #define SHOW_STATS_STR "Show statistical values\n" +/*! \addtogroup stats + * @{ + * \brief VTY interface for statsd / statistic items + */ + /* containing version info */ extern struct host host; @@ -571,6 +576,10 @@ static int config_write_stats(struct vty *vty) return 1; } +/*! \brief Add stats related commands to the VTY + * Call this once during your application initialization if you would + * like to have stats VTY commands enabled. + */ void osmo_stats_vty_add_cmds() { install_element_ve(&show_stats_cmd); @@ -599,3 +608,5 @@ void osmo_stats_vty_add_cmds() install_element_ve(&show_stats_asciidoc_table_cmd); } + +/*! @} */ diff --git a/src/vty/telnet_interface.c b/src/vty/telnet_interface.c index 218f9abf..d53881a1 100644 --- a/src/vty/telnet_interface.c +++ b/src/vty/telnet_interface.c @@ -38,6 +38,12 @@ /*! \addtogroup telnet_interface * @{ + * \brief Telnet interface towards Osmocom VTY + * + * This module contains the code implementing a telnet server for VTY + * access. This telnet server gets linked into each libosmovty-using + * process in order to enable interactive command-line introspection, + * interaction and configuration. */ /*! \file telnet_interface.c */ diff --git a/src/vty/utils.c b/src/vty/utils.c index 27c1a854..6772593d 100644 --- a/src/vty/utils.c +++ b/src/vty/utils.c @@ -82,6 +82,33 @@ void vty_out_rate_ctr_group(struct vty *vty, const char *prefix, rate_ctr_for_each_counter(ctrg, rate_ctr_handler, &vctx); } +static int rate_ctr_group_handler(struct rate_ctr_group *ctrg, void *vctx_) +{ + struct vty_out_context *vctx = vctx_; + struct vty *vty = vctx->vty; + + if (ctrg->desc->class_id > vctx->max_level) + return 0; + + if (ctrg->idx) + vty_out(vty, "%s%s (%d):%s", vctx->prefix, + ctrg->desc->group_description, ctrg->idx, VTY_NEWLINE); + else + vty_out(vty, "%s%s:%s", vctx->prefix, + ctrg->desc->group_description, VTY_NEWLINE); + + rate_ctr_for_each_counter(ctrg, rate_ctr_handler, vctx); + + return 0; +} + +/*! @} */ + + +/*! \addtogroup stats + * @{ + */ + static int osmo_stat_item_handler( struct osmo_stat_item_group *statg, struct osmo_stat_item *item, void *vctx_) { @@ -135,25 +162,11 @@ static int osmo_stat_item_group_handler(struct osmo_stat_item_group *statg, void return 0; } -static int rate_ctr_group_handler(struct rate_ctr_group *ctrg, void *vctx_) -{ - struct vty_out_context *vctx = vctx_; - struct vty *vty = vctx->vty; - - if (ctrg->desc->class_id > vctx->max_level) - return 0; - - if (ctrg->idx) - vty_out(vty, "%s%s (%d):%s", vctx->prefix, - ctrg->desc->group_description, ctrg->idx, VTY_NEWLINE); - else - vty_out(vty, "%s%s:%s", vctx->prefix, - ctrg->desc->group_description, VTY_NEWLINE); - - rate_ctr_for_each_counter(ctrg, rate_ctr_handler, vctx); +/*! @} */ - return 0; -} +/*! \addtogroup vty + * @{ + */ static int handle_counter(struct osmo_counter *counter, void *vctx_) { @@ -239,5 +252,4 @@ err: return str; } - /*! @} */ diff --git a/src/vty/vector.c b/src/vty/vector.c index c5a99af3..b95e15c3 100644 --- a/src/vty/vector.c +++ b/src/vty/vector.c @@ -27,6 +27,11 @@ #include <osmocom/core/talloc.h> #include <string.h> +/*! \addtogroup vector + * @{ + * \brief Generic vector routines, used by VTY internally + */ + void *tall_vty_vec_ctx; /* Initialize vector : allocate memory and return vector. */ @@ -190,3 +195,5 @@ unsigned int vector_count(vector v) return count; } + +/*! @} */ diff --git a/src/vty/vty.c b/src/vty/vty.c index 01d5ec09..2ec9538c 100644 --- a/src/vty/vty.c +++ b/src/vty/vty.c @@ -14,7 +14,7 @@ * routines in libosmovty are not thread-safe. If you must use them in * a multi-threaded context, you have to add your own locking. * - * libosmocovty is developed as part of the Osmocom (Open Source Mobile + * libosmovty is developed as part of the Osmocom (Open Source Mobile * Communications) project, a community-based, collaborative development * project to create Free and Open Source implementations of mobile * communications systems. For more information about Osmocom, please diff --git a/src/write_queue.c b/src/write_queue.c index c7a43205..1e4cda5a 100644 --- a/src/write_queue.c +++ b/src/write_queue.c @@ -27,6 +27,7 @@ /*! \addtogroup write_queue * @{ + * \brief write queue for writing \ref msgb to sockets/fd's */ /*! \file write_queue.c */ |