Global Functions¶

libqdma_init¶

Syntax:

int libqdma_init (
    unsigned int num_threads,
    void* debugfs_root
    )

Details:

Initializes the QDMA core library

Parameters:

num_threads	number of threads to be created each for request processing and writeback processing
debugfs_root	root path for debugfs

Returns:

0: success <0: error

libqdma_exit¶

Syntax:

void libqdma_exit (void)

Details:

cleanup the QDMA core library before exiting

intr_legacy_init¶

Syntax:

void intr_legacy_init (void)

Details:

legacy interrupt init

qdma_device_open¶

Syntax:

int qdma_device_open (
    const char* mod_name,
    struct qdma_dev_conf* conf,
    unsigned long* dev_hndl
    )

Details:

Read the pci bars and configure the fpga This API should be called from probe()

User interrupt will not be enabled until qdma_user_isr_enable() is called

Parameters:

mod_name	the module name, used for request_irq
conf	device configuration
dev_hndl	an opaque handle for libqdma to identify the device

Returns:

0 in case of success and <0 in case of error

qdma_device_close¶

Syntax:

int qdma_device_close (
    struct pci_dev* pdev,
    unsigned long dev_hndl
    )

Details:

Prepare fpga for removal: disable all interrupts (users and qdma) and release all resources.This API should be called from remove()

Parameters:

pdev	ptr to struct pci_dev
dev_hndl	dev_hndl retured from qdma_device_open()

Returns:

0 in case of success and <0 in case of error

qdma_device_offline¶

Syntax:

int qdma_device_offline (
    struct pci_dev* pdev,
    unsigned long dev_hndl,
    int reset
    )

Details:

Set the device in offline mode

Parameters:

pdev	ptr to struct pci_dev
dev_hndl	dev_hndl retured from qdma_device_open()
reset	0/1 function level reset active or not

Returns:

0 for success and <0 for error

qdma_device_online¶

Syntax:

int qdma_device_online (
    struct pci_dev* pdev,
    unsigned long dev_hndl,
    int reset
    )

Details:

Set the device in online mode and re-initialze it

Parameters:

pdev	ptr to struct pci_dev
dev_hndl	dev_hndl retured from qdma_device_open()
reset	0/1 function level reset active or not

Returns:

0 for success and <0 for error

qdma_device_flr_quirk_set¶

Syntax:

int qdma_device_flr_quirk_set (
    struct pci_dev* pdev,
    unsigned long dev_hndl
    )

Details:

Start pre-flr processing

Parameters:

pdev	ptr to struct pci_dev
dev_hndl	dev_hndl returned from qdma_device_open()

Returns:

0 for success and <0 for error

qdma_device_flr_quirk_check¶

Syntax:

int qdma_device_flr_quirk_check (
    struct pci_dev* pdev,
    unsigned long dev_hndl
    )

Details:

Check if pre-flr processing completed

Parameters:

pdev	ptr to struct pci_dev
dev_hndl	dev_hndl retunred from qdma_device_open()

Returns:

0 for success <0 for error

qdma_device_get_config¶

Syntax:

int qdma_device_get_config (
    unsigned long dev_hndl,
    struct qdma_dev_conf* conf,
    char* buf,
    int buflen
    )

Details:

Retrieve the current device configuration

Parameters:

dev_hndl	dev_hndl retunred from qdma_device_open()
conf	device configuration
buflen	input buffer length
buf	error message buffer, can be NULL/0 (i.e., optional)

Returns:

0 for success and <0 for error

qdma_device_clear_stats¶

Syntax:

int qdma_device_clear_stats (unsigned long dev_hndl)

Details:

Clear device statistics

Parameters:

dev_hndl

dev_hndl retunred from qdma_device_open()

Returns:

0 for success and <0 for error

qdma_device_get_mmh2c_pkts¶

Syntax:

int qdma_device_get_mmh2c_pkts (
    unsigned long dev_hndl,
    unsigned long long* mmh2c_pkts
    )

Details:

Get mm h2c packets processed

Parameters:

dev_hndl	dev_hndl retunred from qdma_device_open()
mmh2c_pkts	number of mm h2c packets processed

Returns:

0 for success and <0 for error

qdma_device_get_mmc2h_pkts¶

Syntax:

int qdma_device_get_mmc2h_pkts (
    unsigned long dev_hndl,
    unsigned long long* mmc2h_pkts
    )

Details:

Get mm c2h packets processed

Parameters:

dev_hndl	dev_hndl retunred from qdma_device_open()
mmc2h_pkts	number of mm c2h packets processed

Returns:

0 for success and <0 for error

qdma_device_get_sth2c_pkts¶

Syntax:

int qdma_device_get_sth2c_pkts (
    unsigned long dev_hndl,
    unsigned long long* sth2c_pkts
    )

Details:

Get st h2c packets processed

Parameters:

dev_hndl	dev_hndl retunred from qdma_device_open()
sth2c_pkts	number of st h2c packets processed

Returns:

0 for success and <0 for error

qdma_device_get_stc2h_pkts¶

Syntax:

int qdma_device_get_stc2h_pkts (
    unsigned long dev_hndl,
    unsigned long long* stc2h_pkts
    )

Details:

Get st c2h packets processed

Parameters:

dev_hndl	dev_hndl retunred from qdma_device_open()
stc2h_pkts	number of st c2h packets processed

Returns:

0 for success and <0 for error

qdma_device_get_ping_pong_min_lat¶

Syntax:

int qdma_device_get_ping_pong_min_lat (
    unsigned long dev_hndl,
    unsigned long long* min_lat
    )

Details:

Min latency (in CPU ticks) observed for all packets to do H2C-C2H loopback. Packet is transmitted in ST H2C direction, the user-logic ST Traffic generator is configured to loop back the packet in C2H direction. Timestamp (in CPU ticks) of the H2C transmission is embedded in H2C packet at time of PIDX update, then timestamp of the loopback packet is taken at time when data interrupt is hit, diff is used to measure roundtrip latency.

Parameters:

dev_hndl	dev_hndl retunred from qdma_device_open()
min_lat	Minimum ping pong latency in CPU ticks. Divide with the nominal CPU freqeuncy to get latency in NS.

Returns:

0 for success and <0 for error

qdma_device_get_ping_pong_max_lat¶

Syntax:

int qdma_device_get_ping_pong_max_lat (
    unsigned long dev_hndl,
    unsigned long long* max_lat
    )

Details:

Max latency (in CPU ticks) observed for all packets to do H2C-C2H loopback. Packet is transmitted in ST H2C direction, the user-logic ST Traffic generator is configured to loop back the packet in C2H direction. Timestamp (in CPU ticks) of the H2C transmission is embedded in H2C packet at time of PIDX update, then timestamp of the loopback packet is taken at time when data interrupt is hit, diff is used to measure roundtrip latency.

Parameters:

dev_hndl	dev_hndl retunred from qdma_device_open()
max_lat	Max ping pong latency in CPU ticks. Divide with the nominal CPU freqeuncy to get latency in NS.

Returns:

0 for success and <0 for error

qdma_device_get_ping_pong_tot_lat¶

Syntax:

int qdma_device_get_ping_pong_tot_lat (
    unsigned long dev_hndl,
    unsigned long long* lat_total
    )

Details:

Total latency (in CPU ticks) observed for all packets to do H2C-C2H loopback. Packet is transmitted in ST H2C direction, the user-logic ST Traffic generator is configured to loop back the packet in C2H direction. Timestamp (in CPU ticks) of the H2C transmission is embedded in H2C packet at time of PIDX update, then timestamp of the loopback packet is taken at time when data interrupt is hit, diff is used to measure roundtrip latency.

Parameters:

dev_hndl	dev_hndl retunred from qdma_device_open()
lat_total	Total Ping Pong latency. Divide with total loopback C2H packets to get average ping pong latency. Divide further with the nominal CPU frequency to get the avg latency in NS.

Returns:

0 for success and <0 for error

qdma_device_set_config¶

Syntax:

int qdma_device_set_config (
    unsigned long dev_hndl,
    struct qdma_dev_conf* conf
    )

Details:

Set the current device configuration

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
conf	device configuration to set

Returns:

0 for success and <0 for error

qdma_device_sriov_config¶

Syntax:

int qdma_device_sriov_config (
    struct pci_dev* pdev,
    unsigned long dev_hndl,
    int num_vfs
    )

Details:

Configure sriov

configures sriov

Parameters:

pdev	ptr to struct pci_dev
dev_hndl	dev_hndl returned from qdma_device_open()
num_vfs	# of VFs to be instantiated

Returns:

0 for success and <0 for error

qdma_device_read_config_register¶

Syntax:

int qdma_device_read_config_register (
    unsigned long dev_hndl,
    unsigned int reg_addr,
    unsigned int* value
    )

Details:

Read dma config register

reads dma config register

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
reg_addr	register address
value	pointer to hold the read value

Returns:

0 for success and <0 for error

qdma_device_write_config_register¶

Syntax:

int qdma_device_write_config_register (
    unsigned long dev_hndl,
    unsigned int reg_addr,
    unsigned int val
    )

Details:

Write dma config register

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
reg_addr	register address
val	register value to be writen

Returns:

0 for success and <0 for error writes dma config register

qdma_device_capabilities_info¶

Syntax:

int qdma_device_capabilities_info (
    unsigned long dev_hndl,
    struct qdma_dev_attributes* dev_attr
    )

Details:

retrieve the capabilities of a device.

Parameters:

dev_hndl	handle returned from qdma_device_open()
dev_attr	pointer to hold all the device attributes

Returns:

0 for success and <0 for error

qdma_device_version_info¶

Syntax:

int qdma_device_version_info (
    unsigned long dev_hndl,
    struct qdma_version_info* version_info
    )

Details:

Retrieve the RTL version , Vivado Release ID and Versal IP info

retrieves the RTL version , Vivado Release ID and Versal IP info

Parameters:

dev_hndl	handle returned from qdma_device_open()
version_info	pointer to hold all the version details

Returns:

0 for success and <0 for error

qdma_software_version_info¶

Syntax:

int qdma_software_version_info (
    char* software_version,
    int length
    )

Details:

Retrieve the software version

retrieves the software version

Parameters:

software_version	A pointer to a null-terminated string
length	Length of the version name string

Returns:

0 for success and <0 for error

qdma_global_csr_get¶

Syntax:

int qdma_global_csr_get (
    unsigned long dev_hndl,
    u8 index,
    u8 count,
    struct global_csr_conf* csr
    )

Details:

Retrieve the global csr settings

retrieves the global csr settings

Parameters:

dev_hndl	handle returned from qdma_device_open()
index	Index from where the values needs to read
count	number of entries to be read
csr	data structures to hold the csr values

Returns:

0 for success and <0 for error

qdma_queue_add¶

Syntax:

int qdma_queue_add (
    unsigned long dev_hndl,
    struct qdma_queue_conf* qconf,
    unsigned long* qhndl,
    char* buf,
    int buflen
    )

Details:

Add a queue

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
qconf	queue configuration parameters
qhndl	list of unsigned long values that are the opaque qhndl
buflen	length of the input buffer
buf	message buffer

Returns:

0 for success and <0 for error

qdma_queue_config¶

Syntax:

int qdma_queue_config (
    unsigned long dev_hndl,
    unsigned long qid,
    struct qdma_queue_conf* qconf,
    char* buf,
    int buflen
    )

Details:

Configure the queue with qcong parameters

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
qid	queue id
qconf	queue configuration parameters
buflen	length of the input buffer
buf	message buffer

Returns:

0: success <0: error

qdma_queue_start¶

Syntax:

int qdma_queue_start (
    unsigned long dev_hndl,
    unsigned long id,
    char* buf,
    int buflen
    )

Details:

start a queue (i.e, online, ready for dma)

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
id	the opaque qhndl
buflen	length of the input buffer
buf	message buffer

Returns:

0 for success and <0 for error

qdma_queue_stop¶

Syntax:

int qdma_queue_stop (
    unsigned long dev_hndl,
    unsigned long id,
    char* buf,
    int buflen
    )

Details:

Stop a queue (i.e., offline, NOT ready for dma)

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
id	the opaque qhndl
buflen	length of the input buffer
buf	message buffer

Returns:

0 for success and <0 for error

qdma_get_queue_state¶

Syntax:

int qdma_get_queue_state (
    unsigned long dev_hndl,
    unsigned long id,
    struct qdma_q_state* q_state,
    char* buf,
    int buflen
    )

Details:

Get the state of the queue

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
id	the opaque qhndl
q_state	state of the queue
buflen	length of the input buffer
buf	message buffer

Returns:

0 for success and <0 for error

qdma_queue_remove¶

Syntax:

int qdma_queue_remove (
    unsigned long dev_hndl,
    unsigned long id,
    char* buf,
    int buflen
    )

Details:

remove a queue

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
id	the opaque qhndl
buflen	length of the input buffer
buf	message buffer

Returns:

0 for success and <0 for error

qdma_queue_get_config¶

Syntax:

int qdma_queue_get_config (
    unsigned long dev_hndl,
    unsigned long id,
    struct qdma_queue_conf* qconf,
    char* buf,
    int buflen
    )

Details:

retrieve the configuration of a queue

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
id	an opaque queue handle of type unsigned long
qconf	pointer to hold the qdma_queue_conf structure.
buflen	length of the input buffer
buf	message buffer

Returns:

0: success <0: error

qdma_queue_list¶

Syntax:

int qdma_queue_list (
    unsigned long dev_hndl,
    int qidx,
    int num_q,
    char* buf,
    int buflen
    )

Details:

Display all configured queues in a string buffer

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
qidx	Queue index
num_q	Number of Queues to list
buflen	length of the input buffer
buf	message buffer

Returns:

if optional message buffer used then strlen of buf, otherwise QDMA_OPERATION_SUCCESSFUL and <0 for error

qdma_config_reg_dump¶

Syntax:

int qdma_config_reg_dump (
    unsigned long dev_hndl,
    char* buf,
    int buflen
    )

Details:

Display a config registers in a string buffer

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
buflen	length of the input buffer
buf	message buffer

Returns:

success: if optional message buffer used then strlen of buf, otherwise 0 and <0: error

qdma_queue_dump¶

Syntax:

int qdma_queue_dump (
    unsigned long dev_hndl,
    unsigned long id,
    char* buf,
    int buflen
    )

Details:

display a queue’s state in a string buffer

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
id	an opaque queue handle of type unsigned long
buflen	length of the input buffer
buf	message buffer

Returns:

if optional message buffer used then strlen of buf, otherwise QDMA_OPERATION_SUCCESSFUL and <0 for error

qdma_queue_dump_desc¶

Syntax:

int qdma_queue_dump_desc (
    unsigned long dev_hndl,
    unsigned long id,
    unsigned int start,
    unsigned int end,
    char* buf,
    int buflen
    )

Details:

Display a queue’s descriptor ring from index start ~ end in a string buffer

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
id	an opaque queue handle of type unsigned long
start	start index
end	end index
buflen	length of the input buffer
buf	message buffer

Returns:

if optional message buffer used then strlen of buf, otherwise QDMA_OPERATION_SUCCESSFUL and <0 for error

qdma_queue_dump_cmpt¶

Syntax:

int qdma_queue_dump_cmpt (
    unsigned long dev_hndl,
    unsigned long id,
    unsigned int start,
    unsigned int end,
    char* buf,
    int buflen
    )

Details:

display a queue’s descriptor ring from index start ~ end in a string buffer

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
id	an opaque queue handle of type unsigned long
start	start index
end	end index
buflen	length of the input buffer
buf	message buffer

Returns:

if optional message buffer used then strlen of buf, otherwise QDMA_OPERATION_SUCCESSFUL and <0 for error

qdma_request_submit¶

Syntax:

ssize_t qdma_request_submit (
    unsigned long dev_hndl,
    unsigned long id,
    struct qdma_request* req
    )

Details:

Submit a scatter-gather list of data for dma operation (for both read and write)

Parameters:

dev_hndl	hndl returned from qdma_device_open()
id	queue index
req	qdma request

Returns:

# of bytes transferred for success and <0 for error

qdma_batch_request_submit¶

Syntax:

ssize_t qdma_batch_request_submit (
    unsigned long dev_hndl,
    unsigned long id,
    unsigned long count,
    struct qdma_request** reqv
    )

Details:

Submit a scatter-gather list of data for dma operation (for both read and write)

Parameters:

dev_hndl	hndl returned from qdma_device_open()
id	queue index
count	number of requests
reqv	qdma request

Returns:

# of bytes transferred for success and <0 for error

qdma_queue_c2h_peek¶

Syntax:

int qdma_queue_c2h_peek (
    unsigned long dev_hndl,
    unsigned long id,
    unsigned int* udd_cnt,
    unsigned int* pkt_cnt,
    unsigned int* data_len
    )

Details:

Peek a receive (c2h) queue

filled in by libqdma:

Parameters:

dev_hndl	hndl returned from qdma_device_open()
id	queue hndl returned from qdma_queue_add()
udd_cnt	# of udd received
pkt_cnt	# of packets received
data_len	# of bytes of packet data received

Returns:

# of packets received in the Q or <0 for error

qdma_queue_avail_desc¶

Syntax:

int qdma_queue_avail_desc (
    unsigned long dev_hndl,
    unsigned long id
    )

Details:

Query of # of free descriptor

Parameters:

dev_hndl	hndl returned from qdma_device_open()
id	queue hndl returned from qdma_queue_add()

Returns:

# of available desc in the queue or <0 for error

qdma_queue_cmpl_ctrl¶

Syntax:

int qdma_queue_cmpl_ctrl (
    unsigned long dev_hndl,
    unsigned long id,
    struct qdma_cmpl_ctrl* cctrl,
    bool set
    )

Details:

packet/streaming interfaces Read/set the c2h Q’s completion control

Parameters:

dev_hndl	hndl returned from qdma_device_open()
id	hndl returned from qdma_queue_add()
cctrl	completion control
set	read or set

Returns:

0 for success or <0 for error

qdma_queue_packet_read¶

Syntax:

int qdma_queue_packet_read (
    unsigned long dev_hndl,
    unsigned long id,
    struct qdma_request* req,
    struct qdma_cmpl_ctrl* cctrl
    )

Details:

Read rcv’ed data (ST C2H dma operation)

Parameters:

dev_hndl	hndl returned from qdma_device_open()
id	queue hndl returned from qdma_queue_add()
req	pointer to the request data
cctrl	completion control, if no change is desired, set it to NULL

Returns:

# of bytes transferred for success and <0 for error

qdma_queue_packet_write¶

Syntax:

int qdma_queue_packet_write (
    unsigned long dev_hndl,
    unsigned long id,
    struct qdma_request* req
    )

Details:

Submit data for ST H2C dma operation

Parameters:

dev_hndl	hndl returned from qdma_device_open()
id	queue hndl returned from qdma_queue_add()
req	pointer to the list of packet data

Returns:

# of bytes transferred for success and <0 for error

qdma_queue_service¶

Syntax:

int qdma_queue_service (
    unsigned long dev_hndl,
    unsigned long id,
    int budget,
    bool c2h_upd_cmpl
    )

Details:

Service the queue in the case of irq handler is registered by the user, the user should call qdma_queue_service() in its interrupt handler to service the queue

Return: 0 for success or <0 for error

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
id	queue hndl returned from qdma_queue_add()
budget	ST C2H only, max number of completions to be processed.
c2h_upd_cmpl	flag to update the completion

qdma_queue_update_pointers¶

Syntax:

int qdma_queue_update_pointers (
    unsigned long dev_hndl,
    unsigned long qhndl
    )

Details:

Update queue pointers

Return: 0 for success or <0 for error

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
qhndl	hndl returned from qdma_queue_add()

qdma_intr_ring_dump¶

Syntax:

int qdma_intr_ring_dump (
    unsigned long dev_hndl,
    unsigned int vector_idx,
    int start_idx,
    int end_idx,
    char* buf,
    int buflen
    )

Details:

Display the interrupt ring info of a vector

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
vector_idx	vector number
start_idx	interrupt ring start idx
end_idx	interrupt ring end idx
buflen	length of the input buffer
buf	message bufferuffer

Returns:

0 for success or <0 for error

qdma_descq_get_cmpt_udd¶

Syntax:

int qdma_descq_get_cmpt_udd (
    unsigned long dev_hndl,
    unsigned long id,
    char* buf,
    int buflen
    )

Details:

Function to receive the user defined data

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
id	queue handle
buflen	length of the input buffer
buf	message bufferuffer

Returns:

0 for success or <0 for error

qdma_descq_read_cmpt_data¶

Syntax:

int qdma_descq_read_cmpt_data (
    unsigned long dev_hndl,
    unsigned long id,
    u32* num_entries,
    u8** cmpt_entries,
    char* buf,
    int buflen
    )

Details:

Function to receive the completion data

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
id	queue handle
num_entries	I/O number of entries
cmpt_entries	List of completion entries
buflen	length of the input buffer
buf	message bufferuffer

Returns:

0 for success or <0 for error

qdma_get_queue_count¶

Syntax:

int qdma_get_queue_count (
    unsigned long dev_hndl,
    struct qdma_queue_count* q_count,
    char* buf,
    int buflen
    )

Details:

Function to receive the queue count

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
q_count	queue count
buflen	length of the input buffer
buf	message bufferuffer

Returns:

0 for success or <0 for error

qdma_config_reg_info_dump¶

Syntax:

int qdma_config_reg_info_dump (
    unsigned long dev_hndl,
    uint32_t reg_addr,
    uint32_t num_regs,
    char* buf,
    int buflen
    )

Details:

Function to print out detailed information for register value

Parameters:

dev_hndl	dev_hndl returned from qdma_device_open()
reg_addr	register address
num_regs	num of registerse to be dumped
buf	message bufferuffer
buflen	length of the input buffer

Returns:

0 for success or <0 for error