GPRS NS: Add some doxygen API documentation

2 files changed, 143 insertions, 26 deletions

diff --git a/openbsc/include/openbsc/gprs_ns.h b/openbsc/include/openbsc/gprs_ns.h
index e26337a69..f0ec26ed5 100644
--- a/openbsc/include/openbsc/gprs_ns.h
+++ b/openbsc/include/openbsc/gprs_ns.h
@@ -7,12 +7,19 @@
  * 3GPP TS 08.16 version 8.0.1 Release 1999 / ETSI TS 101 299 V8.0.1 (2002-05)
  * 3GPP TS 48.016 version 6.5.0 Release 6 / ETSI TS 148 016 V6.5.0 (2005-11) */
 
+/*! \addtogroup libgb
+ *  @{
+ */
+
+/*! \file gprs_ns.h */
+
+/*! \brief Common header of GPRS NS */
 struct gprs_ns_hdr {
-	uint8_t pdu_type;
-	uint8_t data[0];
+	uint8_t pdu_type;	/*!< NS PDU type */
+	uint8_t data[0];	/*!< variable-length payload */
 } __attribute__((packed));
 
-/* TS 08.16, Section 10.3.7, Table 14 */
+/*! \brief NS PDU Type (TS 08.16, Section 10.3.7, Table 14) */
 enum ns_pdu_type {
 	NS_PDUT_UNITDATA	= 0x00,
 	NS_PDUT_RESET		= 0x02,
@@ -35,7 +42,7 @@ enum ns_pdu_type {
 	SNS_PDUT_SIZE_ACK	= 0x13,
 };
 
-/* TS 08.16, Section 10.3, Table 12 */
+/*! \brief NS Control IE (TS 08.16, Section 10.3, Table 12) */
 enum ns_ctrl_ie {
 	NS_IE_CAUSE		= 0x00,
 	NS_IE_VCI		= 0x01,
@@ -52,7 +59,7 @@ enum ns_ctrl_ie {
 	NS_IE_IP_ADDR		= 0x0b,
 };
 
-/* TS 08.16, Section 10.3.2, Table 13 */
+/*! \brief NS Cause (TS 08.16, Section 10.3.2, Table 13) */
 enum ns_cause {
 	NS_CAUSE_TRANSIT_FAIL		= 0x00,
 	NS_CAUSE_OM_INTERVENTION	= 0x01,
@@ -106,40 +113,44 @@ enum ns_timeout {
 #define NSE_S_BLOCKED	0x0001
 #define NSE_S_ALIVE	0x0002
 
+/*! \brief Osmocom NS link layer types */
 enum gprs_ns_ll {
-	GPRS_NS_LL_UDP,
-	GPRS_NS_LL_E1,
-	GPRS_NS_LL_FR_GRE,
+	GPRS_NS_LL_UDP,		/*!< NS/UDP/IP */
+	GPRS_NS_LL_E1,		/*!< NS/E1 */
+	GPRS_NS_LL_FR_GRE,	/*!< NS/FR/GRE/IP */
 };
 
+/*! \brief Osmoco NS events */
 enum gprs_ns_evt {
 	GPRS_NS_EVT_UNIT_DATA,
 };
 
 struct gprs_nsvc;
+/*! \brief Osmocom GPRS callback function type */
 typedef int gprs_ns_cb_t(enum gprs_ns_evt event, struct gprs_nsvc *nsvc,
 			 struct msgb *msg, uint16_t bvci);
 
-/* An instance of the NS protocol stack */
+/*! \brief An instance of the NS protocol stack */
 struct gprs_ns_inst {
-	/* callback to the user for incoming UNIT DATA IND */
+	/*! \brief callback to the user for incoming UNIT DATA IND */
 	gprs_ns_cb_t *cb;
 
-	/* linked lists of all NSVC in this instance */
+	/*! \brief linked lists of all NSVC in this instance */
 	struct llist_head gprs_nsvcs;
 
-	/* a NSVC object that's needed to deal with packets for unknown NSVC */
+	/*! \brief a NSVC object that's needed to deal with packets for
+	 * 	   unknown NSVC */
 	struct gprs_nsvc *unknown_nsvc;
 
 	uint16_t timeout[NS_TIMERS_COUNT];
 
-	/* NS-over-IP specific bits */
+	/*! \brief NS-over-IP specific bits */
 	struct {
 		struct osmo_fd fd;
 		uint32_t local_ip;
 		uint16_t local_port;
 	} nsip;
-	/* NS-over-FR-over-GRE-over-IP specific bits */
+	/*! \brief NS-over-FR-over-GRE-over-IP specific bits */
 	struct {
 		struct osmo_fd fd;
 		uint32_t local_ip;
@@ -155,12 +166,15 @@ enum nsvc_timer_mode {
 	_NSVC_TIMER_NR,
 };
 
+/*! \brief Structure representing a single NS-VC */
 struct gprs_nsvc {
+	/*! \brief list of NS-VCs within NS Instance */
 	struct llist_head list;
+	/*! \brief pointer to NS Instance */
 	struct gprs_ns_inst *nsi;
 
-	uint16_t nsei;		/* end-to-end significance */
-	uint16_t nsvci;	/* uniquely identifies NS-VC at SGSN */
+	uint16_t nsei;	/*! \brief end-to-end significance */
+	uint16_t nsvci;	/*! \brief uniquely identifies NS-VC at SGSN */
 
 	uint32_t state;
 	uint32_t remote_state;
@@ -174,7 +188,7 @@ struct gprs_nsvc {
 
 	struct rate_ctr_group *ctrg;
 
-	/* which link-layer are we based on? */
+	/*! \brief which link-layer are we based on? */
 	enum gprs_ns_ll ll;
 
 	union {
@@ -231,4 +245,6 @@ static inline struct msgb *gprs_ns_msgb_alloc(void)
 	return msgb_alloc_headroom(NS_ALLOC_SIZE, NS_ALLOC_HEADROOM, "GPRS/NS");
 }
 
+/*! }@ */
+
 #endif
diff --git a/openbsc/src/libgb/gprs_ns.c b/openbsc/src/libgb/gprs_ns.c
index dab57e663..a8f97e2a2 100644
--- a/openbsc/src/libgb/gprs_ns.c
+++ b/openbsc/src/libgb/gprs_ns.c
@@ -1,4 +1,4 @@
-/* GPRS Networks Service (NS) messages on the Gb interfacebvci = msgb_bvci(msg);
+/* GPRS Networks Service (NS) messages on the Gb interface
  * 3GPP TS 08.16 version 8.0.1 Release 1999 / ETSI TS 101 299 V8.0.1 (2002-05) */
 
 /* (C) 2009-2010 by Harald Welte <laforge@gnumonks.org>
@@ -20,7 +20,17 @@
  *
  */
 
-/* Some introduction into NS:  NS is used typically on top of frame relay,
+/*! \addtogroup libgb
+ *  @{
+ */
+
+/*! \file gprs_ns.c */
+
+/*!
+ * GPRS Networks Service (NS) messages on the Gb interface
+ * 3GPP TS 08.16 version 8.0.1 Release 1999 / ETSI TS 101 299 V8.0.1 (2002-05) 
+ *
+ * Some introduction into NS:  NS is used typically on top of frame relay,
  * but in the ip.access world it is encapsulated in UDP packets.  It serves
  * as an intermediate shim betwen BSSGP and the underlying medium.  It doesn't
  * do much, apart from providing congestion notification and status indication.
@@ -106,7 +116,11 @@ static const struct rate_ctr_group_desc nsvc_ctrg_desc = {
 	.ctr_desc = nsvc_ctr_description,
 };
 
-/* Lookup struct gprs_nsvc based on NSVCI */
+/*! \brief Lookup struct gprs_nsvc based on NSVCI
+ *  \param[in] nsi NS instance in which to search
+ *  \param[in] nsvci NSVCI to be searched
+ *  \returns gprs_nsvc of respective NSVCI
+ */
 struct gprs_nsvc *nsvc_by_nsvci(struct gprs_ns_inst *nsi, uint16_t nsvci)
 {
 	struct gprs_nsvc *nsvc;
@@ -117,7 +131,11 @@ struct gprs_nsvc *nsvc_by_nsvci(struct gprs_ns_inst *nsi, uint16_t nsvci)
 	return NULL;
 }
 
-/* Lookup struct gprs_nsvc based on NSVCI */
+/*! \brief Lookup struct gprs_nsvc based on NSEI
+ *  \param[in] nsi NS instance in which to search
+ *  \param[in] nsei NSEI to be searched
+ *  \returns gprs_nsvc of respective NSEI
+ */
 struct gprs_nsvc *nsvc_by_nsei(struct gprs_ns_inst *nsi, uint16_t nsei)
 {
 	struct gprs_nsvc *nsvc;
@@ -164,6 +182,9 @@ struct gprs_nsvc *nsvc_create(struct gprs_ns_inst *nsi, uint16_t nsvci)
 	return nsvc;
 }
 
+/*! \brief Delete given NS-VC
+ *  \param[in] nsvc gprs_nsvc to be deleted
+ */
 void nsvc_delete(struct gprs_nsvc *nsvc)
 {
 	if (osmo_timer_pending(&nsvc->timer))
@@ -199,6 +220,7 @@ static const struct value_string ns_cause_str[] = {
 	{ 0, NULL }
 };
 
+/*! \brief Obtain a human-readable string for NS cause value */
 const char *gprs_ns_cause_str(enum ns_cause cause)
 {
 	return get_value_string(ns_cause_str, cause);
@@ -251,6 +273,10 @@ static int gprs_ns_tx_simple(struct gprs_nsvc *nsvc, uint8_t pdu_type)
 	return gprs_ns_tx(nsvc, msg);
 }
 
+/*! \brief Transmit a NS-RESET on a given NSVC
+ *  \param[in] nsvc NS-VC used for transmission
+ *  \paam[in] cause Numeric NS cause value
+ */
 int gprs_ns_tx_reset(struct gprs_nsvc *nsvc, uint8_t cause)
 {
 	struct msgb *msg = gprs_ns_msgb_alloc();
@@ -278,6 +304,11 @@ int gprs_ns_tx_reset(struct gprs_nsvc *nsvc, uint8_t cause)
 
 }
 
+/*! \brief Transmit a NS-STATUS on a given NSVC
+ *  \param[in] nsvc NS-VC to be used for transmission
+ *  \param[in] cause Numeric NS cause value
+ *  \param[in] bvci BVCI to be reset within NSVC
+ *  \param[in] orig_msg message causing the STATUS */
 int gprs_ns_tx_status(struct gprs_nsvc *nsvc, uint8_t cause,
 		      uint16_t bvci, struct msgb *orig_msg)
 {
@@ -327,6 +358,11 @@ int gprs_ns_tx_status(struct gprs_nsvc *nsvc, uint8_t cause,
 	return gprs_ns_tx(nsvc, msg);
 }
 
+/*! \brief Transmit a NS-BLOCK on a tiven NS-VC
+ *  \param[in] nsvc NS-VC on which the NS-BLOCK is to be transmitted
+ *  \param[in] cause Numeric NS Cause value
+ *  \returns 0 in case of success
+ */
 int gprs_ns_tx_block(struct gprs_nsvc *nsvc, uint8_t cause)
 {
 	struct msgb *msg = gprs_ns_msgb_alloc();
@@ -355,6 +391,10 @@ int gprs_ns_tx_block(struct gprs_nsvc *nsvc, uint8_t cause)
 	return gprs_ns_tx(nsvc, msg);
 }
 
+/*! \brief Transmit a NS-UNBLOCK on a given NS-VC
+ *  \param[in] nsvc NS-VC on which the NS-UNBLOCK is to be transmitted
+ *  \returns 0 in case of success
+ */
 int gprs_ns_tx_unblock(struct gprs_nsvc *nsvc)
 {
 	log_set_context(BSC_CTX_NSVC, nsvc);
@@ -364,6 +404,10 @@ int gprs_ns_tx_unblock(struct gprs_nsvc *nsvc)
 	return gprs_ns_tx_simple(nsvc, NS_PDUT_UNBLOCK);
 }
 
+/*! \brief Transmit a NS-ALIVE on a given NS-VC
+ *  \param[in] nsvc NS-VC on which the NS-ALIVE is to be transmitted
+ *  \returns 0 in case of success
+ */
 int gprs_ns_tx_alive(struct gprs_nsvc *nsvc)
 {
 	log_set_context(BSC_CTX_NSVC, nsvc);
@@ -373,6 +417,10 @@ int gprs_ns_tx_alive(struct gprs_nsvc *nsvc)
 	return gprs_ns_tx_simple(nsvc, NS_PDUT_ALIVE);
 }
 
+/*! \brief Transmit a NS-ALIVE-ACK on a given NS-VC
+ *  \param[in] nsvc NS-VC on which the NS-ALIVE-ACK is to be transmitted
+ *  \returns 0 in case of success
+ */
 int gprs_ns_tx_alive_ack(struct gprs_nsvc *nsvc)
 {
 	log_set_context(BSC_CTX_NSVC, nsvc);
@@ -493,7 +541,16 @@ static int gprs_ns_tx_reset_ack(struct gprs_nsvc *nsvc)
 	return gprs_ns_tx(nsvc, msg);
 }
 
-/* Section 9.2.10: transmit side / NS-UNITDATA-REQUEST primitive */
+/*! \brief High-level function for transmitting a NS-UNITDATA messsage
+ *  \param[in] nsi NS-instance on which we shall transmit
+ *  \param[in] msg struct msgb to be trasnmitted
+ *
+ * This function obtains the NS-VC by the msgb_nsei(msg) and then checks
+ * if the NS-VC is ALIVEV and not BLOCKED.  After that, it adds a NS
+ * header for the NS-UNITDATA message type and sends it off.
+ *
+ * Section 9.2.10: transmit side / NS-UNITDATA-REQUEST primitive 
+ */
 int gprs_ns_sendmsg(struct gprs_ns_inst *nsi, struct msgb *msg)
 {
 	struct gprs_nsvc *nsvc;
@@ -671,7 +728,16 @@ static int gprs_ns_rx_block(struct gprs_nsvc *nsvc, struct msgb *msg)
 	return gprs_ns_tx_simple(nsvc, NS_PDUT_BLOCK_ACK);
 }
 
-/* main entry point, here incoming NS frames enter */
+/*! \brief Receive incoming NS message from underlying transport layer
+ *  \param nsi NS instance to which the data belongs
+ *  \param[in] msg message buffer containing newly-received data
+ *  \param[in] saddr socketaddr from which data was received
+ *  \param[in] ll link-layer type in which data was received
+ *  \returns 0 in case of success, < 0 in case of error
+ *
+ * This is the main entry point int othe NS imlementation where frames
+ * from the underlying transport (normally UDP) enter.
+ */
 int gprs_ns_rcvmsg(struct gprs_ns_inst *nsi, struct msgb *msg,
 		   struct sockaddr_in *saddr, enum gprs_ns_ll ll)
 {
@@ -823,6 +889,10 @@ int gprs_ns_rcvmsg(struct gprs_ns_inst *nsi, struct msgb *msg,
 	return rc;
 }
 
+/*! \brief Create a new GPRS NS instance
+ *  \param[in] cb Call-back function for incoming BSSGP data
+ *  \returns dynamically allocated gprs_ns_inst
+ */
 struct gprs_ns_inst *gprs_ns_instantiate(gprs_ns_cb_t *cb)
 {
 	struct gprs_ns_inst *nsi = talloc_zero(tall_bsc_ctx, struct gprs_ns_inst);
@@ -845,6 +915,12 @@ struct gprs_ns_inst *gprs_ns_instantiate(gprs_ns_cb_t *cb)
 	return nsi;
 }
 
+/*! \brief Destroy an entire NS instance
+ *  \param nsi gprs_ns_inst that is to be destroyed
+ *
+ *  This function SHOULD release all resources associated with the
+ *  NS-instance but is actually not completely implemented!
+ */
 void gprs_ns_destroy(struct gprs_ns_inst *nsi)
 {
 	/* FIXME: clear all timers */
@@ -940,7 +1016,14 @@ static int nsip_fd_cb(struct osmo_fd *bfd, unsigned int what)
 	return rc;
 }
 
-/* Listen for incoming GPRS packets */
+/*! \brief Create a listening socket for GPRS NS/UDP/IP
+ *  \param[in] nsi NS protocol instance to listen
+ *  \returns >=0 (fd) in case of success, negative in case of error
+ *
+ *  A call to this function will create a UDP socket bound to the port
+ *  number and IP address specified in the NS protocol instance. The
+ *  file descriptor of the socket will be stored in nsi->nsip.fd.
+ */
 int gprs_ns_nsip_listen(struct gprs_ns_inst *nsi)
 {
 	int ret;
@@ -955,7 +1038,14 @@ int gprs_ns_nsip_listen(struct gprs_ns_inst *nsi)
 	return ret;
 }
 
-/* Initiate a RESET procedure */
+/*! \brief Initiate a RESET procedure
+ *  \param[in] nsvc NS-VC in which to start the procedure
+ *  \param[in] cause Numeric NS cause value
+ *
+ * This is a high-level function initiating a NS-RESET procedure. It
+ * will not only send a NS-RESET, but also set the state to BLOCKED and
+ * start the Tns-reset timer.
+ */
 void gprs_nsvc_reset(struct gprs_nsvc *nsvc, uint8_t cause)
 {
 	LOGP(DNS, LOGL_INFO, "NSEI=%u RESET procedure based on API request\n",
@@ -972,7 +1062,16 @@ void gprs_nsvc_reset(struct gprs_nsvc *nsvc, uint8_t cause)
 	nsvc_start_timer(nsvc, NSVC_TIMER_TNS_RESET);
 }
 
-/* Establish a connection (from the BSS) to the SGSN */
+/*! \brief Establish a NS connection (from the BSS) to the SGSN
+ *  \param nsi NS-instance
+ *  \param[in] dest Destination IP/Port
+ *  \param[in] nsei NSEI of the to-be-established NS-VC
+ *  \param[in] nsvci NSVCI of the to-be-established NS-VC
+ *  \returns struct gprs_nsvc representing the new NS-VC
+ *
+ * This function will establish a single NS/UDP/IP connection in uplink
+ * (BSS to SGSN) direction.
+ */
 struct gprs_nsvc *nsip_connect(struct gprs_ns_inst *nsi,
 				struct sockaddr_in *dest, uint16_t nsei,
 				uint16_t nsvci)
@@ -990,3 +1089,5 @@ struct gprs_nsvc *nsip_connect(struct gprs_ns_inst *nsi,
 	gprs_nsvc_reset(nsvc, NS_CAUSE_OM_INTERVENTION);
 	return nsvc;
 }
+
+/*! }@ */