From 7166094a85b88bdf18f19ea1e3a85874c0236748 Mon Sep 17 00:00:00 2001 From: Harald Welte Date: Mon, 16 Oct 2017 14:52:37 +0200 Subject: [doc] Expand Doxuygen documentation for osmo_prim Also, make sure prim.c is actually part of the 'prim' module. Change-Id: I4363e46a5f606eb2114a9cc1d2086007eaa58d31 --- include/osmocom/core/prim.h | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) (limited to 'include') diff --git a/include/osmocom/core/prim.h b/include/osmocom/core/prim.h index 88ae08b5..99eabff0 100644 --- a/include/osmocom/core/prim.h +++ b/include/osmocom/core/prim.h @@ -2,6 +2,18 @@ /*! \defgroup prim Osmocom primitives * @{ + * + * Osmocom Primitives are a method to express inter-layer primitives as + * used often in ITU/ETSI/3GPP specifications in a generic way. They + * are based on \ref msgb and encapsulate any (optional) user payload + * data with a primitive header. The header contains information on + * - which SAP this primitive is used on + * - what is the name of the primitive + * - is it REQUEST, RESPONSE, INDICATION or CONFIRMATION + * + * For more information on the inter-layer primitives concept, see + * ITU-T X.21@ as found at https://www.itu.int/rec/T-REC-X.212-199511-I/en + * * \file prim.h */ #include @@ -20,21 +32,28 @@ enum osmo_prim_operation { extern const struct value_string osmo_prim_op_names[5]; +/*!< The upper 8 byte of the technology, the lower 24 bits for the SAP */ #define _SAP_GSM_SHIFT 24 #define _SAP_GSM_BASE (0x01 << _SAP_GSM_SHIFT) #define _SAP_TETRA_BASE (0x02 << _SAP_GSM_SHIFT) #define _SAP_SS7_BASE (0x03 << _SAP_GSM_SHIFT) -/*! primitive header */ +/*! Osmocom primitive header */ struct osmo_prim_hdr { - unsigned int sap; /*!< Service Access Point */ + unsigned int sap; /*!< Service Access Point Identifier */ unsigned int primitive; /*!< Primitive number */ enum osmo_prim_operation operation; /*! Primitive Operation */ - struct msgb *msg; /*!< \ref msgb containing associated data */ + struct msgb *msg; /*!< \ref msgb containing associated data. + * Note this can be slightly confusing, as the \ref osmo_prim_hdr + * is stored inside a \ref msgb, but then it contains a pointer + * back to the msgb. This is to simplify development: You can + * pass around a \ref osmo_prim_hdr by itself, and any function + * can autonomously resolve the underlying msgb, if needed (e.g. + * for \ref msgb_free. */ }; -/*! initialize a primitive header +/*! Convenience function to initialize a primitive header * \param[in,out] oph primitive header * \param[in] sap Service Access Point * \param[in] primitive Primitive Number -- cgit v1.2.3