summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorHarald Welte <laforge@gnumonks.org>2017-10-16 14:52:37 +0200
committerHarald Welte <laforge@gnumonks.org>2017-10-16 14:52:37 +0200
commit7166094a85b88bdf18f19ea1e3a85874c0236748 (patch)
tree11ac5e04acf1063a9be6a064d8e18c5a5df24dbc
parentdf8c57f328b350edee4fd59fb4a4b72ed2df1b23 (diff)
[doc] Expand Doxuygen documentation for osmo_prim
Also, make sure prim.c is actually part of the 'prim' module. Change-Id: I4363e46a5f606eb2114a9cc1d2086007eaa58d31
-rw-r--r--include/osmocom/core/prim.h27
-rw-r--r--src/prim.c6
2 files changed, 28 insertions, 5 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
diff --git a/src/prim.c b/src/prim.c
index 20355813..d18dbd76 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 @@ uint32_t osmo_event_for_prim(const struct osmo_prim_hdr *oph,
}
return OSMO_NO_EVENT;
}
+
+/*! @} */