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.
typedef bool(*	spdk_ioat_probe_cb) (void *cb_ctx, struct spdk_pci_device *pci_dev)
	Callback for spdk_ioat_probe() enumeration.
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.

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.
void	spdk_ioat_detach (struct spdk_ioat_chan *ioat)
	Detach specified device returned by spdk_ioat_probe() from the I/OAT driver.
uint32_t	spdk_ioat_get_max_descriptors (struct spdk_ioat_chan *chan)
	Get the maximum number of descriptors supported by the library.
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.
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.
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.
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.
void	spdk_ioat_flush (struct spdk_ioat_chan *chan)
	Flush previously built descriptors.
int	spdk_ioat_process_events (struct spdk_ioat_chan *chan)
	Check for completed requests on an I/OAT channel.
uint32_t	spdk_ioat_get_dma_capabilities (struct spdk_ioat_chan *chan)
	Get the DMA engine capabilities.

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_ctx	User-specified opaque value corresponding to cb_ctx from spdk_ioat_probe().
pci_dev	PCI device that was attached to the driver.
ioat	I/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_ctx	User-specified opaque value corresponding to cb_ctx from spdk_ioat_probe().
pci_dev	PCI 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

arg	User-specified opaque value corresponding to cb_arg from the request submission.

Enumeration Type Documentation

spdk_ioat_dma_capability_flags

enum 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

chan	I/OAT channel to build request.
cb_arg	Opaque value which will be passed back as the arg parameter in the completion callback.
cb_fn	Callback function which will be called when the request is complete.
dst	Destination virtual address.
src	Source virtual address.
nbytes	Number 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

chan	I/OAT channel to build request.
cb_arg	Opaque value which will be passed back as the cb_arg parameter in the completion callback.
cb_fn	Callback function which will be called when the request is complete.
dst	Destination virtual address.
fill_pattern	Repeating eight-byte pattern to use for memory fill.
nbytes	Number 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

ioat	I/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

chan	I/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

chan	I/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

chan	I/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_ctx	Opaque value which will be passed back in cb_ctx parameter of the callbacks.
probe_cb	will be called once per I/OAT device found in the system.
attach_cb	will 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

chan	I/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

chan	I/OAT channel to submit request.
cb_arg	Opaque value which will be passed back as the arg parameter in the completion callback.
cb_fn	Callback function which will be called when the request is complete.
dst	Destination virtual address.
src	Source virtual address.
nbytes	Number 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

chan	I/OAT channel to submit request.
cb_arg	Opaque value which will be passed back as the cb_arg parameter in the completion callback.
cb_fn	Callback function which will be called when the request is complete.
dst	Destination virtual address.
fill_pattern	Repeating eight-byte pattern to use for memory fill.
nbytes	Number of bytes to fill.

Returns

0 on success, negative errno on failure.