hx_stream.h File Reference

A simple serial line framing protocol based on HDLC with 32-bit CRC protection. More...

#include <sys/types.h>
#include <perf/perf_counter.h>

Go to the source code of this file.

Macros
#define	HX_STREAM_MAX_FRAME   64

Typedefs
typedef struct hx_stream *	hx_stream_t
typedef void(*	hx_stream_rx_callback) (void *arg, const void *data, size_t length)

Functions
__BEGIN_DECLS __EXPORT hx_stream_t	hx_stream_init (int fd, hx_stream_rx_callback callback, void *arg)
	Allocate a new hx_stream object. More...
__EXPORT void	hx_stream_free (hx_stream_t stream)
	Free a hx_stream object. More...
__EXPORT void	hx_stream_set_counters (hx_stream_t stream, perf_counter_t tx_frames, perf_counter_t rx_frames, perf_counter_t rx_errors)
	Set performance counters for the stream. More...
__EXPORT void	hx_stream_reset (hx_stream_t stream)
	Reset a stream. More...
__EXPORT int	hx_stream_start (hx_stream_t stream, const void *data, size_t count)
	Prepare to send a frame. More...
__EXPORT int	hx_stream_send_next (hx_stream_t stream)
	Get the next byte to send for a stream. More...
__EXPORT int	hx_stream_send (hx_stream_t stream, const void *data, size_t count)
	Send a frame. More...
__EXPORT void	hx_stream_rx (hx_stream_t stream, uint8_t c)
	Handle a byte from the stream. More...

Detailed Description

A simple serial line framing protocol based on HDLC with 32-bit CRC protection.

Function Documentation

hx_stream_free()

__EXPORT void hx_stream_free

(

hx_stream_t

stream

)

Free a hx_stream object.

Parameters

stream

A handle returned from hx_stream_init.

hx_stream_init()

__BEGIN_DECLS __EXPORT hx_stream_t hx_stream_init	(	int	fd,
		hx_stream_rx_callback	callback,
		void *	arg
	)

Allocate a new hx_stream object.

Parameters

fd	The file handle over which the protocol will communicate, or -1 if the protocol will use hx_stream_start/hx_stream_send_next.
callback	Called when a frame is received.
callback_arg	Passed to the callback.

Returns

A handle to the stream, or NULL if memory could not be allocated.

hx_stream_reset()

__EXPORT void hx_stream_reset

(

hx_stream_t

stream

)

Reset a stream.

Forces the local stream state to idle.

Parameters

stream

A handle returned from hx_stream_init.

hx_stream_rx()

__EXPORT void hx_stream_rx	(	hx_stream_t	stream,
		uint8_t	c
	)

Handle a byte from the stream.

Parameters

stream	A handle returned from hx_stream_init.
c	The character to process.

hx_stream_send()

__EXPORT int hx_stream_send	(	hx_stream_t	stream,
		const void *	data,
		size_t	count
	)

Send a frame.

This function will block until all frame bytes are sent if the descriptor passed to hx_stream_init is marked blocking, otherwise it will return -1 (but may transmit a runt frame at the same time).

Todo:

Handling of non-blocking streams needs to be better.

Parameters

stream	A handle returned from hx_stream_init.
data	Pointer to the data to send.
count	The number of bytes to send.

Returns

Zero on success, -errno on error.

hx_stream_send_next()

__EXPORT int hx_stream_send_next

(

hx_stream_t

stream

)

Get the next byte to send for a stream.

This requires that the stream be prepared for sending by calling hx_stream_start first.

Parameters

stream

A handle returned from hx_stream_init.

Returns

The byte to send, or -1 if there is nothing left to send.

hx_stream_set_counters()

__EXPORT void hx_stream_set_counters	(	hx_stream_t	stream,
		perf_counter_t	tx_frames,
		perf_counter_t	rx_frames,
		perf_counter_t	rx_errors
	)

Set performance counters for the stream.

Any counter may be set to NULL to disable counting that datum.

Parameters

stream	A handle returned from hx_stream_init.
tx_frames	Counter for transmitted frames.
rx_frames	Counter for received frames.
rx_errors	Counter for short and corrupt received frames.

hx_stream_start()

__EXPORT int hx_stream_start	(	hx_stream_t	stream,
		const void *	data,
		size_t	count
	)

Prepare to send a frame.

Use this in conjunction with hx_stream_send_next to set the frame to be transmitted.

Use hx_stream_send() to write to the stream fd directly.

Parameters

stream	A handle returned from hx_stream_init.
data	Pointer to the data to send.
count	The number of bytes to send.

Returns

Zero on success, -errno on error.