Collaboration diagram for DOCA Memory Map:

Typedefs
typedef uint32_t	doca_dpa_dev_mmap_t
	Handle on the DPA for a doca_mmap instance. More...

typedef void()	doca_mmap_memrange_free_cb_t(void addr, size_t len, void cookie)
	Function to be called for each populated memory range on memory map destroy. More...

Functions
DOCA_STABLE doca_error_t	doca_mmap_create (struct doca_mmap **mmap)
	Allocates zero size memory map object with default/unset attributes. More...

DOCA_STABLE doca_error_t	doca_mmap_destroy (struct doca_mmap *mmap)
	Destroy DOCA Memory Map structure. More...

DOCA_STABLE doca_error_t	doca_mmap_start (struct doca_mmap *mmap)
	Start DOCA Memory Map. More...

DOCA_STABLE doca_error_t	doca_mmap_stop (struct doca_mmap *mmap)
	Stop DOCA Memory Map. More...

DOCA_STABLE doca_error_t	doca_mmap_add_dev (struct doca_mmap mmap, struct doca_dev dev)
	Register DOCA memory map on a given device. More...

DOCA_STABLE doca_error_t	doca_mmap_rm_dev (struct doca_mmap mmap, struct doca_dev dev)
	Deregister given device from DOCA memory map. More...

DOCA_STABLE doca_error_t	doca_mmap_export_pci (struct doca_mmap mmap, const struct doca_dev dev, const void *export_desc, size_t export_desc_len)
	Compose memory map representation for later import with doca_mmap_create_from_export() for one of the devices previously added to the memory map. More...

DOCA_STABLE doca_error_t	doca_mmap_export_rdma (struct doca_mmap mmap, const struct doca_dev dev, const void *export_desc, size_t export_desc_len)
	Compose memory map representation for later import with doca_mmap_create_from_export() for one of the devices previously added to the memory map. The imported mmap can then be used for RDMA operations. More...

DOCA_EXPERIMENTAL doca_error_t	doca_mmap_dev_get_dpa_handle (struct doca_mmap mmap, const struct doca_dev dev, doca_dpa_dev_mmap_t *dpa_mmap_handle)
	Extract mmap handle associated with the given DOCA device, for the DPA to operate on. More...

DOCA_STABLE doca_error_t	doca_mmap_create_from_export (const union doca_data user_data, const void export_desc, size_t export_desc_len, struct doca_dev dev, struct doca_mmap *mmap)
	Creates a memory map object representing memory ranges in remote system memory space. More...

DOCA_STABLE doca_error_t	doca_mmap_set_memrange (struct doca_mmap mmap, void addr, size_t len)
	Set the memory range of DOCA memory map. More...

DOCA_STABLE doca_error_t	doca_mmap_set_dmabuf_memrange (struct doca_mmap mmap, int dmabuf_fd, void addr, size_t dmabuf_offset, size_t len)
	Set the memory range of DOCA memory map using dmabuf. More...

DOCA_EXPERIMENTAL doca_error_t	doca_mmap_set_dpa_memrange (struct doca_mmap mmap, struct doca_dpa dpa, uint64_t dpa_addr, size_t len)
	Set the memory range of DOCA memory map to be a DPA heap memory. More...

DOCA_STABLE doca_error_t	doca_mmap_get_memrange (const struct doca_mmap mmap, void addr, size_t len)
	Get the memory range of DOCA memory map. More...

DOCA_STABLE doca_error_t	doca_mmap_set_free_cb (struct doca_mmap mmap, doca_mmap_memrange_free_cb_t free_cb, void *opaque)
	Set callback that will free the memory range when destroying DOCA memory map. More...

DOCA_STABLE doca_error_t	doca_mmap_get_user_data (const struct doca_mmap mmap, union doca_data user_data)
	Get the user_data of a DOCA Memory Map. More...

DOCA_STABLE doca_error_t	doca_mmap_get_max_num_devices (const struct doca_mmap mmap, uint32_t max_num_devices)
	Get the max number of devices to add to a DOCA Memory Map. More...

DOCA_STABLE doca_error_t	doca_mmap_get_num_bufs (const struct doca_mmap mmap, uint32_t num_bufs)
	Get the Total number of `struct doca_buf` objects pointing to the memory in a DOCA Memory Map. More...

DOCA_STABLE doca_error_t	doca_mmap_get_exported (const struct doca_mmap mmap, uint8_t exported)
	Get the flag indicating if a DOCA Memory Map had been exported. More...

DOCA_STABLE doca_error_t	doca_mmap_get_from_export (const struct doca_mmap mmap, uint8_t from_export)
	Get the flag indicating if a DOCA Memory Map had been created from an export. More...

DOCA_STABLE doca_error_t	doca_mmap_set_max_num_devices (struct doca_mmap *mmap, uint32_t max_num_devices)
	Set a new max number of devices to add to a DOCA Memory Map. More...

DOCA_STABLE doca_error_t	doca_mmap_set_permissions (struct doca_mmap *mmap, uint32_t access_mask)
	Set access flags of the registered memory. More...

DOCA_STABLE doca_error_t	doca_mmap_set_user_data (struct doca_mmap *mmap, union doca_data user_data)
	Set user_data for a DOCA Memory Map. More...

DOCA_STABLE doca_error_t	doca_mmap_cap_is_export_pci_supported (const struct doca_devinfo devinfo, uint8_t mmap_export)
	Get the mmap export to PCI capability of a device. More...

DOCA_STABLE doca_error_t	doca_mmap_cap_is_create_from_export_pci_supported (const struct doca_devinfo devinfo, uint8_t from_export)
	Get the mmap create from export PCI capability of a device. More...

DOCA_EXPERIMENTAL doca_error_t	doca_mmap_enable_thread_safety (struct doca_mmap *mmap)
	Enable thread safety for doca_mmap. More...

Detailed Description

The DOCA memory map provides a centralized repository and orchestration of several memory ranges registration for each device attached to the memory map.

Typedef Documentation

◆ doca_dpa_dev_mmap_t

typedef uint32_t doca_dpa_dev_mmap_t

Handle on the DPA for a doca_mmap instance.

Definition at line 80 of file doca_mmap.h.

◆ doca_mmap_memrange_free_cb_t

typedef void() doca_mmap_memrange_free_cb_t(void *addr, size_t len, void *cookie)

Function to be called for each populated memory range on memory map destroy.

Parameters

[in]	addr	Memory range pointer.
[in]	len	Memory range length.
[in]	cookie	An opaque pointer passed to the callback.

Definition at line 233 of file doca_mmap.h.

Function Documentation

◆ doca_mmap_add_dev()

DOCA_STABLE doca_error_t doca_mmap_add_dev	(	struct doca_mmap *	mmap,
		struct doca_dev *	dev
	)

Register DOCA memory map on a given device.

This operation is not permitted for:

started memory map object.
memory map object that have been exported or created from export.

Parameters

[in]	mmap	DOCA memory map structure.
[in]	dev	DOCA Dev instance with appropriate capability.

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_NOT_PERMITTED - if memory deregistration failed or the operation is not permitted for the given mmap (see details in this function description).
DOCA_ERROR_NO_MEMORY - if reached to DOCA_MMAP_MAX_NUM_DEVICES.
DOCA_ERROR_ALREADY_EXIST - if doca_dev already exists in doca_mmap.
DOCA_ERROR_NOT_SUPPORTED - if dev was opened using doca_rdma_bridge_open_dev_from_pd(). Only relevant to memory map objects created using doca_mmap_create().

◆ doca_mmap_cap_is_create_from_export_pci_supported()

DOCA_STABLE doca_error_t doca_mmap_cap_is_create_from_export_pci_supported	(	const struct doca_devinfo *	devinfo,
		uint8_t *	from_export
	)

Get the mmap create from export PCI capability of a device.

Get uint8_t value defining if the device can be used to create an mmap from an exported mmap where the exported mmap was created using doca_mmap_export_pci(). See doca_mmap_create_from_export() true - device can be used with the mmap create from export PCI API. false - create from export API is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.

Parameters

[in]	devinfo	The device to query.
[out]	from_export	1 if the mmap from export PCI capability is supported, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query capability support.

◆ doca_mmap_cap_is_export_pci_supported()

DOCA_STABLE doca_error_t doca_mmap_cap_is_export_pci_supported	(	const struct doca_devinfo *	devinfo,
		uint8_t *	mmap_export
	)

Get the mmap export to PCI capability of a device.

Get uint8_t value defining if the device can be used to export an mmap over the PCI. See doca_mmap_export_pci() true - device can be used with the mmap export API. false - export PCI API is guaranteed to fail with DOCA_ERROR_NOT_SUPPORTED.

Parameters

[in]	devinfo	The device to query.
[out]	mmap_export	1 if the mmap export PCI capability is supported, 0 otherwise.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_DRIVER - failed to query capability support.

◆ doca_mmap_create()

DOCA_STABLE doca_error_t doca_mmap_create ( struct doca_mmap ** mmap )

Allocates zero size memory map object with default/unset attributes.

The returned memory map object can be manipulated with doca_mmap_property_set() API.

Once all required mmap attributes set it should be reconfigured and adjusted to meet object size setting with doca_mmap_start() See doca_mmap_start for the rest of the details.

Parameters

[out] mmap DOCA memory map structure 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_mmap.

◆ doca_mmap_create_from_export()

DOCA_STABLE doca_error_t doca_mmap_create_from_export	(	const union doca_data *	user_data,
		const void *	export_desc,
		size_t	export_desc_len,
		struct doca_dev *	dev,
		struct doca_mmap **	mmap
	)

Creates a memory map object representing memory ranges in remote system memory space.

Once this function called on the object it considered as from_export.

The following are NOT possible for the mmap created from export:

Setting the properties of the mmap using doca_mmap_set_*().
Adding a device to the mmap using doca_mmap_add_dev().
Removing a device to the mmap using doca_mmap_rm_dev().
Exporting the mmap using doca_mmap_export_*.

Parameters

[in]	user_data	Identifier provided by user for the newly created DOCA memory map. If not NULL, pointed user_data will be set.
[in]	export_desc	An export descriptor generated by doca_mmap_export_*.
[in]	export_desc_len	Length in bytes of the export_desc.
[in]	dev	A local device connected to the device that resides in the exported mmap. In case the 'export_desc' was created using doca_mmap_export_pci(), then device must have from export PCI capability. See doca_mmap_cap_is_create_from_export_pci_supported(). And must be on same PCI bus.
[out]	mmap	DOCA memory map granting access to remote memory.

Note: : The created object not backed by local memory.

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 or internal error. The following errors are internal and will occur if failed to produce new mmap from export descriptor:
DOCA_ERROR_NO_MEMORY - if internal memory allocation failed.
DOCA_ERROR_NOT_SUPPORTED - device missing create from export capability, or was opened using doca_rdma_bridge_open_dev_from_pd().
DOCA_ERROR_NOT_PERMITTED
DOCA_ERROR_DRIVER

◆ doca_mmap_destroy()

DOCA_STABLE doca_error_t doca_mmap_destroy ( struct doca_mmap * mmap )

Destroy DOCA Memory Map structure.

Before calling this function all allocated buffers should be returned back to the mmap. Destroy implicitly stops the mmap. doca_mmap_destroy is not thread safe even if thread safety is enabled (

See also: doca_mmap_enable_thread_safety)

Parameters

[in] mmap The DOCA memory map 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_NOT_PERMITTED - if there is a memory region pointed by one or more struct doca_buf, or if memory deregistration failed (unless thread safety is enabled).

◆ doca_mmap_dev_get_dpa_handle()

DOCA_EXPERIMENTAL doca_error_t doca_mmap_dev_get_dpa_handle	(	struct doca_mmap *	mmap,
		const struct doca_dev *	dev,
		doca_dpa_dev_mmap_t *	dpa_mmap_handle
	)

Extract mmap handle associated with the given DOCA device, for the DPA to operate on.

Export the mmap to the DPA.

This operation is not permitted for:

un-started/stopped memory map object.

Parameters

[in]	mmap	DOCA memory map structure.
[in]	dev	Device previously added to the memory map via doca_mmap_add_dev().
[out]	dpa_mmap_handle	On successful return should have a pointer to the mmap handle for the DPA.

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_NOT_FOUND - if device does not exist in mmap.
DOCA_ERROR_NOT_PERMITTED - the operation is not permitted for the given mmap, see details in this function description.

◆ doca_mmap_enable_thread_safety()

DOCA_EXPERIMENTAL doca_error_t doca_mmap_enable_thread_safety ( struct doca_mmap * mmap )

Enable thread safety for doca_mmap.

Enabling thread safety facilitates using a doca_mmap instance from multiple threads including fast path (e.g. doca_buf_inventory_buf_get_by_...) Enabling thread safety disables num allocated bufs reference counting (

See also: doca_mmap_get_num_bufs). doca_mmap_destroy shall NOT fail if one or more doca_bufs are allocated on the mmap when thread safety is enabled. Exclusions: doca_mmap_enable_thread_safety is not thread safe. doca_mmap_destroy is not thread safe.

Parameters

[in] mmap doca_mmap to make thread safe.

Returns

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

DOCA_ERROR_INVALID_VALUE - received invalid input.
DOCA_ERROR_NOT_PERMITTED - mmap is started or num allocated bufs reference count > 0 (

See also: doca_mmap_get_num_bufs).

◆ doca_mmap_export_pci()

DOCA_STABLE doca_error_t doca_mmap_export_pci	(	struct doca_mmap *	mmap,
		const struct doca_dev *	dev,
		const void **	export_desc,
		size_t *	export_desc_len
	)

Compose memory map representation for later import with doca_mmap_create_from_export() for one of the devices previously added to the memory map.

Once this function called on the object it considered as exported. The same mmap can be exported using different devices. Once mmap is stopped then any mmap created from export will be invalidated, and the 'export_desc' is destroyed.

This operation is not permitted for:

un-started/stopped memory map object.
memory map object that have been created from export.
memory map with no PCI access permission set - see doca_mmap_set_permissions()

Note: The exported data contains sensitive information - please make sure to pass this data through a secure channel

Parameters

[in]	mmap	DOCA memory map structure.
[in]	dev	Device previously added to the memory map via doca_mmap_add_dev(). Device must have export capability. See doca_mmap_cap_is_export_pci_supported()
[out]	export_desc	On successful return should have a pointer to the allocated blob containing serialized representation of the memory map object for the device provided as `dev`.
[out]	export_desc_len	Length in bytes of the export_desc.

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_NOT_FOUND - if device does not exist in mmap.
DOCA_ERROR_NOT_PERMITTED - the operation is not permitted for the given mmap, see details in this function description. The following errors will occur if failed to produce export descriptor:
DOCA_ERROR_NO_MEMORY - if failed to alloc memory for export_desc.
DOCA_ERROR_NOT_SUPPORTED - device missing export capability.
DOCA_ERROR_DRIVER

◆ doca_mmap_export_rdma()

DOCA_STABLE doca_error_t doca_mmap_export_rdma	(	struct doca_mmap *	mmap,
		const struct doca_dev *	dev,
		const void **	export_desc,
		size_t *	export_desc_len
	)

Compose memory map representation for later import with doca_mmap_create_from_export() for one of the devices previously added to the memory map. The imported mmap can then be used for RDMA operations.

Once this function called on the object it considered as exported.

This operation is not permitted for:

un-started/stopped memory map object.
memory map with no RDMA access permission set - see doca_mmap_set_permissions()

Note: The exported data contains sensitive information - please make sure to pass this data through a secure channel

Parameters

[in]	mmap	DOCA memory map structure.
[in]	dev	Device previously added to the memory map via doca_mmap_add_dev().
[out]	export_desc	On successful return should have a pointer to the allocated blob containing serialized representation of the memory map object for the device provided as `dev`.
[out]	export_desc_len	Length in bytes of the export_desc.

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_NOT_FOUND - if device does not exist in mmap.
DOCA_ERROR_NOT_PERMITTED - the operation is not permitted for the given mmap, see details in this function description. The following errors will occur if failed to produce export descriptor:
DOCA_ERROR_NO_MEMORY - if failed to alloc memory for export_desc.
DOCA_ERROR_NOT_SUPPORTED - device missing export capability, or was opened using doca_rdma_bridge_open_dev_from_pd().
DOCA_ERROR_DRIVER

◆ doca_mmap_get_exported()

DOCA_STABLE doca_error_t doca_mmap_get_exported	(	const struct doca_mmap *	mmap,
		uint8_t *	exported
	)

Get the flag indicating if a DOCA Memory Map had been exported.

Parameters

[in]	mmap	The DOCA memory map structure.
[out]	exported	1 if mmap had been exported, 0 otherwise.

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_mmap_get_from_export()

DOCA_STABLE doca_error_t doca_mmap_get_from_export	(	const struct doca_mmap *	mmap,
		uint8_t *	from_export
	)

Get the flag indicating if a DOCA Memory Map had been created from an export.

Parameters

[in]	mmap	The DOCA memory map structure.
[out]	from_export	1 if mmap had been created from export, 0 otherwise.

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_mmap_get_max_num_devices()

DOCA_STABLE doca_error_t doca_mmap_get_max_num_devices	(	const struct doca_mmap *	mmap,
		uint32_t *	max_num_devices
	)

Get the max number of devices to add to a DOCA Memory Map.

Parameters

[in]	mmap	The DOCA memory map structure.
[out]	max_num_devices	The max number of devices that can be added add to mmap.

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_mmap_get_memrange()

DOCA_STABLE doca_error_t doca_mmap_get_memrange	(	const struct doca_mmap *	mmap,
		void **	addr,
		size_t *	len
	)

Get the memory range of DOCA memory map.

Parameters

[in]	mmap	DOCA memory map structure.
[out]	addr	Start address of the memory range previously set.
[out]	len	The size of the memory range in bytes.

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 - memrange was never set.

◆ doca_mmap_get_num_bufs()

DOCA_STABLE doca_error_t doca_mmap_get_num_bufs	(	const struct doca_mmap *	mmap,
		uint32_t *	num_bufs
	)

Get the Total number of struct doca_buf objects pointing to the memory in a DOCA Memory Map.

Parameters

[in]	mmap	The DOCA memory map structure.
[out]	num_bufs	The total number of `struct doca_buf` objects pointing to the memory in mmap.

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_mmap_get_user_data()

DOCA_STABLE doca_error_t doca_mmap_get_user_data	(	const struct doca_mmap *	mmap,
		union doca_data *	user_data
	)

Get the user_data of a DOCA Memory Map.

Note: The user_data that was provided to the mmap upon its creation.

Parameters

[in]	mmap	The DOCA memory map structure.
[out]	user_data	The user_data of mmap if set, otherwise 0.

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_mmap_rm_dev()

DOCA_STABLE doca_error_t doca_mmap_rm_dev	(	struct doca_mmap *	mmap,
		struct doca_dev *	dev
	)

Deregister given device from DOCA memory map.

This operation is not permitted for:

started memory map object.
memory map object that have been exported or created from export.

Parameters

[in]	mmap	DOCA memory map structure.
[in]	dev	DOCA Dev instance that was previously added.

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_NOT_FOUND - if doca_dev doesn't exist in doca_mmap.
DOCA_ERROR_NOT_PERMITTED - if memory deregistration failed or the operation is not permitted for the given mmap (see details in this function description).

◆ doca_mmap_set_dmabuf_memrange()

DOCA_STABLE doca_error_t doca_mmap_set_dmabuf_memrange	(	struct doca_mmap *	mmap,
		int	dmabuf_fd,
		void *	addr,
		size_t	dmabuf_offset,
		size_t	len
	)

Set the memory range of DOCA memory map using dmabuf.

This operation is not permitted for:

started memory map object.
memory map object that have been exported or created from export.

Parameters

[in]	mmap	DOCA memory map structure.
[in]	dmabuf_fd	File descriptor of the dmabuf.
[in]	addr	Start address of the memory range to be set.
[in]	dmabuf_offset	Start offset of the dmabuf.
[in]	len	The size of the memory range in bytes.

Returns

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

DOCA_ERROR_NOT_SUPPORTED - if not called from linux operating system
DOCA_ERROR_INVALID_VALUE - if an invalid input had been received, or addr + len overflows.
DOCA_ERROR_BAD_STATE - if mmap is started.
DOCA_ERROR_NOT_PERMITTED - if mmap memory range was set before

Note: : this property is mandatory and can be done only once. it is only supported when used on linux operating system

◆ doca_mmap_set_dpa_memrange()

DOCA_EXPERIMENTAL doca_error_t doca_mmap_set_dpa_memrange	(	struct doca_mmap *	mmap,
		struct doca_dpa *	dpa,
		uint64_t	dpa_addr,
		size_t	len
	)

Set the memory range of DOCA memory map to be a DPA heap memory.

This operation is not permitted for:

started memory map object.
memory map object that have been exported or created from export.

Note: When using dpa memrange, adding DOCA devices using doca_mmap_add_dev() is not allowed.

Parameters

[in]	mmap	DOCA memory map structure.
[in]	dpa	DOCA DPA context associated with the memory pointed by the given 'dpa_addr'.
[in]	dpa_addr	Start address of the memory range to be set on the DPA address space.
[in]	len	The size of the memory range in bytes.

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, or addr + len overflows.
DOCA_ERROR_BAD_STATE - if mmap is started.
DOCA_ERROR_NOT_PERMITTED - if mmap memory range was set before

Note: : this property is mandatory and can be done only once

◆ doca_mmap_set_free_cb()

DOCA_STABLE doca_error_t doca_mmap_set_free_cb	(	struct doca_mmap *	mmap,
		doca_mmap_memrange_free_cb_t *	free_cb,
		void *	opaque
	)

Set callback that will free the memory range when destroying DOCA memory map.

Note: Callback is called on mmap destroy, only in case the mmap was started and destroyed without changing the callback.

Parameters

[in]	mmap	DOCA memory map structure.
[in]	free_cb	Callback function to free the set memory range on memory map destroy.
[out]	opaque	User opaque value passed to free_cb.

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 mmap is started.

◆ doca_mmap_set_max_num_devices()

DOCA_STABLE doca_error_t doca_mmap_set_max_num_devices	(	struct doca_mmap *	mmap,
		uint32_t	max_num_devices
	)

Set a new max number of devices to add to a DOCA Memory Map.

Parameters

[in]	mmap	The DOCA memory map structure.
[in]	max_num_devices	The new max number of devices that can be added add to mmap.

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_NOT_PERMITTED - if trying to set the max number of devices after first start of the mmap.

◆ doca_mmap_set_memrange()

DOCA_STABLE doca_error_t doca_mmap_set_memrange	(	struct doca_mmap *	mmap,
		void *	addr,
		size_t	len
	)

Set the memory range of DOCA memory map.

This operation is not permitted for:

started memory map object.
memory map object that have been exported or created from export.

Parameters

[in]	mmap	DOCA memory map structure.
[in]	addr	Start address of the memory range to be set.
[in]	len	The size of the memory range in bytes.

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, or addr + len overflows.
DOCA_ERROR_BAD_STATE - if mmap is started.
DOCA_ERROR_NOT_PERMITTED - if mmap memory range was set before

Note: : this property is mandatory and can be done only once

◆ doca_mmap_set_permissions()

DOCA_STABLE doca_error_t doca_mmap_set_permissions	(	struct doca_mmap *	mmap,
		uint32_t	access_mask
	)

Set access flags of the registered memory.

this defines what kind of access the added devices have to the memory defined in mmap

Parameters

[in]	mmap	The DOCA memory map structure.
[in]	access_mask	bitwise combination of access flags - see enum doca_access_flag

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 or trying to set an undefined access flag, or invalid combination
DOCA_ERROR_BAD_STATE - If mmap is started

◆ doca_mmap_set_user_data()

DOCA_STABLE doca_error_t doca_mmap_set_user_data	(	struct doca_mmap *	mmap,
		union doca_data	user_data
	)

Set user_data for a DOCA Memory Map.

Parameters

[in]	mmap	The DOCA memory map structure.
[out]	user_data	The user_data to set for mmap.

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 mmap is started.

◆ doca_mmap_start()

DOCA_STABLE doca_error_t doca_mmap_start ( struct doca_mmap * mmap )

Start DOCA Memory Map.

Allows execution of different operations on the mmap, detailed below. On start verifies & finalizes the mmap object configuration.

The following become possible only after start:

Exporting the mmap using doca_mmap_export_*.
Mapping doca_buf structures to the memory ranges in the using doca_buf_inventory_buf_get_by_addr() or doca_buf_inventory_buf_dup().

The following are NOT possible while mmap is started:

Setting the properties of the mmap through doca_mmap_set_*.
Adding a device to the mmap using doca_mmap_add_dev().
Removing a device to the mmap using doca_mmap_rm_dev().

Parameters

[in] mmap DOCA memory map 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_NO_MEMORY - if memory allocation failed.
DOCA_ERROR_NOT_PERMITTED - if mmap is exported or created from export.

◆ doca_mmap_stop()

DOCA_STABLE doca_error_t doca_mmap_stop ( struct doca_mmap * mmap )

Stop DOCA Memory Map.

Prevents execution of different operations and allows operations that were available before start. For details see doca_mmap_start(). Frees any export descriptor received from doca_mmap_export_*, and invalidates any mmap created from this mmap export. Stop does not have to be called before destroy (that implicitly stops the mmap).

Parameters

[in] mmap DOCA memory map 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_NOT_PERMITTED - if mmap was exported or created from export, or buffers that were created for this mmap, are still not destroyed.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ doca_dpa_dev_mmap_t

◆ doca_mmap_memrange_free_cb_t

Function Documentation

◆ doca_mmap_add_dev()

◆ doca_mmap_cap_is_create_from_export_pci_supported()

◆ doca_mmap_cap_is_export_pci_supported()

◆ doca_mmap_create()

◆ doca_mmap_create_from_export()

◆ doca_mmap_destroy()

◆ doca_mmap_dev_get_dpa_handle()

◆ doca_mmap_enable_thread_safety()

◆ doca_mmap_export_pci()

◆ doca_mmap_export_rdma()

◆ doca_mmap_get_exported()

◆ doca_mmap_get_from_export()

◆ doca_mmap_get_max_num_devices()

◆ doca_mmap_get_memrange()

◆ doca_mmap_get_num_bufs()

◆ doca_mmap_get_user_data()

◆ doca_mmap_rm_dev()

◆ doca_mmap_set_dmabuf_memrange()

◆ doca_mmap_set_dpa_memrange()

◆ doca_mmap_set_free_cb()

◆ doca_mmap_set_max_num_devices()

◆ doca_mmap_set_memrange()

◆ doca_mmap_set_permissions()

◆ doca_mmap_set_user_data()

◆ doca_mmap_start()

◆ doca_mmap_stop()