AXI4-Lite Slave C Driver Reference

When an AXI4-Lite slave interface is added to the design, a set of C driver files are automatically created. These C driver files provide a set of APIs that can be integrated into any software running on a CPU and used to communicate with the device using the AXI4-Lite interface.

The API functions derive their name from the top-level function for synthesis. This reference section assumes the top-level function is called DUT. The following table lists each of the API function provided in the C driver files.

Table 1. C Driver API Functions
API Function Description
XDut_Initialize This API will write 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.
XDut_CfgInitialize Initialize a device configuration. When a MMU is used in the system, replace the base address in the XDut_Config variable with virtual base address before calling this function. Not for use on Linux systems.
XDut_LookupConfig Used to obtain the configuration information of the device by ID. The configuration information contain the physical base address. Not for use on Linux.
XDut_Release Release the uio device in linux. Delete the mappings by munmap: the mapping will automatically be deleted if the process terminated. Only for use on Linux systems.
XDut_Start 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.
XDut_IsDone 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.
XDut_IsIdle 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.
XDut_IsReady 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.
XDut_Continue Assert port ap_continue. Available only if there is an ap_continue port on the device.
XDut_EnableAutoRestart Enables “auto restart” on device. When this is set the device will automatically start the next transaction when the current transaction completes.
XDut_DisableAutoRestart Disable the “auto restart” function.
XDut_Set_ARG Write a value to port ARG (a scalar argument of the top function). Available only if ARG is input port.
XDut_Set_ARG_vld Assert port ARG_vld. Available only if ARG is an input port and implemented with an ap_hs or ap_vld interface protocol.
XDut_Set_ARG_ack Assert port ARG_ack. Available only if ARG is an output port and implemented with an ap_hs or ap_ack interface protocol.
XDut_Get_ARG Read a value from ARG. Only available if port ARG is an output port on the device.
XDut_Get_ARg_vld 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.
XDut_Get_ARg_ack 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.
XDut_Get_ARG_BaseAddress Return the base address of the array inside the interface. Only available when ARG is an array grouped into the AXI4-Lite interface.
XDut_Get_ARG_HighAddress Return the address of the uppermost element of the array. Only available when ARG is an array grouped into the AXI4-Lite interface.
XDut_Get_ARG_TotalBytes

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.

XDut_Get_ARG_BitWidth

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.

XDut_Get_ARG_Depth

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.

XDut_Write_ARG_Words 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.
XDut_Read_ARG_Words 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.
XDut_Write_ARG_Bytes Write the length of bytes 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.
XDut_Read_ARG_Bytes Read the length of bytes from the array. This API requires the data target, the offset address from BaseAddress, and the length of data to be loaded. Only available when ARG is an array grouped into the AXI4-Lite interface.
XDut_InterruptGlobalEnable Enable the interrupt output. Interrupt functions are available only if there is ap_start.
XDut_InterruptGlobalDisable Disable the interrupt output.
XDut_InterruptEnable Enable the interrupt source. There may be at most 2 interrupt sources (source 0 for ap_done and source 1 for ap_ready)
XDut_InterruptDisable Disable the interrupt source.
XDut_InterruptClear Clear the interrupt status.
XDut_InterruptGetEnabled Check which interrupt sources are enabled.
XDut_InterruptGetStatus Check which interrupt sources are triggered.

The details on the API functions are provided below.

XDut_Initialize

Synopsis

int XDut_Initialize(XDut *InstancePtr, u16 DeviceId);

int XDut_Initialize(XDut *InstancePtr, const char* InstanceName);

Description

int XDut_Initialize(XDut *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 XDut_CfgInitialize.

int XDut_Initialize(XDut *InstancePtr, const char* InstanceName): For use on Linux systems, initialize a specifically named uio device. Create up to 5 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.

XDut_CfgInitialize

Synopsis

XDut_CfgInitializeint XDut_CfgInitialize(XDut *InstancePtr, XDut_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 XDut_Config.

Return: XST_SUCCESS indicates success, otherwise fail.

XDut_LookupConfig

Synopsis

XDut_Config* XDut_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 XDut_LookupConfig variable that holds the configuration information of the device whose ID is DeviceId. NULL if no matching DeviceId is found.

XDut_Release

Synopsis

int XDut_Release(XDut *InstancePtr);

Description

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

  • InstanceName: The name of the uio device.
  • Return: XST_SUCCESS indicates success, otherwise fail.

XDut_Start

Synopsis

void XDut_Start(XDut *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.

XDut_IsDone

Synopsis

void XDut_IsDone(XDut *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.

XDut_IsIdle

Synopsis

void XDut_IsIdle(XDut *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.

XDut_IsReady

Synopsis

void XDut_IsReady(XDut *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.

XDut_Continue

Synopsis

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.

XDut_EnableAutoRestart

Synopsis

void XDut_EnableAutoRestart(XDut *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.

XDut_DisableAutoRestart

Synopsis

void XDut_DisableAutoRestart(XDut *InstancePtr);

Description

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

  • InstancePtr: A pointer to the device instance.

XDut_Set_ARG

Synopsis

void XDut_Set_ARG(XDut *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.

XDut_Set_ARG_vld

Synopsis

void XDut_Set_ARG_vld(XDut *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.

XDut_Set_ARG_ack

Synopsis

void XDut_Set_ARG_ack(XDut *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.

XDut_Get_ARG

Synopsis

u32 XDut_Get_ARG(XDut *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.

XDut_Get_ARG_vld

Synopsis

u32 XDut_Get_ARG_vld(XDut *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.

XDut_Get_ARG_ack

Synopsis

u32 XDut_Get_ARG_ack(XDut *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.

XDut_Get_ARG_BaseAddress

Synopsis

u32 XDut_Get_ARG_BaseAddress(XDut *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.

XDut_Get_ARG_HighAddress

Synopsis

u32 XDut_Get_ARG_HighAddress(XDut *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.

XDut_Get_ARG_TotalBytes

Synopsis

u32 XDut_Get_ARG_TotalBytes(XDut *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.

XDut_Get_ARG_BitWidth

Synopsis

u32 XDut_Get_ARG_BitWidth(XDut *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.

XDut_Get_ARG_Depth

Synopsis

u32 XDut_Get_ARG_Depth(XDut *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.

XDut_Write_ARG_Words

Synopsis

u32 XDut_Write_ARG_Words(XDut *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.

XDut_Read_ARG_Words

Synopsis

u32 XDut_Read_ARG_Words(XDut *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.

XDut_Write_ARG_Bytes

Synopsis

u32 XDut_Write_ARG_Bytes(XDut *InstancePtr, int offset, char *data, int length);

Description

Write the length of bytes 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 ARG.
  • data: A pointer to the data value to be stored.
  • length: The length of data to be stored.

Return: Write length of data from the specified address.

XDut_Read_ARG_Bytes

Synopsis

u32 XDut_Read_ARG_Bytes(XDut *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 BaseAddress, 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 data to be loaded.

Return: Read length of data from the specified address.

XDut_InterruptGlobalEnable

Synopsis

void XDut_InterruptGlobalEnable(XDut *InstancePtr);

Description

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

  • InstancePtr: A pointer to the device instance.

XDut_InterruptGlobalDisable

Synopsis

void XDut_InterruptGlobalDisable(XDut *InstancePtr);

Description

Disable the interrupt output.

  • InstancePtr: A pointer to the device instance.

XDut_InterruptEnable

Synopsis

void XDut_InterruptEnable(XDut *InstancePtr, u32 Mask);

Description

Enable the interrupt source. There may be at most 2 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.

XDut_InterruptDisable

Synopsis

void XDut_InterruptDisable(XDut *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.

XDut_InterruptClear

Synopsis

void XDut_InterruptClear(XDut *InstancePtr, u32 Mask);

Description

Clear the interrupt status.

  • InstancePtr: A pointer to the device instance.
  • Mask: Bit mask.
    • Bit n = 1: toggle interrupt status n.
    • Bit n = 0: no change.

XDut_InterruptGetEnabled

Synopsis

u32 XDut_InterruptGetEnabled(XDut *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.

XDut_InterruptGetStatus

Synopsis

u32 XDut_InterruptGetStatus(XDut *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.