class xlnx::qdma_interface¶

#include "qdma_exports.h"

Overview

qdma_interface - libqdma interface class

This class defines the interfaces that can be used while using the libqdma library.

Fields

WDFDMAENABLER dma_enabler

Handle to WDF DMA Enabler object to enable and start DMA operations

Methods¶

init¶

Syntax:

virtual NTSTATUS init (
    queue_op_mode operation_mode,
    UINT8 cfg_bar,
    UINT16 qsets_max
    ) = 0

Details:

init() - Initializes the qdma device with operation mode and config bar number to use

Parameters:

operation_mode	queue oper mode (poll, intr, aggr)
cfg_bar	config bar number for qdma device
qsets_max	Maximum number of queues requested for this device

Returns:

STATUS_SUCCESS for success else error

open¶

Syntax:

virtual NTSTATUS open (
    WDFDEVICE device,
    WDFCMRESLIST resources,
    WDFCMRESLIST resources_translated
    ) = 0

Details:

open() - Prepares the qdma_device with all necessary information like allocating memory for resources, BAR mappings, Initializes the hardware structure, Initializes queues etc.,

Parameters:

device	WDF Device
resources	Handle to WDF Framework raw HW resources list
resources_translated	Handle to WDF Framework translated HW resources list

Returns:

STATUS_SUCCESS for success else error

close¶

Syntax:

virtual void close (void) = 0

Details:

close() - Closes the QDMA device by freeing memory for resources, unmapping BARs, De-initializes the hardware structure, De-initializes queues etc.,

Returns:

void

qdma_is_device_online¶

Syntax:

virtual bool qdma_is_device_online (void) = 0

Details:

qdma_is_device_online() - Checks if qdma device is ready for operations.

Returns:

true when device is online state. false when device is offline state.

read_bar¶

Syntax:

virtual NTSTATUS read_bar (
    qdma_bar_type bar_type,
    size_t offset,
    void* data,
    size_t size
    ) = 0

Details:

read_bar() - Performs PCIe read operation on specified BAR number at requested offset of requested size

Parameters:

bar_type	BAR Type
offset	address offset to read the data from
data	data buffer to store the read data
size	size of the requested read operation(in bytes)

Returns:

STATUS_SUCCESS for success else error

write_bar¶

Syntax:

virtual NTSTATUS write_bar (
    qdma_bar_type bar_type,
    size_t offset,
    void* data,
    size_t size
    ) = 0

Details:

write_bar() - Performs PCIe write operation on specified BAR number at requested offset of requested size

Parameters:

bar_type	BAR Type
offset	address offset to write the data to
data	data buffer contains the data bytes to write
size	size of the requested write operation(in bytes)

Returns:

STATUS_SUCCESS for success else error

qdma_get_queues_state¶

Syntax:

virtual NTSTATUS qdma_get_queues_state (
    UINT16 qid,
    char* state,
    size_t sz
    ) = 0

Details:

qdma_get_queues_state() - Retrieves the state of the specified queue

Parameters:

qid	queue id relative to this QDMA device
state	state of the queue specified as character string
sz	size of the state character array

Returns:

STATUS_SUCCESS for success else error

qdma_add_queue¶

Syntax:

virtual NTSTATUS qdma_add_queue (
    UINT16 qid,
    queue_config& conf
    ) = 0

Details:

qdma_add_queue() - Configures the specified queue addition process with provided configuration

Parameters:

qid	queue id relative to this QDMA device
conf	configuration parameters for qid

Returns:

STATUS_SUCCESS for success else error

qdma_start_queue¶

Syntax:

virtual NTSTATUS qdma_start_queue (UINT16 qid) = 0

Details:

qdma_start_queue() - Starts the configured queue(qid) and the queue will be in operational state

Parameters:

qid	queue id relative to this QDMA device

Returns:

STATUS_SUCCESS for success else error

qdma_stop_queue¶

Syntax:

virtual NTSTATUS qdma_stop_queue (UINT16 qid) = 0

Details:

qdma_stop_queue() - Stops the queue(qid) and the queue will be in non operational state

Parameters:

qid	queue id relative to this QDMA device

Returns:

STATUS_SUCCESS for success else error

qdma_remove_queue¶

Syntax:

virtual NTSTATUS qdma_remove_queue (UINT16 qid) = 0

Details:

qdma_remove_queue() - Removes the queue(qid) configuration and puts in available state for re-use

Parameters:

qid	queue id relative to this QDMA device

Returns:

STATUS_SUCCESS for success else error

qdma_is_queue_in_range¶

Syntax:

virtual NTSTATUS qdma_is_queue_in_range (UINT16 qid) = 0

Details:

qdma_is_queue_in_range() - Validate qid of a queue for this device

Parameters:

qid	queue id relative to this QDMA device

Returns:

STATUS_SUCCESS for success else error

qdma_enqueue_mm_request¶

Syntax:

virtual NTSTATUS qdma_enqueue_mm_request (
    UINT16 qid,
    WDF_DMA_DIRECTION direction,
    PSCATTER_GATHER_LIST sg_list,
    LONGLONG device_offset,
    dma_completion_cb compl_cb,
    VOID* priv,
    size_t& xfered_len
    ) = 0

Details:

qdma_enqueue_mm_request() - enqueues an MM request into specified queue

Parameters:

qid	queue id relative to this QDMA device
direction	DMA direction (read or write)
sg_list	scatter-gather list of data buffers
device_offset	Device address to write/from read
compl_cb	completion call back function
priv	private data that gets passed to compl_cb function
xfered_len	If status is NT_SUCCESS, then number of bytes for a request successfully enqueued

Returns:

STATUS_SUCCESS for success else error

qdma_enqueue_st_tx_request¶

Syntax:

virtual NTSTATUS qdma_enqueue_st_tx_request (
    UINT16 qid,
    PSCATTER_GATHER_LIST sg_list,
    dma_completion_cb compl_cb,
    VOID* priv,
    size_t& xfered_len
    ) = 0

Details:

qdma_enqueue_st_tx_request() - enqueues an ST write request into specified queue

Parameters:

qid	queue id relative to this QDMA device
sg_list	scatter-gather list of data buffers
compl_cb	completion call back function to indicate write operation is completed
priv	private data that gets passed to compl_cb function
xfered_len	If status is NT_SUCCESS, then number of bytes for a request successfully enqueued.

Returns:

STATUS_SUCCESS for success else error

qdma_enqueue_st_rx_request¶

Syntax:

virtual NTSTATUS qdma_enqueue_st_rx_request (
    UINT16 qid,
    size_t length,
    st_rx_completion_cb compl_cb,
    VOID* priv
    ) = 0

Details:

qdma_enqueue_st_rx_request() - enqueues an ST read request into specified queue

Parameters:

qid	queue id relative to this QDMA device
length	desired data length to be received
compl_cb	completion call back function once data is available
priv	private data that gets passed to compl_cb function

Returns:

STATUS_SUCCESS for success else error

qdma_retrieve_st_udd_data¶

Syntax:

virtual NTSTATUS qdma_retrieve_st_udd_data (
    UINT16 qid,
    void* addr,
    UINT8* buf,
    UINT32* len
    ) = 0

Details:

qdma_retrieve_st_udd_data() - Retrieves the User Defined Data(side band data) from ST C2H descriptors

Parameters:

qid	queue id relative to this QDMA device
addr	UDD address in descriptor
buf	buffer to store user defined data
len	specifies the length of UDD in bytes

Returns:

STATUS_SUCCESS for success else error

qdma_retrieve_last_st_udd_data¶

Syntax:

virtual NTSTATUS qdma_retrieve_last_st_udd_data (
    UINT16 qid,
    UINT8* buf,
    UINT32* len
    ) = 0

Details:

qdma_retrieve_last_st_udd_data() - Retrieves the User Defined Data (side band data) from ST C2H descriptors that can be consumed in driver

Parameters:

qid	queue id relative to this QDMA device
buf	buffer to store user defined data
len	specifies the length of UDD in bytes

Returns:

STATUS_SUCCESS for success else error

qdma_queue_desc_dump¶

Syntax:

virtual NTSTATUS qdma_queue_desc_dump (qdma_desc_info* desc_info) = 0

Details:

qdma_queue_desc_dump() - Retrieves the descriptors data into desc_info

Parameters:

desc_info

pointer to qdma_desc_info

Returns:

STATUS_SUCCESS for success else error

qdma_read_mm_cmpt_data¶

Syntax:

virtual NTSTATUS qdma_read_mm_cmpt_data (qdma_cmpt_info* cmpt_info) = 0

Details:

qdma_read_mm_cmpt_data() - Retrieves the User Defined Data(side band data) from MM write back ring (if HW support available)

Parameters:

cmpt_info

user defined data(completion) information

Returns:

STATUS_SUCCESS for success else error

qdma_queue_dump_context¶

Syntax:

virtual NTSTATUS qdma_queue_dump_context (qdma_ctx_info* ctx_info) = 0

Details:

qdma_queue_dump_context() - Dumps the queue context information of given direction

Parameters:

ctx_info

context information structure

Returns:

STATUS_SUCCESS for success else error

qdma_intring_dump¶

Syntax:

virtual NTSTATUS qdma_intring_dump (qdma_intr_ring_info* intring_info) = 0

Details:

qdma_intring_dump() - Dumps the interrupt ring context information of given vector ID from start index to end index

Parameters:

intring_info

interrupt ring context information

Returns:

STATUS_SUCCESS for success else error

qdma_regdump¶

Syntax:

virtual NTSTATUS qdma_regdump (qdma_reg_dump_info* regdump_info) = 0

Details:

qdma_regdump() - Dumps all the QDMA registers to given buffer

Parameters:

regdump_info

Register dump information

Returns:

STATUS_SUCCESS for success else error

qdma_read_csr_conf¶

Syntax:

virtual NTSTATUS qdma_read_csr_conf (qdma_glbl_csr_conf* conf) = 0

Details:

qdma_read_csr_conf() - Retrieves the CSR registers information

Parameters:

conf	CSR registers information

Returns:

STATUS_SUCCESS for success else error

qdma_get_dev_capabilities_info¶

Syntax:

virtual NTSTATUS qdma_get_dev_capabilities_info (qdma_device_attributes_info& dev_attr) = 0

Details:

qdma_get_dev_capabilities_info() - Retrieves the HW device features info

Parameters:

dev_attr

HW device attributes

Returns:

STATUS_SUCCESS for success else error

qdma_device_version_info¶

Syntax:

virtual NTSTATUS qdma_device_version_info (qdma_version_info& version_info) = 0

Details:

qdma_device_version_info() - Retrieves the QDMA HW and SW versions in character array format

Parameters:

version_info

HW & SW versions information in character array format

Returns:

STATUS_SUCCESS for success else error

qdma_set_qmax¶

Syntax:

virtual NTSTATUS qdma_set_qmax (UINT32 qmax) = 0

Details:

qdma_set_qmax() - Set maximum queues number for this QDMA function.

Parameters:

qmax	Maximum number of queues for this function.

Returns:

STATUS_SUCCESS for success else error

qdma_get_qstats_info¶

Syntax:

virtual NTSTATUS qdma_get_qstats_info (qdma_qstat_info& qstats) = 0

Details:

qdma_get_qstats_info() - Retrieves the QDMA statistics for queue resources

Parameters:

qstats

Total queues for function with occupied H2C, C2H and CMPT queues count.

Returns:

STATUS_SUCCESS for success else error

create_qdma_device¶

Syntax:

static qdma_interface* create_qdma_device (void)

Details:

create_qdma_device() - Allocates an instance for qdma device

Returns:

Address of qdma_interface class or NULL in case of error

remove_qdma_device¶

Syntax:

static void remove_qdma_device (qdma_interface* qdma_dev)

Details:

remove_qdma_device() - frees the allocated instance for qdma_device

Parameters:

qdma_dev

address of the qdma_device instance

Returns:

void