Collaboration diagram for DOCA Buffer:

Functions
DOCA_STABLE doca_error_t	doca_buf_inc_refcount (struct doca_buf buf, uint16_t refcount)
	Increase the object reference count by 1. More...

DOCA_STABLE doca_error_t	doca_buf_dec_refcount (struct doca_buf buf, uint16_t refcount)
	Decrease the object reference count by 1, if 0 reached, return the element back to the inventory. More...

DOCA_STABLE doca_error_t	doca_buf_get_refcount (const struct doca_buf buf, uint16_t refcount)
	Get the reference count of the object. More...

DOCA_STABLE doca_error_t	doca_buf_get_len (const struct doca_buf buf, size_t len)
	Get the buffer's length. More...

DOCA_STABLE doca_error_t	doca_buf_get_head (const struct doca_buf buf, void *head)
	Get the buffer's head. More...

DOCA_STABLE doca_error_t	doca_buf_get_data_len (const struct doca_buf buf, size_t data_len)
	Get buffer's data length. More...

DOCA_STABLE doca_error_t	doca_buf_get_data (const struct doca_buf buf, void *data)
	Get the buffer's data. More...

DOCA_STABLE doca_error_t	doca_buf_set_data (struct doca_buf buf, void data, size_t data_len)

DOCA_STABLE doca_error_t	doca_buf_set_data_len (struct doca_buf *buf, size_t data_len)

DOCA_STABLE doca_error_t	doca_buf_reset_data_len (struct doca_buf *buf)

DOCA_STABLE doca_error_t	doca_buf_get_next_in_list (struct doca_buf buf, struct doca_buf *next_buf)
	Get next DOCA Buf in linked list. More...

DOCA_STABLE doca_error_t	doca_buf_get_last_in_list (struct doca_buf buf, struct doca_buf *last_buf)
	Get last DOCA Buf in linked list. More...

DOCA_STABLE doca_error_t	doca_buf_is_last_in_list (const struct doca_buf buf, uint8_t is_last)
	Check if provided DOCA Buf is the last element in a linked list. More...

DOCA_STABLE doca_error_t	doca_buf_is_first_in_list (const struct doca_buf buf, uint8_t is_first)
	Check if provided DOCA Buf is the first element in a linked list. More...

DOCA_STABLE doca_error_t	doca_buf_is_in_list (const struct doca_buf buf, uint8_t is_in_list)
	Check if provided DOCA Buf is a linked list. More...

DOCA_STABLE doca_error_t	doca_buf_get_list_len (const struct doca_buf buf, uint32_t num_elements)
	Get the number of the elements in list. More...

DOCA_STABLE doca_error_t	doca_buf_chain_list (struct doca_buf list1, struct doca_buf list2)
	Append list2 to list1. More...

DOCA_EXPERIMENTAL doca_error_t	doca_buf_chain_list_tail (struct doca_buf list1_head, struct doca_buf list1_tail, struct doca_buf *list2)
	Append list2 to list1. More...

DOCA_STABLE doca_error_t	doca_buf_unchain_list (struct doca_buf list1, struct doca_buf list2)
	Separate list2 from list1. More...

Detailed Description

The DOCA Buffer is used for reference data. It holds the information on a memory region that belongs to a DOCA memory map, and its descriptor is allocated from DOCA Buffer Inventory.

Function Documentation

◆ doca_buf_chain_list()

DOCA_STABLE doca_error_t doca_buf_chain_list	(	struct doca_buf *	list1,
		struct doca_buf *	list2
	)

Append list2 to list1.

Before:
          +----+  +----+  +----+
list1 ->  |1   |->|2   |->|3   |
          +----+  +----+  +----+
 
          +----+  +----+
list2 ->  |4   |->|5   |
          +----+  +----+
 
After:
 
          +----+  +----+  +----+  +----+  +----+
list1 ->  |1   |->|2   |->|3   |->|4   |->|5   |
          +----+  +----+  +----+  +----+  +----+
                                 /
                              list2

Parameters

[in]	list1	DOCA Buf representing list1. MUST NOT BE NULL AND MUST BE HEAD OF LIST.
[in]	list2	DOCA Buf representing list2. MUST NOT BE NULL AND MUST BE HEAD OF LIST. must have a refcount of 1

Returns

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

DOCA_ERROR_NOT_PERMITTED - if list2 has a reference count that is not 1

◆ doca_buf_chain_list_tail()

DOCA_EXPERIMENTAL doca_error_t doca_buf_chain_list_tail	(	struct doca_buf *	list1_head,
		struct doca_buf *	list1_tail,
		struct doca_buf *	list2
	)

Append list2 to list1.

Before:
          +----+  +----+  +----+
list1 ->  |1   |->|2   |->|3   |
          +----+  +----+  +----+
 
          +----+  +----+
list2 ->  |4   |->|5   |
          +----+  +----+
 
After:
 
          +----+  +----+  +----+  +----+  +----+
list1 ->  |1   |->|2   |->|3   |->|4   |->|5   |
          +----+  +----+  +----+  +----+  +----+
                                 /
                              list2

Parameters

[in]	list1_head	DOCA Buf representing list1. MUST NOT BE NULL AND MUST BE HEAD OF LIST.
[in]	list1_tail	DOCA Buf representing list1 tail. MUST NOT BE NULL AND MUST BE TAIL OF LIST 1.
[in]	list2	DOCA Buf representing list2. MUST NOT BE NULL AND MUST BE HEAD OF LIST. must have a refcount of 1

Returns

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

DOCA_ERROR_NOT_PERMITTED - if list2 has a reference count that is not 1

◆ doca_buf_dec_refcount()

DOCA_STABLE doca_error_t doca_buf_dec_refcount	(	struct doca_buf *	buf,
		uint16_t *	refcount
	)

Decrease the object reference count by 1, if 0 reached, return the element back to the inventory.

When refcount 0 reached, all related resources should be released. For example if the element points into some mmap its state will be adjusted accordingly.

Parameters

[in]	buf	DOCA Buf element. MUST NOT BE NULL.
[out]	refcount	The number of references to the object before this operation took place. Can be NULL.

Returns

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

DOCA_ERROR_NOT_PERMITTED - buf is the next element in some list.
DOCA_ERROR_BAD_STATE - reference count is already 0.

Note: In case of list if head refcount reaches 0, then all buffers in the list will be released.

◆ doca_buf_get_data()

DOCA_STABLE doca_error_t doca_buf_get_data	(	const struct doca_buf *	buf,
		void **	data
	)

Get the buffer's data.

Parameters

[in]	buf	DOCA Buf element. MUST NOT BE NULL.
[out]	data	The data of the buffer. MUST NOT BE NULL.

Returns: DOCA_SUCCESS - always.

◆ doca_buf_get_data_len()

DOCA_STABLE doca_error_t doca_buf_get_data_len	(	const struct doca_buf *	buf,
		size_t *	data_len
	)

Get buffer's data length.

Parameters

[in]	buf	DOCA Buf element. MUST NOT BE NULL.
[out]	data_len	The data length of the buffer. MUST NOT BE NULL.

Returns: DOCA_SUCCESS - always.

◆ doca_buf_get_head()

DOCA_STABLE doca_error_t doca_buf_get_head	(	const struct doca_buf *	buf,
		void **	head
	)

Get the buffer's head.

Parameters

[in]	buf	DOCA Buf element. MUST NOT BE NULL.
[out]	head	The head of the buffer. MUST NOT BE NULL.

Returns: DOCA_SUCCESS - always.

◆ doca_buf_get_last_in_list()

DOCA_STABLE doca_error_t doca_buf_get_last_in_list	(	struct doca_buf *	buf,
		struct doca_buf **	last_buf
	)

Get last DOCA Buf in linked list.

Parameters

[in]	buf	DOCA Buf element.
[out]	last_buf	The last DOCA Buf in the linked list, which may be buf.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.

◆ doca_buf_get_len()

DOCA_STABLE doca_error_t doca_buf_get_len	(	const struct doca_buf *	buf,
		size_t *	len
	)

Get the buffer's length.

Parameters

[in]	buf	DOCA Buf element. MUST NOT BE NULL.
[out]	len	The length of the buffer. MUST NOT BE NULL.

Returns: DOCA_SUCCESS - always.

◆ doca_buf_get_list_len()

DOCA_STABLE doca_error_t doca_buf_get_list_len	(	const struct doca_buf *	buf,
		uint32_t *	num_elements
	)

Get the number of the elements in list.

Parameters

[in]	buf	DOCA Buf element. Buf must be a head of a list.
[out]	num_elements	Number of elements in list.

Returns

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

DOCA_ERROR_INVALID_VALUE - if an invalid input had been received.
DOCA_ERROR_NOT_PERMITTED - if the buffer is not a head of a list.

◆ doca_buf_get_next_in_list()

DOCA_STABLE doca_error_t doca_buf_get_next_in_list	(	struct doca_buf *	buf,
		struct doca_buf **	next_buf
	)

Get next DOCA Buf in linked list.

Parameters

[in]	buf	DOCA Buf element. MUST NOT BE NULL.
[out]	next_buf	The next DOCA Buf in the linked list, *next_buf will be NULL if the no other element in the list. MUST NOT BE NULL.

Returns: DOCA_SUCCESS - always.

◆ doca_buf_get_refcount()

DOCA_STABLE doca_error_t doca_buf_get_refcount	(	const struct doca_buf *	buf,
		uint16_t *	refcount
	)

Get the reference count of the object.

Parameters

[in]	buf	DOCA Buf element. MUST NOT BE NULL.
[out]	refcount	The number of references to the object. MUST NOT BE NULL.

Returns: DOCA_SUCCESS - always.

◆ doca_buf_inc_refcount()

DOCA_STABLE doca_error_t doca_buf_inc_refcount	(	struct doca_buf *	buf,
		uint16_t *	refcount
	)

Increase the object reference count by 1.

Parameters

[in]	buf	DOCA Buf element.
[out]	refcount	The number of references to the object before this operation took place.

Returns

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

DOCA_ERROR_NOT_PERMITTED - buf is the next element in some list.
DOCA_ERROR_TOO_BIG - reference count already reached maximum value of UINT16_MAX.

Note: In case of list all intermediate buffers will always have a refcount of 1. As such the reference count is managed for the head only.

◆ doca_buf_is_first_in_list()

DOCA_STABLE doca_error_t doca_buf_is_first_in_list	(	const struct doca_buf *	buf,
		uint8_t *	is_first
	)

Check if provided DOCA Buf is the first element in a linked list.

Parameters

[in]	buf	DOCA Buf element.
[out]	is_first	1 if buf is the first element, 0 otherwise.

Returns: DOCA_SUCCESS - always.

◆ doca_buf_is_in_list()

DOCA_STABLE doca_error_t doca_buf_is_in_list	(	const struct doca_buf *	buf,
		uint8_t *	is_in_list
	)

Check if provided DOCA Buf is a linked list.

Parameters

[in]	buf	DOCA Buf element. MUST NOT BE NULL.
[out]	is_in_list	1 if buf is part of a linked list, 0 if it is not. MUST NOT BE NULL.

Returns: DOCA_SUCCESS - always.

◆ doca_buf_is_last_in_list()

DOCA_STABLE doca_error_t doca_buf_is_last_in_list	(	const struct doca_buf *	buf,
		uint8_t *	is_last
	)

Check if provided DOCA Buf is the last element in a linked list.

Parameters

[in]	buf	DOCA Buf element. MUST NOT BE NULL.
[out]	is_last	1 if buf is the last element, 0 otherwise. MUST NOT BE NULL.

Returns: DOCA_SUCCESS - always.

◆ doca_buf_reset_data_len()

DOCA_STABLE doca_error_t doca_buf_reset_data_len ( struct doca_buf * buf )

Reset the data length to 0 (data will still point to the same location)

Data positioning:
 
                __data_len__
               /            \
        +-----+--------------+--------------+
Before  |     |data          |              |
        +-----+--------------+--------------+
             /
           data
 
                data_len = 0
               /
        +-----+-----------------------------+
After   |     |                             |
        +-----+-----------------------------+
             /
           data

Parameters

[in] buf DOCA Buf element. MUST NOT BE NULL.

Returns: DOCA_SUCCESS - always

◆ doca_buf_set_data()

DOCA_STABLE doca_error_t doca_buf_set_data	(	struct doca_buf *	buf,
		void *	data,
		size_t	data_len
	)

Set data pointer and data length

Data positioning:
 
        +-----------+-----+-----------------+
Before  |           |data |                 |
        +-----------+-----+-----------------+
 
                __data_len__
               /            \
        +-----+--------------+--------------+
After   |     |data          |              |
        +-----+--------------+--------------+
             /
           data

Parameters

[in]	buf	DOCA Buf element. MUST NOT BE NULL.
[in]	data	Data address. MUST NOT BE NULL.
[in]	data_len	Data length.

Note: The range [data, data + data_len] must be in [head, head + len]. Otherwise undefined behavior.

Returns: DOCA_SUCCESS - always

◆ doca_buf_set_data_len()

DOCA_STABLE doca_error_t doca_buf_set_data_len	(	struct doca_buf *	buf,
		size_t	data_len
	)

Set data length

Data positioning:
                __data_len__
               /            \
        +-----+--------------+--------------+
Before  |     |data          |              |
        +-----+--------------+--------------+
             /
           data
 
                ____data_len____
               /                \
        +-----+------------------+----------+
After   |     |data              |          |
        +-----+------------------+----------+
             /
           data

Parameters

[in]	buf	DOCA Buf element. MUST NOT BE NULL.
[in]	data_len	Data length.

Note: The range [data, data + data_len] must be in [head, head + len]. Otherwise undefined behavior.

Returns: DOCA_SUCCESS - always

◆ doca_buf_unchain_list()

DOCA_STABLE doca_error_t doca_buf_unchain_list	(	struct doca_buf *	list1,
		struct doca_buf *	list2
	)

Separate list2 from list1.

Before:
          +----+  +----+  +----+  +----+  +----+
list1 ->  |1   |->|2   |->|3   |->|4   |->|5   |
          +----+  +----+  +----+  +----+  +----+
                                 /
                              list2
 
After:
          +----+  +----+  +----+
list1 ->  |1   |->|2   |->|3   |
          +----+  +----+  +----+
 
          +----+  +----+
list2 ->  |4   |->|5   |
          +----+  +----+

Parameters

[in]	list1	DOCA Buf representing list1. MUST NOT BE NULL.
[in]	list2	DOCA Buf representing list2, list2 should be contained in list1. list2 must be different from list1. MUST NOT BE NULL

Returns

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

DOCA_ERROR_INVALID_VALUE - if list2 is not part of list1.

Note: reference count of list2 will always be 1 after unchaining

Functions

Detailed Description

Function Documentation

◆ doca_buf_chain_list()

◆ doca_buf_chain_list_tail()

◆ doca_buf_dec_refcount()

◆ doca_buf_get_data()

◆ doca_buf_get_data_len()

◆ doca_buf_get_head()

◆ doca_buf_get_last_in_list()

◆ doca_buf_get_len()

◆ doca_buf_get_list_len()

◆ doca_buf_get_next_in_list()

◆ doca_buf_get_refcount()

◆ doca_buf_inc_refcount()

◆ doca_buf_is_first_in_list()

◆ doca_buf_is_in_list()

◆ doca_buf_is_last_in_list()

◆ doca_buf_reset_data_len()

◆ doca_buf_set_data()

◆ doca_buf_set_data_len()

◆ doca_buf_unchain_list()