diff options
Diffstat (limited to 'include')
| -rw-r--r-- | include/osmocom/core/prim.h | 27 |
1 files changed, 23 insertions, 4 deletions
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 <stdint.h> @@ -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 |