diff options
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_ |