Macros
#define	NULL_BUFFER 0x0000

Typedefs
typedef uint16_t	Buffer

typedef Buffer	MessageBufferQueue

typedef Buffer	PacketHeader

typedef Buffer	EmberMessageBuffer

typedef void(*	Marker ) ( Buffer *buffer)

typedef void(*	BufferMarker ) (void)

Functions
Buffer	emAllocateBuffer (uint16_t dataSizeInBytes)
	Allocates a buffer.

uint8_t *	emGetBufferPointer ( Buffer buffer)
	gets a pointer to the specified buffer

uint16_t	emGetBufferLength ( Buffer buffer)
	gets the length of the specified buffer

Buffer	emFillStringBuffer (const uint8_t *contents)
	allocates a buffer and fills it with the given null terminated string

Buffer	emFillBuffer (const uint8_t *contents, uint16_t length)
	Allocates a buffer and fills with length bytes of contents.

uint16_t	emBufferBytesUsed (void)
	returns the number of bytes of buffer space currently in use

uint16_t	emBufferBytesRemaining (void)
	returns the number of available bytes remaining in the buffer system

uint16_t	emBufferBytesTotal (void)
	returns the number of bytes allocated to the buffer system

bool	emIsValidBuffer ( Buffer buffer)
	returns whether the given buffer is valid

void	emSetBufferLength ( Buffer buffer, uint16_t length)
	Truncates the buffer. New length cannot be longer than the old length.

void	emSetBufferLengthFromEnd ( Buffer buffer, uint16_t length)
	Truncates the buffer, removing bytes from the front. New length cannot be longer than the old length.

void	emReclaimUnusedBuffers (const BufferMarker *markers)
	Reclaims unused buffers and compacts the heap.

void	emMarkBuffer ( Buffer *root)
	Marks the passed buffer. Called from Marker function.

void	emMarkBufferWeak ( Buffer *root)
	weakly mark buffer

Detailed Description

These buffers are contiguous blocks of bytes. Buffers are allocated linearly from a single chunk of memory. When space gets short any buffers still in use can be moved to the beginning of buffer memory, which consolidates any unused space.

'Buffer' values are actually offsets from the beginning of buffer memory. Using uint8_ts would require additional memory for the mapping between the uint8_ts and memory locations.

In fact, Buffers are offsets from one before the beginning of buffer memory. The first buffer is thus 0x0001. This allows us to use 0x0000 as the null buffer, just as C uses zero for the null pointer.

In general the buffer functions are not safe for use in ISRs. The one exception is the PHY->MAC queue, which is handled specially. It is safe for an ISR to allocate a new buffer and put it on the PHY->MAC queue.

Any code which holds on to buffers beyond the context in which they are allocated must provide a marking function to prevent them from being garbage collected. See emReclaimUnusedBuffers for details.

Macro Definition Documentation

◆ NULL_BUFFER

#define NULL_BUFFER 0x0000

Typedef Documentation

◆ Buffer

typedef uint16_t Buffer

◆ BufferMarker

typedef void(* BufferMarker) (void)

◆ EmberMessageBuffer

typedef Buffer EmberMessageBuffer

◆ Marker

typedef void(* Marker) ( Buffer *buffer)

◆ MessageBufferQueue

typedef Buffer MessageBufferQueue

◆ PacketHeader

typedef Buffer PacketHeader

Function Documentation

◆ emAllocateBuffer()

Buffer emAllocateBuffer ( uint16_t dataSizeInBytes )

Allocates a buffer.

◆ emBufferBytesRemaining()

uint16_t emBufferBytesRemaining ( void )

returns the number of available bytes remaining in the buffer system

◆ emBufferBytesTotal()

uint16_t emBufferBytesTotal ( void )

returns the number of bytes allocated to the buffer system

◆ emBufferBytesUsed()

uint16_t emBufferBytesUsed ( void )

returns the number of bytes of buffer space currently in use

◆ emFillBuffer()

Buffer emFillBuffer	(	const uint8_t *	`contents,`
		uint16_t	`length`
	)

Allocates a buffer and fills with length bytes of contents.

◆ emFillStringBuffer()

Buffer emFillStringBuffer ( const uint8_t * contents )

allocates a buffer and fills it with the given null terminated string

'contents' may be NULL, in which case NULL_BUFFER is returned.

◆ emGetBufferLength()

uint16_t emGetBufferLength ( Buffer buffer )

gets the length of the specified buffer

◆ emGetBufferPointer()

uint8_t* emGetBufferPointer ( Buffer buffer )

gets a pointer to the specified buffer

◆ emIsValidBuffer()

bool emIsValidBuffer ( Buffer buffer )

returns whether the given buffer is valid

◆ emMarkBuffer()

void emMarkBuffer ( Buffer * root )

Marks the passed buffer. Called from Marker function.

◆ emMarkBufferWeak()

void emMarkBufferWeak ( Buffer * root )

weakly mark buffer

emMarkBufferWeak only operates during the update references phase if emMark Buffer is called on the same buffer elsewhere, the weak reference will be updated. If a buffer is only weakly marked, the update phase will replace it with NULL_BUFFER

◆ emReclaimUnusedBuffers()

void emReclaimUnusedBuffers ( const BufferMarker * markers )

Reclaims unused buffers and compacts the heap.

Reclaims all buffers not reachable from 'roots', the PHY->MAC queue, by one of marker functions. The marker functions should call their argument on all known buffer references.

The idea is that single top level references, such as a queue, can be put in 'roots', whereas buffers stored in data structures, such as the retry table, are handled by marker functions.

Surviving buffers moved to the beginning of the heap, which amalgamates the free memory into a single contiguous block. This should only be called when there are no references to buffers outside of 'roots', the PHY->MAC queue, and the locations passed to the marker functions.

IMPORTANT: BufferMarker routines should not reference buffers after they have been marked. The buffers may be in an inconsistent state until the reclaimation has completed.

Right: void myBufferMarker(void) { ... myBuffer ... emMarkBuffer(&myBuffer); }

Wrong: void myBufferMarker(void) { emMarkBuffer(&myBuffer); ... myBuffer ... }

◆ emSetBufferLength()

void emSetBufferLength	(	Buffer	`buffer,`
		uint16_t	`length`
	)

Truncates the buffer. New length cannot be longer than the old length.

◆ emSetBufferLengthFromEnd()

void emSetBufferLengthFromEnd	(	Buffer	`buffer,`
		uint16_t	`length`
	)

Truncates the buffer, removing bytes from the front. New length cannot be longer than the old length.

Packet Buffers EmberZNet Stack API Reference

Macros

Typedefs

Functions