Packet Buffer

Packet buffer management for IPv6 stack layers to minimize data copy across stack layers. More...

Data Structures
struct	iot_pbuffer_t
	Packet buffer used for exchanging IPv6 payload across layers in both receive and transmit paths. More...
struct	iot_pbuffer_alloc_param_t
	Parameters required to allocate the packet buffer. More...

Enumerations
enum	iot_pbuffer_type_t {   UNASSIGNED_TYPE = 0,   RAW_PACKET_TYPE = 1,   IPV6_PACKET_TYPE = 2,   ICMP6_PACKET_TYPE = 3,   UDP6_PACKET_TYPE = 4,   COAP_PACKET_TYPE = 5 }
	IPv6 packet type identifiers that are needed to ensure that enough space is reserved for headers from layers below during memory allocation. More...
enum	iot_pbuffer_flags_t {   PBUFFER_FLAG_DEFAULT = 0,   PBUFFER_FLAG_NO_MEM_ALLOCATION = 1 }
	Additional information that must be provided to the module during allocation or reallocation to ensure optimal utilization of memory and avoid unnecessary data copies. More...

Functions
uint32_t	iot_pbuffer_init (void)
	Function for initializing the module. More...
uint32_t	iot_pbuffer_allocate (iot_pbuffer_alloc_param_t *p_param, iot_pbuffer_t **pp_pbuffer)
	Function for allocating a packet buffer. More...
uint32_t	iot_pbuffer_reallocate (iot_pbuffer_alloc_param_t *p_param, iot_pbuffer_t *p_pbuffer)
	Function for reallocating a packet buffer. More...
uint32_t	iot_pbuffer_free (iot_pbuffer_t *p_pbuffer, bool free_flag)
	Function for freeing a packet buffer. More...

Detailed Description

Packet buffer management for IPv6 stack layers to minimize data copy across stack layers.

This module interfaces with the Memory Manager to allocate packet buffers for the IPv6 stack layers, without each layer having to ensure sufficient header space for layers below.

Enumeration Type Documentation

enum iot_pbuffer_flags_t

Additional information that must be provided to the module during allocation or reallocation to ensure optimal utilization of memory and avoid unnecessary data copies.

Enumerator
PBUFFER_FLAG_DEFAULT	Default behavior with respect to memory allocation when allocating packet buffer. Memory will be allocated for the length indicated by this default.
PBUFFER_FLAG_NO_MEM_ALLOCATION	Only allocate packet buffer, not memory. This is needed when a packet already exists and the packet buffer is needed only to feed it to the IPv6 stack.

enum iot_pbuffer_type_t

IPv6 packet type identifiers that are needed to ensure that enough space is reserved for headers from layers below during memory allocation.

Enumerator
UNASSIGNED_TYPE	Indicates that the packet buffer is unassigned and not in use.
RAW_PACKET_TYPE	Raw packet, with no room made for headers of any lower layer.
IPV6_PACKET_TYPE	Indicates that the packet buffer is requested for an entire IPv6 packet; pbuffer provisions 40 bytes of IPv6 header.
ICMP6_PACKET_TYPE	Indicates that the packet buffer is requested for an ICMPv6 packet, and provision for 40 bytes of IPv6 header is made by pbuffer.
UDP6_PACKET_TYPE	Indicates that the packet buffer is requested for a UDP packet, and provision for 40 bytes of IPv6 header and UDP header is made by pbuffer.
COAP_PACKET_TYPE	Indicates that the packet buffer is requested for a CoAP packet, and provision for 4 bytes of CoAP header, 8 bytes of UDP header, and 40 bytes of IPv6 header is made.

Function Documentation

uint32_t iot_pbuffer_allocate	(	iot_pbuffer_alloc_param_t *	p_param,
		iot_pbuffer_t **	pp_pbuffer
	)

Function for allocating a packet buffer.

Parameters

[in]	p_param	Pointer to allocation parameters that indicate the length of the payload requested, the type of payload, and additional information using the flags. This parameter cannot be NULL.
[out]	pp_pbuffer	Pointer to allocated packet buffer. This parameter shall not be NULL.

Return values

NRF_SUCCESS

If the packet buffer was successfully allocated. Otherwise, an error code that indicates the reason for the failure is returned.

uint32_t iot_pbuffer_free	(	iot_pbuffer_t *	p_pbuffer,
		bool	free_flag
	)

Function for freeing a packet buffer.

This function frees the packet buffer. If the parameter free_flag is set, the function tries to free the memory allocated as well. This action is performed irrespective of whether the memory was allocated using the PBUFFER_FLAG_DEFAULT or the PBUFFER_FLAG_NO_MEM_ALLOCATION flag.

Parameters

[in]	p_pbuffer	Pointer to the packet buffer requested to be freed. This parameter shall not be NULL.
[in]	free_flag	Indicates if the allocated memory should be freed or not when freeing the packet buffer.

Return values

NRF_SUCCESS

If the packet buffer was successfully freed. Otherwise, an error code that indicates the reason for the failure is returned.

uint32_t iot_pbuffer_init

(

void

)

Function for initializing the module.

Return values

NRF_SUCCESS

If the module was successfully initialized. Otherwise, an error code that indicates the reason for the failure is returned.

uint32_t iot_pbuffer_reallocate	(	iot_pbuffer_alloc_param_t *	p_param,
		iot_pbuffer_t *	p_pbuffer
	)

Function for reallocating a packet buffer.

Reallocation requests are treated as follows:

• If the requested reallocation is less than or equal to the allocated size, no data is moved, and the function returns NRF_SUCCESS.
• If the requested reallocation is more than what is allocated, the function requests new memory, backs up existing data, and then frees the previously allocated memory.
• If reallocation is requested with the PBUFFER_FLAG_NO_MEM_ALLOCATION flag, the function does not free previously allocated memory or copy it to the new location. In this case, the application that uses the pbuffer must decide when to move previously allocated memory and when to free it and handle this.

Parameters

[in]	p_param	Pointer to reallocation parameters that indicate the length of the payload requested, the type of payload, and additional information using the flags. This parameter cannot be NULL.
[in]	p_pbuffer	Pointer to the packet buffer being reallocated. This parameter shall not be NULL.

Return values

NRF_SUCCESS

If the packet buffer was successfully reallocated. Otherwise, an error code that indicates the reason for the failure is returned.