Circular buffer data type used by the OTA (Over-The-Air) firmware update client and transparent serial cluster. More...

Files
file	cbuf.h

file	xbee_cbuf.c
	Circular buffer data type used by the OTA (Over-The-Air) firmware update client and transparent serial cluster.

Data Structures
struct	xbee_cbuf_t
	Circular buffer used by transparent serial cluster handler. More...

Macros
#define	XBEE_CBUF_OVERHEAD sizeof(xbee_cbuf_t)
	XBEE_CBUF_OVERHEAD is used when allocating memory for a circular buffer. More...

#define	xbee_cbuf_length(cbuf) ((cbuf)->mask)
	Returns the capacity of the circular buffer. More...

Functions
int	xbee_cbuf_init (xbee_cbuf_t FAR *cbuf, unsigned int datasize)
	Initialize the fields of the circular buffer. More...

int	xbee_cbuf_putch (xbee_cbuf_t FAR *cbuf, uint_fast8_t ch)
	Append a single byte to the circular buffer (if not full). More...

int	xbee_cbuf_getch (xbee_cbuf_t FAR *cbuf)
	Remove and return the first byte of the circular buffer. More...

unsigned int	xbee_cbuf_used (xbee_cbuf_t FAR *cbuf)
	Returns the number of bytes stored in the circular buffer. More...

unsigned int	xbee_cbuf_free (xbee_cbuf_t FAR *cbuf)
	Returns the number of additional bytes that can be stored in the circular buffer. More...

void	xbee_cbuf_flush (xbee_cbuf_t FAR *cbuf)
	Flush the contents of the circular buffer. More...

unsigned int	xbee_cbuf_put (xbee_cbuf_t FAR cbuf, const void FAR buffer, unsigned int length)
	Append multiple bytes to the end of a circular buffer. More...

unsigned int	xbee_cbuf_get (xbee_cbuf_t cbuf, void FAR buffer, unsigned int length)
	Read (and remove) multiple bytes from circular buffer. More...

Detailed Description

Circular buffer data type used by the OTA (Over-The-Air) firmware update client and transparent serial cluster.

Macro Definition Documentation

#define xbee_cbuf_length ( cbuf ) ((cbuf)->mask)

Returns the capacity of the circular buffer.

Parameters

[in] cbuf Pointer to circular buffer.

Returns: Maximum number of bytes that can be stored in the circular buffer.

See also: xbee_cbuf_used, xbee_cbuf_free

#define XBEE_CBUF_OVERHEAD sizeof(xbee_cbuf_t)

XBEE_CBUF_OVERHEAD is used when allocating memory for a circular buffer.

For a cbuf that can hold X bytes, you need (X + CBUF_OVERHEAD) bytes of memory.

XBEE_CBUF_OVERHEAD includes a header, plus a separator byte in the buffered data.

For example, to set up a 31-byte circular buffer:

 #define MY_BUF_SIZE 31        // must be 2^n -1
 char my_buf_space[MY_BUF_SIZE + XBEE_CBUF_OVERHEAD];
 xbee_cbuf_t *my_buf;
 
 my_buf = (xbee_cbuf_t *)my_buf_space;
 xbee_cbuf_init( my_buf, MY_BUF_SIZE);
 
 // or
 
 struct {
    xbee_cbuf_t    cbuf;
    char           buf_space[MY_BUF_SIZE];
 } my_buf;
 
 xbee_cbuf_init( &my_buf.cbuf, MY_BUF_SIZE);

Function Documentation

void xbee_cbuf_flush ( xbee_cbuf_t FAR * cbuf )

Flush the contents of the circular buffer.

Parameters

[in,out] cbuf Pointer to circular buffer.

Referenced by xbee_ser_rx_flush(), and xbee_ser_tx_flush().

unsigned int xbee_cbuf_free ( xbee_cbuf_t FAR * cbuf )

Returns the number of additional bytes that can be stored in the circular buffer.

Parameters

[in] cbuf Pointer to circular buffer.

Returns: Number of unused bytes in the circular buffer.

See also: xbee_cbuf_length, xbee_cbuf_free

Referenced by xbee_cbuf_put(), xbee_ser_flowcontrol(), xbee_ser_getchar(), xbee_ser_read(), xbee_ser_rx_free(), xbee_ser_tx_free(), and xbee_ser_write().

unsigned int xbee_cbuf_get	(	xbee_cbuf_t *	cbuf,
		void FAR *	buffer,
		unsigned int	length
	)

Read (and remove) multiple bytes from circular buffer.

Parameters

[in,out]	cbuf	circular buffer
[out]	buffer	destination to copy data from circular buffer
[in]	length	number of bytes to copy

Returns: number of bytes copied (may be less than length if buffer is empty)

References FAR, and xbee_cbuf_used().

Referenced by _pxbee_ota_xmodem_read(), and xbee_ser_read().

int xbee_cbuf_getch ( xbee_cbuf_t FAR * cbuf )

Remove and return the first byte of the circular buffer.

Parameters

[in] cbuf Pointer to circular buffer.

Return values

-1	buffer is empty
0-255	byte removed from the head of the buffer

See also: xbee_cbuf_putch, xbee_cbuf_get, xbee_cbuf_put

Referenced by xbee_ser_getchar(), and xbee_ser_write().

int xbee_cbuf_init	(	xbee_cbuf_t FAR *	cbuf,
		unsigned int	datasize
	)

Initialize the fields of the circular buffer.

Note: You must initialize the xbee_cbuf_t structure before using it with any other xbee_cbuf_xxx() functions. If you have ISRs pushing data into the buffer, don't enable them until AFTER you've called xbee_cbuf_init.

Parameters

[in,out]	cbuf	Address of buffer to use for the circular buffer. This buffer must be (datasize + CBUF_OVEREAD) bytes long to hold the locks, head, tail, size and buffered bytes.
[in]	datasize	Maximum number of bytes to store in the circular buffer. This size must be at least 3 and a power of 2 minus 1 (2^n - 1).

Return values

0	success
-EINVAL	invalid parameter

References EINVAL.

Referenced by pxbee_ota_init(), and xbee_ser_open().

unsigned int xbee_cbuf_put	(	xbee_cbuf_t FAR *	cbuf,
		const void FAR *	buffer,
		unsigned int	length
	)

Append multiple bytes to the end of a circular buffer.

Parameters

[in,out]	cbuf	circular buffer
[in]	buffer	data to copy into circular buffer
[in]	length	number of bytes to copy

Returns: number of bytes copied (may be less than length if buffer is full)

References FAR, and xbee_cbuf_free().

Referenced by _pxbee_ota_transparent_rx(), and xbee_ser_write().

int xbee_cbuf_putch	(	xbee_cbuf_t FAR *	cbuf,
		uint_fast8_t	ch
	)

Append a single byte to the circular buffer (if not full).

Parameters

[in,out]	cbuf	Pointer to circular buffer.
[in]	ch	Byte to append.

Return values

0	buffer is full
1	the byte was appended

See also: xbee_cbuf_getch, xbee_cbuf_get, xbee_cbuf_put

Referenced by xbee_ser_baudrate(), and xbee_ser_putchar().

unsigned int xbee_cbuf_used ( xbee_cbuf_t FAR * cbuf )

Returns the number of bytes stored in the circular buffer.

Parameters

[in] cbuf Pointer to circular buffer.

Returns: Number of bytes stored in the circular buffer.

See also: xbee_cbuf_length, xbee_cbuf_free

Referenced by xbee_cbuf_get(), xbee_ser_read(), xbee_ser_rx_used(), and xbee_ser_tx_used().

Files

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation