diff options
| -rw-r--r-- | include/osmocom/gsm/lapdm.h | 138 | ||||
| -rw-r--r-- | src/gsm/lapdm.c | 42 |
2 files changed, 116 insertions, 64 deletions
diff --git a/include/osmocom/gsm/lapdm.h b/include/osmocom/gsm/lapdm.h index 2e78aeee..b71feef1 100644 --- a/include/osmocom/gsm/lapdm.h +++ b/include/osmocom/gsm/lapdm.h @@ -7,57 +7,68 @@ #include <osmocom/core/msgb.h> #include <osmocom/gsm/prim.h> +/*! \defgroup lapdm LAPDm implementation according to GSM TS 04.06 + * @{ + */ + +/*! \file lapdm.h */ + /* primitive related sutff */ +/*! \brief LAPDm related primitives */ enum osmo_ph_prim { - PRIM_PH_DATA, /* PH-DATA */ - PRIM_PH_RACH, /* PH-RANDOM_ACCESS */ - PRIM_PH_CONN, /* PH-CONNECT */ - PRIM_PH_EMPTY_FRAME, /* PH-EMPTY_FRAME */ - PRIM_PH_RTS, /* PH-RTS */ + PRIM_PH_DATA, /*!< \brief PH-DATA */ + PRIM_PH_RACH, /*!< \brief PH-RANDOM_ACCESS */ + PRIM_PH_CONN, /*!< \brief PH-CONNECT */ + PRIM_PH_EMPTY_FRAME, /*!< \brief PH-EMPTY_FRAME */ + PRIM_PH_RTS, /*!< \brief PH-RTS */ }; -/* for PH-RANDOM_ACCESS.req */ +/*! \brief for PH-RANDOM_ACCESS.req */ struct ph_rach_req_param { - uint8_t ra; - uint8_t ta; - uint8_t tx_power; - uint8_t is_combined_ccch; - uint16_t offset; + uint8_t ra; /*!< \brief Random Access */ + uint8_t ta; /*!< \brief Timing Advance */ + uint8_t tx_power; /*!< \brief Transmit Power */ + uint8_t is_combined_ccch;/*!< \brief Are we using a combined CCCH? */ + uint16_t offset; /*!< \brief Timing Offset */ }; -/* for PH-RANDOM_ACCESS.ind */ +/*! \brief for PH-RANDOM_ACCESS.ind */ struct ph_rach_ind_param { - uint8_t ra; - uint8_t acc_delay; - uint32_t fn; + uint8_t ra; /*!< \brief Random Access */ + uint8_t acc_delay; /*!< \brief Delay in bit periods */ + uint32_t fn; /*!< \brief GSM Frame Number at time of RA */ }; -/* for PH-[UNIT]DATA.{req,ind} */ +/*! \brief for PH-[UNIT]DATA.{req,ind} */ struct ph_data_param { - uint8_t link_id; - uint8_t chan_nr; + uint8_t link_id; /*!< \brief Link Identifier (Like RSL) */ + uint8_t chan_nr; /*!< \brief Channel Number (Like RSL) */ }; +/*! \brief for PH-CONN.ind */ struct ph_conn_ind_param { - uint32_t fn; + uint32_t fn; /*!< \brief GSM Frame Number */ }; +/*! \brief primitive header for LAPDm PH-SAP primitives */ struct osmo_phsap_prim { - struct osmo_prim_hdr oph; + struct osmo_prim_hdr oph; /*!< \brief generic primitive header */ union { struct ph_data_param data; struct ph_rach_req_param rach_req; struct ph_rach_ind_param rach_ind; struct ph_conn_ind_param conn_ind; - } u; + } u; /*!< \brief request-specific data */ }; +/*! \brief LAPDm mode/role */ enum lapdm_mode { - LAPDM_MODE_MS, - LAPDM_MODE_BTS, + LAPDM_MODE_MS, /*!< \brief behave like a MS (mobile phone) */ + LAPDM_MODE_BTS, /*!< \brief behave like a BTS (network) */ }; +/*! \brief LAPDm state */ enum lapdm_state { LAPDm_STATE_NULL = 0, LAPDm_STATE_IDLE, @@ -69,6 +80,7 @@ enum lapdm_state { struct lapdm_entity; +/*! \brief LAPDm message context */ struct lapdm_msg_ctx { struct lapdm_datalink *dl; int lapdm_fmt; @@ -81,33 +93,35 @@ struct lapdm_msg_ctx { uint8_t tx_power_ind; }; -/* TS 04.06 / Section 3.5.2 */ +/*! \brief LAPDm datalink like TS 04.06 / Section 3.5.2 */ struct lapdm_datalink { - uint8_t V_send; /* seq nr of next I frame to be transmitted */ - uint8_t V_ack; /* last frame ACKed by peer */ - uint8_t N_send; /* ? set to V_send at Tx time*/ - uint8_t V_recv; /* seq nr of next I frame expected to be received */ - uint8_t N_recv; /* expected send seq nr of the next received I frame */ - uint32_t state; - int seq_err_cond; /* condition of sequence error */ - uint8_t own_busy, peer_busy; - struct osmo_timer_list t200; - uint8_t retrans_ctr; - struct llist_head send_queue; /* frames from L3 */ - struct msgb *send_buffer; /* current frame transmitting */ - int send_out; /* how much was sent from send_buffer */ - uint8_t tx_hist[8][200]; /* tx history buffer */ - int tx_length[8]; /* length in history buffer */ - struct llist_head tx_queue; /* frames to L1 */ - struct lapdm_msg_ctx mctx; /* context of established connection */ - struct msgb *rcv_buffer; /* buffer to assemble the received message */ - - struct lapdm_entity *entity; + uint8_t V_send; /*!< \brief seq nr of next I frame to be transmitted */ + uint8_t V_ack; /*!< \brief last frame ACKed by peer */ + uint8_t N_send; /*!< \brief ? set to V_send at Tx time*/ + uint8_t V_recv; /*!< \brief seq nr of next I frame expected to be received */ + uint8_t N_recv; /*!< \brief expected send seq nr of the next received I frame */ + uint32_t state; /*!< \brief LAPDm state (\ref lapdm_state) */ + int seq_err_cond; /*!< \brief condition of sequence error */ + uint8_t own_busy; /*!< \brief receiver busy on our side */ + uint8_t peer_busy; /*!< \brief receiver busy on remote side */ + struct osmo_timer_list t200; /*!< \brief T200 timer */ + uint8_t retrans_ctr; /*!< \brief re-transmission counter */ + struct llist_head send_queue; /*!< \brief frames from L3 */ + struct msgb *send_buffer; /*!< \brief current frame transmitting */ + int send_out; /*!< \brief how much was sent from send_buffer */ + uint8_t tx_hist[8][200]; /*!< \brief tx history buffer */ + int tx_length[8]; /*!< \brief length in history buffer */ + struct llist_head tx_queue; /*!< \brief frames to L1 */ + struct lapdm_msg_ctx mctx; /*!< \brief context of established connection */ + struct msgb *rcv_buffer; /*!< \brief buffer to assemble the received message */ + + struct lapdm_entity *entity; /*!< \brief LAPDm entity we are part of */ }; +/*! \brief LAPDm datalink SAPIs */ enum lapdm_dl_sapi { - DL_SAPI0 = 0, - DL_SAPI3 = 1, + DL_SAPI0 = 0, /*!< \brief SAPI 0 */ + DL_SAPI3 = 1, /*!< \brief SAPI 1 */ _NR_DL_SAPI }; @@ -121,35 +135,37 @@ struct lapdm_cr_ent { #define LAPDM_ENT_F_EMPTY_FRAME 0x0001 #define LAPDM_ENT_F_POLLING_ONLY 0x0002 -/* register message handler for messages that are sent from L2->L3 */ +/*! \brief a LAPDm Entity */ struct lapdm_entity { + /*! \brief the SAPIs of the LAPDm entity */ struct lapdm_datalink datalink[_NR_DL_SAPI]; - int last_tx_dequeue; /* last entity that was dequeued */ - int tx_pending; /* currently a pending frame not confirmed by L1 */ - enum lapdm_mode mode; /* are we in BTS mode or MS mode */ + int last_tx_dequeue; /*!< \brief last entity that was dequeued */ + int tx_pending; /*!< \brief currently a pending frame not confirmed by L1 */ + enum lapdm_mode mode; /*!< \brief are we in BTS mode or MS mode */ unsigned int flags; struct { - /* filled-in once we set the lapdm_mode above */ + /*! \brief filled-in once we set the lapdm_mode above */ struct lapdm_cr_ent loc2rem; struct lapdm_cr_ent rem2loc; } cr; - void *l1_ctx; /* context for layer1 instance */ - void *l3_ctx; /* context for layer3 instance */ + void *l1_ctx; /*!< \brief context for layer1 instance */ + void *l3_ctx; /*!< \brief context for layer3 instance */ - osmo_prim_cb l1_prim_cb; - lapdm_cb_t l3_cb; /* callback for sending stuff to L3 */ + osmo_prim_cb l1_prim_cb;/*!< \brief callback for sending prims to L1 */ + lapdm_cb_t l3_cb; /*!< \brief callback for sending stuff to L3 */ + /*! \brief pointer to \ref lapdm_channel of which we're part */ struct lapdm_channel *lapdm_ch; }; -/* the two lapdm_entities that form a GSM logical channel (ACCH + DCCH) */ +/*! \brief the two lapdm_entities that form a GSM logical channel (ACCH + DCCH) */ struct lapdm_channel { - struct llist_head list; - char *name; - struct lapdm_entity lapdm_acch; - struct lapdm_entity lapdm_dcch; + struct llist_head list; /*!< \brief internal linked list */ + char *name; /*!< \brief human-readable name */ + struct lapdm_entity lapdm_acch; /*!< \brief Associated Control Channel */ + struct lapdm_entity lapdm_dcch; /*!< \brief Dedicated Control Channel */ }; const char *get_rsl_name(int value); @@ -183,4 +199,6 @@ void lapdm_channel_set_flags(struct lapdm_channel *lc, unsigned int flags); int lapdm_phsap_dequeue_prim(struct lapdm_entity *le, struct osmo_phsap_prim *pp); +/*! }@ */ + #endif /* _OSMOCOM_LAPDM_H */ diff --git a/src/gsm/lapdm.c b/src/gsm/lapdm.c index 470a5b2a..f99c1193 100644 --- a/src/gsm/lapdm.c +++ b/src/gsm/lapdm.c @@ -21,7 +21,14 @@ * */ -/* Notes on Buffering: rcv_buffer, tx_queue, tx_hist, send_buffer, send_queue +/*! \addtogroup lapdm + * @{ + */ + +/*! \file lapdm.c */ + +/*! + * Notes on Buffering: rcv_buffer, tx_queue, tx_hist, send_buffer, send_queue * * RX data is stored in the rcv_buffer (pointer). If the message is complete, it * is removed from rcv_buffer pointer and forwarded to L3. If the RX data is @@ -184,6 +191,10 @@ static void lapdm_dl_init(struct lapdm_datalink *dl, dl->entity = entity; } +/*! \brief initialize a LAPDm entity and all datalinks inside + * \param[in] le LAPDm entity + * \param[in] mode \ref lapdm_mode (BTS/MS) + */ void lapdm_entity_init(struct lapdm_entity *le, enum lapdm_mode mode) { unsigned int i; @@ -194,13 +205,19 @@ void lapdm_entity_init(struct lapdm_entity *le, enum lapdm_mode mode) lapdm_entity_set_mode(le, mode); } +/*! \brief initialize a LAPDm channel and all its channels + * \param[in] lc \ref lapdm_channel to be initialized + * \param[in] mode \ref lapdm_mode (BTS/MS) + * + * This really is a convenience wrapper around calling \ref + * lapdm_entity_init twice. + */ void lapdm_channel_init(struct lapdm_channel *lc, enum lapdm_mode mode) { lapdm_entity_init(&lc->lapdm_acch, mode); lapdm_entity_init(&lc->lapdm_dcch, mode); } - static void lapdm_dl_flush_send(struct lapdm_datalink *dl) { struct msgb *msg; @@ -227,6 +244,7 @@ static void lapdm_dl_flush_tx(struct lapdm_datalink *dl) dl->tx_length[i] = 0; } +/*! \brief flush and release all resoures in LAPDm entity */ void lapdm_entity_exit(struct lapdm_entity *le) { unsigned int i; @@ -241,6 +259,11 @@ void lapdm_entity_exit(struct lapdm_entity *le) } } +/* \brief lfush and release all resources in LAPDm channel + * + * A convenience wrapper calling \ref lapdm_entity_exit on both + * entities inside the \ref lapdm_channel + */ void lapdm_channel_exit(struct lapdm_channel *lc) { lapdm_entity_exit(&lc->lapdm_acch); @@ -355,7 +378,7 @@ static struct msgb *tx_dequeue_msgb(struct lapdm_entity *le) return msg; } -/* dequeue a msg that's pending transmission via L1 and wrap it into +/*! \brief dequeue a msg that's pending transmission via L1 and wrap it into * a osmo_phsap_prim */ int lapdm_phsap_dequeue_prim(struct lapdm_entity *le, struct osmo_phsap_prim *pp) { @@ -1702,6 +1725,7 @@ static int l2_ph_rach_ind(struct lapdm_entity *le, uint8_t ra, uint32_t fn, uint static int l2_ph_chan_conf(struct msgb *msg, struct lapdm_entity *le, uint32_t frame_nr); +/*! \brief Receive a PH-SAP primitive from L1 */ int lapdm_phsap_up(struct osmo_prim_hdr *oph, struct lapdm_entity *le) { struct osmo_phsap_prim *pp = (struct osmo_phsap_prim *) oph; @@ -2411,7 +2435,7 @@ static int rslms_rx_com_chan(struct msgb *msg, struct lapdm_channel *lc) return rc; } -/* input into layer2 (from layer 3) */ +/*! \brief Receive a RSLms \ref msgb from Layer 3 */ int lapdm_rslms_recvmsg(struct msgb *msg, struct lapdm_channel *lc) { struct abis_rsl_common_hdr *rslh = msgb_l2(msg); @@ -2439,6 +2463,7 @@ int lapdm_rslms_recvmsg(struct msgb *msg, struct lapdm_channel *lc) return rc; } +/*! \brief Set the \ref lapdm_mode of a LAPDm entity */ int lapdm_entity_set_mode(struct lapdm_entity *le, enum lapdm_mode mode) { switch (mode) { @@ -2463,6 +2488,7 @@ int lapdm_entity_set_mode(struct lapdm_entity *le, enum lapdm_mode mode) return 0; } +/*! \brief Set the \ref lapdm_mode of a LAPDm channel*/ int lapdm_channel_set_mode(struct lapdm_channel *lc, enum lapdm_mode mode) { int rc; @@ -2474,6 +2500,7 @@ int lapdm_channel_set_mode(struct lapdm_channel *lc, enum lapdm_mode mode) return lapdm_entity_set_mode(&lc->lapdm_acch, mode); } +/*! \brief Set the L1 callback and context of a LAPDm channel */ void lapdm_channel_set_l1(struct lapdm_channel *lc, osmo_prim_cb cb, void *ctx) { lc->lapdm_dcch.l1_prim_cb = cb; @@ -2482,6 +2509,7 @@ void lapdm_channel_set_l1(struct lapdm_channel *lc, osmo_prim_cb cb, void *ctx) lc->lapdm_acch.l1_ctx = ctx; } +/*! \brief Set the L3 callback and context of a LAPDm channel */ void lapdm_channel_set_l3(struct lapdm_channel *lc, lapdm_cb_t cb, void *ctx) { lc->lapdm_dcch.l3_cb = cb; @@ -2490,6 +2518,7 @@ void lapdm_channel_set_l3(struct lapdm_channel *lc, lapdm_cb_t cb, void *ctx) lc->lapdm_acch.l3_ctx = ctx; } +/*! \brief Reset an entire LAPDm entity and all its datalinks */ void lapdm_entity_reset(struct lapdm_entity *le) { struct lapdm_datalink *dl; @@ -2510,19 +2539,24 @@ void lapdm_entity_reset(struct lapdm_entity *le) } } +/*! \brief Reset a LAPDm channel with all its entities */ void lapdm_channel_reset(struct lapdm_channel *lc) { lapdm_entity_reset(&lc->lapdm_dcch); lapdm_entity_reset(&lc->lapdm_acch); } +/*! \brief Set the flags of a LAPDm entity */ void lapdm_entity_set_flags(struct lapdm_entity *le, unsigned int flags) { le->flags = flags; } +/*! \brief Set the flags of all LAPDm entities in a LAPDm channel */ void lapdm_channel_set_flags(struct lapdm_channel *lc, unsigned int flags) { lapdm_entity_set_flags(&lc->lapdm_dcch, flags); lapdm_entity_set_flags(&lc->lapdm_acch, flags); } + +/*! }@ */ |