This is merely a historical archive of years 2008-2021, before the migration to mailman3.
A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.
Harald Welte gerrit-no-reply at lists.osmocom.orgHarald Welte has submitted this change and it was merged. Change subject: [doc] Expand Doxuygen documentation for osmo_prim ...................................................................... [doc] Expand Doxuygen documentation for osmo_prim Also, make sure prim.c is actually part of the 'prim' module. Change-Id: I4363e46a5f606eb2114a9cc1d2086007eaa58d31 --- M include/osmocom/core/prim.h M src/prim.c 2 files changed, 28 insertions(+), 5 deletions(-) Approvals: Harald Welte: Looks good to me, approved Jenkins Builder: Verified diff --git a/include/osmocom/core/prim.h b/include/osmocom/core/prim.h index 88ae08b..99eabff 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 @@ 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 diff --git a/src/prim.c b/src/prim.c index 2035581..d18dbd7 100644 --- a/src/prim.c +++ b/src/prim.c @@ -1,4 +1,6 @@ -/*! \file prim.c */ +/*! \addtogroup prim + * @{ + * \file prim.c */ #include <osmocom/core/utils.h> #include <osmocom/core/prim.h> @@ -30,3 +32,5 @@ } return OSMO_NO_EVENT; } + +/*! @} */ -- To view, visit https://gerrit.osmocom.org/4289 To unsubscribe, visit https://gerrit.osmocom.org/settings Gerrit-MessageType: merged Gerrit-Change-Id: I4363e46a5f606eb2114a9cc1d2086007eaa58d31 Gerrit-PatchSet: 1 Gerrit-Project: libosmocore Gerrit-Branch: master Gerrit-Owner: Harald Welte <laforge at gnumonks.org> Gerrit-Reviewer: Harald Welte <laforge at gnumonks.org> Gerrit-Reviewer: Jenkins Builder