Collaboration diagram for DOCA Buffer Inventory:

Functions
DOCA_STABLE doca_error_t	doca_buf_inventory_create (size_t num_elements, struct doca_buf_inventory **inventory)
	Allocates buffer inventory with default/unset attributes. More...

DOCA_STABLE doca_error_t	doca_buf_inventory_destroy (struct doca_buf_inventory *inventory)
	Destroy buffer inventory structure. More...

DOCA_STABLE doca_error_t	doca_buf_inventory_start (struct doca_buf_inventory *inventory)
	Start element retrieval from inventory. More...

DOCA_STABLE doca_error_t	doca_buf_inventory_stop (struct doca_buf_inventory *inventory)
	Stop element retrieval from inventory. More...

DOCA_STABLE doca_error_t	doca_buf_inventory_buf_get_by_args (struct doca_buf_inventory inventory, struct doca_mmap mmap, void addr, size_t len, void data, size_t data_len, struct doca_buf **buf)
	Allocate single element from buffer inventory and point it to the buffer defined by `addr`, `len`, `data` and `data_len` arguments. More...

static doca_error_t	doca_buf_inventory_buf_get_by_addr (struct doca_buf_inventory inventory, struct doca_mmap mmap, void addr, size_t len, struct doca_buf *buf)
	Allocate single element from buffer inventory and point it to the buffer defined by `addr` & `len` arguments. More...

static doca_error_t	doca_buf_inventory_buf_get_by_data (struct doca_buf_inventory inventory, struct doca_mmap mmap, void data, size_t data_len, struct doca_buf *buf)
	Allocate single element from buffer inventory and point it to the buffer defined by `data` & `data_len` arguments. More...

DOCA_STABLE doca_error_t	doca_buf_inventory_buf_dup (struct doca_buf_inventory inventory, const struct doca_buf src_buf, struct doca_buf **dst_buf)
	Duplicates content of the `buf` argument into element allocated from buffer inventory. (I.e., deep copy). More...

DOCA_STABLE doca_error_t	doca_buf_inventory_set_user_data (struct doca_buf_inventory *inventory, union doca_data user_data)
	Set user_data for a DOCA Buffer Inventory. More...

DOCA_STABLE doca_error_t	doca_buf_inventory_get_num_elements (const struct doca_buf_inventory inventory, uint32_t num_of_elements)
	Read the total number of elements in a DOCA Buffer Inventory. More...

DOCA_STABLE doca_error_t	doca_buf_inventory_get_num_free_elements (const struct doca_buf_inventory inventory, uint32_t num_of_free_elements)
	Get the total number of free elements in a DOCA Buffer Inventory. More...

DOCA_STABLE doca_error_t	doca_buf_inventory_get_user_data (const struct doca_buf_inventory inventory, union doca_data user_data)
	Get the user_data of a DOCA Buffer Inventory. More...

DOCA_EXPERIMENTAL doca_error_t	doca_buf_inventory_expand (struct doca_buf_inventory *inventory, uint32_t num_elements)
	Expand the inventory. More...

Detailed Description

The DOCA buffer inventory manages a pool of doca_buf objects. Each buffer obtained from an inventory is a descriptor that points to a memory region from a doca_mmap memory range of the user's choice.

Function Documentation

◆ doca_buf_inventory_buf_dup()

DOCA_STABLE doca_error_t doca_buf_inventory_buf_dup	(	struct doca_buf_inventory *	inventory,
		const struct doca_buf *	src_buf,
		struct doca_buf **	dst_buf
	)

Duplicates content of the buf argument into element allocated from buffer inventory. (I.e., deep copy).

Call doca_buf_dec_refcount to return the buffer to the inventory (until ref count == 0).

Parameters

[in]	inventory	Buffer inventory structure that will hold the new doca_buf.
[in]	src_buf	The DOCA buf to be duplicated.
[out]	dst_buf	A duplicate DOCA Buf.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_BAD_STATE - if src_buf mmap or input inventory unstarted/stopped.
DOCA_ERROR_NOT_PERMITTED - if src_buf is part of a list and it isn't its head.
DOCA_ERROR_NO_MEMORY - if cannot alloc new doca_buf from the given inventory.

◆ doca_buf_inventory_buf_get_by_addr()

static doca_error_t doca_buf_inventory_buf_get_by_addr	(	struct doca_buf_inventory *	inventory,
		struct doca_mmap *	mmap,
		void *	addr,
		size_t	len,
		struct doca_buf **	buf
	)

inlinestatic

Allocate single element from buffer inventory and point it to the buffer defined by addr & len arguments.

Call doca_buf_dec_refcount to return the buffer to the inventory (until ref count == 0).

Parameters

[in]	inventory	The DOCA Buf inventory. MUST NOT BE NULL AND MUST BE STARTED.
[in]	mmap	DOCA memory map structure. MUST NOT BE NULL AND MUST BE STARTED.
[in]	addr	The start address of the payload.
[in]	len	The length in bytes of the payload.
[out]	buf	Doca buf allocated and initialized with args. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_NO_MEMORY - if doca_buf_inventory is empty.

Definition at line 197 of file doca_buf_inventory.h.

◆ doca_buf_inventory_buf_get_by_args()

DOCA_STABLE doca_error_t doca_buf_inventory_buf_get_by_args	(	struct doca_buf_inventory *	inventory,
		struct doca_mmap *	mmap,
		void *	addr,
		size_t	len,
		void *	data,
		size_t	data_len,
		struct doca_buf **	buf
	)

Allocate single element from buffer inventory and point it to the buffer defined by addr, len, data and data_len arguments.

Call doca_buf_dec_refcount to return the buffer to the inventory (until ref count == 0).

Parameters

[in]	inventory	The DOCA Buf inventory. MUST NOT BE NULL AND MUST BE STARTED.
[in]	mmap	DOCA memory map structure. MUST NOT BE NULL AND MUST BE STARTED.
[in]	addr	The start address of the buffer.
[in]	len	The length in bytes of the buffer.
[in]	data	The start address of the data inside the buffer.
[in]	data_len	The length in bytes of the data.
[out]	buf	Doca buf allocated and initialized with args. MUST NOT BE NULL.

Note: The range [data, data + data_len] must fit within [addr, addr +len]. Otherwise undefined behavior.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - or if there is no suitable memory range for the given address and length.
DOCA_ERROR_NO_MEMORY - if doca_buf_inventory is empty.

◆ doca_buf_inventory_buf_get_by_data()

static doca_error_t doca_buf_inventory_buf_get_by_data	(	struct doca_buf_inventory *	inventory,
		struct doca_mmap *	mmap,
		void *	data,
		size_t	data_len,
		struct doca_buf **	buf
	)

inlinestatic

Allocate single element from buffer inventory and point it to the buffer defined by data & data_len arguments.

Call doca_buf_dec_refcount to return the buffer to the inventory (until ref count == 0).

Parameters

[in]	inventory	The DOCA Buf inventory. MUST NOT BE NULL AND MUST BE STARTED.
[in]	mmap	DOCA memory map structure. MUST NOT BE NULL AND MUST BE STARTED.
[in]	data	The start address of the data inside the buffer.
[in]	data_len	The length in bytes of the data.
[out]	buf	Doca buf allocated and initialized with args. MUST NOT BE NULL.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_NO_MEMORY - if doca_buf_inventory is empty.

Definition at line 228 of file doca_buf_inventory.h.

◆ doca_buf_inventory_create()

DOCA_STABLE doca_error_t doca_buf_inventory_create	(	size_t	num_elements,
		struct doca_buf_inventory **	inventory
	)

Allocates buffer inventory with default/unset attributes.

The returned object can be manipulated with doca_buf_inventory_property_set() API. Once all required attributes are set, it should be reconfigured and adjusted to meet the setting with doca_buf_inventory_start(). See doca_buf_inventory_start for the rest of the details.

Parameters

[in]	num_elements	Initial number of elements in the inventory.
[out]	inventory	Buffer inventory with default/unset attributes.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NO_MEMORY - failed to alloc doca_buf_inventory.

◆ doca_buf_inventory_destroy()

DOCA_STABLE doca_error_t doca_buf_inventory_destroy ( struct doca_buf_inventory * inventory )

Destroy buffer inventory structure.

Before calling this function all allocated elements should be returned back to the inventory. Destroy implicitly stops the buf inventory. Call doca_buf_dec_refcount to return a buffer to the inventory (until ref count == 0).

Parameters

[in] inventory Buffer inventory structure.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_IN_USE - if not all allocated elements had been returned to the inventory.

◆ doca_buf_inventory_expand()

DOCA_EXPERIMENTAL doca_error_t doca_buf_inventory_expand	(	struct doca_buf_inventory *	inventory,
		uint32_t	num_elements
	)

Expand the inventory.

Add more doca_bufs to the inventory.

Parameters

[in]	inventory	Inventory to expand
[in]	num_elements	Number of doca_bufs to add to the inventory

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - inventory is not started.

◆ doca_buf_inventory_get_num_elements()

DOCA_STABLE doca_error_t doca_buf_inventory_get_num_elements	(	const struct doca_buf_inventory *	inventory,
		uint32_t *	num_of_elements
	)

Read the total number of elements in a DOCA Buffer Inventory.

The total number of elements type: uint32_t.

Parameters

[in]	inventory	The DOCA Buffer Inventory.
[out]	num_of_elements	The total number of elements in inventory.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

◆ doca_buf_inventory_get_num_free_elements()

DOCA_STABLE doca_error_t doca_buf_inventory_get_num_free_elements	(	const struct doca_buf_inventory *	inventory,
		uint32_t *	num_of_free_elements
	)

Get the total number of free elements in a DOCA Buffer Inventory.

The total number of free elements type: uint32_t.

Parameters

[in]	inventory	The DOCA Buffer Inventory.
[out]	num_of_free_elements	The total number of free elements in inventory.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

◆ doca_buf_inventory_get_user_data()

DOCA_STABLE doca_error_t doca_buf_inventory_get_user_data	(	const struct doca_buf_inventory *	inventory,
		union doca_data *	user_data
	)

Get the user_data of a DOCA Buffer Inventory.

The user_data that was provided to the inventory upon its creation.

Parameters

[in]	inventory	The DOCA Buffer Inventory.
[out]	user_data	The user_data of inventory if set, otherwise 0.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.

◆ doca_buf_inventory_set_user_data()

DOCA_STABLE doca_error_t doca_buf_inventory_set_user_data	(	struct doca_buf_inventory *	inventory,
		union doca_data	user_data
	)

Set user_data for a DOCA Buffer Inventory.

Parameters

[in]	inventory	The DOCA Buffer Inventory.
[in]	user_data	The user_data to set for inventory.

Returns

DOCA_SUCCESS - in case of success. Error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_BAD_STATE - if inventory is un-started/stopped.

◆ doca_buf_inventory_start()

DOCA_STABLE doca_error_t doca_buf_inventory_start ( struct doca_buf_inventory * inventory )

Start element retrieval from inventory.

Un-started/stopped buffer inventory rejects all attempts to retrieve element. On first start verifies & finalizes the buffer inventory object configuration.

The following become possible only after start:

Retrieval of free elements from the inventory using doca_buf_inventory_buf_get_by_addr().
Duplicating a buffer's content into a buffer allocated from the inventory using doca_buf_inventory_buf_dup().

The following are NOT possible after the first time start is called:

Setting the properties of the inventory using doca_buf_inventory_property_set().

Parameters

[in] inventory Buffer inventory structure.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

◆ doca_buf_inventory_stop()

DOCA_STABLE doca_error_t doca_buf_inventory_stop ( struct doca_buf_inventory * inventory )

Stop element retrieval from inventory.

No retrieval of elements with for stopped inventory. Stop does not have to be called before destroy (that implicitly stops the buf inventory). For details see doca_buf_inventory_start().

Parameters

[in] inventory Buffer inventory structure.

Returns

DOCA_SUCCESS - in case of success. doca_error code - in case of failure:

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

Functions

Detailed Description

Function Documentation

◆ doca_buf_inventory_buf_dup()

◆ doca_buf_inventory_buf_get_by_addr()

◆ doca_buf_inventory_buf_get_by_args()

◆ doca_buf_inventory_buf_get_by_data()

◆ doca_buf_inventory_create()

◆ doca_buf_inventory_destroy()

◆ doca_buf_inventory_expand()

◆ doca_buf_inventory_get_num_elements()

◆ doca_buf_inventory_get_num_free_elements()

◆ doca_buf_inventory_get_user_data()

◆ doca_buf_inventory_set_user_data()

◆ doca_buf_inventory_start()

◆ doca_buf_inventory_stop()