ioat.h File Reference

I/OAT DMA engine driver public interface. More...

Typedefs

typedef void(* spdk_ioat_req_cb) (void *arg)
 Signature for callback function invoked when a request is completed. More...
 
typedef bool(* spdk_ioat_probe_cb) (void *cb_ctx, struct spdk_pci_device *pci_dev)
 Callback for spdk_ioat_probe() enumeration. More...
 
typedef void(* spdk_ioat_attach_cb) (void *cb_ctx, struct spdk_pci_device *pci_dev, struct spdk_ioat_chan *ioat)
 Callback for spdk_ioat_probe() to report a device that has been attached to the userspace I/OAT driver. More...
 

Enumerations

enum  spdk_ioat_dma_capability_flags { SPDK_IOAT_ENGINE_COPY_SUPPORTED = 0x1 , SPDK_IOAT_ENGINE_FILL_SUPPORTED = 0x2 }
 DMA engine capability flags. More...
 

Functions

int spdk_ioat_probe (void *cb_ctx, spdk_ioat_probe_cb probe_cb, spdk_ioat_attach_cb attach_cb)
 Enumerate the I/OAT devices attached to the system and attach the userspace I/OAT driver to them if desired. More...
 
void spdk_ioat_detach (struct spdk_ioat_chan *ioat)
 Detach specified device returned by spdk_ioat_probe() from the I/OAT driver. More...
 
uint32_t spdk_ioat_get_max_descriptors (struct spdk_ioat_chan *chan)
 Get the maximum number of descriptors supported by the library. More...
 
int spdk_ioat_build_copy (struct spdk_ioat_chan *chan, void *cb_arg, spdk_ioat_req_cb cb_fn, void *dst, const void *src, uint64_t nbytes)
 Build a DMA engine memory copy request. More...
 
int spdk_ioat_submit_copy (struct spdk_ioat_chan *chan, void *cb_arg, spdk_ioat_req_cb cb_fn, void *dst, const void *src, uint64_t nbytes)
 Build and submit a DMA engine memory copy request. More...
 
int spdk_ioat_build_fill (struct spdk_ioat_chan *chan, void *cb_arg, spdk_ioat_req_cb cb_fn, void *dst, uint64_t fill_pattern, uint64_t nbytes)
 Build a DMA engine memory fill request. More...
 
int spdk_ioat_submit_fill (struct spdk_ioat_chan *chan, void *cb_arg, spdk_ioat_req_cb cb_fn, void *dst, uint64_t fill_pattern, uint64_t nbytes)
 Build and submit a DMA engine memory fill request. More...
 
void spdk_ioat_flush (struct spdk_ioat_chan *chan)
 Flush previously built descriptors. More...
 
int spdk_ioat_process_events (struct spdk_ioat_chan *chan)
 Check for completed requests on an I/OAT channel. More...
 
uint32_t spdk_ioat_get_dma_capabilities (struct spdk_ioat_chan *chan)
 Get the DMA engine capabilities. More...
 

Detailed Description

I/OAT DMA engine driver public interface.

Typedef Documentation

◆ spdk_ioat_attach_cb

typedef void(* spdk_ioat_attach_cb) (void *cb_ctx, struct spdk_pci_device *pci_dev, struct spdk_ioat_chan *ioat)

Callback for spdk_ioat_probe() to report a device that has been attached to the userspace I/OAT driver.

Parameters
cb_ctxUser-specified opaque value corresponding to cb_ctx from spdk_ioat_probe().
pci_devPCI device that was attached to the driver.
ioatI/OAT channel that was attached to the driver.

◆ spdk_ioat_probe_cb

typedef bool(* spdk_ioat_probe_cb) (void *cb_ctx, struct spdk_pci_device *pci_dev)

Callback for spdk_ioat_probe() enumeration.

Parameters
cb_ctxUser-specified opaque value corresponding to cb_ctx from spdk_ioat_probe().
pci_devPCI device that is being probed.
Returns
true to attach to this device.

◆ spdk_ioat_req_cb

typedef void(* spdk_ioat_req_cb) (void *arg)

Signature for callback function invoked when a request is completed.

Parameters
argUser-specified opaque value corresponding to cb_arg from the request submission.

Enumeration Type Documentation

◆ spdk_ioat_dma_capability_flags

DMA engine capability flags.

Enumerator
SPDK_IOAT_ENGINE_COPY_SUPPORTED 

The memory copy is supported.

SPDK_IOAT_ENGINE_FILL_SUPPORTED 

The memory fill is supported.

Function Documentation

◆ spdk_ioat_build_copy()

int spdk_ioat_build_copy ( struct spdk_ioat_chan *  chan,
void *  cb_arg,
spdk_ioat_req_cb  cb_fn,
void *  dst,
const void *  src,
uint64_t  nbytes 
)

Build a DMA engine memory copy request.

This function will build the descriptor in the channel's ring. The caller must also explicitly call spdk_ioat_flush to submit the descriptor, possibly after building additional descriptors.

Parameters
chanI/OAT channel to build request.
cb_argOpaque value which will be passed back as the arg parameter in the completion callback.
cb_fnCallback function which will be called when the request is complete.
dstDestination virtual address.
srcSource virtual address.
nbytesNumber of bytes to copy.
Returns
0 on success, negative errno on failure.

◆ spdk_ioat_build_fill()

int spdk_ioat_build_fill ( struct spdk_ioat_chan *  chan,
void *  cb_arg,
spdk_ioat_req_cb  cb_fn,
void *  dst,
uint64_t  fill_pattern,
uint64_t  nbytes 
)

Build a DMA engine memory fill request.

This function will build the descriptor in the channel's ring. The caller must also explicitly call spdk_ioat_flush to submit the descriptor, possibly after building additional descriptors.

Parameters
chanI/OAT channel to build request.
cb_argOpaque value which will be passed back as the cb_arg parameter in the completion callback.
cb_fnCallback function which will be called when the request is complete.
dstDestination virtual address.
fill_patternRepeating eight-byte pattern to use for memory fill.
nbytesNumber of bytes to fill.
Returns
0 on success, negative errno on failure.

◆ spdk_ioat_detach()

void spdk_ioat_detach ( struct spdk_ioat_chan *  ioat)

Detach specified device returned by spdk_ioat_probe() from the I/OAT driver.

Parameters
ioatI/OAT channel to detach from the driver.

◆ spdk_ioat_flush()

void spdk_ioat_flush ( struct spdk_ioat_chan *  chan)

Flush previously built descriptors.

Descriptors are flushed by writing the channel's dmacount doorbell register. This function enables batching multiple descriptors followed by a single doorbell write.

Parameters
chanI/OAT channel to flush.

◆ spdk_ioat_get_dma_capabilities()

uint32_t spdk_ioat_get_dma_capabilities ( struct spdk_ioat_chan *  chan)

Get the DMA engine capabilities.

Parameters
chanI/OAT channel to query.
Returns
a combination of flags from spdk_ioat_dma_capability_flags().

◆ spdk_ioat_get_max_descriptors()

uint32_t spdk_ioat_get_max_descriptors ( struct spdk_ioat_chan *  chan)

Get the maximum number of descriptors supported by the library.

Parameters
chanI/OAT channel
Returns
maximum number of descriptors.

◆ spdk_ioat_probe()

int spdk_ioat_probe ( void *  cb_ctx,
spdk_ioat_probe_cb  probe_cb,
spdk_ioat_attach_cb  attach_cb 
)

Enumerate the I/OAT devices attached to the system and attach the userspace I/OAT driver to them if desired.

If called more than once, only devices that are not already attached to the SPDK I/OAT driver will be reported.

To stop using the controller and release its associated resources, call spdk_ioat_detach() with the ioat_channel instance returned by this function.

Parameters
cb_ctxOpaque value which will be passed back in cb_ctx parameter of the callbacks.
probe_cbwill be called once per I/OAT device found in the system.
attach_cbwill be called for devices for which probe_cb returned true once the I/OAT controller has been attached to the userspace driver.
Returns
0 on success, -1 on failure.

◆ spdk_ioat_process_events()

int spdk_ioat_process_events ( struct spdk_ioat_chan *  chan)

Check for completed requests on an I/OAT channel.

Parameters
chanI/OAT channel to check for completions.
Returns
number of events handled on success, negative errno on failure.

◆ spdk_ioat_submit_copy()

int spdk_ioat_submit_copy ( struct spdk_ioat_chan *  chan,
void *  cb_arg,
spdk_ioat_req_cb  cb_fn,
void *  dst,
const void *  src,
uint64_t  nbytes 
)

Build and submit a DMA engine memory copy request.

This function will build the descriptor in the channel's ring and then immediately submit it by writing the channel's doorbell. Calling this function does not require a subsequent call to spdk_ioat_flush.

Parameters
chanI/OAT channel to submit request.
cb_argOpaque value which will be passed back as the arg parameter in the completion callback.
cb_fnCallback function which will be called when the request is complete.
dstDestination virtual address.
srcSource virtual address.
nbytesNumber of bytes to copy.
Returns
0 on success, negative errno on failure.

◆ spdk_ioat_submit_fill()

int spdk_ioat_submit_fill ( struct spdk_ioat_chan *  chan,
void *  cb_arg,
spdk_ioat_req_cb  cb_fn,
void *  dst,
uint64_t  fill_pattern,
uint64_t  nbytes 
)

Build and submit a DMA engine memory fill request.

This function will build the descriptor in the channel's ring and then immediately submit it by writing the channel's doorbell. Calling this function does not require a subsequent call to spdk_ioat_flush.

Parameters
chanI/OAT channel to submit request.
cb_argOpaque value which will be passed back as the cb_arg parameter in the completion callback.
cb_fnCallback function which will be called when the request is complete.
dstDestination virtual address.
fill_patternRepeating eight-byte pattern to use for memory fill.
nbytesNumber of bytes to fill.
Returns
0 on success, negative errno on failure.