spandsp 0.0.6

hdlc.h File Reference

Go to the source code of this file.

## Classes
struct | hdlc_rx_stats_t

## Macros
#define | HDLC_MAXFRAME_LEN 400

## Typedefs
typedef void(* | hdlc_frame_handler_t) (void *user_data, const uint8_t *pkt, int len, int ok)
typedef void(* | hdlc_underflow_handler_t) (void *user_data)
typedef struct hdlc_rx_state_s | hdlc_rx_state_t
typedef struct hdlc_tx_state_s | hdlc_tx_state_t

## Functions
hdlc_rx_state_t * | hdlc_rx_init (hdlc_rx_state_t *s, int crc32, int report_bad_frames, int framing_ok_threshold, hdlc_frame_handler_t handler, void *user_data)
| Initialise an HDLC receiver context.
int | hdlc_rx_restart (hdlc_rx_state_t *s)
| Re-initialise an HDLC receiver context.
void | hdlc_rx_set_frame_handler (hdlc_rx_state_t *s, hdlc_frame_handler_t handler, void *user_data)
| Change the put_bit function associated with an HDLC receiver context.
void | hdlc_rx_set_status_handler (hdlc_rx_state_t *s, modem_status_func_t handler, void *user_data)
| Change the status report function associated with an HDLC receiver context.
int | hdlc_rx_release (hdlc_rx_state_t *s)
| Release an HDLC receiver context.
int | hdlc_rx_free (hdlc_rx_state_t *s)
| Free an HDLC receiver context.
void | hdlc_rx_set_max_frame_len (hdlc_rx_state_t *s, size_t max_len)
| Set the maximum frame length for an HDLC receiver context.
void | hdlc_rx_set_octet_counting_report_interval (hdlc_rx_state_t *s, int interval)
| Set the octet counting report interval.
int | hdlc_rx_get_stats (hdlc_rx_state_t *s, hdlc_rx_stats_t *t)
| Get the current receive statistics.
| SPAN_DECLARE_NONSTD (void) hdlc_rx_put_bit(hdlc_rx_state_t *s
| Put a single bit of data to an HDLC receiver.
hdlc_tx_state_t * | hdlc_tx_init (hdlc_tx_state_t *s, int crc32, int inter_frame_flags, int progressive, hdlc_underflow_handler_t handler, void *user_data)
| Initialise an HDLC transmitter context.
int | hdlc_tx_restart (hdlc_tx_state_t *s)
| Re-initialise an HDLC transmitter context.
int | hdlc_tx_release (hdlc_tx_state_t *s)
| Release an HDLC transmitter context.
int | hdlc_tx_free (hdlc_tx_state_t *s)
| Free an HDLC transmitter context.
void | hdlc_tx_set_max_frame_len (hdlc_tx_state_t *s, size_t max_len)
| Set the maximum frame length for an HDLC transmitter context.
int | hdlc_tx_frame (hdlc_tx_state_t *s, const uint8_t *frame, size_t len)
| Transmit a frame.
int | hdlc_tx_corrupt_frame (hdlc_tx_state_t *s)
| Corrupt the frame currently being transmitted, by giving it the wrong CRC.
int | hdlc_tx_flags (hdlc_tx_state_t *s, int len)
| Transmit a specified quantity of flag octets, typically as a preamble.
int | hdlc_tx_abort (hdlc_tx_state_t *s)
| Send an abort.
| SPAN_DECLARE_NONSTD (int) hdlc_tx_get_bit(hdlc_tx_state_t *s)
| Get the next bit for transmission.

## Variables
int | new_bit
int | new_byte
const uint8_t | buf []
const uint8_t int | len
uint8_t size_t | max_len

## Macro Definition Documentation

## ◆ HDLC_MAXFRAME_LEN

#define HDLC_MAXFRAME_LEN 400

HDLC_MAXFRAME_LEN is the maximum length of a stuffed HDLC frame, excluding the CRC.

Referenced by hdlc_tx_corrupt_frame(), hdlc_tx_frame(), hdlc_tx_init(), and hdlc_tx_set_max_frame_len().

## Typedef Documentation

## ◆ hdlc_rx_state_t

typedef struct hdlc_rx_state_s hdlc_rx_state_t

HDLC receive descriptor. This contains all the state information for an HDLC receiver.

## ◆ hdlc_tx_state_t

typedef struct hdlc_tx_state_s hdlc_tx_state_t

HDLC transmit descriptor. This contains all the state information for an HDLC transmitter.

## Function Documentation

## ◆ hdlc_rx_free()

int hdlc_rx_free | ( | hdlc_rx_state_t * | s | ) |

Free an HDLC receiver context.

Free an HDLC receiver context.

Parameters

  s | A pointer to an HDLC receiver context.

Returns
  0 for OK

## ◆ hdlc_rx_get_stats()

int hdlc_rx_get_stats | ( | hdlc_rx_state_t * | s,
|  | hdlc_rx_stats_t * | t )

Get the current receive statistics.

Parameters

  s | A pointer to an HDLC receiver context.
  t | A pointer to the buffer for the statistics.

Returns
  0 for OK, else -1.

References hdlc_rx_stats_t::aborts, hdlc_rx_stats_t::bytes, hdlc_rx_stats_t::crc_errors, hdlc_rx_stats_t::good_frames, hdlc_rx_stats_t::length_errors, hdlc_rx_state_s::rx_aborts, hdlc_rx_state_s::rx_bytes, hdlc_rx_state_s::rx_crc_errors, hdlc_rx_state_s::rx_frames, and hdlc_rx_state_s::rx_length_errors.

## ◆ hdlc_rx_init()

hdlc_rx_state_t * hdlc_rx_init | ( | hdlc_rx_state_t * | s,
|  | int | crc32,
|  | int | report_bad_frames,
|  | int | framing_ok_threshold,
|  | hdlc_frame_handler_t | handler,
|  | void * | user_data )

Initialise an HDLC receiver context.

Initialise an HDLC receiver context.

Parameters

  s | A pointer to an HDLC receiver context.
  crc32 | TRUE to use ITU CRC32. FALSE to use ITU CRC16.
  report_bad_frames | TRUE to request the reporting of bad frames.
  framing_ok_threshold | The number of back-to-back flags needed to start the framing OK condition. This may be used where a series of flag octets is used as a preamble, such as in the T.30 protocol.
  handler | The function to be called when a good HDLC frame is received.
  user_data | An opaque parameter for the callback routine.

Returns
  A pointer to the HDLC receiver context.

References hdlc_rx_state_s::buffer, hdlc_rx_state_s::crc_bytes, hdlc_rx_state_s::frame_handler, hdlc_rx_state_s::frame_user_data, hdlc_rx_state_s::framing_ok_threshold, hdlc_rx_state_s::max_frame_len, and hdlc_rx_state_s::report_bad_frames.

Referenced by v42_restart().

## ◆ hdlc_rx_release()

int hdlc_rx_release | ( | hdlc_rx_state_t * | s | ) |

Release an HDLC receiver context.

Release an HDLC receiver context.

Parameters

  s | A pointer to an HDLC receiver context.

Returns
  0 for OK

## ◆ hdlc_rx_restart()

int hdlc_rx_restart | ( | hdlc_rx_state_t * | s | ) |

Re-initialise an HDLC receiver context.

Re-initialise an HDLC receiver context. This does not reset the usage statistics.

Parameters

  s | A pointer to an HDLC receiver context.

Returns
  0 for success.

References hdlc_rx_state_s::byte_in_progress, hdlc_rx_state_s::flags_seen, hdlc_rx_state_s::framing_ok_announced, hdlc_rx_state_s::len, hdlc_rx_state_s::num_bits, hdlc_rx_state_s::octet_count, hdlc_rx_state_s::octet_counting_mode, and hdlc_rx_state_s::raw_bit_stream.

## ◆ hdlc_rx_set_frame_handler()

void hdlc_rx_set_frame_handler | ( | hdlc_rx_state_t * | s,
|  | hdlc_frame_handler_t | handler,
|  | void * | user_data )

Change the put_bit function associated with an HDLC receiver context.

Change the put_bit function associated with an HDLC receiver context.

Parameters

  s | A pointer to an HDLC receiver context.
  handler | The function to be called when a good HDLC frame is received.
  user_data | An opaque parameter for the callback routine.

References hdlc_rx_state_s::frame_handler, and hdlc_rx_state_s::frame_user_data.

## ◆ hdlc_rx_set_max_frame_len()

void hdlc_rx_set_max_frame_len | ( | hdlc_rx_state_t * | s,
|  | size_t | max_len )

Set the maximum frame length for an HDLC receiver context.

Parameters

  s | A pointer to an HDLC receiver context.
  max_len | The maximum permitted length of a frame.

References hdlc_rx_state_s::buffer, hdlc_rx_state_s::crc_bytes, and hdlc_rx_state_s::max_frame_len.

## ◆ hdlc_rx_set_octet_counting_report_interval()

void hdlc_rx_set_octet_counting_report_interval | ( | hdlc_rx_state_t * | s,
|  | int | interval )

Set the octet counting report interval.

Parameters

  s | A pointer to an HDLC receiver context.
  interval | The interval, in octets.

References hdlc_rx_state_s::octet_count_report_interval.

## ◆ hdlc_rx_set_status_handler()

void hdlc_rx_set_status_handler | ( | hdlc_rx_state_t * | s,
|  | modem_status_func_t | handler,
|  | void * | user_data )

Change the status report function associated with an HDLC receiver context.

Change the status report function associated with an HDLC receiver context.

Parameters

  s | A pointer to an HDLC receiver context.
  handler | The callback routine used to report status changes.
  user_data | An opaque parameter for the callback routine.

References hdlc_rx_state_s::status_handler, and hdlc_rx_state_s::status_user_data.

## ◆ hdlc_tx_abort()

int hdlc_tx_abort | ( | hdlc_tx_state_t * | s | ) |

Send an abort.

Parameters

  s | A pointer to an HDLC transmitter context.

Returns
  0 if the frame was aborted, else -1.

References hdlc_tx_state_s::abort_octets, and hdlc_tx_state_s::flag_octets.

## ◆ hdlc_tx_corrupt_frame()

int hdlc_tx_corrupt_frame | ( | hdlc_tx_state_t * | s | ) |

Corrupt the frame currently being transmitted, by giving it the wrong CRC.

Parameters

  s | A pointer to an HDLC transmitter context.

Returns
  0 if the frame was corrupted, else -1.

References hdlc_tx_state_s::buffer, hdlc_tx_state_s::crc, HDLC_MAXFRAME_LEN, and hdlc_tx_state_s::len.

## ◆ hdlc_tx_flags()

int hdlc_tx_flags | ( | hdlc_tx_state_t * | s,
|  | int | len )

Transmit a specified quantity of flag octets, typically as a preamble.

Parameters

  s | A pointer to an HDLC transmitter context.
  len | The length of the required period of flags, in flag octets. If len is zero this requests that HDLC transmission be terminated when the buffers have fully drained.

Returns
  0 if the flags were accepted for transmission, else -1.

References hdlc_tx_state_s::flag_octets, hdlc_tx_state_s::pos, hdlc_tx_state_s::report_flag_underflow, and hdlc_tx_state_s::tx_end.

## ◆ hdlc_tx_frame()

int hdlc_tx_frame | ( | hdlc_tx_state_t * | s,
|  | const uint8_t * | frame,
|  | size_t | len )

Transmit a frame.

Parameters

  s | A pointer to an HDLC transmitter context.
  frame | A pointer to the frame to be transmitted.
  len | The length of the frame to be transmitted.

Returns
  0 if the frame was accepted for transmission, else -1.

References hdlc_tx_state_s::buffer, hdlc_tx_state_s::crc, hdlc_tx_state_s::crc_bytes, crc_itu16_calc(), crc_itu32_calc(), HDLC_MAXFRAME_LEN, hdlc_tx_state_s::len, hdlc_tx_state_s::max_frame_len, hdlc_tx_state_s::pos, hdlc_tx_state_s::progressive, and hdlc_tx_state_s::tx_end.

## ◆ hdlc_tx_free()

int hdlc_tx_free | ( | hdlc_tx_state_t * | s | ) |

Free an HDLC transmitter context.

Free an HDLC transmitter context.

Parameters

  s | A pointer to an HDLC transmitter context.

Returns
  0 for OK

## ◆ hdlc_tx_init()

hdlc_tx_state_t * hdlc_tx_init | ( | hdlc_tx_state_t * | s,
|  | int | crc32,
|  | int | inter_frame_flags,
|  | int | progressive,
|  | hdlc_underflow_handler_t | handler,
|  | void * | user_data )

Initialise an HDLC transmitter context.

Initialise an HDLC transmitter context.

Parameters

  s | A pointer to an HDLC transmitter context.
  crc32 | TRUE to use ITU CRC32. FALSE to use ITU CRC16.
  inter_frame_flags | The minimum flag octets to insert between frames (usually one).
  progressive | TRUE if frame creation works in progressive mode.
  handler | The callback function called when the HDLC transmitter underflows.
  user_data | An opaque parameter for the callback routine.

Returns
  A pointer to the HDLC transmitter context.

References hdlc_tx_state_s::crc, hdlc_tx_state_s::crc_bytes, HDLC_MAXFRAME_LEN, hdlc_tx_state_s::idle_octet, hdlc_tx_state_s::inter_frame_flags, hdlc_tx_state_s::max_frame_len, hdlc_tx_state_s::progressive, hdlc_tx_state_s::underflow_handler, and hdlc_tx_state_s::user_data.

Referenced by v42_restart().

## ◆ hdlc_tx_release()

int hdlc_tx_release | ( | hdlc_tx_state_t * | s | ) |

Release an HDLC transmitter context.

Release an HDLC transmitter context.

Parameters

  s | A pointer to an HDLC transmitter context.

Returns
  0 for OK

## ◆ hdlc_tx_restart()

int hdlc_tx_restart | ( | hdlc_tx_state_t * | s | ) |

Re-initialise an HDLC transmitter context.

Re-initialise an HDLC transmitter context.

Parameters

  s | A pointer to an HDLC transmitter context.

Returns
  0 for success.

References hdlc_tx_state_s::abort_octets, hdlc_tx_state_s::bits, hdlc_tx_state_s::byte, hdlc_tx_state_s::crc, hdlc_tx_state_s::crc_bytes, hdlc_tx_state_s::flag_octets, hdlc_tx_state_s::idle_octet, hdlc_tx_state_s::len, hdlc_tx_state_s::num_bits, hdlc_tx_state_s::octets_in_progress, hdlc_tx_state_s::pos, hdlc_tx_state_s::report_flag_underflow, and hdlc_tx_state_s::tx_end.

## ◆ hdlc_tx_set_max_frame_len()

void hdlc_tx_set_max_frame_len | ( | hdlc_tx_state_t * | s,
|  | size_t | max_len )

Set the maximum frame length for an HDLC transmitter context.

Parameters

  s | A pointer to an HDLC transmitter context.
  max_len | The maximum length.

References HDLC_MAXFRAME_LEN, and hdlc_tx_state_s::max_frame_len.

## ◆ SPAN_DECLARE_NONSTD() [1/2]

SPAN_DECLARE_NONSTD | ( | int |  | ) |

Get the next bit for transmission.

Get the next bit of data from a T.38 rate adapting non-ECM buffer context.

Get a bit of received non-ECM image data.

Get the next bit of a transmitted serial bit stream.

Get the next sequence of bytes for transmission.

Get the next byte for transmission.

Parameters

  s | A pointer to an HDLC transmitter context.

Returns
  The next bit for transmission.

Parameters

  s | A pointer to an HDLC transmitter context.

Returns
  The next byte for transmission.

Parameters

  s | A pointer to an HDLC transmitter context.
  buf | The buffer for the data.
  max_len | The number of bytes to get.

Returns
  The number of bytes actually got.

## ◆ SPAN_DECLARE_NONSTD() [2/2]

SPAN_DECLARE_NONSTD | ( | void |  | ) |

Put a single bit of data to an HDLC receiver.

Put a series of bytes of data to an HDLC receiver.

Put a byte of data to an HDLC receiver.

Parameters

  s | A pointer to an HDLC receiver context.
  new_bit | The bit.
  s | A pointer to an HDLC receiver context.
  new_byte | The byte of data.
  s | A pointer to an HDLC receiver context.
  buf | The buffer of data.
  len | The length of the data in the buffer.