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 (qdma_drv_config conf) = 0

Details:

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

Parameters:

conf	Device operation configuration

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

get_bar_info¶

Syntax:

virtual NTSTATUS get_bar_info (
    qdma_bar_type bar_type,
    PVOID& bar_base,
    size_t& bar_length
    ) = 0

Details:

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

Parameters:

bar_type	BAR Type
bar_base	BAR base mapped address
bar_lenght	Bar length(in bytes)

Returns:

STATUS_SUCCESS for success else error

qdma_get_queues_state¶

Syntax:

virtual NTSTATUS qdma_get_queues_state (
    UINT16 qid,
    enum queue_state* qstate,
    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
qstate	state of the queue specified as enumeration
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
    ) = 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

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
    ) = 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

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

qdma_get_reg_info¶

Syntax:

virtual NTSTATUS qdma_get_reg_info (qdma_reg_info* reg_info) = 0

Details:

qdma_get_reg_info() - Retrieves the requested QDMA registers information

Parameters:

reg_info

Register information (Address, Len, etc.,)

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