QDMA Linux Driver Exported APIs¶

Xilinx QDMA Library Interface Definitions

Header file libqdma_export.h defines data structures and function signatures exported by Xilinx QDMA(libqdma) Library. libqdma is part of Xilinx QDMA Linux Driver.

enum qdma_error_codes¶: List of QDMA error codes

Constants

QDMA_OPERATION_SUCCESSFUL

QDMA driver API operation successful

QDMA_ERR_PCI_DEVICE_NOT_FOUND

not found on the PCIe bus

QDMA_ERR_PCI_DEVICE_ALREADY_ATTACHED

device already attached

QDMA_ERR_PCI_DEVICE_ENABLE_FAILED

Failed to enable the PCIe device

QDMA_ERR_PCI_DEVICE_INIT_FAILED

Failed to initialize the device

QDMA_ERR_INVALID_INPUT_PARAM

Invalid input parameter received

QDMA_ERR_INVALID_PCI_DEV

Invalid PCIe device

QDMA_ERR_INVALID_QIDX

Invalid Queue ID provided as input

QDMA_ERR_INVALID_DESCQ_STATE

Invalid descriptor queue state

QDMA_ERR_INVALID_DIRECTION

Invalid descriptor direction provided

QDMA_ERR_DESCQ_SETUP_FAILED

Failed to setup the descriptor queue

QDMA_ERR_DESCQ_FULL

Descriptor queue is full

QDMA_ERR_DESCQ_IDX_ALREADY_ADDED

Descriptor queue index is already added

QDMA_ERR_QUEUE_ALREADY_CONFIGURED

Queue is already configured

QDMA_ERR_OUT_OF_MEMORY

Out of memory

QDMA_ERR_INVALID_QDMA_DEVICE

Invalid QDMA device, QDMA device: is not yet created

QDMA_ERR_INTERFACE_NOT_ENABLED_IN_DEVICE

The ST or MM or Both: interface not enabled in the device

QDMA_ERR_MISSING_DEVICE_CAPABILITY

Device capability is: missing

Description

When libqdma APIs are invoked by application, if any error occured, the corresponding error code would be returned.

enum qdma_drv_mode¶: Indicates whether PF/VF qdma driver is loaded in poll or interrupt mode

Constants

AUTO_MODE

auto mode decided automatically,: mix of poll and interrupt mode

POLL_MODE

driver is inserted in poll mode

DIRECT_INTR_MODE

driver is inserted in direct interrupt mode

INDIRECT_INTR_MODE

driver is inserted in: indirect interrupt mode

LEGACY_INTR_MODE

driver is inserted in legacy interrupt mode

Description

QDMA PF/VF drivers can be loaded in one of these modes. Mode options is exposed as a user configurable module parameter

struct drv_mode_name¶: Structure to hold the driver name and mode

Definition

struct drv_mode_name {
  enum qdma_drv_mode drv_mode;
  char name;
};

Members

drv_mode: mode of the driver in which it it loaded.
name: Driver Name

Description

QDMA PF/VF drivers can be loaded in one of these modes. This structure holds the driver mode and name of the driver

int libqdma_init(unsigned int num_threads)¶: initializes the QDMA core library

Parameters

unsigned int num_threads: number of threads to be created each for request processing and writeback processing

Return

0: success <0: error

void libqdma_exit(void)¶: cleanup the QDMA core library before exiting

Parameters

void: no arguments

Description

cleanup the QDMA core library before exiting

enum intr_ring_size_sel¶: qdma interrupt ring size selection

Constants

INTR_RING_SZ_4KB: accommodates 512 entries
INTR_RING_SZ_8KB: accommodates 1024 entries
INTR_RING_SZ_12KB: accommodates 1536 entries
INTR_RING_SZ_16KB: accommodates 2048 entries
INTR_RING_SZ_20KB: accommodates 2560 entries
INTR_RING_SZ_24KB: accommodates 3072 entries
INTR_RING_SZ_28KB: accommodates 3584 entries
INTR_RING_SZ_32KB: accommodates 4096 entries

Description

Each interrupt vector can be associated with 1 or more interrupt rings. The software can choose 8 different interrupt ring sizes. The ring size for each vector is programmed during interrupt context programming

enum qdma_dev_qmax_state¶

Constants

QMAX_CFG_UNCONFIGURED

device qmax not configured

QMAX_CFG_INITIAL

device qmax configured with: initial default values

QMAX_CFG_USER

device qmax configured from: sysfs as per user choice

Description

Each PF/VF device can be configured with 0 or more number of queues. When the queue is not assigned to any device, device is in unfonfigured state. When PF/VF is instatiated, it has the default number of queues assigned and the device is in initial state. Sysfs interface enables the users to alter the default number of queues assigned to a device and it moves to user configured state.

QDMA_DEV_NAME_MAXLEN()¶

Parameters

struct qdma_dev_conf¶: device qdma property.

Definition

struct qdma_dev_conf {
  struct pci_dev * pdev;
  unsigned short qsets_max;
  unsigned short rsvd2;
  u8 zerolen_dma:1;
  u8 master_pf:1;
  u8 isr_top_q_en:1;
  u8 rsvd1:5;
  u8 vf_max;
  u8 intr_rngsz;
  u8 msix_qvec_max;
  unsigned long uld;
  enum qdma_drv_mode qdma_drv_mode;
  char name;
#ifdef RTL2_FEATURE_CONFIGURABLE_BAR
  char bar_num_config;
  char bar_num_user;
  char bar_num_bypass;
#endif
  char bar_num_config;
  char bar_num_user;
  char bar_num_bypass;
  char bar_num_stm;
  int qsets_base;
  u32 bdf;
  u32 idx;
  u8 tm_mode_en;
  u8 tm_one_cdh_en;
  void (* fp_user_isr_handler) (unsigned long dev_hndl, unsigned long uld);
  void (* fp_q_isr_top_dev) (unsigned long dev_hndl, unsigned long uld);
};

Members

pdev

pointer to pci_dev

qsets_max

Maximum number of queue pairs per device

rsvd2

Reserved

zerolen_dma

Indicates whether zero length: DMA is allowed or not

master_pf

Indicates whether the current pf: is master_pf or not

isr_top_q_en

extra handling of per descq handling in top half: (i.e., qdma_descq.fp_descq_isr_top will be set)

rsvd1

Reserved1

vf_max

Maximum number of virtual functions for: current physical function

intr_rngsz

Interrupt ring size

msix_qvec_max

max. of vectors used for queues.: libqdma update w/ actual #

uld

upper layer data, i.e. callback data

qdma_drv_mode

qdma driver mode

name

an unique string to identify the dev. current format: qdma[pf|vf][idx] filled in by libqdma

bar_num_config

dma config bar #, < 0 not present

bar_num_user

user bar

bar_num_bypass

bypass bar

bar_num_config

dma config bar #, < 0 not present

bar_num_user

user bar

bar_num_bypass

bypass bar

bar_num_stm

STM bar, PF only

qsets_base

queue base for this funciton

bdf

device index

idx

index of device in device list

tm_mode_en

xmit in traffic manager mode

tm_one_cdh_en

enable 1 CDH for Traffic Manager

fp_user_isr_handler

user interrupt, if null,: default libqdma handler is used

fp_q_isr_top_dev

Q interrupt top,: per-device addtional handling code

NOTE

if any of the max requested is less than supported, the value will: be updated

void intr_legacy_init(void)¶: legacy interrupt init

Parameters

void: no arguments

int qdma_device_open(const char * mod_name, struct qdma_dev_conf * conf, unsigned long * dev_hndl)¶: read the pci bars and configure the fpga This API should be called from probe()

Parameters

const char * mod_name: the module name, used for request_irq
struct qdma_dev_conf * conf: device configuration
unsigned long * dev_hndl: an opaque handle for libqdma to identify the device

Description

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

Return

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

void qdma_device_close(struct pci_dev * pdev, unsigned long dev_hndl)¶: prepare fpga for removal: disable all interrupts (users and qdma) and release all resources.This API should be called from remove()

Parameters

struct pci_dev * pdev: ptr to struct pci_dev
unsigned long dev_hndl: dev_hndl retured from qdma_device_open()

void qdma_device_offline(struct pci_dev * pdev, unsigned long dev_hndl)¶: Set the device in offline mode

Parameters

struct pci_dev * pdev: ptr to struct pci_dev
unsigned long dev_hndl: dev_hndl retured from qdma_device_open()

Return

0 for success and <0 for error

int qdma_device_online(struct pci_dev * pdev, unsigned long dev_hndl)¶: Set the device in online mode and re-initialze it

Parameters

struct pci_dev * pdev: ptr to struct pci_dev
unsigned long dev_hndl: dev_hndl retured from qdma_device_open()

Return

0 for success and <0 for error

int qdma_device_flr_quirk_set(struct pci_dev * pdev, unsigned long dev_hndl)¶: start pre-flr processing

Parameters

struct pci_dev * pdev: ptr to struct pci_dev
unsigned long dev_hndl: dev_hndl returned from qdma_device_open()

Return

0 for success and <0 for error

int qdma_device_flr_quirk_check(struct pci_dev * pdev, unsigned long dev_hndl)¶: check if pre-flr processing completed

Parameters

struct pci_dev * pdev: ptr to struct pci_dev
unsigned long dev_hndl: dev_hndl retunred from qdma_device_open()

Return

0 for success <0 for error

int qdma_device_get_config(unsigned long dev_hndl, struct qdma_dev_conf * conf, char * ebuf, int ebuflen)¶: retrieve the current device configuration

Parameters

unsigned long dev_hndl: dev_hndl retunred from qdma_device_open()
struct qdma_dev_conf * conf: device configuration
char * ebuf: error message buffer, can be NULL/0 (i.e., optional)
int ebuflen: input buffer length

Return

0 for success and <0 for error

int qdma_device_clear_stats(unsigned long dev_hndl)¶: clear device statistics

Parameters

unsigned long dev_hndl: dev_hndl retunred from qdma_device_open()

Return

0 for success and <0 for error

int qdma_device_get_mmh2c_pkts(unsigned long dev_hndl, unsigned long long * mmh2c_pkts)¶: get mm h2c packets processed

Parameters

unsigned long dev_hndl: dev_hndl retunred from qdma_device_open()
unsigned long long * mmh2c_pkts: number of mm h2c packets processed

Return

0 for success and <0 for error

int qdma_device_get_mmc2h_pkts(unsigned long dev_hndl, unsigned long long * mmc2h_pkts)¶: get mm c2h packets processed

Parameters

unsigned long dev_hndl: dev_hndl retunred from qdma_device_open()
unsigned long long * mmc2h_pkts: number of mm c2h packets processed

Return

0 for success and <0 for error

int qdma_device_get_sth2c_pkts(unsigned long dev_hndl, unsigned long long * sth2c_pkts)¶: get st h2c packets processed

Parameters

unsigned long dev_hndl: dev_hndl retunred from qdma_device_open()
unsigned long long * sth2c_pkts: number of st h2c packets processed

Return

0 for success and <0 for error

int qdma_device_get_stc2h_pkts(unsigned long dev_hndl, unsigned long long * stc2h_pkts)¶: get st c2h packets processed

Parameters

unsigned long dev_hndl: dev_hndl retunred from qdma_device_open()
unsigned long long * stc2h_pkts: number of st c2h packets processed

Return

0 for success and <0 for error

int qdma_device_set_config(unsigned long dev_hndl, struct qdma_dev_conf * conf)¶: set the current device configuration

Parameters

unsigned long dev_hndl: dev_hndl returned from qdma_device_open()
struct qdma_dev_conf * conf: device configuration to set

Return

0 for success and <0 for error

int qdma_device_sriov_config(struct pci_dev * pdev, unsigned long dev_hndl, int num_vfs)¶: configure sriov

Parameters

struct pci_dev * pdev: ptr to struct pci_dev
unsigned long dev_hndl: dev_hndl returned from qdma_device_open()
int num_vfs: # of VFs to be instantiated

Return

0 for success and <0 for error

configures sriov

unsigned int qdma_device_read_config_register(unsigned long dev_hndl, unsigned int reg_addr)¶: read dma config register

Parameters

unsigned long dev_hndl: dev_hndl returned from qdma_device_open()
unsigned int reg_addr: register address

Return

value of the config register

reads dma config register

void qdma_device_write_config_register(unsigned long dev_hndl, unsigned int reg_addr, u32 value)¶: write dma config register

Parameters

unsigned long dev_hndl: dev_hndl returned from qdma_device_open()
unsigned int reg_addr: register address
u32 value: register value to be writen

Description

writes dma config register

int qdma_device_capabilities_info(unsigned long dev_hndl, struct qdma_dev_attributes * dev_attr)¶: retrieve the capabilities of a device.

Parameters

unsigned long dev_hndl: handle returned from qdma_device_open()
struct qdma_dev_attributes * dev_attr: pointer to hold all the device attributes

Return

0 for success and <0 for error

struct qdma_version_info¶: defines the per-device version information

Definition

struct qdma_version_info {
  char rtl_version_str;
  char vivado_release_str;
  char everest_ip_str;
};

Members

rtl_version_str: Version string
vivado_release_str: Release string
everest_ip_str: Everest IP version string

int qdma_device_version_info(unsigned long dev_hndl, struct qdma_version_info * version_info)¶: retrieve the RTL version , Vivado Release ID and Everest IP info

Parameters

unsigned long dev_hndl: handle returned from qdma_device_open()
struct qdma_version_info * version_info: pointer to hold all the version details

Return

0 for success and <0 for error

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

int qdma_software_version_info(char * software_version)¶: retrieve the software version

Parameters

char * software_version: A pointer to a null-terminated string

Return

0 for success and <0 for error

retrieves the software version

struct global_csr_conf¶

Definition

struct global_csr_conf {
  unsigned int ring_sz;
  unsigned int c2h_timer_cnt;
  unsigned int c2h_cnt_th;
  unsigned int c2h_buf_sz;
  unsigned int wb_intvl;
};

Members

ring_sz: Descriptor ring size ie. queue depth
c2h_timer_cnt: C2H timer count list
c2h_cnt_th: C2H counter threshold list
c2h_buf_sz: C2H buffer size list
wb_intvl: Writeback interval

int qdma_global_csr_get(unsigned long dev_hndl, u8 index, u8 count, struct global_csr_conf * csr)¶: retrieve the global csr settings

Parameters

unsigned long dev_hndl: handle returned from qdma_device_open()
u8 index: Index from where the values needs to read
u8 count: number of entries to be read
struct global_csr_conf * csr: data structures to hold the csr values

Return

0 for success and <0 for error

retrieves the global csr settings

enum cmpt_desc_sz_t¶

Constants

CMPT_DESC_SZ_8B: completion size 8B
CMPT_DESC_SZ_16B: completion size 16B
CMPT_DESC_SZ_32B: completion size 32B
CMPT_DESC_SZ_64B: completion size 64B

enum desc_sz_t¶

Constants

DESC_SZ_8B: descriptor size 8B
DESC_SZ_16B: descriptor size 16B
DESC_SZ_32B: descriptor size 32B
DESC_SZ_64B: descriptor size 64B

enum tigger_mode_t¶

Constants

TRIG_MODE_DISABLE: disable trigger mode
TRIG_MODE_ANY: any trigger mode
TRIG_MODE_COUNTER: counter trigger mode
TRIG_MODE_USER: trigger mode of user choice
TRIG_MODE_TIMER: timer trigger mode
TRIG_MODE_COMBO: timer and counter combo trigger mode

struct qdma_sw_sg¶: qdma scatter gather request

Definition

struct qdma_sw_sg {
  struct qdma_sw_sg * next;
  struct page * pg;
  unsigned int offset;
  unsigned int len;
  dma_addr_t dma_addr;
};

Members

next: pointer to next page
pg: pointer to current page
offset: offset in current page
len: length of the page
dma_addr: dma address of the allocated page

struct qdma_queue_conf¶: qdma configuration parameters

Definition

struct qdma_queue_conf {
  u32 qidx:24;
  u32 st:1;
  u32 c2h:1;
  u32 pipe:1;
  u32 irq_en:1;
  u32 desc_rng_sz_idx:4;
  u8 wb_status_en:1;
  u8 cmpl_status_acc_en:1;
  u8 cmpl_status_pend_chk:1;
  u8 desc_bypass:1;
  u8 pfetch_en:1;
  u8 fetch_credit:1;
  u8 st_pkt_mode:1;
  u8 c2h_use_fl:1;
  u8 c2h_buf_sz_idx:4;
  u8 cmpl_rng_sz_idx:4;
  u8 cmpl_desc_sz:2;
  u8 cmpl_stat_en:1;
  u8 cmpl_udd_en:1;
  u8 cmpl_timer_idx:4;
  u8 cmpl_cnt_th_idx:4;
  u8 cmpl_trig_mode:3;
  u8 cmpl_en_intr:1;
  u8 sw_desc_sz:2;
  u8 pfetch_bypass:1;
  u8 cmpl_ovf_chk_dis:1;
  u8 port_id:3;
  u8 at:1;
  u8 en_mm_cmpt;
  u8 cdh_max;
  u8 pipe_gl_max;
  u8 pipe_flow_id;
  u8 pipe_slr_id;
  u16 pipe_tdest;
  unsigned long quld;
  void (* fp_descq_isr_top) (unsigned long qhndl, unsigned long quld);
  int (* fp_descq_c2h_packet) (unsigned long qhndl, unsigned long quld,unsigned int len, unsigned int sgcnt, struct qdma_sw_sg *sgl, void *udd);
  char name;
  unsigned int rngsz;
  unsigned int rngsz_cmpt;
  unsigned int c2h_bufsz;
};

Members

qidx

0xFFFF: libqdma choose the queue idx 0 ~

(qdma_dev_conf.qsets_max - 1) the calling function choose the: queue idx

st

Indicates the streaming mode

c2h

c2h direction

pipe

SDx only: inter-kernel communication pipe

irq_en

poll or interrupt

desc_rng_sz_idx

global_csr_conf.ringsz[N]

wb_status_en

writeback enable, disabled for ST C2H

cmpl_status_acc_en

sw context.cmpl_status_acc_en

cmpl_status_pend_chk

sw context.cmpl_stauts_pend_chk

desc_bypass

send descriptor to bypass out

pfetch_en

descriptor prefetch enable control

fetch_credit

sw context.frcd_en[32]

st_pkt_mode

SDx only: ST packet mode: (i.e., with TLAST to identify the packet boundary)

c2h_use_fl

c2h use pre-alloc free list

c2h_buf_sz_idx

global_csr_conf.c2h_buf_sz[N]

cmpl_rng_sz_idx

global_csr_conf.ringsz[N]

cmpl_desc_sz

C2H ST cmpt + immediate data, desc_sz_t

cmpl_stat_en

enable status desc. for CMPT

cmpl_udd_en

C2H Completion entry user-defined data

cmpl_timer_idx

global_csr_conf.c2h_timer_cnt[N]

cmpl_cnt_th_idx

global_csr_conf.c2h_cnt_th[N]

cmpl_trig_mode

tigger_mode_t

cmpl_en_intr

enable interrupt for CMPT

sw_desc_sz

SW Context desc size, desc_sz_t

pfetch_bypass

prefetch bypass en

cmpl_ovf_chk_dis

OVF_DIS C2H ST over flow disable

port_id

Port ID

at

Address Translation

en_mm_cmpt

MM Completions enabled?

cdh_max

max 16. CDH length per packet

pipe_gl_max

<= 7, max # gather buf. per packet

pipe_flow_id

pipe flow id

pipe_slr_id

pipe SLR id

pipe_tdest

pipe route id

quld

user provided per-Q irq handler

fp_descq_isr_top

Q interrupt top, per-queue additional handling: code for example, network rx napi_schedule(Q->napi)

fp_descq_c2h_packet

optional rx packet handler:: called from irq BH (i.e.:c:func:qdma_queue_service_bh())

udd: user defined data in the completion entry sgcnt / sgl: packet data in scatter-gather list

NOTE: a. do NOT modify any field of sgl

if zero copy, do a get_page() to prevent page freeing

do loop through the sgl with sg->next and stop at sgcnt. the last sg may not have sg->next = NULL

Returns:: 0 to allow libqdma free/re-task the sgl < 0, libqdma will keep the packet for processing again

A single packet could contain: in the case of c2h_udd_en = 1:

udd only (udd valid, sgcnt = 0, sgl = NULL), or udd + packdet data in the case of c2h_udd_en = 0: packet data (udd = NULL, sgcnt > 0 and sgl valid)

name

name of the qdma device

rngsz

ring size of the queue

rngsz_cmpt

completion ring size of the queue

c2h_bufsz

C2H buffer size

Description

qdma_queue_conf defines the per-dma Q property. if any of the max requested is less than supported, the value will be updated

int qdma_queue_add(unsigned long dev_hndl, struct qdma_queue_conf * qconf, unsigned long * qhndl, char * buf, int buflen)¶: add a queue

Parameters

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

Return

0 for success and <0 for error

int qdma_queue_config(unsigned long dev_hndl, unsigned long qid, struct qdma_queue_conf * qconf, char * buf, int buflen)¶: configure the queue with qcong parameters

Parameters

unsigned long dev_hndl: dev_hndl returned from qdma_device_open()
unsigned long qid: queue id
struct qdma_queue_conf * qconf: queue configuration parameters
char * buf: message buffer
int buflen: length of the input buffer

Description

return 0: success return <0: error

int qdma_queue_start(unsigned long dev_hndl, unsigned long id, char * buf, int buflen)¶: start a queue (i.e, online, ready for dma)

Parameters

unsigned long dev_hndl: dev_hndl returned from qdma_device_open()
unsigned long id: the opaque qhndl
char * buf: message buffer
int buflen: length of the input buffer

Return

0 for success and <0 for error

int qdma_queue_stop(unsigned long dev_hndl, unsigned long id, char * buf, int buflen)¶: stop a queue (i.e., offline, NOT ready for dma)

Parameters

unsigned long dev_hndl: dev_hndl returned from qdma_device_open()
unsigned long id: the opaque qhndl
char * buf: message buffer
int buflen: length of the input buffer

Return

0 for success and <0 for error

struct qdma_q_state¶: display queue state in a string buffer

Definition

struct qdma_q_state {
  u32 qstate;
  u32 qidx:24;
  u32 st:1;
  u32 c2h:1;
  u32 reserved:6;
};

Members

qstate

current q state

qidx

0xFFFF: libqdma choose the queue idx 0 ~

(qdma_dev_conf.qsets_max - 1) the calling function choose the: queue idx

st

Indicates the streaming mode

c2h

c2h direction

reserved

reserved

int qdma_queue_prog_stm(unsigned long dev_hndl, unsigned long id, char * buf, int buflen)¶: Program STM for queue (context, map, etc)

Parameters

unsigned long dev_hndl: dev_hndl returned from qdma_device_open()
unsigned long id: queue index
char * buf: message buffer
int buflen: length of the input buffer

Return

0 for success and <0 for error

int qdma_queue_remove(unsigned long dev_hndl, unsigned long id, char * buf, int buflen)¶: remove a queue

Parameters

unsigned long dev_hndl: dev_hndl returned from qdma_device_open()
unsigned long id: the opaque qhndl
char * buf: message buffer
int buflen: length of the input buffer

Return

0 for success and <0 for error

struct qdma_queue_conf * qdma_queue_get_config(unsigned long dev_hndl, unsigned long id, char * buf, int buflen)¶: retrieve the configuration of a queue

Parameters

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

Return

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

int qdma_queue_list(unsigned long dev_hndl, char * buf, int buflen)¶: display all configured queues in a string buffer

Parameters

unsigned long dev_hndl: dev_hndl returned from qdma_device_open()
char * buf: message buffer
int buflen: length of the input buffer

Return

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

int qdma_queue_dump(unsigned long dev_hndl, unsigned long id, char * buf, int buflen)¶: display a queue’s state in a string buffer

Parameters

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

Return

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

int qdma_queue_dump_desc(unsigned long dev_hndl, unsigned long id, unsigned int start, unsigned int end, char * buf, int buflen)¶: display a queue’s descriptor ring from index start ~ end in a string buffer

Parameters

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

Return

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

int qdma_queue_dump_cmpt(unsigned long dev_hndl, unsigned long id, unsigned int start, unsigned int end, char * buf, int buflen)¶: display a queue’s descriptor ring from index start ~ end in a string buffer

Parameters

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

Return

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

int qdma_queue_set_err_induction(unsigned long dev_hndl, unsigned long id, u32 err, char * buf, int buflen)¶: Induce the error

Parameters

unsigned long dev_hndl: dev_hndl returned from qdma_device_open()
unsigned long id: error id
u32 err: error info
char * buf: message buffer
int buflen: length of the input buffer

Return

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

struct qdma_request¶: qdma request for read or write

Definition

struct qdma_request {
  unsigned char opaque;
  unsigned long uld_data;
  int (* fp_done) (struct qdma_request *req, unsigned int bytes_done, int err);
  unsigned int timeout_ms;
  unsigned int count;
  u64 ep_addr;
  u8 no_memcpy:1;
  u8 write:1;
  u8 dma_mapped:1;
  u8 h2c_eot:1;
  u8 udd_len;
  unsigned int sgcnt;
  struct qdma_sw_sg * sgl;
  u8 udd;
};

Members

opaque

private to the dma driver, do NOT touch

uld_data

filled in by the calling function: for the calling function

fp_done

set fp_done for non-blocking mode

timeout_ms

timeout in mili-seconds, 0 - no timeout

count

total data size

ep_addr

MM only, DDR/BRAM memory addr

no_memcpy

flag to indicate if memcpy is required

write

if write to the device

dma_mapped

if sgt is already dma mapped

h2c_eot

user defined data present

udd_len

indicates end of transfer towards user kernel

sgcnt

# of scatter-gather entries < 64K

sgl

scatter-gather list of data bufs

udd

udd data

ssize_t qdma_request_submit(unsigned long dev_hndl, unsigned long id, struct qdma_request * req)¶: submit a scatter-gather list of data for dma operation (for both read and write)

Parameters

unsigned long dev_hndl: hndl returned from qdma_device_open()
unsigned long id: queue index
struct qdma_request * req: qdma request

Return

# of bytes transferred for success and <0 for error

ssize_t qdma_batch_request_submit(unsigned long dev_hndl, unsigned long id, unsigned long count, struct qdma_request ** reqv)¶: submit a scatter-gather list of data for dma operation (for both read and write)

Parameters

unsigned long dev_hndl: hndl returned from qdma_device_open()
unsigned long id: queue index
unsigned long count: number of requests
struct qdma_request ** reqv: qdma request

Return

# of bytes transferred for success and <0 for error

int qdma_queue_c2h_peek(unsigned long dev_hndl, unsigned long qhndl, unsigned int * udd_cnt, unsigned int * pkt_cnt, unsigned int * data_len)¶: peek a receive (c2h) queue

Parameters

unsigned long dev_hndl: hndl returned from qdma_device_open()
unsigned long qhndl: hndl returned from qdma_queue_add()
unsigned int * udd_cnt: # of udd received
unsigned int * pkt_cnt: # of packets received
unsigned int * data_len: # of bytes of packet data received

Description

filled in by libqdma:

Return

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

int qdma_queue_avail_desc(unsigned long dev_hndl, unsigned long qhndl)¶: query of # of free descriptor

Parameters

unsigned long dev_hndl: hndl returned from qdma_device_open()
unsigned long qhndl: hndl returned from qdma_queue_add()

Return

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

struct qdma_cmpl_ctrl¶: completion control

Definition

struct qdma_cmpl_ctrl {
  u8 cnt_th_idx:4;
  u8 timer_idx:4;
  u8 trigger_mode:3;
  u8 en_stat_desc:1;
  u8 cmpl_en_intr:1;
};

Members

cnt_th_idx: global_csr_conf.c2h_cnt_th[N]
timer_idx: global_csr_conf.c2h_timer_cnt[N]
trigger_mode: tigger_mode_t
en_stat_desc: enable status desc. for CMPT
cmpl_en_intr: enable interrupt for CMPT

int qdma_queue_cmpl_ctrl(unsigned long dev_hndl, unsigned long qhndl, struct qdma_cmpl_ctrl * cctrl, bool set)¶: read/set the c2h Q’s completion control

Parameters

unsigned long dev_hndl: hndl returned from qdma_device_open()
unsigned long qhndl: hndl returned from qdma_queue_add()
struct qdma_cmpl_ctrl * cctrl: completion control
bool set: read or set

Return

0 for success or <0 for error

int qdma_queue_packet_read(unsigned long dev_hndl, unsigned long qhndl, struct qdma_request * req, struct qdma_cmpl_ctrl * cctrl)¶: read rcv’ed data (ST C2H dma operation)

Parameters

unsigned long dev_hndl: hndl returned from qdma_device_open()
unsigned long qhndl: hndl returned from qdma_queue_add()
struct qdma_request * req: pointer to the request data
struct qdma_cmpl_ctrl * cctrl: completion control, if no change is desired, set it to NULL

Return

0 for success or <0 for error

int qdma_queue_packet_write(unsigned long dev_hndl, unsigned long qhndl, struct qdma_request * req)¶: submit data for h2c dma operation

Parameters

unsigned long dev_hndl: hndl returned from qdma_device_open()
unsigned long qhndl: hndl returned from qdma_queue_add()
struct qdma_request * req: pointer to the list of packet data

Return

0 for success or <0 for error

void qdma_queue_service(unsigned long dev_hndl, unsigned long qhndl, int budget, bool c2h_upd_cmpl)¶: 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

Parameters

unsigned long dev_hndl: dev_hndl returned from qdma_device_open()
unsigned long qhndl: hndl returned from qdma_queue_add()
int budget: ST C2H only, max number of completions to be processed.
bool c2h_upd_cmpl: flag to update the completion

int qdma_intr_ring_dump(unsigned long dev_hndl, unsigned int vector_idx, int start_idx, int end_idx, char * buf, int buflen)¶: display the interrupt ring info of a vector

Parameters

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

Return

0 for success or <0 for error

int qdma_descq_get_cmpt_udd(unsigned long dev_hndl, unsigned long qhndl, char * buf, int buflen)¶: function to receive the user defined data

Parameters

unsigned long dev_hndl: dev_hndl returned from qdma_device_open()
unsigned long qhndl: queue handle
char * buf: message bufferuffer
int buflen: length of the input buffer

Return

0 for success or <0 for error

int qdma_descq_read_cmpt_data(unsigned long dev_hndl, unsigned long qhndl, u32 * num_entries, u8 ** cmpt_entries, char * buf, int buflen)¶: function to receive the completion data

Parameters

unsigned long dev_hndl: dev_hndl returned from qdma_device_open()
unsigned long qhndl: queue handle
u32 * num_entries: I/O number of entries
u8 ** cmpt_entries: List of completion entries
char * buf: message bufferuffer
int buflen: length of the input buffer

Return

0 for success or <0 for error

int qdma_vf_qconf(unsigned long dev_hndl, int qmax)¶: call for VF to request qmax number of Qs

Parameters

unsigned long dev_hndl: dev_hndl returned from qdma_device_open()
int qmax: number of qs requested by vf

Return

0 for success or <0 for error