Buffer Interface

Functions
wwd_result_t	host_buffer_add_remove_at_front (wiced_buffer_t *buffer, int32_t add_remove_amount)
wwd_result_t	host_buffer_check_leaked (void)
wwd_result_t	host_buffer_get (wiced_buffer_t *buffer, wwd_buffer_dir_t direction, unsigned short size, wiced_bool_t wait)
	Allocates a packet buffer.
uint8_t *	host_buffer_get_current_piece_data_pointer (wiced_buffer_t buffer)
uint16_t	host_buffer_get_current_piece_size (wiced_buffer_t buffer)
wiced_buffer_t	host_buffer_get_next_piece (wiced_buffer_t buffer)
void	host_buffer_init_fifo (wiced_buffer_fifo_t *fifo)
wiced_bool_t	host_buffer_pool_is_full (wwd_buffer_dir_t direction)
wiced_buffer_t	host_buffer_pop_from_fifo (wiced_buffer_fifo_t *fifo, wwd_interface_t *interface)
void	host_buffer_push_to_fifo (wiced_buffer_fifo_t *fifo, wiced_buffer_t buffer, wwd_interface_t interface)
void	host_buffer_release (wiced_buffer_t buffer, wwd_buffer_dir_t direction)
wwd_result_t	host_buffer_set_size (wiced_buffer_t buffer, unsigned short size)
wwd_result_t	internal_host_buffer_get (wiced_buffer_t *buffer, wwd_buffer_dir_t direction, unsigned short size, unsigned long timeout_ms)
	Allocates a packet buffer.
wwd_result_t	wwd_buffer_deinit (void)
wwd_result_t	wwd_buffer_init (void *native_arg)

Detailed Description

Allows WICED to use packet buffers in an abstract way.

Function Documentation

host_buffer_add_remove_at_front()

wwd_result_t host_buffer_add_remove_at_front ( wiced_buffer_t * buffer, int32_t add_remove_amount )

extern

Moves the current pointer of a packet buffer

Implemented in the WICED buffer interface which is specific to the buffering scheme in use. Since packet buffers usually need to be created with space at the front for additional headers, this function allows WICED to move the current 'front' location pointer so that it has space to add headers to transmit packets, and so that the network stack does not see the internal WICED headers on received packets.

Parameters

buffer	: A pointer to the handle of the current packet buffer for which the current pointer will be moved. On return this may contain a pointer to a newly allocated packet buffer which has been daisy chained to the front of the given one. This would be the case if the given packet buffer didn't have enough space at the front.
add_remove_amount	: This is the number of bytes to move the current pointer of the packet buffer - a negative value increases the space for headers at the front of the packet, a positive value decreases the space.

Returns

WWD_SUCCESS = Success, Error code = Failure

host_buffer_check_leaked()

wwd_result_t host_buffer_check_leaked ( void )

extern

Checks for buffers that have been leaked

Implemented in the WICED buffer interface which is specific to the buffering scheme in use. This function must only be used when all buffers are expected to have been released. Function triggers an assertion if any buffers are in use.

Returns

WWD_SUCCESS = Success, Error code = Failure

host_buffer_get()

wwd_result_t host_buffer_get ( wiced_buffer_t * buffer, wwd_buffer_dir_t direction, unsigned short size, wiced_bool_t wait )

extern

Allocates a packet buffer.

Implemented in the WICED buffer interface which is specific to the buffering scheme in use. Attempts to allocate a packet buffer of the size requested. It can do this by allocating a pre-existing packet from a pool, using a static buffer, or by dynamically allocating memory. The method of allocation does not concern WICED, however it must match the way the network stack expects packet buffers to be allocated.

Parameters

buffer	A pointer which receives the allocated packet buffer handle
direction	: Indicates transmit/receive direction that the packet buffer is used for. This may be needed if tx/rx pools are separate.
size	: The number of bytes to allocate.
wait	: Whether to wait for a packet buffer to be available

Returns

WWD_SUCCESS = Success, Error code = Failure

host_buffer_get_current_piece_data_pointer()

uint8_t * host_buffer_get_current_piece_data_pointer ( wiced_buffer_t buffer )

extern

Retrieves the current pointer of a packet buffer

Implemented in the WICED buffer interface which is specific to the buffering scheme in use. Since packet buffers usually need to be created with space at the front for additional headers, this function allows WICED to get the current 'front' location pointer.

Parameters

buffer

: The handle of the packet buffer whose pointer is to be retrieved

Returns

The packet buffer's current pointer.

host_buffer_get_current_piece_size()

uint16_t host_buffer_get_current_piece_size ( wiced_buffer_t buffer )

extern

Retrieves the size of a packet buffer

Implemented in the WICED buffer interface which is specific to the buffering scheme in use. Since packet buffers usually need to be created with space at the front for additional headers, the memory block used to contain a packet buffer will often be larger than the current size of the packet buffer data. This function allows WICED to retrieve the current size of a packet buffer's data.

Parameters

buffer

: The handle of the packet buffer whose size is to be retrieved

Returns

The size of the packet buffer.

host_buffer_get_next_piece()

wiced_buffer_t host_buffer_get_next_piece ( wiced_buffer_t buffer )

extern

Retrieves the next piece of a set of daisy chained packet buffers

Implemented in the WICED buffer interface which is specific to the buffering scheme in use. Some buffering schemes allow buffers to be daisy chained into linked lists. This allows more flexibility with packet buffers and avoids memory copies. It does however require scatter-gather DMA for the hardware bus. This function retrieves the next buffer in a daisy chain of packet buffers.

Parameters

buffer

: The handle of the packet buffer whose next buffer is to be retrieved

Returns

The handle of the next buffer, or NULL if there is none.

host_buffer_init_fifo()

void host_buffer_init_fifo ( wiced_buffer_fifo_t * fifo )

extern

Init fifo

Parameters

fifo	: pointer to fifo structure

host_buffer_pool_is_full()

wiced_bool_t host_buffer_pool_is_full

(

wwd_buffer_dir_t

direction

)

Check whether pools are full or not (whether all packets are freed).

Parameters

direction

- TX or RX pools to check

Returns

WICED_TRUE if polls are full, otherwise WICED_FALSE.

host_buffer_pop_from_fifo()

wiced_buffer_t host_buffer_pop_from_fifo ( wiced_buffer_fifo_t * fifo, wwd_interface_t * interface )

extern

Pop packet from head of fifo.

Parameters

fifo	- pointer to fifo structure
interface	- out parameter which filled with interface buffer belong

Returns

NULL if fifo empty, otherwise return buffer and store interface in 'interface' out parameter.

host_buffer_push_to_fifo()

void host_buffer_push_to_fifo ( wiced_buffer_fifo_t * fifo, wiced_buffer_t buffer, wwd_interface_t interface )

extern

Push buffer to tail of fifo

Parameters

fifo	: pointer to fifo structure
buffer	: buffer to push
interface	: which interface buffer belong

host_buffer_release()

void host_buffer_release ( wiced_buffer_t buffer, wwd_buffer_dir_t direction )

extern

Releases a packet buffer

Implemented in the Wiced buffer interface, which will be specific to the buffering scheme in use. This function is used by WICED to indicate that it no longer requires a packet buffer. The buffer can then be released back into a pool for reuse, or the dynamically allocated memory can be freed, according to how the packet was allocated. Returns void since WICED cannot do anything about failures

Parameters

buffer	: the handle of the packet buffer to be released
direction	: indicates transmit/receive direction that the packet buffer has been used for. This might be needed if tx/rx pools are separate.

host_buffer_set_size()

wwd_result_t host_buffer_set_size ( wiced_buffer_t buffer, unsigned short size )

extern

Sets the current size of a Wiced packet

Implemented in the WICED buffer interface which is specific to the buffering scheme in use. This function sets the current length of a WICED packet buffer

Parameters

buffer	: The packet to be modified
size	: The new size of the packet buffer

Returns

WWD_SUCCESS = Success, Error code = Failure

internal_host_buffer_get()

wwd_result_t internal_host_buffer_get ( wiced_buffer_t * buffer, wwd_buffer_dir_t direction, unsigned short size, unsigned long timeout_ms )

extern

Allocates a packet buffer.

Implemented in the WICED buffer interface which is specific to the buffering scheme in use. Attempts to allocate a packet buffer of the size requested. It can do this by allocating a pre-existing packet from a pool, using a static buffer, or by dynamically allocating memory. The method of allocation does not concern WICED, however it must match the way the network stack expects packet buffers to be allocated.

Parameters

buffer	A pointer which receives the allocated packet buffer handle
direction	: Indicates transmit/receive direction that the packet buffer is used for. This may be needed if tx/rx pools are separate.
size	: The number of bytes to allocate.
timeout_ms	: Maximum period to block for. Can be passed NEVER_TIMEOUT to request no timeout

Returns

WWD_SUCCESS = Success, Error code = Failure

wwd_buffer_deinit()

wwd_result_t wwd_buffer_deinit ( void )

extern

Deinitialize the packet buffer interface

Implemented in the WICED buffer interface which is specific to the buffering scheme in use.

Returns

WWD_SUCCESS = Success, Error code = Failure

wwd_buffer_init()

wwd_result_t wwd_buffer_init ( void * native_arg )

extern

Initialize the packet buffer interface

Implemented in the WICED buffer interface which is specific to the buffering scheme in use. Some implementations of the packet buffer interface may need additional information for initialization, especially the location of packet buffer pool(s). These can be passed via the 'native_arg' parameter.

Parameters

native_arg

An implementation specific argument

Returns

WWD_SUCCESS = Success, Error code = Failure