Packet Buffer

Table of Contents

• Allocating the packet buffer
• Reallocating the packet buffer
• Freeing the packet buffer
• Code examples
  • Allocating CoAP packet, with 100 bytes payload
  • Reallocating the UDP packet buffer to 10 bytes more
• Configuration parameters

The Packet Buffer module interfaces with the Memory Manager to allocate memory for the IPv6 stack layers, so each layer does not need to worry about the needed space for the headers of the layers below.

Allocating the packet buffer

To successfully allocate the packet buffer, the application has to use the iot_pbuffer_allocate function with the needed configuration. The application needs to specify the length, the type of buffer, and the allocation method.

The type of buffer depends on the use case and protocol layer

Buffer Type	Description
RAW_PACKET_TYPE	Raw packet, with no room made for the headers of any lower layer.
IPV6_PACKET_TYPE	Buffer for an entire IPv6 packet, pbuffer provisions for 40 bytes of IPv6 header.
ICMP6_PACKET_TYPE	Buffer for an ICMPv6 packet, and provision for 40 bytes of IPv6 header is made by pbuffer.
UDP6_PACKET_TYPE	Buffer for an UDP packet, and provision for 40 bytes of IPv6 header and UDP header is made by pbuffer.
COAP_PACKET_TYPE	Buffer for a CoAP packet, and provision for 4 bytes of CoAP header, 8 bytes of UDP Header + 40 bytes IPv6 header is made.

Any payload data and length are available by using the iot_pbuffer_t structure's p_payload and length value.

While allocating, the application needs to declare the memory allocation algorithm. When using the memory manager module set the PBUFFER_FLAG_DEFAULT flag, and when not using any memory allocation set the PBUFFER_FLAG_NO_MEM_ALLOCATION flag. In the second scenario, the application is responsible for pointing to the memory it wants to use, and to declare the length of it.

Reallocating the packet buffer

The Packet Buffer module also allows to reallocate buffers. iot_pbuffer_reallocate performs the following operation on reallocation. If the requested reallocation is less than or equal to the allocated size, no data movement is made, and the API returns a success. If the requested reallocation is more than previously allocated, the module requests new memory, backs up the existing data and then frees the previously allocated one.

In case reallocation is requested with the PBUFFER_FLAG_NO_MEM_ALLOCATION flag, the module will not free any previously allocated memory or copy it to the new location. It is understood that the application using the pbuffer is the best judge of when to move the data in the previously allocated memory and when it is ready to be freed.

Freeing the packet buffer

The API function iot_pbuffer_free is used to free a packet buffer. If the second parameter free_flag is set, the function tries to free the allocated memory. The operation does not depend on the PBUFFER_FLAG_DEFAULT or the PBUFFER_FLAG_NO_MEM_ALLOCATION flag.

Code examples

Allocating CoAP packet, with 100 bytes payload

uint32_t                    err_code;
iot_pbuffer_alloc_param_t   param;
iot_pbuffer_t             * p_buffer;

// Initialization of pbuffer module.
err_code = iot_pbuffer_init();
APP_ERROR_CHECK(err_code);

// Setup params.
param.flags  = PBUFFER_FLAG_DEFAULT;
param.length = 100;
param.type   = COAP_PACKET_TYPE;

// Allocate packet buffer.
err_code = iot_pbuffer_allocate(&param, &p_buffer);  
APP_ERROR_CHECK(err_code);

// Do other stuff with buffer..
memset(p_buffer->p_payload, 'A', 100);

Reallocating the UDP packet buffer to 10 bytes more

uint32_t                    err_code;
iot_pbuffer_alloc_param_t   param;
iot_pbuffer_t             * p_buffer;

// Initialization of pbuffer module.
err_code = iot_pbuffer_init();
APP_ERROR_CHECK(err_code);

// Setup params.
param.flags  = PBUFFER_FLAG_DEFAULT;
param.length = 50;
param.type   = UDP6_PACKET_TYPE;

// Allocate packet buffer.
err_code = iot_pbuffer_allocate(&param, &p_buffer);  
APP_ERROR_CHECK(err_code);

// Try to increase the size.
param.flags  = PBUFFER_FLAG_DEFAULT;
param.length = param.length + 10;
param.type   = UDP6_PACKET_TYPE;

// Allocate packet buffer.
err_code = iot_pbuffer_reallocate(&param, &p_buffer);  
APP_ERROR_CHECK(err_code);

Configuration parameters

The following configuration parameters should be defined in sdk_config.h.

IOT_PBUFFER_DISABLE_LOG

Disables debug tracing in the module. To enable tracing, this flag must be set to 0 and ENABLE_DEBUG_LOG_SUPPORT must be set to 1.

Description	Value
Enable debug trace	0
Disable debug trace	1
Dependencies	ENABLE_DEBUG_LOG_SUPPORT

IOT_PBUFFER_DISABLE_API_PARAM_CHECK

Disables API parameter checks in the module. Set this define to 1 to disable checks on API parameters in the module.

API parameter checks are added to ensure that the correct parameters are passed to the module. These checks are useful during development phase, but they might be redundant when the application is finalized. Disabling these checks might improve performance.

Description	Value
Enable API parameters check	0
Disable API parameters check	1
Dependencies	None

IOT_PBUFFER_MAX_COUNT

Maximum number of interfaces that can be managed by the module. This is usually as many 6LoWPAN channels as the application is configured to support.

Restriction	Value
Minimum value	1
Maximum value	255
Dependencies	None