nRF5 SDK for Thread and Zigbee v4.1.0
Data Structures | Macros | Typedefs | Enumerations | Functions
Packet buffers pool
ZBOSS framework

Data Structures

struct  zb_buf_hdr_s
 
struct  zb_mult_buf_s
 
struct  zb_leg_buf_s
 

Macros

#define ZB_RESERVED_BUF_TO_ALIGN_HDR_SIZE   3u
 
#define ZB_BUF_INVALID   0
 
#define ZB_UNDEFINED_BUFFER   0
 
#define TRACE_PROTO_VOID   void
 
#define TRACE_PROTO
 
#define TRACE_CALL_VOID
 
#define TRACE_CALL
 
#define ZB_TRACE_BUFS_USAGE()
 
#define zb_buf_get(is_in, max_size)   zb_buf_get_func(TRACE_CALL (is_in), (max_size))
 
#define zb_buf_get_out()   zb_buf_get_out_func(TRACE_CALL_VOID)
 
#define zb_buf_get_any()   zb_buf_get_any_func(TRACE_CALL_VOID)
 
#define zb_buf_get_hipri(a)   zb_buf_get_hipri_func(TRACE_CALL (a))
 
#define zb_buf_get_max_size(a)   zb_buf_get_max_size_func(TRACE_CALL (a))
 
#define zb_buf_get_out_delayed(callback)   zb_buf_get_out_delayed_func(TRACE_CALL (callback))
 Allocate OUT buffer, call a callback when the buffer is available. More...
 
#define zb_buf_get_in_delayed(callback)   zb_buf_get_in_delayed_func(TRACE_CALL (callback))
 Allocate IN buffer, call a callback when the buffer is available. More...
 
#define zb_buf_get_out_delayed_ext(callback, arg, max_size)   zb_buf_get_out_delayed_ext_func(TRACE_CALL (callback),(arg),(max_size))
 Allocate OUT buffer, call a callback when the buffer is available. More...
 
#define zb_buf_get_in_delayed_ext(callback, arg, max_size)   zb_buf_get_in_delayed_ext_func(TRACE_CALL (callback),(arg),(max_size))
 Allocate IN buffer, call a callback when the buffer is available. More...
 
#define zb_buf_free(buf)   zb_buf_free_func(TRACE_CALL (buf))
 Free packet buffer and put it into freelist. More...
 
#define zb_buf_begin(buf)   zb_buf_begin_func(TRACE_CALL (buf))
 
#define zb_buf_end(buf)   zb_buf_end_func(TRACE_CALL (buf))
 
#define zb_buf_ptr(buf)   zb_buf_ptr_func(TRACE_CALL (buf))
 
#define zb_buf_from_ptr(ptr)   zb_buf_from_ptr_func(TRACE_CALL (ptr))
 
#define zb_buf_set_data_offset(buf, off)   zb_buf_set_data_offset_func(TRACE_CALL (buf), (off))
 
#define zb_buf_len(buf)   zb_buf_len_func(TRACE_CALL (buf))
 
#define zb_buf_copy(src_buf, dst_buf)   zb_buf_copy_func(TRACE_CALL (src_buf),(dst_buf))
 
#define zb_buf_initial_alloc(buf, size)   zb_buf_initial_alloc_func(TRACE_CALL (buf),(size))
 Initial data space allocation in buffer. More...
 
#define zb_buf_reuse(buf)   zb_buf_reuse_func(TRACE_CALL (buf))
 
#define zb_buf_alloc_tail(buf, size)   zb_buf_alloc_tail_func(TRACE_CALL (buf),(size))
 
#define zb_buf_get_tail(buf, size)   zb_buf_get_tail_func(TRACE_CALL (buf),(size))
 
#define ZB_BUF_GET_PARAM(buf, type)   ((type *)zb_buf_get_tail_func(TRACE_CALL (buf), sizeof(type)))
 
#define zb_buf_cut_right(buf, size)   zb_buf_cut_right_func(TRACE_CALL (buf),(size))
 
#define zb_buf_cut_left(buf, size)   zb_buf_cut_left_func(TRACE_CALL (buf),(size))
 
#define zb_buf_alloc_right(buf, size)   zb_buf_alloc_right_func(TRACE_CALL (buf),(size))
 
#define zb_buf_alloc_left(buf, size)   zb_buf_alloc_left_func(TRACE_CALL (buf),(size))
 
#define zb_buf_flags_or(buf, val)   zb_buf_flags_or_func(TRACE_CALL (buf),(val))
 
#define zb_buf_flags_clr(buf, mask)   zb_buf_flags_clr_func(TRACE_CALL (buf),(mask))
 
#define zb_buf_flags_clr_encr(buf)   zb_buf_flags_clr_encr_func(TRACE_CALL (buf))
 
#define zb_buf_flags_get(buf)   zb_buf_flags_get_func(TRACE_CALL (buf))
 
#define zb_buf_get_status(buf)   zb_buf_get_status_func(TRACE_CALL (buf))
 
#define zb_buf_set_status(buf, status)   zb_buf_set_status_func(TRACE_CALL (buf), (status))
 
#define zb_buf_get_handle(buf)   zb_buf_get_handle_func(TRACE_CALL (buf))
 
#define zb_buf_set_handle(buf, handle)   zb_buf_set_handle_func(TRACE_CALL (buf),(handle))
 

Typedefs

typedef struct zb_buf_hdr_s zb_buf_hdr_t
 
typedef struct zb_mult_buf_s zb_mult_buf_t
 
typedef struct zb_leg_buf_s zb_leg_buf_t
 
typedef zb_mult_buf_t zb_buf_ent_t
 
typedef zb_uint8_t zb_bufid_t
 
typedef enum zb_buf_flags_bm_e zb_buf_flags_bm_t
 

Enumerations

enum  zb_buffer_types_e { ZB_OUT_BUFFER = 0, ZB_IN_BUFFER = 1 }
 
enum  zb_buf_flags_bm_e {
  ZB_BUF_IS_IN = (1<<0), ZB_BUF_SECUR_NWK_ENCR = (1<<1), ZB_BUF_SECUR_APS_ENCR = (1<<2), ZB_BUF_SECUR_MAC_ENCR = (1<<3),
  ZB_BUF_USE_SAME_KEY = (1<<4), ZB_BUF_ZDO_CMD_NO_RESP = (1<<5), ZB_BUF_HAS_APS_PAYLOAD = (1<<6)
}
 

Functions

 ZB_ASSERT_COMPILE_DECL ((sizeof(zb_buf_hdr_t)%sizeof(zb_uint32_t))==0)
 
zb_bool_t zb_buf_is_oom_state (void)
 
void zb_buf_oom_trace (void)
 
zb_bool_t zb_buf_memory_close_to_low (void)
 
zb_bool_t zb_buf_memory_low (void)
 
void zb_buf_set_mac_rx_need (zb_bool_t needs)
 
zb_bool_t zb_buf_get_mac_rx_need (void)
 
zb_bool_t zb_buf_have_rx_bufs (void)
 

Detailed Description

Packet buffers

The main idea is to be simple, CPU effective and eliminate data copy when possible (again, to decrease CPU load).

One of the main data structure of the ZBOSS stack is memory buffer, which is used for storing Zigbee packet. Zigbee packets has limited size (127 bytes). Zigbee packets are usually not fragmented, excluding fragmentation of big packets at APS layer. Extended buffers are used to store big packets.

To use extended buffers in application use zb_buf_get_out_delayed_ext() and zb_buf_get_in_delayed_ext() functions.

So, the same memory buffer can be used for a single packet going down-up or up-down between the user application and ZBOSS layers. Each layer or the application can modify the memory buffer: remove data partly or fully or add more data if there is free memory space in the buffer.

ZBOSS uses pre-defined pool of the fixed size memory buffers. The size of buffer pool can be changed, see more information about it in Memory configuration feature. A memory buffer consists of a header and a data buffer of 148 bytes. An application or the stack functions can get a single memory buffer from the pool (allocate the memory buffer) when it is necessary or put the buffer back when it is not needed anymore (release the memory buffer).

Every buffer has a header with these header fields:

To avoid data copying, the following technique is used: when a Zigbee packet moves up between the Zigbee layers, the data related to the lower layers is removed by modifying the data pointer and data length in the buffer header. When a Zigbee packet is passing down between the Zigbee layers, the initial data is stored not from the beginning of the data buffer, but in the middle, so some space is reserved before and after the data. Therefore, if a lower Zigbee layer puts some data to a header or to a tail, data copying is generally not required. However, if there is not enough space for a header or a tail, the existing data may be moved to the right or to the left.

Logically, the memory buffers are divided into 2 types: for in and out packets. Thus, the buffer pool allocates both 'in' and 'out' types of buffers. This approach helps prevent allocating of all the memory buffers for incoming or outgoing packets, only those that may block ZBOSS from sending or receiving respectively any data. Obviously, such blocking may cause a scenario where it is impossible to send an acknowledgement for the received packet and the packet will be retransmitted by a remote due to the lack of the acknowledgement.

Memory buffers are commonly used for passing parameters to ZBOSS API functions. The following technique is used: data space needed for storing the parameters is allocated in the memory buffer at the end of its data buffer. The limitation is that both a caller and called functions must be aware of the parameter sizes, so it makes it impossible to pass parameters with a variable length. Special helpers are provided for storing and getting parameters form the memory buffer: ZB_BUF_GET_PARAM().

Macro Definition Documentation

#define zb_buf_alloc_left (   buf,
  size 
)    zb_buf_alloc_left_func(TRACE_CALL (buf),(size))

Allocate space at the beginning of buffer

Parameters
buf- buffer ID
size- size to allocate
Returns
pointer to new data begin
#define zb_buf_alloc_right (   buf,
  size 
)    zb_buf_alloc_right_func(TRACE_CALL (buf),(size))

Allocate space at buffer end

Parameters
buf- buffer ID
size- size to allocate
Returns
pointer to allocated data data begin
#define zb_buf_alloc_tail (   buf,
  size 
)    zb_buf_alloc_tail_func(TRACE_CALL (buf),(size))

Alloc buffer tail of size 'size', initialize by zero.

Usually used to place external information (some parameters) to the buffer.

Parameters
buf- buffer ID
size- requested size. Must met already allocated size.
Returns
pointer to the buffer tail or NULL is buffer has no parameter of such size.
#define zb_buf_begin (   buf)    zb_buf_begin_func(TRACE_CALL (buf))

Return pointer to data stored in buffer

Parameters
buf- buffer ID
Returns
pointer to beginning of data in buffer
#define zb_buf_copy (   src_buf,
  dst_buf 
)    zb_buf_copy_func(TRACE_CALL (src_buf),(dst_buf))

Copy one buffer to another

Parameters
src_buf- source buffer
dst_buf- destination buffer
#define zb_buf_cut_left (   buf,
  size 
)    zb_buf_cut_left_func(TRACE_CALL (buf),(size))

Cut space at the beginning of buffer

Parameters
buf- buffer ID
size- size to cut
Returns
pointer to the new data begin
#define zb_buf_cut_right (   buf,
  size 
)    zb_buf_cut_right_func(TRACE_CALL (buf),(size))

Cut space at the end of buffer

Parameters
buf- buffer ID
size- size to cut
#define zb_buf_end (   buf)    zb_buf_end_func(TRACE_CALL (buf))

Return pointer to the data section end

Parameters
buf- buffer ID
Returns
pointer to the first byte after data in the buffer
#define zb_buf_flags_clr (   buf,
  mask 
)    zb_buf_flags_clr_func(TRACE_CALL (buf),(mask))

Clear buffer' flags by mask by doing flags = flags & ~mask

Parameters
buf- buffer ID
mask- value to be cleared from the flags -
See also
zb_buf_flags_bm_t
#define zb_buf_flags_clr_encr (   buf)    zb_buf_flags_clr_encr_func(TRACE_CALL (buf))

Clear buffer's flags related ro encryption

That function calls zb_buf_flags_clr(buf, ZB_BUF_SECUR_ALL_ENCR)

Parameters
buf- buffer ID
#define zb_buf_flags_get (   buf)    zb_buf_flags_get_func(TRACE_CALL (buf))

Get buffer's flags byte

Parameters
buf- buffer ID
Returns
flags value -
See also
zb_buf_flags_bm_t
#define zb_buf_flags_or (   buf,
  val 
)    zb_buf_flags_or_func(TRACE_CALL (buf),(val))

Add bits to the buffer's flags

Parameters
buf- buffer ID
val- value to be ORed with buffer' flags
#define zb_buf_free (   buf)    zb_buf_free_func(TRACE_CALL (buf))

Free packet buffer and put it into freelist.

Can be called from the main loop.

Parameters
buf- buffer ID

See any sample.

#define zb_buf_from_ptr (   ptr)    zb_buf_from_ptr_func(TRACE_CALL (ptr))

Return buffer id

Parameters
ptr- pointer to the first byte of the buffer memory
Returns
buffer ID
#define zb_buf_get (   is_in,
  max_size 
)    zb_buf_get_func(TRACE_CALL (is_in), (max_size))

Synchronous buffer allocation. If no buffers available, does not block. Note: this is low-level API. Usually user calls blocked alloc API.

Parameters
is_inif ZB_TRUE, allocate IN buffer, else allocate OUT buffer
max_sizerequired maximum buffer payload size (in bytes). It can be bigger or smaller than the default buffer size. Depending on the specific value, the buffer pool may decide to use a fraction of buffer or long buffers. Special value 0 means "single default buffer".
Returns
buffer id or ZB_BUF_INVALID if no buffers available
#define zb_buf_get_any ( )    zb_buf_get_any_func(TRACE_CALL_VOID)

Allocate IN or OUT buffer balancing @ of allocated IN and OUT

To be used at ZBOSS init time.

#define zb_buf_get_handle (   buf)    zb_buf_get_handle_func(TRACE_CALL (buf))

Get 'handle' field of the buffer's header

Parameters
buf- buffer ID
Returns
handle field value
#define zb_buf_get_hipri (   a)    zb_buf_get_hipri_func(TRACE_CALL (a))

Synchronous allocation of the high-priority buffer

#define zb_buf_get_in_delayed (   callback)    zb_buf_get_in_delayed_func(TRACE_CALL (callback))

Allocate IN buffer, call a callback when the buffer is available.

Use default buffer size _func(alloc single standard buffer). If buffer is available, schedules callback for execution immediately. If no buffers are available now, schedule callback later, when buffer will be available.

Parameters
callback- callback to call.
Returns
RET_OK or error code.
#define zb_buf_get_in_delayed_ext (   callback,
  arg,
  max_size 
)    zb_buf_get_in_delayed_ext_func(TRACE_CALL (callback),(arg),(max_size))

Allocate IN buffer, call a callback when the buffer is available.

If buffer is available, schedules callback for execution immediately. If no buffers are available now, schedule callback later, when buffer will be available.

Parameters
callback- callback to call.
arg- second argument for a callback
max_sizerequired maximum buffer payload size (in bytes). It can be bigger or smaller than the default buffer size. Depending on the specific value, the buffer pool may decide to use a fraction of buffer or long buffers. Special value 0 means "single default buffer".
Returns
RET_OK or error code.
#define zb_buf_get_max_size (   a)    zb_buf_get_max_size_func(TRACE_CALL (a))

Return maximum data size for that buffer.

#define zb_buf_get_out ( )    zb_buf_get_out_func(TRACE_CALL_VOID)

Allocate OUT buffer of the default size.

#define zb_buf_get_out_delayed (   callback)    zb_buf_get_out_delayed_func(TRACE_CALL (callback))

Allocate OUT buffer, call a callback when the buffer is available.

Use default buffer size _func(alloc single standard buffer). If buffer is available, schedules callback for execution immediately. If no buffers are available now, schedule callback later, when buffer will be available.

Parameters
callback- callback to call.
Returns
RET_OK or error code.
#define zb_buf_get_out_delayed_ext (   callback,
  arg,
  max_size 
)    zb_buf_get_out_delayed_ext_func(TRACE_CALL (callback),(arg),(max_size))

Allocate OUT buffer, call a callback when the buffer is available.

If buffer is available, schedules callback for execution immediately. If no buffers are available now, schedule callback later, when buffer will be available.

Parameters
callback- callback to call.
arg- second argument for a callback
max_sizerequired maximum buffer payload size (in bytes). It can be bigger or smaller than the default buffer size. Depending on the specific value, the buffer pool may decide to use a fraction of buffer or long buffers. Special value 0 means "single default buffer".
Returns
RET_OK or error code.
#define ZB_BUF_GET_PARAM (   buf,
  type 
)    ((type *)zb_buf_get_tail_func(TRACE_CALL (buf), sizeof(type)))

Get buffer tail of size sizeof(type)

Usually used to place external information _func(some parameters) to the buffer

Parameters
buf- buffer ID
type- data type that will be placed at the buffer end
Returns
pointer to the buffer tail casted to _func(type*)

Example

zb_zdo_nwk_addr_req_param_t *req = ZB_BUF_GET_PARAM(buf, zb_zdo_nwk_addr_req_param_t);
req->dst_addr = 0xffff;
ZB_IEEE_ADDR_COPY_func(req->ieee_addr, g_ieee_addr_r4);
req->start_index = 0;
req->request_type = 0x00;
zb_zdo_nwk_addr_req(ZB_REF_FROM_BUF_func(buf), NULL);
#define zb_buf_get_status (   buf)    zb_buf_get_status_func(TRACE_CALL (buf))

Get 'status' field of the buffer's header

Parameters
buf- buffer ID
Returns
status field value
#define zb_buf_get_tail (   buf,
  size 
)    zb_buf_get_tail_func(TRACE_CALL (buf),(size))

Get or allocate buffer tail of size 'size'. Do not initialize.

Usually used to get or place external information (some parameters) to the buffer.

Parameters
buf- buffer ID
size- requested size
Returns
pointer to the buffer tail
#define zb_buf_initial_alloc (   buf,
  size 
)    zb_buf_initial_alloc_func(TRACE_CALL (buf),(size))

Initial data space allocation in buffer.

Allocate space in the buffer center (keep space in both buffer head and tail). Use it at upper layers before filling buffer by data. Old buffer contents is lost.

Parameters
buf- buffer ID
size- size to allocate
Returns
pointer to buffer data begin
#define zb_buf_len (   buf)    zb_buf_len_func(TRACE_CALL (buf))

Return current buffer length

Parameters
buf- buffer ID
Returns
size of data placed in buffer
#define zb_buf_ptr (   buf)    zb_buf_ptr_func(TRACE_CALL (buf))

Return pointer to the memory of the buffer

Parameters
buf- buffer ID
Returns
pointer to the first byte of the buffer memory
#define zb_buf_reuse (   buf)    zb_buf_reuse_func(TRACE_CALL (buf))

Reuse buffer data space by setting data start and length to 0 and zeroing buffer contents

Parameters
buf- buffer ID
Returns
pointer to the buf data buffer begin
#define zb_buf_set_data_offset (   buf,
  off 
)    zb_buf_set_data_offset_func(TRACE_CALL (buf), (off))

Set buffer data offset

Parameters
buf- buffer ID
off- data offset
#define zb_buf_set_handle (   buf,
  handle 
)    zb_buf_set_handle_func(TRACE_CALL (buf),(handle))

Set 'handle' field of the buffer's header

Parameters
buf- buffer ID
handle- 'handle' field value
#define zb_buf_set_status (   buf,
  status 
)    zb_buf_set_status_func(TRACE_CALL (buf), (status))

Set 'status' field of the buffer's header

Parameters
buf- buffer ID
status- new status field value

Typedef Documentation

typedef enum zb_buf_flags_bm_e zb_buf_flags_bm_t

Buffer's internals flags bitmask

typedef struct zb_buf_hdr_s zb_buf_hdr_t

Packet buffer header.

zb_uint8_t zb_bufid_t

Buffer handler

typedef struct zb_leg_buf_s zb_leg_buf_t

Packet buffer (legacy)

typedef struct zb_mult_buf_s zb_mult_buf_t

Packet buffer

Enumeration Type Documentation

enum zb_buf_flags_bm_e

Buffer's internals flags bitmask

Enumerator
ZB_BUF_SECUR_NWK_ENCR 

Encrypt flags. That enum is actually bitmask.NWK frame encryption

ZB_BUF_SECUR_APS_ENCR 

APS encryption. Analyze APS header to define which key to use

ZB_BUF_SECUR_MAC_ENCR 

MAC encryption - for 802.15.4 certification only

enum zb_buffer_types_e

Buffer type (direction).

Enumerator
ZB_OUT_BUFFER 

Out buffer

ZB_IN_BUFFER 

In buffer

Function Documentation

zb_bool_t zb_buf_get_mac_rx_need ( void  )

Get "mac needs more buffers" flag.

To be used internally by ZBOSS.

Returns
"mac needs more buffers" flag value
zb_bool_t zb_buf_is_oom_state ( void  )

Check if buffer pool is in Out Of Memory (OOM) state

Returns
ZB_TRUE if ZBOSS is in OOM state
zb_bool_t zb_buf_memory_close_to_low ( void  )

Check if buffer pool is close to Out Of Memory (OOM) state

Returns
ZB_TRUE if ZBOSS is nearly in OOM state
zb_bool_t zb_buf_memory_low ( void  )

Check if buffer pool is close to Out Of Memory (OOM) state

Returns
ZB_TRUE if ZBOSS is nearly in OOM state
void zb_buf_oom_trace ( void  )

Trace buffer statistics into ZBOSS trace

void zb_buf_set_mac_rx_need ( zb_bool_t  needs)

Set or reset "mac needs more buffers" flag.

To be used internally by ZBOSS.

Parameters
needs- new "mac needs more buffers" flag value
Documentation feedback | Developer Zone | Subscribe | Updated