Collaboration diagram for DOCA DPDK Bridge:

Functions
DOCA_EXPERIMENTAL doca_error_t	doca_dpdk_cap_is_rep_port_supported (const struct doca_devinfo devinfo, uint8_t is_rep_port_supported)
	Check if the device supports representors for port_probe. More...

DOCA_EXPERIMENTAL doca_error_t	doca_dpdk_port_probe (struct doca_dev dev, const char devargs)
	Attach a DPDK port specified by DOCA device. More...

DOCA_EXPERIMENTAL doca_error_t	doca_dpdk_get_first_port_id (const struct doca_dev dev, uint16_t port_id)
	Return the first DPDK port id associated to a DOCA device. Assumption is that the doca device that was probed using doca_dpdk_port_probe(). More...

DOCA_EXPERIMENTAL doca_error_t	doca_dpdk_port_as_dev (uint16_t port_id, struct doca_dev **dev)
	Return the DOCA device associated with a DPDK port. More...

DOCA_EXPERIMENTAL doca_error_t	doca_dpdk_open_dev_rep_by_port_id (uint16_t port_id, struct doca_dev dev, struct doca_dev_rep *rep)
	Return a new DOCA device representor associated with a DPDK port. Assumption is that the DPDK port is probed using doca_dev or doca_dpdk_port_probe(). More...

DOCA_EXPERIMENTAL doca_error_t	doca_dpdk_get_rep_vf_index (const struct doca_devinfo_rep rep, uint16_t vf_idx)
	Return the VF index of a network VF representor. More...

DOCA_EXPERIMENTAL doca_error_t	doca_dpdk_get_rep_sf_num (const struct doca_devinfo_rep rep, uint16_t sf_num)
	Return the SF number of a network SF representor. More...

DOCA_EXPERIMENTAL doca_error_t	doca_dpdk_mempool_create (const struct rte_mempool mbuf_pool, struct doca_dpdk_mempool *mempool_out)
	Create a DOCA DPDK memory pool, with ability to convert rte_mbuf to doca_buf Expected flow is as follows: Control path: // Create the memory pool based on a DPDK memory pool doca_dpdk_mempool_create() // Add 1 or more DOCA devices doca_dpdk_mempool_dev_add() // Set permission level across all devices (default=LOCAL_READ/WRITE) doca_dpdk_mempool_set_permissions() // Start the pool doca_dpdk_mempool_start() More...

DOCA_EXPERIMENTAL doca_error_t	doca_dpdk_mempool_destroy (struct doca_dpdk_mempool *mempool)
	Destroy a DOCA DPDK memory pool Before destroying need to make sure that all buffers that were acquired using doca_dpdk_mempool_mbuf_to_buf() have been released This must be called before destroying the originating DPDK mempool. More...

DOCA_EXPERIMENTAL doca_error_t	doca_dpdk_mempool_dev_add (struct doca_dpdk_mempool mempool, struct doca_dev dev)
	Add a DOCA device to the mempool This allows the DOCA bufs that are retrieved from the pool to be compatible with other DOCA libraries, that use the DOCA device. More...

DOCA_EXPERIMENTAL doca_error_t	doca_dpdk_mempool_set_permissions (struct doca_dpdk_mempool *mempool, uint32_t access_mask)
	Set the read/write permissions of the memory for devices Default: DOCA_ACCESS_FLAG_LOCAL_READ_WRITE Setting the permission will set the access that the added devices have over the memory of the DOCA buffers. More...

DOCA_EXPERIMENTAL doca_error_t	doca_dpdk_mempool_start (struct doca_dpdk_mempool *mempool)
	Start the DOCA DPDK memory pool Operations that must be done before start: Adding at least 1 device - doca_dpdk_mempool_dev_add() Optionally, setting the permission level - doca_dpdk_mempool_set_permissions() Operations that are allowed after start: Acquiring a matching doca_buf from an rte_mbuf - doca_dpdk_mempool_mbuf_to_buf() Destroying the DOCA DPDK memory pool - doca_dpdk_mempool_destroy() More...

DOCA_EXPERIMENTAL doca_error_t	doca_dpdk_mempool_mbuf_to_buf (struct doca_dpdk_mempool mempool, struct doca_buf_inventory inventory, struct rte_mbuf mbuf, struct doca_buf *buf)
	Acquire a doca_buf based on an rte_mbuf The acquired doca_buf attempts to be as similar as possible to the rte_mbuf Level of support: More...

Detailed Description

DOCA API for integration with DPDK.

Function Documentation

◆ doca_dpdk_cap_is_rep_port_supported()

DOCA_EXPERIMENTAL doca_error_t doca_dpdk_cap_is_rep_port_supported	(	const struct doca_devinfo *	devinfo,
		uint8_t *	is_rep_port_supported
	)

Check if the device supports representors for port_probe.

Note: This function should be used before calling doca_dpdk_port_probe() in case representors are required in devargs.; This function should be called with root privileges.

Parameters

[in]	devinfo	The DOCA device information
[out]	is_rep_port_supported	1 if the device supports representors for port_probe, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_DRIVER - failed to query device capabilities.

◆ doca_dpdk_get_first_port_id()

DOCA_EXPERIMENTAL doca_error_t doca_dpdk_get_first_port_id	(	const struct doca_dev *	dev,
		uint16_t *	port_id
	)

Return the first DPDK port id associated to a DOCA device. Assumption is that the doca device that was probed using doca_dpdk_port_probe().

Parameters

[in]	dev	DOCA device object
[out]	port_id	DPDK port id

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NOT_FOUND - No DPDK port matches the DOCA device.

◆ doca_dpdk_get_rep_sf_num()

DOCA_EXPERIMENTAL doca_error_t doca_dpdk_get_rep_sf_num	(	const struct doca_devinfo_rep *	rep,
		uint16_t *	sf_num
	)

Return the SF number of a network SF representor.

Can be used to build probe string for representors: E.g., representor=sf[sf_num0, sf_num1, sf_num2]

Parameters

[in]	rep	A DOCA representor representing a network SF.
[out]	sf_num	The returned SF number

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NOT_SUPPORTED - in case representor is not of SF.
DOCA_ERROR_TOO_BIG - parsing failure
DOCA_ERROR_NO_MEMORY - out of memory while parsing
DOCA_ERROR_OPERATING_SYSTEM - parsing failure due to unexpected format

◆ doca_dpdk_get_rep_vf_index()

DOCA_EXPERIMENTAL doca_error_t doca_dpdk_get_rep_vf_index	(	const struct doca_devinfo_rep *	rep,
		uint16_t *	vf_idx
	)

Return the VF index of a network VF representor.

Can be used to build probe string for representors: E.g., representor=vf[vf_index0, vf_index1, vf_index2]

Parameters

[in]	rep	A DOCA representor representing a network VF.
[out]	vf_idx	The returned VF index

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NOT_SUPPORTED - in case representor is not of VF.

◆ doca_dpdk_mempool_create()

DOCA_EXPERIMENTAL doca_error_t doca_dpdk_mempool_create	(	const struct rte_mempool *	mbuf_pool,
		struct doca_dpdk_mempool **	mempool_out
	)

Create a DOCA DPDK memory pool, with ability to convert rte_mbuf to doca_buf Expected flow is as follows: Control path: // Create the memory pool based on a DPDK memory pool doca_dpdk_mempool_create() // Add 1 or more DOCA devices doca_dpdk_mempool_dev_add() // Set permission level across all devices (default=LOCAL_READ/WRITE) doca_dpdk_mempool_set_permissions() // Start the pool doca_dpdk_mempool_start()

Data path: // Convert DPDK mbuf to DOCA buf doca_dpdk_mempool_mbuf_to_buf() // Optionally release DPDK mbuf back to the DPDK pool in case it is no longer needed rte_pktmbuf_free() // Release the doca_buf once finished with it doca_buf_refcnt_rm()

Parameters

[in]	mbuf_pool	A DPDK pool of mbufs, created with rte_pktmbuf_pool_create*()
[out]	mempool_out	The newly created DOCA DPDK memory pool in case of success

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.

◆ doca_dpdk_mempool_destroy()

DOCA_EXPERIMENTAL doca_error_t doca_dpdk_mempool_destroy ( struct doca_dpdk_mempool * mempool )

Destroy a DOCA DPDK memory pool Before destroying need to make sure that all buffers that were acquired using doca_dpdk_mempool_mbuf_to_buf() have been released This must be called before destroying the originating DPDK mempool.

Note: : Once destroyed the originating DPDK memory pool, and any allocated RTE mbuf are not affected

Parameters

[in] mempool The DOCA DPDK memory pool to destroy

Returns

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

DOCA_ERROR_IN_USE - at least 1 DOCA buf has been acquired and still not released

◆ doca_dpdk_mempool_dev_add()

DOCA_EXPERIMENTAL doca_error_t doca_dpdk_mempool_dev_add	(	struct doca_dpdk_mempool *	mempool,
		struct doca_dev *	dev
	)

Add a DOCA device to the mempool This allows the DOCA bufs that are retrieved from the pool to be compatible with other DOCA libraries, that use the DOCA device.

Note: Once device has been added it can't be removed. Only option is to destroy the doca_dpdk_mempool

Parameters

[in]	mempool	The DOCA DPDK memory pool to add the device to
[in]	dev	A DOCA device instance

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NO_MEMORY - out of memory.

◆ doca_dpdk_mempool_mbuf_to_buf()

DOCA_EXPERIMENTAL doca_error_t doca_dpdk_mempool_mbuf_to_buf	(	struct doca_dpdk_mempool *	mempool,
		struct doca_buf_inventory *	inventory,
		struct rte_mbuf *	mbuf,
		struct doca_buf **	buf
	)

Acquire a doca_buf based on an rte_mbuf The acquired doca_buf attempts to be as similar as possible to the rte_mbuf Level of support:

After acquiring the buffer the refcount of the mbuf is increased
In case mbuf is indirect refcount of the direct buffer is increased instead and metadata of the indirect
mbuf is used where metadata refers to the mbuf's data offset, data length, and next pointer
In case the acquired doca_buf is duplicated, then the duplication process will increase the refcount of the direct mbufs as well Limitations:
The mbuf must represent memory from the originating rte_mempool associated with this mempool and mbuf cannot be created from external memory
Any changes made to the rte_mbuf after the acquisition will not affect the doca_buf
Any changes made to the doca_buf after acquisition will not affect the rte_mbuf

rte_mbuf chain before calling this method:
 
         buf_addr              __data_len__
                 \            /            \
                  +----------+--------------+----------+         +----------+--------------+----------+
                  | headroom |     data     | tailroom |  ---->  | headroom |     data     | tailroom |
                  +----------+--------------+----------+         +----------+--------------+----------+
 
doca_buf created after calling this method:
 
             head              __data_len__
                 \            /            \
                  +----------+--------------+----------+         +----------+--------------+----------+
                  |          |     data     |          |  ---->  |          |     data     |          |
                  +----------+--------------+----------+         +----------+--------------+----------+

Note: : Destroying the doca_buf using 'doca_buf_dec_refcount()' will call 'rte_pktmbuf_free_seg()' on each direct mbuf

Parameters

[in]	mempool	The DOCA DPDK memory pool created using the rte_mempool that created the rte_mbuf
[in]	inventory	A DOCA Buffer Inventory to be used for allocating the doca_buf. Must be started and have enough space
[in]	mbuf	A DPDK buffer that references memory that is within the RTE mempool associated with the DOCA DPDK mempool
[out]	buf	A DOCA buffer that references the same memory as the provided mbuf

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NO_MEMORY - The inventory does not have enough free elements.

◆ doca_dpdk_mempool_set_permissions()

DOCA_EXPERIMENTAL doca_error_t doca_dpdk_mempool_set_permissions	(	struct doca_dpdk_mempool *	mempool,
		uint32_t	access_mask
	)

Set the read/write permissions of the memory for devices Default: DOCA_ACCESS_FLAG_LOCAL_READ_WRITE Setting the permission will set the access that the added devices have over the memory of the DOCA buffers.

Parameters

[in]	mempool	The DOCA DPDK memory pool
[in]	access_mask	The access permissions - see 'enum doca_access_flag'

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input or bad access flag combination.

Note: : setting DOCA_ACCESS_FLAG_DPU_* flags is invalid

◆ doca_dpdk_mempool_start()

DOCA_EXPERIMENTAL doca_error_t doca_dpdk_mempool_start ( struct doca_dpdk_mempool * mempool )

Start the DOCA DPDK memory pool Operations that must be done before start: Adding at least 1 device - doca_dpdk_mempool_dev_add() Optionally, setting the permission level - doca_dpdk_mempool_set_permissions() Operations that are allowed after start: Acquiring a matching doca_buf from an rte_mbuf - doca_dpdk_mempool_mbuf_to_buf() Destroying the DOCA DPDK memory pool - doca_dpdk_mempool_destroy()

Parameters

[in] mempool The DOCA DPDK memory pool to add the device to

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NO_MEMORY - out of memory.

◆ doca_dpdk_open_dev_rep_by_port_id()

DOCA_EXPERIMENTAL doca_error_t doca_dpdk_open_dev_rep_by_port_id	(	uint16_t	port_id,
		struct doca_dev *	dev,
		struct doca_dev_rep **	rep
	)

Return a new DOCA device representor associated with a DPDK port. Assumption is that the DPDK port is probed using doca_dev or doca_dpdk_port_probe().

Parameters

[in]	port_id	The DPDK port identifier to get the associated DOCA device representor for.
[in]	dev	The DPDK DOCA device which is parent of requested representor.
[out]	rep	The DPDK DOCA device representor associated with the given DPDK port identifier.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NOT_FOUND - in case there is no such DPDK port associated with a DOCA device.

◆ doca_dpdk_port_as_dev()

DOCA_EXPERIMENTAL doca_error_t doca_dpdk_port_as_dev	(	uint16_t	port_id,
		struct doca_dev **	dev
	)

Return the DOCA device associated with a DPDK port.

Parameters

[in]	port_id	The DPDK port identifier to get the associated DOCA device for.
[out]	dev	The DPDK DOCA device associated with the given DPDK port identifier.

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_NOT_FOUND - in case there is no such DPDK port associated with a DOCA device.

◆ doca_dpdk_port_probe()

DOCA_EXPERIMENTAL doca_error_t doca_dpdk_port_probe	(	struct doca_dev *	dev,
		const char *	devargs
	)

Attach a DPDK port specified by DOCA device.

Thread unsafe API.

It's the user responsibility to set the DPDK EAL initialization to skip probing the PCI device associated with the given DOCA device to prevent EAL from using it.

No initialization is done for the probed PDPK port and the port is not started.

Parameters

[in]	dev	DOCA device to attach PDK port for.
[in]	devargs	DPDK devargs style - must NOT contains the device's PCI address ([domain:]bus:devid.func).

Returns

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

DOCA_ERROR_INVALID_VALUE - in case of invalid input.
DOCA_ERROR_DRIVER - in case of DPDK error during DPDK port attach.
DOCA_ERROR_NO_MEMORY - in case of memory allocation failure.

Functions

Detailed Description

Function Documentation

◆ doca_dpdk_cap_is_rep_port_supported()

◆ doca_dpdk_get_first_port_id()

◆ doca_dpdk_get_rep_sf_num()

◆ doca_dpdk_get_rep_vf_index()

◆ doca_dpdk_mempool_create()

◆ doca_dpdk_mempool_destroy()

◆ doca_dpdk_mempool_dev_add()

◆ doca_dpdk_mempool_mbuf_to_buf()

◆ doca_dpdk_mempool_set_permissions()

◆ doca_dpdk_mempool_start()

◆ doca_dpdk_open_dev_rep_by_port_id()

◆ doca_dpdk_port_as_dev()

◆ doca_dpdk_port_probe()