diff options
Diffstat (limited to 'include/osmocom')
| -rw-r--r-- | include/osmocom/gsm/lapdm.h | 138 |
1 files changed, 78 insertions, 60 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 */ |