From 914660d6f65e7a5f90cdebc31b173ba8bc0f0483 Mon Sep 17 00:00:00 2001 From: Harald Welte Date: Wed, 23 Nov 2011 15:01:31 +0100 Subject: GPRS NS: Add some doxygen API documentation --- openbsc/include/openbsc/gprs_ns.h | 50 ++++++++++------ openbsc/src/libgb/gprs_ns.c | 119 +++++++++++++++++++++++++++++++++++--- 2 files changed, 143 insertions(+), 26 deletions(-) (limited to 'openbsc') 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 @@ -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; } + +/*! }@ */ -- cgit v1.2.3