SPDK DMA device framework. More...

Data Structures
struct	spdk_memory_domain_translation_result

struct	spdk_memory_domain_translation_ctx

struct	spdk_memory_domain_rdma_ctx
	Context of memory domain of RDMA type. More...

struct	spdk_memory_domain_ctx

Macros
#define	SPDK_RDMA_DMA_DEVICE "SPDK_RDMA_DMA_DEVICE"
	Identifier of SPDK internal DMA device of RDMA type.

Typedefs
typedef void(*	spdk_memory_domain_data_cpl_cb) (void *ctx, int rc)
	Definition of completion callback to be called by pull, push or memzero functions.

typedef int(*	spdk_memory_domain_pull_data_cb) (struct spdk_memory_domain src_domain, void src_domain_ctx, struct iovec src_iov, uint32_t src_iovcnt, struct iovec dst_iov, uint32_t dst_iovcnt, spdk_memory_domain_data_cpl_cb cpl_cb, void *cpl_cb_arg)
	Definition of function which asynchronously pulles data from src_domain to local memory domain.

typedef int(*	spdk_memory_domain_push_data_cb) (struct spdk_memory_domain dst_domain, void dst_domain_ctx, struct iovec dst_iov, uint32_t dst_iovcnt, struct iovec src_iov, uint32_t src_iovcnt, spdk_memory_domain_data_cpl_cb cpl_cb, void *cpl_cb_arg)
	Definition of function which asynchronously pushes data from local memory to destination memory domain.

typedef int(*	spdk_memory_domain_memzero_cb) (struct spdk_memory_domain domain, void domain_ctx, struct iovec iov, uint32_t iovcnt, spdk_memory_domain_data_cpl_cb cpl_cb, void cpl_cb_arg)
	Definition of function which asynchronously fills memory in domain with zeroes.

typedef int(*	spdk_memory_domain_translate_memory_cb) (struct spdk_memory_domain src_domain, void src_domain_ctx, struct spdk_memory_domain dst_domain, struct spdk_memory_domain_translation_ctx dst_domain_ctx, void addr, size_t len, struct spdk_memory_domain_translation_result result)
	Definition of function which translates data from src_domain to a form accessible by dst_domain.

typedef void(*	spdk_memory_domain_invalidate_data_cb) (struct spdk_memory_domain domain, void domain_ctx, struct iovec *iov, uint32_t iovcnt)
	Definition of function which invalidates the data range in the given domain.

Enumerations
enum	spdk_dma_device_type { SPDK_DMA_DEVICE_TYPE_RDMA , SPDK_DMA_DEVICE_TYPE_DMA , SPDK_DMA_DEVICE_TYPE_ACCEL , SPDK_DMA_DEVICE_VENDOR_SPECIFIC_TYPE_START = 1000 , SPDK_DMA_DEVICE_VENDOR_SPECIFIC_TYPE_END = SPDK_DMA_DEVICE_VENDOR_SPECIFIC_TYPE_START + 999 }

Functions
int	spdk_memory_domain_create (struct spdk_memory_domain *domain, enum spdk_dma_device_type type, struct spdk_memory_domain_ctx ctx, const char *id)
	Creates a new memory domain of the specified type.

void	spdk_memory_domain_set_translation (struct spdk_memory_domain *domain, spdk_memory_domain_translate_memory_cb translate_cb)
	Set translation function for memory domain.

void	spdk_memory_domain_set_invalidate (struct spdk_memory_domain *domain, spdk_memory_domain_invalidate_data_cb invalidate_cb)
	Set invalidate function for memory domain.

void	spdk_memory_domain_set_pull (struct spdk_memory_domain *domain, spdk_memory_domain_pull_data_cb pull_cb)
	Set pull function for memory domain.

void	spdk_memory_domain_set_push (struct spdk_memory_domain *domain, spdk_memory_domain_push_data_cb push_cb)
	Set push function for memory domain.

void	spdk_memory_domain_set_memzero (struct spdk_memory_domain *domain, spdk_memory_domain_memzero_cb memzero_cb)
	Set memzero function for memory domain.

struct spdk_memory_domain_ctx *	spdk_memory_domain_get_context (struct spdk_memory_domain *domain)
	Get the context passed by the user in spdk_memory_domain_create.

enum spdk_dma_device_type	spdk_memory_domain_get_dma_device_type (struct spdk_memory_domain *domain)
	Get type of the DMA device that can access this memory domain.

const char *	spdk_memory_domain_get_dma_device_id (struct spdk_memory_domain *domain)
	Get an identifier representing the DMA device that can access this memory domain.

void	spdk_memory_domain_destroy (struct spdk_memory_domain *domain)
	Destroy memory domain.

int	spdk_memory_domain_pull_data (struct spdk_memory_domain src_domain, void src_domain_ctx, struct iovec src_iov, uint32_t src_iov_cnt, struct iovec dst_iov, uint32_t dst_iov_cnt, spdk_memory_domain_data_cpl_cb cpl_cb, void *cpl_cb_arg)
	Asynchronously pull data which is described by src_domain and located in src_iov to a location dst_iov local memory space.

int	spdk_memory_domain_push_data (struct spdk_memory_domain dst_domain, void dst_domain_ctx, struct iovec dst_iov, uint32_t dst_iovcnt, struct iovec src_iov, uint32_t src_iovcnt, spdk_memory_domain_data_cpl_cb cpl_cb, void *cpl_cb_arg)
	Asynchronously push data located in local memory to dst_domain.

int	spdk_memory_domain_translate_data (struct spdk_memory_domain src_domain, void src_domain_ctx, struct spdk_memory_domain dst_domain, struct spdk_memory_domain_translation_ctx dst_domain_ctx, void addr, size_t len, struct spdk_memory_domain_translation_result result)
	Translate data located in src_domain space at address addr with size len into an equivalent description of memory in dst_domain.

void	spdk_memory_domain_invalidate_data (struct spdk_memory_domain domain, void domain_ctx, struct iovec *iov, uint32_t iovcnt)
	Invalidate memory in the given domain.

int	spdk_memory_domain_memzero (struct spdk_memory_domain domain, void domain_ctx, struct iovec iov, uint32_t iovcnt, spdk_memory_domain_data_cpl_cb cpl_cb, void cpl_cb_arg)
	Fills memory in domain with zeroes.

struct spdk_memory_domain *	spdk_memory_domain_get_first (const char *id)
	Get the first memory domain.

struct spdk_memory_domain *	spdk_memory_domain_get_next (struct spdk_memory_domain prev, const char id)
	Get the next memory domain.

struct spdk_memory_domain *	spdk_memory_domain_get_system_domain (void)
	Get the System memory domain.

Detailed Description

SPDK DMA device framework.

Typedef Documentation

◆ spdk_memory_domain_data_cpl_cb

typedef void(* spdk_memory_domain_data_cpl_cb) (void *ctx, int rc)

Definition of completion callback to be called by pull, push or memzero functions.

Parameters

ctx	User context passed to pull of push functions
rc	Result of asynchronous data pull or push function

◆ spdk_memory_domain_invalidate_data_cb

typedef void(* spdk_memory_domain_invalidate_data_cb) (struct spdk_memory_domain *domain, void *domain_ctx, struct iovec *iov, uint32_t iovcnt)

Definition of function which invalidates the data range in the given domain.

Parameters

domain	Memory domain to which the data buffer belongs
domain_ctx	Optional context passed by upper layer
iov	Iov array in domain memory space to be invalidated
iovcnt	Iov array size

◆ spdk_memory_domain_memzero_cb

typedef int(* spdk_memory_domain_memzero_cb) (struct spdk_memory_domain *domain, void *domain_ctx, struct iovec *iov, uint32_t iovcnt, spdk_memory_domain_data_cpl_cb cpl_cb, void *cpl_cb_arg)

Definition of function which asynchronously fills memory in domain with zeroes.

Parameters

domain	Memory domain in which address space data buffer is located
domain_ctx	User defined context
iov	iov in domain memory space to be filled with zeroes
iovcnt	iov array size
cpl_cb	Completion callback
cpl_cb_arg	Completion callback argument

Returns: 0 on success, negated errno on failure

◆ spdk_memory_domain_pull_data_cb

typedef int(* spdk_memory_domain_pull_data_cb) (struct spdk_memory_domain *src_domain, void *src_domain_ctx, struct iovec *src_iov, uint32_t src_iovcnt, struct iovec *dst_iov, uint32_t dst_iovcnt, spdk_memory_domain_data_cpl_cb cpl_cb, void *cpl_cb_arg)

Definition of function which asynchronously pulles data from src_domain to local memory domain.

Implementation of this function must call cpl_cb only when it returns 0. All other return codes mean failure.

Parameters

src_domain	Memory domain to which the data buffer belongs
src_domain_ctx	Optional context passed by upper layer with IO request
src_iov	Iov vector in src_domain space
src_iovcnt	src_iov array size
dst_iov	Iov vector in local memory domain space, data buffers must be allocated by the caller of this function, total size of data buffers must not be less than the size of data in src_iov.
dst_iovcnt	dst_iov array size
cpl_cb	A callback to be called when pull operation completes
cpl_cb_arg	Optional argument to be passed to cpl_cb

Returns: 0 on success, negated errno on failure

◆ spdk_memory_domain_push_data_cb

typedef int(* spdk_memory_domain_push_data_cb) (struct spdk_memory_domain *dst_domain, void *dst_domain_ctx, struct iovec *dst_iov, uint32_t dst_iovcnt, struct iovec *src_iov, uint32_t src_iovcnt, spdk_memory_domain_data_cpl_cb cpl_cb, void *cpl_cb_arg)

Definition of function which asynchronously pushes data from local memory to destination memory domain.

Implementation of this function must call cpl_cb only when it returns 0. All other return codes mean failure.

Parameters

dst_domain	Memory domain to which the data should be pushed
dst_domain_ctx	Optional context passed by upper layer with IO request
dst_iov	Iov vector in dst_domain space
dst_iovcnt	dst_iov array size
src_iov	Iov vector in local memory
src_iovcnt	src_iov array size
cpl_cb	A callback to be called when push operation completes
cpl_cb_arg	Optional argument to be passed to cpl_cb

Returns: 0 on success, negated errno on failure

◆ spdk_memory_domain_translate_memory_cb

typedef int(* spdk_memory_domain_translate_memory_cb) (struct spdk_memory_domain *src_domain, void *src_domain_ctx, struct spdk_memory_domain *dst_domain, struct spdk_memory_domain_translation_ctx *dst_domain_ctx, void *addr, size_t len, struct spdk_memory_domain_translation_result *result)

Definition of function which translates data from src_domain to a form accessible by dst_domain.

Parameters

src_domain	Memory domain to which the data buffer belongs
src_domain_ctx	Optional context passed by upper layer with IO request
dst_domain	Memory domain which determines type of translation function
dst_domain_ctx	Ancillary data for dst_domain
addr	Data buffer address in src_domain memory space which should be translated into dst_domain
len	Length of data buffer
result	Result of translation function

Returns: 0 on success, negated errno on failure

Enumeration Type Documentation

◆ spdk_dma_device_type

enum spdk_dma_device_type

Enumerator
SPDK_DMA_DEVICE_TYPE_RDMA	RDMA devices are capable of performing DMA operations on memory domains using the standard RDMA model (protection domain, remote key, address).
SPDK_DMA_DEVICE_TYPE_DMA	DMA devices are capable of performing DMA operations on memory domains using physical or I/O virtual addresses.
SPDK_DMA_DEVICE_TYPE_ACCEL	Virtual memory domain representing memory being transformed by accel framework.
SPDK_DMA_DEVICE_VENDOR_SPECIFIC_TYPE_START	Start of the range of vendor-specific DMA device types.
SPDK_DMA_DEVICE_VENDOR_SPECIFIC_TYPE_END	End of the range of vendor-specific DMA device types.

Function Documentation

◆ spdk_memory_domain_create()

int spdk_memory_domain_create	(	struct spdk_memory_domain **	domain,
		enum spdk_dma_device_type	type,
		struct spdk_memory_domain_ctx *	ctx,
		const char *	id )

Creates a new memory domain of the specified type.

Translation functions can be provided to translate addresses from one memory domain to another. If the two domains both use the same addressing scheme for, then this translation does nothing. However, it is possible that the two memory domains may address the same physical memory differently, so this translation step is required.

Parameters

domain	Double pointer to memory domain to be allocated by this function
type	Type of the DMA device which can access this memory domain
ctx	Optional memory domain context to be copied by this function. Later ctx can be retrieved using spdk_memory_domain_get_context function
id	String identifier representing the DMA device that can access this memory domain.

Returns: 0 on success, negated errno on failure

◆ spdk_memory_domain_destroy()

void spdk_memory_domain_destroy ( struct spdk_memory_domain * domain )

Destroy memory domain.

Parameters

domain Memory domain

◆ spdk_memory_domain_get_context()

struct spdk_memory_domain_ctx * spdk_memory_domain_get_context ( struct spdk_memory_domain * domain )

Get the context passed by the user in spdk_memory_domain_create.

Parameters

domain Memory domain

Returns: Memory domain context

◆ spdk_memory_domain_get_dma_device_id()

const char * spdk_memory_domain_get_dma_device_id ( struct spdk_memory_domain * domain )

Get an identifier representing the DMA device that can access this memory domain.

Parameters

domain Memory domain

Returns: DMA device identifier

◆ spdk_memory_domain_get_dma_device_type()

enum spdk_dma_device_type spdk_memory_domain_get_dma_device_type ( struct spdk_memory_domain * domain )

Get type of the DMA device that can access this memory domain.

Parameters

domain Memory domain

Returns: DMA device type

◆ spdk_memory_domain_get_first()

struct spdk_memory_domain * spdk_memory_domain_get_first ( const char * id )

Get the first memory domain.

Combined with spdk_memory_domain_get_next to iterate over all memory domains

Parameters

id	Optional identifier representing the DMA device that can access a memory domain, if set then this function returns the first memory domain which id matches or NULL

Returns: Pointer to the first memory domain or NULL

◆ spdk_memory_domain_get_next()

struct spdk_memory_domain * spdk_memory_domain_get_next	(	struct spdk_memory_domain *	prev,
		const char *	id )

Get the next memory domain.

Parameters

prev	Previous memory domain
id	Optional identifier representing the DMA device that can access a memory domain, if set then this function returns the next memory domain which id matches or NULL

Returns: Pointer to next memory domain or NULL;

◆ spdk_memory_domain_get_system_domain()

struct spdk_memory_domain * spdk_memory_domain_get_system_domain ( void )

Get the System memory domain.

Returns: Pointer to the System memory domain.

◆ spdk_memory_domain_invalidate_data()

void spdk_memory_domain_invalidate_data	(	struct spdk_memory_domain *	domain,
		void *	domain_ctx,
		struct iovec *	iov,
		uint32_t	iovcnt )

Invalidate memory in the given domain.

This function calls domain invalidate callback, the callback needs to be set using spdk_memory_domain_set_invalidate function. This operation is optional and is meant to be executed on the translation result spdk_memory_domain_translate_data.

Parameters

domain	Memory domain in which address space of the buffer is located
domain_ctx	User defined context
iov	Iov vector in domain memory space to be invalidated
iovcnt	iov array size

◆ spdk_memory_domain_memzero()

int spdk_memory_domain_memzero	(	struct spdk_memory_domain *	domain,
		void *	domain_ctx,
		struct iovec *	iov,
		uint32_t	iovcnt,
		spdk_memory_domain_data_cpl_cb	cpl_cb,
		void *	cpl_cb_arg )

Fills memory in domain with zeroes.

Parameters

domain	Memory domain in which address space data buffer is located
domain_ctx	User defined context
iov	iov in domain memory space to be filled with zeroes
iovcnt	iov array size
cpl_cb	Completion callback
cpl_cb_arg	Completion callback argument

Returns: 0 on success, negated errno on failure. memzero implementation must only call the callback when 0 is returned

◆ spdk_memory_domain_pull_data()

int spdk_memory_domain_pull_data	(	struct spdk_memory_domain *	src_domain,
		void *	src_domain_ctx,
		struct iovec *	src_iov,
		uint32_t	src_iov_cnt,
		struct iovec *	dst_iov,
		uint32_t	dst_iov_cnt,
		spdk_memory_domain_data_cpl_cb	cpl_cb,
		void *	cpl_cb_arg )

Asynchronously pull data which is described by src_domain and located in src_iov to a location dst_iov local memory space.

Parameters

src_domain	Memory domain in which space data buffer is located
src_domain_ctx	User defined context
src_iov	Source data iov
src_iov_cnt	The number of elements in src_iov
dst_iov	Destination iov
dst_iov_cnt	The number of elements in dst_iov
cpl_cb	Completion callback
cpl_cb_arg	Completion callback argument

Returns: 0 on success, negated errno on failure. pull_cb implementation must only call the callback when 0 is returned

◆ spdk_memory_domain_push_data()

int spdk_memory_domain_push_data	(	struct spdk_memory_domain *	dst_domain,
		void *	dst_domain_ctx,
		struct iovec *	dst_iov,
		uint32_t	dst_iovcnt,
		struct iovec *	src_iov,
		uint32_t	src_iovcnt,
		spdk_memory_domain_data_cpl_cb	cpl_cb,
		void *	cpl_cb_arg )

Asynchronously push data located in local memory to dst_domain.

Parameters

dst_domain	Memory domain to which the data should be pushed
dst_domain_ctx	Optional context passed by upper layer with IO request
dst_iov	Iov vector in dst_domain space
dst_iovcnt	dst_iov array size
src_iov	Iov vector in local memory
src_iovcnt	src_iov array size
cpl_cb	Completion callback
cpl_cb_arg	Completion callback argument

Returns: 0 on success, negated errno on failure. push_cb implementation must only call the callback when 0 is returned

◆ spdk_memory_domain_set_invalidate()

void spdk_memory_domain_set_invalidate	(	struct spdk_memory_domain *	domain,
		spdk_memory_domain_invalidate_data_cb	invalidate_cb )

Set invalidate function for memory domain.

Overwrites existing invalidate function.

Parameters

domain	Memory domain
invalidate_cb	Invalidate function

◆ spdk_memory_domain_set_memzero()

void spdk_memory_domain_set_memzero	(	struct spdk_memory_domain *	domain,
		spdk_memory_domain_memzero_cb	memzero_cb )

Set memzero function for memory domain.

Overwrites existing memzero function.

Parameters

domain	Memory domain
memzero_cb	memzero function

◆ spdk_memory_domain_set_pull()

void spdk_memory_domain_set_pull	(	struct spdk_memory_domain *	domain,
		spdk_memory_domain_pull_data_cb	pull_cb )

Set pull function for memory domain.

Overwrites existing pull function.

Parameters

domain	Memory domain
pull_cb	pull function

◆ spdk_memory_domain_set_push()

void spdk_memory_domain_set_push	(	struct spdk_memory_domain *	domain,
		spdk_memory_domain_push_data_cb	push_cb )

Set push function for memory domain.

Overwrites existing push function.

Parameters

domain	Memory domain
push_cb	push function

◆ spdk_memory_domain_set_translation()

void spdk_memory_domain_set_translation	(	struct spdk_memory_domain *	domain,
		spdk_memory_domain_translate_memory_cb	translate_cb )

Set translation function for memory domain.

Overwrites existing translation function.

Parameters

domain	Memory domain
translate_cb	Translation function

◆ spdk_memory_domain_translate_data()

int spdk_memory_domain_translate_data	(	struct spdk_memory_domain *	src_domain,
		void *	src_domain_ctx,
		struct spdk_memory_domain *	dst_domain,
		struct spdk_memory_domain_translation_ctx *	dst_domain_ctx,
		void *	addr,
		size_t	len,
		struct spdk_memory_domain_translation_result *	result )

Translate data located in src_domain space at address addr with size len into an equivalent description of memory in dst_domain.

This function calls src_domain translation callback, the callback needs to be set using spdk_memory_domain_set_translation function. No data is moved during this operation. Both src_domain and dst_domain must describe the same physical memory, just from the point of view of two different memory domain. This is a translation of the description of the memory only. Result of translation is stored in result, its content depends on the type of dst_domain.

Parameters

src_domain	Memory domain in which address space data buffer is located
src_domain_ctx	User defined context
dst_domain	Memory domain in which memory space data buffer should be translated
dst_domain_ctx	Ancillary data for dst_domain
addr	Address in src_domain memory space
len	Length of the data
result	Translation result. The content of the translation result is only valid if this function returns 0.

Returns: 0 on success, negated errno on failure.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ spdk_memory_domain_data_cpl_cb

◆ spdk_memory_domain_invalidate_data_cb

◆ spdk_memory_domain_memzero_cb

◆ spdk_memory_domain_pull_data_cb

◆ spdk_memory_domain_push_data_cb

◆ spdk_memory_domain_translate_memory_cb

Enumeration Type Documentation

◆ spdk_dma_device_type

Function Documentation

◆ spdk_memory_domain_create()

◆ spdk_memory_domain_destroy()

◆ spdk_memory_domain_get_context()

◆ spdk_memory_domain_get_dma_device_id()

◆ spdk_memory_domain_get_dma_device_type()

◆ spdk_memory_domain_get_first()

◆ spdk_memory_domain_get_next()

◆ spdk_memory_domain_get_system_domain()

◆ spdk_memory_domain_invalidate_data()

◆ spdk_memory_domain_memzero()

◆ spdk_memory_domain_pull_data()

◆ spdk_memory_domain_push_data()

◆ spdk_memory_domain_set_invalidate()

◆ spdk_memory_domain_set_memzero()

◆ spdk_memory_domain_set_pull()

◆ spdk_memory_domain_set_push()

◆ spdk_memory_domain_set_translation()

◆ spdk_memory_domain_translate_data()