Operations on packet events. More...

Functions
void *	em_packet_pointer (em_event_t pktev)

uint32_t	em_packet_size (em_event_t pktev)
	Get the packet size. More...

void *	em_packet_pointer_and_size (em_event_t pktev, uint32_t *size)
	Get the packet event data pointer as well as the packet size. More...

void *	em_packet_resize (em_event_t pktev, uint32_t size)
	Resize a packet event. More...

uint32_t	em_packet_headroom (em_event_t pktev)
	Packet event headroom length. More...

uint32_t	em_packet_tailroom (em_event_t pktev)
	Packet event tailroom length. More...

void *	em_packet_push_head (em_event_t pktev, uint32_t len)
	Push out the beginning of the packet into the headroom. More...

void *	em_packet_pull_head (em_event_t pktev, uint32_t len)
	Pull in the beginning of the packet from the headroom. More...

void *	em_packet_push_tail (em_event_t pktev, uint32_t len)
	Push out the end of the packet into the tailroom. More...

void *	em_packet_pull_tail (em_event_t pktev, uint32_t len)

em_status_t	em_packet_reset (em_event_t pktev, uint32_t size)

Detailed Description

Operations on packet events.

Packet events

Event (major) Type: EM_EVENT_TYPE_PACKET

EM APIs for basic manipulation of packet events (i.e. events allocated from EM pools created with event type EM_EVENT_TYPE_PACKET). More advanced packet manipulation should be done via ODP APIs by first converting the EM event to an ODP packet (see include/event_machine/platform/event_machine_odp_ext.h).

Packet events contain a certain amount of headroom before the start of the actual packet data. The headroom allows new data, e.g. additional protocol headers, to be inserted before the start of the existing packet data. The amount of headroom available for newly allocated packets can be configured globally via the EM config file or, specifically for a pool via the em_pool_cfg_t struct passed to em_pool_create(). Similarly, the packet may contain a certain amount of tailroom that can be used to extend the payload with additional data. The tailroom is located after the end of the packet payload until the end of the packet buffer. Pushing out the head/tail via APIs is required to include head- or tailroom into the packet data, see below.

The start of the packet data area can be modified by "pushing out" the head into the headroom or "pulling in" the head from the headroom. Similarly, the end of the packet data area can be modified by "pushing out" or "pulling in" the tail. Pushing out the head of the packet increases the packet data area from the beginning. This allows for e.g. insertion of new packet headers (prepend). Pulling in the head of the packet allows for e.g. dropping of packet headers from the beginning of the packet data. Pushing out the tail of the packet increases the packet data area at the end of the packet. This allows for extending the packet with new data (append). Pulling in the tail can be used to trim the end of unwanted data or set the packet size exactly so no extra data is present (avoids extra data over packet I/O).

Function Documentation

◆ em_packet_headroom()

uint32_t em_packet_headroom ( em_event_t pktev )

Packet event headroom length.

Returns the current length of the packet headroom.

Only events allocated from EM pools created with event type EM_EVENT_TYPE_PACKET can be used with this API.

Parameters

pktev Packet event handle

Returns: Headroom length

Return values

0	if no headroom, but also on error (e.g. if the event isn't a packet)

Definition at line 135 of file event_machine_packet.c.

◆ em_packet_pointer()

void* em_packet_pointer ( em_event_t pktev )

Get the packet event data pointer

Returns a pointer to the first byte of the packet data.

The data pointer can be adjusted with em_packet_push/pull_head().

Only events allocated from EM pools created with event type EM_EVENT_TYPE_PACKET can be used with this API.

Parameters

pktev Packet event handle

Returns: Pointer to the beginning of the packet data area

Return values

NULL on error

See also: em_event_pointer()

Definition at line 42 of file event_machine_packet.c.

◆ em_packet_pointer_and_size()

void* em_packet_pointer_and_size	(	em_event_t	pktev,
		uint32_t *	size
	)

Get the packet event data pointer as well as the packet size.

Returns a pointer to the first byte of the packet data and optionally outputs the packet payload size.

This API is a combination of em_packet_pointer() and em_packet_size() since both are often needed at the same time.

Only events allocated from EM pools created with event type EM_EVENT_TYPE_PACKET can be used with this API.

Parameters

	pktev	Packet event handle
[out]	size	Optional output arg into which the packet event payload size (in bytes) is stored. Use 'size=NULL' if no size information is needed. Only set by the function when no errors occurred.

Returns: Pointer to the beginning of the packet data area

Return values

NULL	on error ('size' not touched)

See also: em_packet_pointer(), em_packet_size(); em_event_pointer(), em_event_get_size(), em_event_pointer_and_size()

Definition at line 75 of file event_machine_packet.c.

◆ em_packet_pull_head()

void* em_packet_pull_head	(	em_event_t	pktev,
		uint32_t	len
	)

Pull in the beginning of the packet from the headroom.

Decrease the packet data length by removing data from the beginning (head) of the packet. The packet headroom is increased by the same amount. The packet head may be pulled in until only 1 byte of the packet data remains. The packet is not modified if there's not enough data.

Only events allocated from EM pools created with event type EM_EVENT_TYPE_PACKET can be used with this API.

The event is not modified on error.

Parameters

pktev	Packet event handle
len	The number of bytes to pull in the head with (0 ... packet data len - 1)

Returns: Pointer to the new beginning of the decreased packet data area

Return values

NULL	on unsupported event type, invalid length or other error

Definition at line 190 of file event_machine_packet.c.

◆ em_packet_pull_tail()

void* em_packet_pull_tail	(	em_event_t	pktev,
		uint32_t	len
	)

Pull in the end of the packet from the tailroom.

Decrease the packet data length by removing data from the end (tail) of the packet. The packet tailroom is increased by the same amount. The packet tail may be pulled in until only 1 byte of the packet data remains. The packet is not modified if there's not enough data.

Only events allocated from EM pools created with event type EM_EVENT_TYPE_PACKET can be used with this API.

The event is not modified on error.

Parameters

pktev	Packet event handle
len	The number of bytes to pull in the tail with (0 ... packet data len - 1)

Returns: Pointer to the end of the packet

Return values

NULL	on unsupported event type, invalid length or other error

Definition at line 236 of file event_machine_packet.c.

◆ em_packet_push_head()

void* em_packet_push_head	(	em_event_t	pktev,
		uint32_t	len
	)

Push out the beginning of the packet into the headroom.

Increase the packet data length by moving the beginning (head) of the packet into the packet headroom. The packet headroom is decreased by the same amount. The packet head may be pushed out by up to 'headroom' bytes. The packet is not modified if there's not enough space in the headroom.

Only events allocated from EM pools created with event type EM_EVENT_TYPE_PACKET can be used with this API.

The event is not modified on error.

Parameters

pktev	Packet event handle
len	The number of bytes to push out the head (0 ... headroom)

Returns: Pointer to the new beginning of the increased packet data area

Return values

NULL	on unsupported event type, invalid length or other error

Definition at line 167 of file event_machine_packet.c.

◆ em_packet_push_tail()

void* em_packet_push_tail	(	em_event_t	pktev,
		uint32_t	len
	)

Push out the end of the packet into the tailroom.

Increase the packet data length by moving the end (tail) of the packet into the packet tailroom. The packet tailroom is decreased by the same amount. The packet tail may be pushed out by up to 'tailroom' bytes. The packet is not modified if there's not enough space in the tailroom.

Only events allocated from EM pools created with event type EM_EVENT_TYPE_PACKET can be used with this API.

The event is not modified on error.

Parameters

pktev	Packet event handle
len	The number of bytes to push out the tail (0 ... tailroom)

Returns: Pointer to the start of the newly added data at the end of the packet

Return values

NULL	on unsupported event type or other error

Definition at line 213 of file event_machine_packet.c.

◆ em_packet_reset()

em_status_t em_packet_reset	(	em_event_t	pktev,
		uint32_t	size
	)

Reset a packet event

Resets packet event metadata and adjusts the start of the packet data back to pool (and subpool) defaults. The packet data size is set to 'size' and must fit the used subpool sizing.

The event type, set by em_alloc...() (or em_event_set_type()) is untouched by the reset-operation.

The event user area metadata is reset, i.e. the user area id is unset but the actual user area content is untouched.

Logically, this reset operation is similar to freeing the event and then allocating the same event again with a given 'size' and the same type (but without any actual free & alloc via the event pool being done).

This function must not be called for events with references.

Only events allocated from EM pools created with event type EM_EVENT_TYPE_PACKET can be used with this API.

Parameters

pktev	Packet event handle
size	Packet data size

Returns: EM_OK when successful or an EM error code on error.

Definition at line 259 of file event_machine_packet.c.

◆ em_packet_resize()

void* em_packet_resize	(	em_event_t	pktev,
		uint32_t	size
	)

Resize a packet event.

Set a new size for a packet, by adjusting the end of the packet via the packet tailroom. Only the end (tail) of the packet is modified to change the size, the beginning (head) is untouched.

The packet can be enlarged with max 'em_packet_tailroom()' bytes or reduced to min one (1) byte: 1 <= 'size' <= (em_packet_size() + em_packet_tailroom())

Only events allocated from EM pools created with event type EM_EVENT_TYPE_PACKET can be used with this API.

The event is not modified on error.

Parameters

pktev	Packet event handle
size	New size of the packet event (1 ... current-size + tailroom)

Returns: Pointer to the beginning of the packet data

Return values

NULL	on unsupported event type, invalid size or other error

See also: em_packet_push_tail(), em_packet_pull_tail()

Definition at line 98 of file event_machine_packet.c.

◆ em_packet_size()

uint32_t em_packet_size ( em_event_t pktev )

Get the packet size.

Returns the number of linearly accessible data bytes that follows after the current packet data pointer position.

Only events allocated from EM pools created with event type EM_EVENT_TYPE_PACKET can be used with this API.

Parameters

pktev Packet event handle

Returns: Packet data size in bytes following em_packet_pointer()

Return values

0 on error

Definition at line 58 of file event_machine_packet.c.

◆ em_packet_tailroom()

uint32_t em_packet_tailroom ( em_event_t pktev )

Packet event tailroom length.

Returns the current length of the packet tailroom.

Only events allocated from EM pools created with event type EM_EVENT_TYPE_PACKET can be used with this API.

Parameters

pktev Packet event handle

Returns: Tailroom length

Return values

0	if no tailroom, but also on error (e.g. if the event isn't a packet)

Definition at line 151 of file event_machine_packet.c.

Functions

Detailed Description

Packet events

Function Documentation

◆ em_packet_headroom()

◆ em_packet_pointer()

◆ em_packet_pointer_and_size()

◆ em_packet_pull_head()

◆ em_packet_pull_tail()

◆ em_packet_push_head()

◆ em_packet_push_tail()

◆ em_packet_reset()

◆ em_packet_resize()

◆ em_packet_size()

◆ em_packet_tailroom()