dma.h File Reference

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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 

Enumerations

enum  spdk_dma_device_type { SPDK_DMA_DEVICE_TYPE_RDMA , SPDK_DMA_DEVICE_TYPE_DMA , 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. More...
 
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. More...
 
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. More...
 
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. More...
 
void spdk_memory_domain_set_memzero (struct spdk_memory_domain *domain, spdk_memory_domain_memzero_cb memzero_cb)
 Set memzero function for memory domain. More...
 
struct spdk_memory_domain_ctxspdk_memory_domain_get_context (struct spdk_memory_domain *domain)
 Get the context passed by the user in spdk_memory_domain_create. More...
 
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. More...
 
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. More...
 
void spdk_memory_domain_destroy (struct spdk_memory_domain *domain)
 Destroy memory domain. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
struct spdk_memory_domain * spdk_memory_domain_get_first (const char *id)
 Get the first memory domain. More...
 
struct spdk_memory_domain * spdk_memory_domain_get_next (struct spdk_memory_domain *prev, const char *id)
 Get the next memory domain. More...
 

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
ctxUser context passed to pull of push functions
rcResult of asynchronous data pull or push function

◆ 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
domainMemory domain in which address space data buffer is located
domain_ctxUser defined context
ioviov in domain memory space to be filled with zeroes
iovcntiov array size
cpl_cbCompletion callback
cpl_cb_argCompletion 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_domainMemory domain to which the data buffer belongs
src_domain_ctxOptional context passed by upper layer with IO request
src_iovIov vector in src_domain space
src_iovcntsrc_iov array size
dst_iovIov 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_iovcntdst_iov array size
cpl_cbA callback to be called when pull operation completes
cpl_cb_argOptional 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_domainMemory domain to which the data should be pushed
dst_domain_ctxOptional context passed by upper layer with IO request
dst_iovIov vector in dst_domain space
dst_iovcntdst_iov array size
src_iovIov vector in local memory
src_iovcntsrc_iov array size
cpl_cbA callback to be called when push operation completes
cpl_cb_argOptional 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_domainMemory domain to which the data buffer belongs
src_domain_ctxOptional context passed by upper layer with IO request
dst_domainMemory domain which determines type of translation function
dst_domain_ctxAncillary data for dst_domain
addrData buffer address in src_domain memory space which should be translated into dst_domain
lenLength of data buffer
resultResult of translation function
Returns
0 on success, negated errno on failure

Enumeration Type Documentation

◆ 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_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
domainDouble pointer to memory domain to be allocated by this function
typeType of the DMA device which can access this memory domain
ctxOptional memory domain context to be copied by this function. Later ctx can be retrieved using spdk_memory_domain_get_context function
idString 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
domainMemory 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
domainMemory 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
domainMemory 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
domainMemory 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
idOptional 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
prevPrevious memory domain
idOptional 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_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
domainMemory domain in which address space data buffer is located
domain_ctxUser defined context
ioviov in domain memory space to be filled with zeroes
iovcntiov array size
cpl_cbCompletion callback
cpl_cb_argCompletion 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_domainMemory domain in which space data buffer is located
src_domain_ctxUser defined context
src_iovSource data iov
src_iov_cntThe number of elements in src_iov
dst_iovDestination iov
dst_iov_cntThe number of elements in dst_iov
cpl_cbCompletion callback
cpl_cb_argCompletion 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_domainMemory domain to which the data should be pushed
dst_domain_ctxOptional context passed by upper layer with IO request
dst_iovIov vector in dst_domain space
dst_iovcntdst_iov array size
src_iovIov vector in local memory
src_iovcntsrc_iov array size
cpl_cbCompletion callback
cpl_cb_argCompletion 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_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
domainMemory domain
memzero_cbmemzero 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
domainMemory domain
pull_cbpull 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
domainMemory domain
push_cbpush 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
domainMemory domain
translate_cbTranslation 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_domainMemory domain in which address space data buffer is located
src_domain_ctxUser defined context
dst_domainMemory domain in which memory space data buffer should be translated
dst_domain_ctxAncillary data for dst_domain
addrAddress in src_domain memory space
lenLength of the data
resultTranslation result. The content of the translation result is only valid if this function returns 0.
Returns
0 on success, negated errno on failure.