Vitis HLS C Driver Reference

Syntax

int X<DUT>_Initialize(X<DUT> *InstancePtr, u16 DeviceId);
int X<DUT>_Initialize(X<DUT> *InstancePtr, const char* InstanceName);

Description

int X<DUT>_Initialize(X<DUT> *InstancePtr, u16 DeviceId): For use on standalone systems, initialize a device. This API will write a proper value to InstancePtr which then can be used in other APIs. Xilinx recommends calling this API to initialize a device except when an MMU is used in the system, in which case refer to function X<DUT>_CfgInitialize.

int X<DUT>_Initialize(X<DUT> *InstancePtr, const char* InstanceName): For use on Linux systems, initialize a specifically named uio device. Create up to five memory mappings and assign the slave base addresses by mmap, utilizing the uio device information in sysfs.

InstancePtr

A pointer to the device instance.

DeviceId

Device ID as defined in xparameters.h.

InstanceName

The name of the uio device.

Return

XST_SUCCESS indicates success, otherwise fail.

Syntax

X<DUT>_CfgInitializeint X<DUT>_CfgInitialize(X<DUT> *InstancePtr, X<DUT>_Config *ConfigPtr);

Description

Initialize a device when an MMU is used in the system. In such a case the effective address of the AXI4-Lite slave is different from that defined in xparameters.h and API is required to initialize the device.

InstancePtr

A pointer to the device instance.

DeviceId

A pointer to a X<DUT>_Config.

Return

XST_SUCCESS indicates success, otherwise fail.

Syntax

X<DUT>_Config* X<DUT>_LookupConfig(u16 DeviceId);

Description

This function is used to obtain the configuration information of the device by ID.

DeviceId

Device ID as defined in xparameters.h.

Return

A pointer to a X<DUT>_LookupConfig variable that holds the configuration information of the device whose ID is DeviceId. NULL if no matching DeviceId is found.

Syntax

int X<DUT>_Release(X<DUT> *InstancePtr);

Description

Release the uio device. Delete the mappings by munmap. The mapping will automatically be deleted if the process is terminated.

InstanceName

The name of the uio device.

Return

XST_SUCCESS indicates success, otherwise fail.

Syntax

void X<DUT>_Start(X<DUT> *InstancePtr);

Description

Start the device. This function will assert the ap_start port on the device. Available only if there is ap_start port on the device.

InstancePtr

A pointer to the device instance.

Syntax

void X<DUT>_IsDone(X<DUT> *InstancePtr);

Description

Check if the device has finished the previous execution: this function will return the value of the ap_done port on the device. Available only if there is an ap_done port on the device.

InstancePtr

A pointer to the device instance.

Syntax

void X<DUT>_IsIdle(X<DUT> *InstancePtr);

Description

Check if the device is in idle state: this function will return the value of the ap_idle port. Available only if there is an ap_idle port on the device.

InstancePtr

A pointer to the device instance.

Syntax

void X<DUT>_IsReady(X<DUT> *InstancePtr);

Description

Check if the device is ready for the next input: this function will return the value of the ap_ready port. Available only if there is an ap_ready port on the device.

InstancePtr

A pointer to the device instance.

Syntax

void XExample_Continue(XExample *InstancePtr);

Description

Assert port ap_continue. Available only if there is an ap_continue port on the device.

InstancePtr

A pointer to the device instance.

Syntax

void X<DUT>_EnableAutoRestart(X<DUT> *InstancePtr);

Description

Enables “auto restart” on device. When this is enabled,

• Port ap_start will be asserted as soon as ap_done is asserted by the device and the device will auto-start the next transaction.
• Alternatively, if the block-level I/O protocol ap_ctrl_chain is implemented on the device, the next transaction will auto-restart (ap_start will be asserted) when ap_ready is asserted by the device and if ap_continue is asserted when ap_done is asserted by the device.

Available only if there is an ap_start port.

InstancePtr

A pointer to the device instance.

Syntax

void X<DUT>_DisableAutoRestart(X<DUT> *InstancePtr);

Description

Disable the “auto restart” function. Available only if there is an ap_start port.

InstancePtr

A pointer to the device instance.

Syntax

void X<DUT>_Set_ARG(X<DUT> *InstancePtr, u32 Data);

Description

Write a value to port ARG (a scalar argument of the top-level function). Available only if ARG is an input port.

InstancePtr

A pointer to the device instance.

Data

Value to write.

Syntax

void X<DUT>_Set_ARG_vld(X<DUT> *InstancePtr);

Description

Assert port ARG_vld. Available only if ARG is an input port and implemented with an ap_hs or ap_vld interface protocol.

InstancePtr

A pointer to the device instance.

Syntax

void X<DUT>_Set_ARG_ack(X<DUT> *InstancePtr);

Description

Assert port ARG_ack. Available only if ARG is an output port and implemented with an ap_hs or ap_ack interface protocol.

InstancePtr

A pointer to the device instance.

Syntax

u32 X<DUT>_Get_ARG(X<DUT> *InstancePtr);

Description

Read a value from ARG. Only available if port ARG is an output port on the device.

InstancePtr

A pointer to the device instance.

Return

Value of ARG.

Syntax

u32 X<DUT>_Get_ARG_vld(X<DUT> *InstancePtr);

Description

Read a value from ARG_vld. Only available if port ARG is an output port on the device and implemented with an ap_hs or ap_vld interface protocol.

InstancePtr

A pointer to the device instance.

Return

Value of ARG_vld.

Syntax

u32 X<DUT>_Get_ARG_ack(X<DUT> *InstancePtr);

Description

Read a value from ARG_ack. Only available if port ARG is an input port on the device and implemented with an ap_hs or ap_ack interface protocol.

InstancePtr

A pointer to the device instance.

Return

Value of ARG_ack.

Syntax

u32 X<DUT>_Get_ARG_BaseAddress(X<DUT> *InstancePtr);

Description

Return the base address of the array inside the interface. Only available when ARG is an array grouped into the AXI4-Lite interface.

InstancePtr

A pointer to the device instance.

Return

Base address of the array.

Syntax

u32 X<DUT>_Get_ARG_HighAddress(X<DUT> *InstancePtr);

Description

Return the address of the uppermost element of the array. Only available when ARG is an array grouped into the AXI4-Lite interface.

InstancePtr

A pointer to the device instance.

Return

Address of the uppermost element of the array.

Syntax

u32 X<DUT>_Get_ARG_TotalBytes(X<DUT> *InstancePtr);

Description

Return the total number of bytes used to store the array. Only available when ARG is an array grouped into the AXI4-Lite interface.

If the elements in the array are less than 16-bit, Vitis™ HLS groups multiple elements into the 32-bit data width of the AXI4-Lite interface. If the bit width of the elements exceeds 32-bit, Vitis HLS stores each element over multiple consecutive addresses.

InstancePtr

A pointer to the device instance.

Return

The total number of bytes used to store the array.

Syntax

u32 X<DUT>_Get_ARG_BitWidth(X<DUT> *InstancePtr);

Description

Return the bit width of each element in the array. Only available when ARG is an array grouped into the AXI4-Lite interface.

If the elements in the array are less than 16-bit, Vitis HLS groups multiple elements into the 32-bit data width of the AXI4-Lite interface. If the bit width of the elements exceeds 32-bit, Vitis HLS stores each element over multiple consecutive addresses.

InstancePtr

A pointer to the device instance.

Return

The bit-width of each element in the array.

Syntax

u32 X<DUT>_Get_ARG_Depth(X<DUT> *InstancePtr);

Description

Return the total number of elements in the array. Only available when ARG is an array grouped into the AXI4-Lite interface.

If the elements in the array are less than 16-bit, Vitis HLS groups multiple elements into the 32-bit data width of the AXI4-Lite interface. If the bit width of the elements exceeds 32-bit, Vitis HLS stores each element over multiple consecutive addresses.

InstancePtr

A pointer to the device instance.

Return

The total number of elements in the array.

Syntax

u32 X<DUT>_Write_ARG_Words(X<DUT> *InstancePtr, int offset, int *data, int length);

Description

Write the length of a 32-bit word into the specified address of the AXI4-Lite interface. This API requires the offset address from BaseAddress and the length of the data to be stored. Only available when ARG is an array grouped into the AXI4-Lite interface.

InstancePtr

A pointer to the device instance.

offset

The address in the AXI4-Lite interface.

data

A pointer to the data value to be stored.

length

The length of the data to be stored.

Return

Write length of data from the specified address.

Syntax

u32 X<DUT>_Read_ARG_Words(X<DUT> *InstancePtr, int offset, int *data, int length);

Description

Read the length of a 32-bit word from the array. This API requires the data target, the offset address from BaseAddress, and the length of the data to be stored. Only available when ARG is an array grouped into the AXI4-Lite interface.

InstancePtr

A pointer to the device instance.

offset

The address in the ARG.

data

A pointer to the data buffer.

length

The length of the data to be stored.

Return

Read length of data from the specified address.

Syntax

u32 X<DUT>_Write_ARG_Bytes(X<DUT> *InstancePtr, int offset, char *data, int length);

Description

Write the length of bytes into the specified address of theAXI4-Lite interface. This API requires the offset address from BaseAddress and the length of the data to be stored. Only available when ARG is an array grouped into the AXI4-Lite interface.

InstancePtr

A pointer to the device instance.

offset

The address in the ARG.

data

A pointer to the data value to be stored.

length

The length of the data to be stored.

Return

Write length of data from the specified address.

Syntax

u32 X<DUT>_Read_ARG_Bytes(X<DUT> *InstancePtr, int offset, char *data, int length);

Description

Read the length of bytes from the array. This API requires the data target, the offset address from Base Address, and the length of data to be loaded. Only available when ARG is an array grouped into the AXI4-Lite interface.

InstancePtr

A pointer to the device instance.

offset

The address in the ARG.

data

A pointer to the data buffer.

length

The length of the data to be loaded.

Return

Read length of data from the specified address.

Syntax

void X<DUT>_InterruptGlobalEnable(X<DUT> *InstancePtr);

Description

Enable the interrupt output. Interrupt functions are available only if there is ap_start.

InstancePtr

A pointer to the device instance.

Syntax

void X<DUT>_InterruptGlobalDisable(X<DUT> *InstancePtr);

Description

Disable the interrupt output.

InstancePtr

A pointer to the device instance.

Syntax

void X<DUT>_InterruptEnable(X<DUT> *InstancePtr, u32 Mask);

Description

Enable the interrupt source. There can be at most two interrupt sources (source 0 for ap_done and source 1 for ap_ready).

InstancePtr

A pointer to the device instance.

Mask

Bit mask.

• Bit n = 1: enable interrupt source n.
• Bit n = 0: no change.

Syntax

void X<DUT>_InterruptDisable(X<DUT> *InstancePtr, u32 Mask);

Description

Disable the interrupt source.

InstancePtr

A pointer to the device instance.

Mask

Bit mask.

• Bit n = 1: disable interrupt source n.
• Bit n = 0: no change.

Syntax

Description

Clear the interrupt status.

InstancePtr

A pointer to the device instance.

Mask

Bit mask.

• Bit n = 1: toggle interrupt source n.
• Bit n = 0: no change.

Syntax

u32 X<DUT>_InterruptGetEnabled(X<DUT> *InstancePtr);

Description

Check which interrupt sources are enabled.

InstancePtr

A pointer to the device instance.

Return

Bit mask.

• Bit n = 1: enabled.
• Bit n = 0: disabled.

Syntax

u32 X<DUT>_InterruptGetStatus(X<DUT> *InstancePtr);

Description

Check which interrupt sources are triggered.

InstancePtr

A pointer to the device instance.

Return

Bit mask.

• Bit n = 1: triggered.
• Bit n = 0: not triggered.