GPRS NS: Add some doxygen API documentation
diff --git a/openbsc/include/openbsc/gprs_ns.h b/openbsc/include/openbsc/gprs_ns.h
index e26337a..f0ec26e 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 @@
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 @@
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 @@
#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 @@
_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 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 @@
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 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;
}
+
+/*! }@ */