|
#define | ZB_RESERVED_BUF_TO_ALIGN_HDR_SIZE 1u |
|
#define | ZB_BUF_INVALID 0U |
|
#define | ZB_UNDEFINED_BUFFER 0U |
|
#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 free list. 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_len(buf) zb_buf_len_func(TRACE_CALL (buf)) |
|
#define | zb_buf_copy(dst_buf, src_buf) zb_buf_copy_func(TRACE_CALL (dst_buf),(src_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), (zb_ret_t)(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)) |
|
#define | ZB_BUF_COPY_FLAG_APS_PAYLOAD(dst, src) |
|
- 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:
- current layer data pointer
- current layer length
- 'status' for 'confirm' interface
- 'handle' for data and confirm interfaces
- flags
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().
◆ zb_buf_alloc_left
#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
◆ zb_buf_alloc_right
#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
◆ zb_buf_alloc_tail
#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.
◆ zb_buf_begin
#define zb_buf_begin |
( |
|
buf | ) |
zb_buf_begin_func(TRACE_CALL (buf)) |
Return pointer to data stored in buffer
- Parameters
-
- Returns
- pointer to beginning of data in buffer
◆ zb_buf_copy
#define zb_buf_copy |
( |
|
dst_buf, |
|
|
|
src_buf |
|
) |
| zb_buf_copy_func(TRACE_CALL (dst_buf),(src_buf)) |
Copy one buffer to another
- Parameters
-
dst_buf | - destination buffer |
src_buf | - source buffer |
◆ ZB_BUF_COPY_FLAG_APS_PAYLOAD
#define ZB_BUF_COPY_FLAG_APS_PAYLOAD |
( |
|
dst, |
|
|
|
src |
|
) |
| |
Value: do { \
{ \
\
{ \
} \
} \
} while(0)
◆ zb_buf_cut_left
#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
◆ zb_buf_cut_right
#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 |
◆ zb_buf_end
#define zb_buf_end |
( |
|
buf | ) |
zb_buf_end_func(TRACE_CALL (buf)) |
Return pointer to the data section end
- Parameters
-
- Returns
- pointer to the first byte after data in the buffer
◆ zb_buf_flags_clr
#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
- buf_flags_bm
◆ zb_buf_flags_clr_encr
#define zb_buf_flags_clr_encr |
( |
|
buf | ) |
zb_buf_flags_clr_encr_func(TRACE_CALL (buf)) |
◆ zb_buf_flags_get
#define zb_buf_flags_get |
( |
|
buf | ) |
zb_buf_flags_get_func(TRACE_CALL (buf)) |
Get buffer's flags byte
- Parameters
-
- Returns
- flags value -
- See also
- buf_flags_bm
◆ zb_buf_flags_or
#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 |
◆ zb_buf_free
#define zb_buf_free |
( |
|
buf | ) |
zb_buf_free_func(TRACE_CALL (buf)) |
Free packet buffer and put it into free list.
Can be called from the main loop.
- Parameters
-
◆ zb_buf_get
#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_in | if ZB_TRUE, allocate IN buffer, else allocate OUT buffer |
max_size | required 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
◆ zb_buf_get_any
#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.
◆ zb_buf_get_handle
#define zb_buf_get_handle |
( |
|
buf | ) |
zb_buf_get_handle_func(TRACE_CALL (buf)) |
Get 'handle' field of the buffer's header
- Parameters
-
- Returns
- handle field value
◆ zb_buf_get_hipri
#define zb_buf_get_hipri |
( |
|
a | ) |
zb_buf_get_hipri_func(TRACE_CALL (a)) |
Synchronous allocation of the high-priority buffer
◆ zb_buf_get_in_delayed
#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.
◆ zb_buf_get_in_delayed_ext
#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_size | required maximum buffer payload size (in bytes). The buffer payload size is the sum of both data and parameters, so the max_size parameter should reflect this. 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. If the value is set to 0, the payload size will be equal to the size of a single default buffer. |
- Returns
- RET_OK if allocation has successfully scheduled. RET_ERROR if there is no room to schedule buffer allocation. RET_OUT_OF_RANGE if buffer with such payload size can't be allocated.
◆ zb_buf_get_max_size
#define zb_buf_get_max_size |
( |
|
a | ) |
zb_buf_get_max_size_func(TRACE_CALL (a)) |
Return maximum data size for that buffer.
◆ zb_buf_get_out
#define zb_buf_get_out |
( |
| ) |
zb_buf_get_out_func(TRACE_CALL_VOID) |
Allocate OUT buffer of the default size.
◆ zb_buf_get_out_delayed
#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.
◆ zb_buf_get_out_delayed_ext
#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_size | - required maximum buffer payload size (in bytes). The buffer payload size is the sum of both data and parameters, so the max_size parameter should reflect this. 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. If the value is set to 0, the payload size will be equal to the size of a single default buffer. |
- Returns
- RET_OK if allocation has successfully scheduled. RET_ERROR if there is no room to schedule buffer allocation. RET_OUT_OF_RANGE if buffer with such payload size can't be allocated.
◆ ZB_BUF_GET_PARAM
#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
-
[in] | buf | - buffer ID |
[in] | type | - data type that will be placed at the buffer end |
- Returns
- pointer to the buffer tail casted to _func(type*)
Example
{
if (dev_idx != ERL_GW_INVALID_DEV_INDEX)
{
req_param->
nwk_addr = g_device_ctx.devices[dev_idx].short_addr;
}
else
{
TRACE_MSG(TRACE_APP2,
"No devices in discovery state were found!", (FMT__0));
}
}
◆ zb_buf_get_status
#define zb_buf_get_status |
( |
|
buf | ) |
zb_buf_get_status_func(TRACE_CALL (buf)) |
Get 'status' field of the buffer's header
- Parameters
-
- Returns
- status field value
◆ zb_buf_get_tail
#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
◆ ZB_BUF_HAS_APS_PAYLOAD
#define ZB_BUF_HAS_APS_PAYLOAD (1U << 6) |
Flag to indicate whether the buffer contains any APS payload
◆ ZB_BUF_HAS_APS_USER_PAYLOAD
#define ZB_BUF_HAS_APS_USER_PAYLOAD (1U << 7) |
Flag to indicate whether the buffer contains APS user payload
◆ zb_buf_initial_alloc
#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
◆ zb_buf_len
#define zb_buf_len |
( |
|
buf | ) |
zb_buf_len_func(TRACE_CALL (buf)) |
Return current buffer length
- Parameters
-
- Returns
- size of data placed in buffer
◆ zb_buf_reuse
#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
-
- Returns
- pointer to the buf data buffer begin
◆ ZB_BUF_SECUR_APS_ENCR
#define ZB_BUF_SECUR_APS_ENCR (1U << 2) |
APS encryption. Analyze APS header to define which key to use
◆ ZB_BUF_SECUR_MAC_ENCR
#define ZB_BUF_SECUR_MAC_ENCR (1U << 3) |
MAC encryption - for 802.15.4 certification only
◆ ZB_BUF_SECUR_NO_ENCR
#define ZB_BUF_SECUR_NO_ENCR 0U |
◆ ZB_BUF_SECUR_NWK_ENCR
#define ZB_BUF_SECUR_NWK_ENCR (1U << 1) |
◆ zb_buf_set_handle
#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 |
◆ zb_buf_set_status
#define zb_buf_set_status |
( |
|
buf, |
|
|
|
status |
|
) |
| zb_buf_set_status_func(TRACE_CALL (buf), (zb_ret_t)(status)) |
Set 'status' field of the buffer's header
- Parameters
-
buf | - buffer ID |
status | - new status field value |
◆ ZB_IN_BUFFER
◆ ZB_OUT_BUFFER
◆ zb_buf_flags_bm_t
Type for buffer's internals flags bitmask.
- Deprecated:
- holds one of buf_flags_bm. Kept only for backward compatibility as buf_flags_bm were declared previously as enum. Can be removed in future releases.
◆ zb_buf_hdr_t
◆ zb_buffer_types_t
Type for Buffer type (direction).
Holds one of buffer_types. Kept for backward compatibility as buffer_types were declared previously as enum.
◆ zb_bufid_t
◆ zb_leg_buf_t
◆ zb_mult_buf_t
◆ zb_buf_get_mac_rx_need()
Get "mac needs more buffers" flag.
To be used internally by ZBOSS.
- Returns
- "mac needs more buffers" flag value
◆ zb_buf_is_oom_state()
Check if buffer pool is in Out Of Memory (OOM) state
- Returns
- ZB_TRUE if ZBOSS is in OOM state
◆ zb_buf_memory_low()
Check if buffer pool is close to Out Of Memory (OOM) state
- Returns
- ZB_TRUE if ZBOSS is nearly in OOM state
◆ zb_buf_oom_trace()
void zb_buf_oom_trace |
( |
void |
| ) |
|
Trace buffer statistics into ZBOSS trace
◆ zb_buf_set_mac_rx_need()
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 |