NVIDIA DOCA SDK Data Center on a Chip Framework Documentation
Functions
DOCA Buffer Pool
DOCA Core
Collaboration diagram for DOCA Buffer Pool:

Functions

DOCA_STABLE doca_error_t doca_buf_pool_create (size_t num_elements, size_t element_size, const struct doca_mmap *mmap, struct doca_buf_pool **buf_pool)
 Allocates a buffer pool and sets it with doca_buf objects. More...
 
DOCA_STABLE doca_error_t doca_buf_pool_destroy (struct doca_buf_pool *buf_pool)
 Destroy a buffer pool structure. More...
 
DOCA_STABLE doca_error_t doca_buf_pool_start (struct doca_buf_pool *buf_pool)
 Start a DOCA buffer pool. More...
 
DOCA_STABLE doca_error_t doca_buf_pool_stop (struct doca_buf_pool *buf_pool)
 Stop a started DOCA buffer pool. More...
 
DOCA_STABLE doca_error_t doca_buf_pool_buf_alloc (struct doca_buf_pool *buf_pool, struct doca_buf **buf)
 This method acquires a doca_buf from a DOCA buffer pool, pointing to an allocated empty buffer. More...
 
DOCA_STABLE doca_error_t doca_buf_pool_set_user_data (struct doca_buf_pool *buf_pool, union doca_data user_data)
 Set user_data for a DOCA buffer pool. More...
 
DOCA_STABLE doca_error_t doca_buf_pool_set_element_alignment (struct doca_buf_pool *buf_pool, size_t element_alignment)
 Set an alignment for each element in a DOCA buffer pool. More...
 
DOCA_STABLE doca_error_t doca_buf_pool_get_num_elements (const struct doca_buf_pool *buf_pool, uint32_t *num_of_elements)
 Get the number of elements that was set in the creation of a DOCA buffer pool. More...
 
DOCA_STABLE doca_error_t doca_buf_pool_get_num_free_elements (const struct doca_buf_pool *buf_pool, uint32_t *num_of_free_elements)
 Get the total number of free elements available for allocation in a DOCA buffer pool. More...
 
DOCA_STABLE doca_error_t doca_buf_pool_get_user_data (const struct doca_buf_pool *buf_pool, union doca_data *user_data)
 Get the user_data of a DOCA buffer pool. More...
 
DOCA_STABLE doca_error_t doca_buf_pool_get_element_alignment (const struct doca_buf_pool *buf_pool, size_t *element_alignment)
 Get the element alignment of a DOCA buffer pool. More...
 

Detailed Description

The DOCA Buffer Pool is a pool of doca_buf objects, such that each doca_buf is set with a permanent, fixed size memory buffer, right from creation and till destruction, which allows immediate allocation of doca_buf objects.

Basic structure example of a Buffer Pool (after creation):
+------------------------------------------+
| memory range |
+-----------+ | +--------+ +--------+ +--------+ |
| doca_mmap |-----------| | buffer | | buffer | | buffer | |
+-----------+ | +--------+ +--------+ ..... +--------+ |
| \ \ \ |
+------------------------------------------+
\ \ \
\ \ \
+--------------------------------------------+
| | | | |
+---------------+ | +----------+ +----------+ +----------+ |
| doca_buf_pool |-------| | doca_buf | | doca_buf | | doca_buf | |
+---------------+ | +----------+ +----------+ ....+----------+ |
+--------------------------------------------+

Function Documentation

◆ doca_buf_pool_buf_alloc()

DOCA_STABLE doca_error_t doca_buf_pool_buf_alloc ( struct doca_buf_pool *  buf_pool,
struct doca_buf **  buf 
)

This method acquires a doca_buf from a DOCA buffer pool, pointing to an allocated empty buffer.

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

Parameters
[in]buf_poolThe DOCA buf_pool from which to acquire a doca_buf, that was set to point to a memory buffer at doca_buf_pool_create().
[out]bufPointer to the allocated doca_buf.

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 buf_pool is un-started/stopped.
  • DOCA_ERROR_EMPTY - if the buf_pool is empty (all doca_bufs are already allocated).

◆ doca_buf_pool_create()

DOCA_STABLE doca_error_t doca_buf_pool_create ( size_t  num_elements,
size_t  element_size,
const struct doca_mmap *  mmap,
struct doca_buf_pool **  buf_pool 
)

Allocates a buffer pool and sets it with doca_buf objects.

Parameters
[in]num_elementsNumber of elements in the buffer pool (must be > 0).
[in]element_sizeSize of a single element (must be > 0).
[in]mmapThe mmap managing the memory chunk. Must be populated with memory chunk.
[out]buf_poolThe newly created DOCA buf_pool.
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 allocate a doca_buf_pool.

◆ doca_buf_pool_destroy()

DOCA_STABLE doca_error_t doca_buf_pool_destroy ( struct doca_buf_pool *  buf_pool)

Destroy a buffer pool structure.

Destroy implicitly stops the buf pool.

Note
Before Calling this method, all allocated doca_bufs should be returned back to the buffer pool. Call doca_buf_dec_refcount to return a buffer to the pool (until ref count == 0).
Parameters
[in]buf_poolThe DOCA buf_pool to destroy.
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 doca_bufs had been returned to buf_pool.

◆ doca_buf_pool_get_element_alignment()

DOCA_STABLE doca_error_t doca_buf_pool_get_element_alignment ( const struct doca_buf_pool *  buf_pool,
size_t *  element_alignment 
)

Get the element alignment of a DOCA buffer pool.

Note
- Unless set with doca_buf_pool_set_element_alignment(), element alignment is 1 by default (meaning no alignment).
Parameters
[in]buf_poolThe DOCA buf_pool.
[out]element_alignmentThe element alignment of buf_pool.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - received invalid input.

◆ doca_buf_pool_get_num_elements()

DOCA_STABLE doca_error_t doca_buf_pool_get_num_elements ( const struct doca_buf_pool *  buf_pool,
uint32_t *  num_of_elements 
)

Get the number of elements that was set in the creation of a DOCA buffer pool.

Parameters
[in]buf_poolThe DOCA buf_pool.
[out]num_of_elementsThe number of elements that was set in the creation of buf_pool.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - received invalid input.

◆ doca_buf_pool_get_num_free_elements()

DOCA_STABLE doca_error_t doca_buf_pool_get_num_free_elements ( const struct doca_buf_pool *  buf_pool,
uint32_t *  num_of_free_elements 
)

Get the total number of free elements available for allocation in a DOCA buffer pool.

Parameters
[in]buf_poolThe DOCA buf_pool.
[out]num_of_free_elementsThe total number of free elements in buf_pool.
Returns
DOCA_SUCCESS - in case of success. Error code - in case of failure:
  • DOCA_ERROR_INVALID_VALUE - received invalid input.

◆ doca_buf_pool_get_user_data()

DOCA_STABLE doca_error_t doca_buf_pool_get_user_data ( const struct doca_buf_pool *  buf_pool,
union doca_data *  user_data 
)

Get the user_data of a DOCA buffer pool.

Note
- Unless set with doca_buf_pool_set_user_data(), user data is 0 by default.
Parameters
[in]buf_poolThe DOCA buf_pool.
[out]user_dataThe user_data of buf_pool 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_pool_set_element_alignment()

DOCA_STABLE doca_error_t doca_buf_pool_set_element_alignment ( struct doca_buf_pool *  buf_pool,
size_t  element_alignment 
)

Set an alignment for each element in a DOCA buffer pool.

Parameters
[in]buf_poolThe DOCA buf_pool.
[in]element_alignmentThe element alignment to set for buf_pool (minimal value is 1, must be a power of 2).
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 buf_pool is started.

◆ doca_buf_pool_set_user_data()

DOCA_STABLE doca_error_t doca_buf_pool_set_user_data ( struct doca_buf_pool *  buf_pool,
union doca_data  user_data 
)

Set user_data for a DOCA buffer pool.

Parameters
[in]buf_poolThe DOCA buf_pool.
[in]user_dataThe user_data to set for buf_pool.
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 buf_pool is started.

◆ doca_buf_pool_start()

DOCA_STABLE doca_error_t doca_buf_pool_start ( struct doca_buf_pool *  buf_pool)

Start a DOCA buffer pool.

This method enables the allocation of doca_bufs using doca_buf_pool_buf_alloc(). Before calling this method, the mmap with which the buffer pool was created must be started.

The following become possible only after start:

The following are NOT possible while buf_pool is started:

  • Setting properties of the buffer pool with doca_buf_pool_set_*.
Parameters
[in]buf_poolThe DOCA buf_pool to start.
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_INITIALIZATION - if the mmap's memory range is smaller than the required size according to the buf_pool's properties.
  • DOCA_ERROR_BAD_STATE - if the mmap with which buf_pool was created is not started.

◆ doca_buf_pool_stop()

DOCA_STABLE doca_error_t doca_buf_pool_stop ( struct doca_buf_pool *  buf_pool)

Stop a started DOCA buffer pool.

This method disables the allocation of doca_bufs, and re-enables Setting properties of the buffer pool with doca_buf_pool_set_*. Before Calling this method, all allocated doca_bufs should be returned back to the buffer pool. Stop does not have to be called before destroy (that implicitly stops the buf pool).

Parameters
[in]buf_poolThe DOCA buf_pool to stop.
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 doca_bufs had been returned to buf_pool.