libosmocore 1.13.1.1-afb4 Osmocom core library

Files | Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
Seriall Communications (HDLC)

Serial communications layer, based on HDLC. More...

## Files
file | sercomm.h
| Osmocom Sercomm HDLC (de)multiplex.
file | sercomm.c

## Data Structures
struct | osmo_sercomm_inst
| one instance of a sercomm multiplex/demultiplex More...

## Macros
#define | DEFAULT_RX_MSG_SIZE 2048
#define | HDLC_FLAG 0x7E
#define | HDLC_ESCAPE 0x7D
#define | HDLC_C_UI 0x03
#define | HDLC_C_P_BIT (1 << 4)
#define | HDLC_C_F_BIT (1 << 4)

## Typedefs
typedef void(* | dlci_cb_t) (struct osmo_sercomm_inst *sercomm, uint8_t dlci, struct msgb *msg)
| call-back function for per-DLC receive handler More...

## Enumerations
enum | sercomm_dlci { SC_DLCI_HIGHEST = 0 , SC_DLCI_DEBUG = 4 , SC_DLCI_L1A_L23 = 5 , SC_DLCI_LOADER = 9 , SC_DLCI_CONSOLE = 10 , SC_DLCI_ECHO = 128 , _SC_DLCI_MAX }
| A low sercomm_dlci means high priority. More...
enum | rx_state { RX_ST_WAIT_START , RX_ST_ADDR , RX_ST_CTRL , RX_ST_DATA , RX_ST_ESCAPE }

## Functions
void | osmo_sercomm_init (struct osmo_sercomm_inst *sercomm)
| Initialize an Osmocom sercomm instance. More...
int | osmo_sercomm_initialized (struct osmo_sercomm_inst *sercomm)
| Determine if a given Osmocom sercomm instance has been initialized. More...
void | osmo_sercomm_sendmsg (struct osmo_sercomm_inst *sercomm, uint8_t dlci, struct msgb *msg)
| User interface for transmitting messages for a given DLCI. More...
unsigned int | osmo_sercomm_tx_queue_depth (struct osmo_sercomm_inst *sercomm, uint8_t dlci)
| How deep is the Tx queue for a given DLCI? More...
int | osmo_sercomm_register_rx_cb (struct osmo_sercomm_inst *sercomm, uint8_t dlci, dlci_cb_t cb)
| Register a handler for a given DLCI. More...
int | osmo_sercomm_change_speed (struct osmo_sercomm_inst *sercomm, uint32_t bdrt)
| wait until everything has been transmitted, then grab the lock and change the baud rate as requested More...
int | osmo_sercomm_drv_pull (struct osmo_sercomm_inst *sercomm, uint8_t *ch)
| fetch one octet of to-be-transmitted serial data More...
int | osmo_sercomm_drv_rx_char (struct osmo_sercomm_inst *sercomm, uint8_t ch)
| the driver has received one byte, pass it into sercomm layer More...
void | sercomm_drv_lock (unsigned long *flags)
void | sercomm_drv_unlock (unsigned long *flags)
void | sercomm_drv_start_tx (struct osmo_sercomm_inst *sercomm)
| low-level driver routine to request start of transmission The Sercomm code calls this function to inform the low-level driver that some data is pending for transmission, and the low-level driver should (if not active already) start enabling tx_empty interrupts and pull drivers out of sercomm using osmo_sercomm_drv_pull() until the latter returns 0. More...
int | sercomm_drv_baudrate_chg (struct osmo_sercomm_inst *sercomm, uint32_t bdrt)
| low-level driver routine to execute baud-rate change More...
static struct msgb * | osmo_sercomm_alloc_msgb (unsigned int len)
| Sercomm msgb allocator function. More...
void | sercomm_drv_lock (unsigned long __attribute__((unused)) *flags)
| Protect against IRQ context. More...
void | sercomm_drv_unlock (unsigned long __attribute__((unused)) *flags)
| Release protection against IRQ context. More...
| __attribute__ ((weak))
static void | dispatch_rx_msg (struct osmo_sercomm_inst *sercomm, uint8_t dlci, struct msgb *msg)

## Variables
enum gsm0808_assignment_requirement | __attribute__
| fls64 - find last set bit in a 64-bit word @x: the word to search More...

## Detailed Description

Serial communications layer, based on HDLC.

## Macro Definition Documentation

## ◆ DEFAULT_RX_MSG_SIZE

#define DEFAULT_RX_MSG_SIZE 2048

## ◆ HDLC_C_F_BIT

#define HDLC_C_F_BIT (1 << 4)

## ◆ HDLC_C_P_BIT

#define HDLC_C_P_BIT (1 << 4)

## ◆ HDLC_C_UI

#define HDLC_C_UI 0x03

## ◆ HDLC_ESCAPE

#define HDLC_ESCAPE 0x7D

## ◆ HDLC_FLAG

#define HDLC_FLAG 0x7E

## Typedef Documentation

## ◆ dlci_cb_t

typedef void(* dlci_cb_t) (struct osmo_sercomm_inst *sercomm, uint8_t dlci, struct msgb *msg)

call-back function for per-DLC receive handler

Parameters

  [in] | sercomm | instance on which msg was received
  [in] | dlci | DLC Identifier of received msg
  [in] | msg | received message that needs to be processed

## Enumeration Type Documentation

## ◆ rx_state

enum rx_state

Enumerator
RX_ST_WAIT_START |
RX_ST_ADDR |
RX_ST_CTRL |
RX_ST_DATA |
RX_ST_ESCAPE |

## ◆ sercomm_dlci

enum sercomm_dlci

A low sercomm_dlci means high priority.

A high DLCI means low priority

Enumerator
SC_DLCI_HIGHEST |
SC_DLCI_DEBUG |
SC_DLCI_L1A_L23 |
SC_DLCI_LOADER |
SC_DLCI_CONSOLE |
SC_DLCI_ECHO |
_SC_DLCI_MAX |

## Function Documentation

## ◆ __attribute__()

__attribute__ | ( | (weak) |  | ) |

## ◆ dispatch_rx_msg()

static void dispatch_rx_msg | ( | struct osmo_sercomm_inst * | sercomm,
|  | uint8_t | dlci,
|  | struct msgb * | msg
| ) |  |
| static

References ARRAY_SIZE, osmo_sercomm_inst::dlci_handler, msg, msgb_free(), and osmo_sercomm_inst::rx.

Referenced by osmo_sercomm_drv_rx_char().

## ◆ osmo_sercomm_alloc_msgb()

static struct msgb * osmo_sercomm_alloc_msgb | ( | unsigned int | len | ) |
| inline static

Sercomm msgb allocator function.

References len(), and msgb_alloc_headroom().

Referenced by osmo_sercomm_drv_rx_char().

## ◆ osmo_sercomm_change_speed()

int osmo_sercomm_change_speed | ( | struct osmo_sercomm_inst * | sercomm,
|  | uint32_t | bdrt
| ) |  |

wait until everything has been transmitted, then grab the lock and change the baud rate as requested

Parameters

  [in] | sercomm | Osmocom sercomm instance
  [in] | bdrt | New UART Baud Rate

Returns
  result of the operation as provided by sercomm_drv_baudrate_chg()

References ARRAY_SIZE, osmo_sercomm_inst::dlci_queues, flags, osmo_sercomm_inst::msg, osmo_sercomm_inst::next_char, osmo_sercomm_tx_queue_depth(), sercomm_drv_baudrate_chg(), sercomm_drv_lock(), sercomm_drv_unlock(), and osmo_sercomm_inst::tx.

## ◆ osmo_sercomm_drv_pull()

int osmo_sercomm_drv_pull | ( | struct osmo_sercomm_inst * | sercomm,
|  | uint8_t * | ch
| ) |  |

fetch one octet of to-be-transmitted serial data

Parameters

  [in] | sercomm | Sercomm Instance from which to fetch pending data
  [out] | ch | pointer to caller-allocaed output memory

Returns
  1 in case of succss; 0 if no data available; negative on error

References ARRAY_SIZE, msgb::data, osmo_sercomm_inst::dlci_queues, flags, HDLC_ESCAPE, HDLC_FLAG, osmo_sercomm_inst::msg, msgb_dequeue(), msgb_free(), osmo_sercomm_inst::next_char, RX_ST_DATA, RX_ST_ESCAPE, sercomm_drv_lock(), sercomm_drv_unlock(), osmo_sercomm_inst::state, msgb::tail, and osmo_sercomm_inst::tx.

## ◆ osmo_sercomm_drv_rx_char()

int osmo_sercomm_drv_rx_char | ( | struct osmo_sercomm_inst * | sercomm,
|  | uint8_t | ch
| ) |  |

the driver has received one byte, pass it into sercomm layer

Parameters

  [in] | sercomm | Sercomm Instance for which a byte was received
  [in] | ch | byte that was received from line for said instance

Returns
  1 on success; 0 on unrecognized char; negative on error

References osmo_sercomm_inst::ctrl, dispatch_rx_msg(), osmo_sercomm_inst::dlci, HDLC_ESCAPE, HDLC_FLAG, osmo_sercomm_inst::msg, osmo_sercomm_inst::msg_size, msgb_free(), msgb_put(), msgb_tailroom(), osmo_sercomm_alloc_msgb(), osmo_sercomm_inst::rx, RX_ST_ADDR, RX_ST_CTRL, RX_ST_DATA, RX_ST_ESCAPE, RX_ST_WAIT_START, and osmo_sercomm_inst::state.

## ◆ osmo_sercomm_init()

void osmo_sercomm_init | ( | struct osmo_sercomm_inst * | sercomm | ) |

Initialize an Osmocom sercomm instance.

Parameters

  sercomm | Caller-allocated sercomm instance to be initialized

This function initializes the sercomm instance, including the registration of the ECHO service at the ECHO DLCI

References ARRAY_SIZE, DEFAULT_RX_MSG_SIZE, osmo_sercomm_inst::dlci_queues, INIT_LLIST_HEAD, osmo_sercomm_inst::initialized, osmo_sercomm_inst::msg, osmo_sercomm_inst::msg_size, osmo_sercomm_register_rx_cb(), osmo_sercomm_sendmsg(), osmo_sercomm_inst::rx, SC_DLCI_ECHO, and osmo_sercomm_inst::tx.

## ◆ osmo_sercomm_initialized()

int osmo_sercomm_initialized | ( | struct osmo_sercomm_inst * | sercomm | ) |

Determine if a given Osmocom sercomm instance has been initialized.

Parameters

  [in] | sercomm | Osmocom sercomm instance to be checked

Returns
  1 in case sercomm was previously initialized; 0 otherwise

References osmo_sercomm_inst::initialized.

## ◆ osmo_sercomm_register_rx_cb()

int osmo_sercomm_register_rx_cb | ( | struct osmo_sercomm_inst * | sercomm,
|  | uint8_t | dlci,
|  | dlci_cb_t | cb
| ) |  |

Register a handler for a given DLCI.

Parameters

  | sercomm | Sercomm Instance in which caller wishes to register
  [in] | dlci | Data Ling Connection Identifier to register
  [in] | cb | Callback function for dlci

Returns
  0 on success; negative on error

References ARRAY_SIZE, osmo_sercomm_inst::dlci_handler, and osmo_sercomm_inst::rx.

Referenced by osmo_sercomm_init().

## ◆ osmo_sercomm_sendmsg()

void osmo_sercomm_sendmsg | ( | struct osmo_sercomm_inst * | sercomm,
|  | uint8_t | dlci,
|  | struct msgb * | msg
| ) |  |

User interface for transmitting messages for a given DLCI.

Parameters

  [in] | sercomm | Osmocom sercomm instance through which to transmit
  [in] | dlci | DLCI through whcih to transmit msg
  [in] | msg | Message buffer to be transmitted via dlci on * sercomm

References osmo_sercomm_inst::dlci_queues, flags, HDLC_C_UI, hdr, msg, msgb_enqueue(), msgb_push(), sercomm_drv_lock(), sercomm_drv_start_tx(), sercomm_drv_unlock(), and osmo_sercomm_inst::tx.

Referenced by osmo_sercomm_init().

## ◆ osmo_sercomm_tx_queue_depth()

unsigned int osmo_sercomm_tx_queue_depth | ( | struct osmo_sercomm_inst * | sercomm,
|  | uint8_t | dlci
| ) |  |

How deep is the Tx queue for a given DLCI?

Parameters

  | [n] | sercomm Osmocom sercomm instance on which to operate
  [in] | dlci | DLCI whose queue depthy is to be determined

Returns
  number of elements in the per-DLCI transmit queue

References osmo_sercomm_inst::dlci_queues, llist_for_each, and osmo_sercomm_inst::tx.

Referenced by osmo_sercomm_change_speed().

## ◆ sercomm_drv_baudrate_chg()

int sercomm_drv_baudrate_chg | ( | struct osmo_sercomm_inst * | sercomm,
|  | uint32_t | bdrt
| ) |  |

low-level driver routine to execute baud-rate change

Parameters

  [in] | sercomm | Osmocom sercomm instance for which to change
  [in] | bdrt | New Baud-Rate (integer)

Returns
  0 on success; negative in case of error

Referenced by osmo_sercomm_change_speed().

## ◆ sercomm_drv_lock() [1/2]

void sercomm_drv_lock | ( | unsigned long * | flags | ) |

## ◆ sercomm_drv_lock() [2/2]

void sercomm_drv_lock | ( | unsigned long __attribute__((unused)) * | flags | ) |

Protect against IRQ context.

Referenced by osmo_sercomm_change_speed(), osmo_sercomm_drv_pull(), and osmo_sercomm_sendmsg().

## ◆ sercomm_drv_start_tx()

void sercomm_drv_start_tx | ( | struct osmo_sercomm_inst * | sercomm | ) |

low-level driver routine to request start of transmission The Sercomm code calls this function to inform the low-level driver that some data is pending for transmission, and the low-level driver should (if not active already) start enabling tx_empty interrupts and pull drivers out of sercomm using osmo_sercomm_drv_pull() until the latter returns 0.

Parameters

  [in] | sercomm | Osmocom sercomm instance for which to change

Referenced by osmo_sercomm_sendmsg().

## ◆ sercomm_drv_unlock() [1/2]

void sercomm_drv_unlock | ( | unsigned long * | flags | ) |

## ◆ sercomm_drv_unlock() [2/2]

void sercomm_drv_unlock | ( | unsigned long __attribute__((unused)) * | flags | ) |

Release protection against IRQ context.

Referenced by osmo_sercomm_change_speed(), osmo_sercomm_drv_pull(), and osmo_sercomm_sendmsg().