[doc] Expand Doxuygen documentation for osmo_prim

Also, make sure prim.c is actually part of the 'prim' module.

Change-Id: I4363e46a5f606eb2114a9cc1d2086007eaa58d31

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;
 }
+
+/*! @} */