GPRS NS: Add some doxygen API documentation
diff --git a/openbsc/src/libgb/gprs_ns.c b/openbsc/src/libgb/gprs_ns.c
index dab57e6..a8f97e2 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 @@
.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 @@
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 @@
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 @@
{ 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 @@
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 @@
}
+/*! \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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
gprs_nsvc_reset(nsvc, NS_CAUSE_OM_INTERVENTION);
return nsvc;
}
+
+/*! }@ */