XRT.jl Public API

struct XilinxDevice

A XilinxDevice struct that allows direct access to the device parameters as fields. The fields return always the up-to-date values.

Fields

device allows access to the XRT.XRTWrap.Device object if required.

index of the device as used by XRT.jl (starts at 1).

xclbin_uuid is a pointer to the last Xclbin UUID loaded onto the device.

bdf is the BDF for the device.

interface_uuid is the UUID when device is programmed with 2RP shell.

kdma is the number of KDMA engines.

max_clock_frequency_mhz is the maximum clock frequency.

m2m indicates whether the device contains m2m.

name is the device name.

nodma indicates whether the device is a NoDMA device.

offline indicates whether the device is offline.

electrical information about electrical and power sensors. Returns as a LazyJSON object.

thermal information about thermal sensors. Returns as a LazyJSON object.

mechanical information about mechanical sensors. Returns as a LazyJSON object.

memory information about device memory. Returns as a LazyJSON object.

platform is a LazyJSON object that contains information about platforms flashed on the device.

pcie_info information about PCIe. Returns as a LazyJSON object.

host is host information. Returns as a LazyJSON object.

aie information about AIE core of the device. Returns as a LazyJSON object.

aie_shim information about AIE shim of the device. Returns as a LazyJSON object.

dynamic_regions information about the xclbin on the device. Returns as a LazyJSON object.

vmr information about vmr on the device. Returns as a LazyJSON object.

Note: The constructor should in general not be called directly! Use XRT.device or XRT.devices instead!

get_xclbin_uuid(; device) -> XRT.XRTWrap.UUIDAllocated

Returns the UUID of the xclbin image that is currently loaded on the active device. The device can be changed by setting the device keyword parameter.

load_xclbin!(xclbin::XRT.Xclbin; device, force) -> XRT.UUID
load_xclbin!(path::String; device, force) -> XRT.UUID

Loads an XRT.Xclbin object on the current active device if it is not yet loaded onto it. The function returns the UUID of the xclbin. XRT.program! is an alias for load_xclbin!.

Keywords

device The target device can be changed by setting the device keyword parameter.

force Forces the Xclbin to be loaded onto the device.

Xclbin(path::AbstractString) -> Xclbin

Structure that allows a more convenient access to parameters provided XRTWrap.Xclbin type. Nevertheless, this type can be called with the field xclbin if required. With the instantiation of an Xclbin object several checks, such as the path or the target type are performed.

Fields

xclbin allows access to the XRT.XRTWrap.Xclbin object if required.

path is the absolute path that leads to the xclbin file.

filename is the file name of the xclbin file including the file extension.

kernels specifies a vector of XRT.XclbinKernel type objects. These elements provide information of all kernels given in the metadata.

ips specifies a vector of XRT.XclbinIP type objects. These elements represent the IP_LAYOUT section of the xclbin file.

mems specifies a vector of XRT.XclbinMem type objects.

xsa_name is the Xilinx Support Archive name of the xclbin file.

uuid is the UUID of the xclbin file.

fpga_device_name is the name of the FPGA device according to the metadata.

target_type is the type of the xlbin file. It is either set to hw, hw_emu, or sw_emu.

interface_uuid is the interface UUID when device is programmed with 2RP shell. Only available for XRT ≥ 2.16.

XclbinArg(arg::XRT.XRTWrap.XclbinArg) -> XRT.XclbinArg

XclbinArg data type that represents a compute unit argument. It treats the attributes of the APIs arg class as fields.

Fields

arg allows access to the XRT.XRTWrap.XclbinArg object if required.

name is the argument name.

mems specifies a vector of XRT.XclbinMem type objects. This vector represents memory objects to which the argument is connected.

port is the port name of the argument.

size is the argument size in bytes.

offset is the argument offset.

host_type is the argument host type.

julia_type is the host types corresponding Julia type.

index is the index of the argument.

XclbinIP(ip::XRT.XRTWrap.XclbinIP) -> XRT.XclbinIP

XclbinIP data type that represents a IP_LAYOUT section of an Xclbin. It treats the attributes of the APIs ip class as fields.

Fields

ip allows access to the XRT.XRTWrap.XclbinIP object if required.

name is the IP name.

cu_name if the IP is a CU it stores the CUs name after the colon.

type is the IP type. It is either set to pl or ps.

control_type is IP control type. It is set to one of hs, chain, none, or fa.

num_args is the number of arguments for the IP per CONNECTIVITY section.

args specifies a vector of XRT.XclbinArg type objects. This vector represents the arguments of the kernel sorted by indices.

base_address is the base address of the compute unit.

size is the address range size of the IP.

XclbinKernel(
    kernel::XRT.XRTWrap.XclbinKernel
) -> XRT.XclbinKernel

Kernel data type that represents a kernel of an Xclbin. It treats the attributes of the APIs kernel class as fields.

Fields

kernel allows access to the XRT.XRTWrap.XclbinKernel object if required.

name is the kernel name.

type is the type of the kernel. Only available for XRT ≥ 2.16.

cus specifies a vector of XRT.XclbinIP type objects. These elements represent the compute units for the kernel object.

num_args is the number of arguments for the kernel.

args specifies a vector of XRT.XclbinArg type objects. This vector represents the arguments of the kernel sorted by indices.

Note: XRT version 2.16 or newer supports the type field. However, this has yet not been implemented in XRT.jl.

XclbinMem(mem::XRT.XRTWrap.XclbinMem) -> XRT.XclbinMem

Memory data type that represents a physical device memory bank. It treats the attributes of the APIs mem class as fields.

Fields

mem allows access to the XRT.XRTWrap.XclbinMem object if required.

tag is the memory tag name.

base_address is the base adress of the memory bank.

size_kb is the size of the memory in KB.

used is the status of the memory, whether it is used by kernels in the xclbin file.

type is the memory type.

index is the index of the memory within the memory topology.

dump_section(
    xclbin::AbstractString,
    section::XRT.SectionType.Type,
    format::AbstractString,
    file::AbstractString
)

This function calls xclbinutil with the --dump-section flag in order to extract a section from the xclbin file. The section will be written to file file. The function provides similar functionality as the custom xclbin parser. It can be called either directly with the path to xclbin file or with an XRT.Xclbin object.

julia> XRT.dump_section("path/to/file.xclbin", XRT.SectionType.BUILD_METADATA, "JSON", "out.json")

info(xclbin::AbstractString; output) -> String

This function calls xclbinutil with the --info flag in order to obtain information provided by the xclbin data type. The optional keyword parameter output allows the output to be written to a file.

migrate_forward(
    xclbin::AbstractString,
    output::AbstractString
) -> Union{Nothing, Xclbin}

This function calls xclbinutil with the --migrate-forward flag in order to migrate an old xclbin format to the new AXLF based format. The migrated file will be returned as Xclbin type.

visualize_streams(xclbin::Xclbin; ...)
visualize_streams(
    xclbin::Xclbin,
    filter::AbstractString;
    io,
    force_io
)

This function analyses the streams between kernels, compute units and memory banks of an XRT.Xclbin object. It prints the resulting graph to the specified io. If the width of the terminal window is not sufficient for proper printing, the graph is printed in a temporary file. This can be prevented with the force_io keyword.

The function also allows the printing of only one single kernel/compute unit of an Xclbin file together with its corresponding streams. This is primarily required to analyse bitstreams with numerous compute units.

For example, a bitstream with a kernel FooKernel consisting of two compute units: FooKernel:BarCU and FooKernel:BazCU. To print only the first compute, filter="BarCU" can be set to the name of the kernel or the compute unit only.

Keywords

io specifies the output to print to.

force_io ensures usage of specified io.

get_kernel_info(xclbin_path::String) -> Any

Get information about contained kernels, instances, arguments and their register offsets as a LazyJSON object.

get_section_string(
    xclbin_path::String,
    type::XRT.SectionType.Type
) -> Union{Nothing, String}

Get the specified raw section from the bitstream file xclbin_path.

get_system_info(xclbin_path::String) -> Any

Get information about resource utilization and connectivity as a LazyJSON object.

Kernel(uuid::XRT.XRTWrap.UUID, name::AbstractString; device::XilinxDevice=device())
Kernel(uuid::XRT.XRTWrap.UUID, name::AbstractString, cus::Vararg{AbstractString}; device::XilinxDevice=device())
Kernel(uuid::XRT.XRTWrap.UUID, kernel::XclbinKernel, cus::Vararg{XclbinIP}; device::XilinxDevice=device())

Create a new kernel instance using a bitstream uuid and kernel name or XRT.XclbinKernel object. Optionally, the compute units to be executed can also be specified. To create the kernel on a device other than the current active device, use the device keyword parameter or set a wrapped device as first parameter.

Run(
    kernel::XRT.XRTWrap.Kernel,
    arg1,
    args...;
    autostart
) -> XRT.XRTWrap.RunAllocated

Execute a kernel with the given arguments. To automatically start the execution, set autostart to true. Otherwise, the execution has to be explicitly started by calling start(run::Run)

wait(run::XRT.XRTWrap.Run) -> XRT.XRTWrap.ErtCmdState.Type

Wait for a given Run object to complete execution. The method will return as soon as the execution is completed.

get_name(kernel::XRT.XRTWrap.Kernel)

Returns the name of the kernel

group_id(kernel::XRT.XRTWrap.Kernel, argno::Integer)

Get the memory bank group id to use when allocating buffers of an kernel argument. The kernel argument index starts at 0!

offset(kernel::XRT.XRTWrap.Kernel, argno::Integer)

Get the kernel register offset of kernel argument. The kernel argument index starts at 0!

set_arg!(run::XRT.XRTWrap.Run, index, val)
set_arg!(run::XRT.XRTWrap.Run, index, val::XRT.AbstractBOArray)
set_arg!(run::XRT.XRTWrap.Run, index, val::XRT.XRTWrap.BO)

Set the argument for a kernel at the given index. Note, that this is a thin wrapper to the C++ API, so the indices start at 0!

call(
    kernel::XRT.XRTWrap.Kernel,
    arg1,
    args...
) -> XRT.XRTWrap.RunAllocated

Execute a kernel with the given arguments and blocks until kernel execution completes. Returns used XRT.Run object.

get_xclbin(kernel::XRT.XRTWrap.Kernel) -> Xclbin

Returns an XRT.Xclbin object containing the kernel.

set_args!(run::XRT.XRTWrap.Run, args...)

Sets multiple arguments for a kernel beginning at the first argument. A kernel argument remains untouched if the new arg at the index is nothing.

IP(uuid::XRT.XRTWrap.UUID, name::AbstractString; device::XilinxDevice=device())

Create a new custom IP instance using a XilinxDevice, bitstream uuid, and kernel name. The target device can be changed by setting the device keyword parameter.

wait(interrupt::XRT.XRTWrap.IPInterrupt)
wait(interrupt::XRT.XRTWrap.IPInterrupt, timeout::Integer) -> XRT.XRTWrap.CVStatus.Type

Wait for interrupt from IP or for the specified timeout to expire.

create_interrupt_notify(ip::XRT.XRTWrap.IP)

Creates an XRT.IPInterrupt object that can be used to control and wait for IP interrupt when IP supports interrupts. The interrupt is automatically enabled.

disable!(interrupt::XRT.XRTWrap.IPInterrupt)

Disables the IP interrupt notification from IP.

enable!(interrupt::XRT.XRTWrap.IPInterrupt)

Enables the IP interrupt if not already enabled.

read_register(ip::XRT.XRTWrap.IP, offset::Integer)

Read data from IP address range.

write_register!(ip::XRT.XRTWrap.IP, offset::Integer, data::Integer)

Write data to the address range of an IP.

AbstractBOArray(userdata::AbstractArray{T, N}, mem; device, flags)
AbstractBOArray(device::XRT.XRTWrap.Device, userdata::AbstractArray{T, N}, mem; flags)

See XRT.BOArray. It can return XRT.ToDeviceBOArray or XRT.FromDeviceBOArray, depending on whether userdata is of Type XRT.ToDeviceArray or XRT.FromDeviceArray.

BOArray(userdata::AbstractArray{T, N}, mem; device, flags) -> XRT.BOArray
BOArray(device::XRT.XRTWrap.Device, userdata::AbstractArray{T, N}, mem; flags) -> XRT.BOArray
BOArray{T,N}(size, mem::Integer; device, flags) -> XRT.BOArray
BOArray{T,N}(device::XRT.XRTWrap.Device, size, mem; flags) -> XRT.BOArray

Array data type usable with XRT. Can be used like BO but supports indexing and automatic alignment of host buffers.

Keywords

device XilinxDevice to allocate buffer on. Default is the current active device.

flags Flags are provided in the XRT.XRTWrap.BOFlags module. Default is XRT.XRTWrap.BOFlags.NORMAL

struct FromDeviceArray{T} <: XRT.AbstractSyncDirectionArray{T}

See ToDeviceArray.

FromDeviceBOArray(userdata::AbstractArray{T, N}, mem; device, flags) -> XRT.FromDeviceBOArray
FromDeviceBOArray(device::XRT.XRTWrap.Device, userdata::AbstractArray{T, N}, mem; flags) -> XRT.FromDeviceBOArray
FromDeviceBOArray{T,N}(size, mem::Integer; device, flags) -> XRT.FromDeviceBOArray
FromDeviceBOArray{T,N}(device::XRT.XRTWrap.Device, size, mem; flags) -> XRT.FromDeviceBOArray

See XRT.BOArray. Synchronisation only takes place in direction from device to host. If a different synchronisation direction than XRT.FROM_DEVICE is specified, synchronisation does not take place. This data structure can be used to avoid unnecessary synchronisation during high-level use.

struct FromDeviceWrapper{T} <: XRT.AbstractSyncDirectionWrapper{T}

See XRT.ToDeviceWrapper.

struct ToDeviceArray{T} <: XRT.AbstractSyncDirectionArray{T}

A data type that wraps an Array in order to prohibit a single synchronisation direction when calling XRT.sync! function. Can be used in functions created by @prepare_bitstream macro. Alternatively, use XRT.ToDeviceWrapper or XRT.FromDeviceWrapper.

ToDeviceBOArray(userdata::AbstractArray{T, N}, mem; device, flags) -> XRT.ToDeviceBOArray
ToDeviceBOArray(device::XRT.XRTWrap.Device, userdata::AbstractArray{T, N}, mem; flags) -> XRT.ToDeviceBOArray
ToDeviceBOArray{T,N}(size, mem::Integer; device, flags) -> XRT.ToDeviceBOArray
ToDeviceBOArray{T,N}(device::XRT.XRTWrap.Device, size, mem; flags) -> XRT.ToDeviceBOArray

See XRT.BOArray. Synchronisation only takes place in direction from host to the device. If a different synchronisation direction than XRT.TO_DEVICE is specified, synchronisation does not take place. This data structure can be used to avoid unnecessary synchronisation during high-level use.

struct ToDeviceWrapper{T} <: XRT.AbstractSyncDirectionWrapper{T}

This wrapper can alternatively used to set a single synchronisation direction to a BOArray or Array. E.g. can be used within the [@prepare_bitstream] macro:

a = Array{Float64}(MemAlign(4096),array_size)
b = Array{Float64}(MemAlign(4096),array_size)
c = Array{Float64}(MemAlign(4096),array_size)
		
a[:] .= rand(array_size)
b[:] .= rand(array_size)
c[:] .= 0
		
kernel_function!(XRT.ToDeviceWrapper(a), XRT.ToDeviceWrapper(b), XRT.FromDeviceWrapper(c), 2.0, array_size, 1)

address(b::XRT.AbstractBOArray) -> UInt64

Returns the device address of this buffer.

get_flags(
    b::XRT.AbstractBOArray
) -> XRT.XRTWrap.BOFlags.Type

Returns the XRT.XRTWrap.BOFlags with which this buffer was constructed.

get_memory_group(b::XRT.AbstractBOArray) -> UInt32

Returns the memory group in which this buffer is allocated

sync!(b::AbstractBOArray, direction::XRTWrap.BOSyncDirection.Type)
sync!(w::AbstractSyncDirectionWrapper, direction::XRTWrap.BOSyncDirection.Type)

Synchronise buffer content in specified direction. Use BOArray or Array with sync direction in type to prohibit a specific sync direction.

Parse a bitstream and generate functions for the included kernels. The functions will automatically copy all relevant buffers to the FPGA memory, and execute the Kernel.

It is recommended to generate the kernel functions in a separate module like this:

module DummyBitstream
    using XRT
    @prepare_bitstream("my_bitstream.xclbin")
end

Afterwards, you find the functions for each kernel in the module. To execute the kernel on a device other than the current active device, use the device keyword parameter:

julia> DummyBitstream.kernel_name!(args...; device=XRT.device(2))

You can also directly execute a single specific compute unit of the kernel specified by '__':

julia> DummyBitstream.kernel_name__cu_name!(args...)

Parse a bitstream and generate adapted, typed XRT.Run function for a given kernel or compute unit. Returns tuple of XRT.Kernel and XRT.UUID object for the specific kernel.

It is recommended to generate the function in a separate module like this:

module DummyBitstream
    using XRT
    kernel, uuid = @prepare_run("my_bitstream.xclbin", "dummyKernel", device=device())
end

Afterwards, you find the function for the kernel object in the module.

julia> DummyBitstream.Run_kernel_name(args...; autostart=true)

You can also directly execute a single specific compute unit of the kernel specified by '__':

julia> DummyBitstream.Run_kernel_name__cu_name(args...; autostart=true)

Synchronise relevant buffers to or from the FPGA device. Therefore, the macro searches for calls of XRT.Run function and detects if its parameters are XRT.BOArray objects, which need to be synchronised. If the buffer objects are to be synchronised back to the host, the completion of the XRT.Run function is also ensured after the expression.

Note: The XRT.Run function requires the autostart keyword argument set to true or is manually started within the expression if the buffer objects should be synchronised back to the host.

Keywords

direction specifies the desired synchronisation direction. The keyword argument can be set to either XRT.TO_DEVICE or XRT.FROM_DEVICE. If the argument is omitted, synchronisation takes place in both directions.

For some exemplary applications of the XRT.@sync_buffers macro, an environment is first defined that corresponds to the usual kernel preparation:

uuid = load_xclbin!("path/to/bitstream.xclbin")
kernel = XRT.Kernel(uuid, "kernel")

a = Array{Float64}(MemAlign(4096), 1024)
xa = XRT.BOArray(a, group_id(kernel, 0))

To subsequently execute the kernel without taking the buffer synchronisation into account, the macro can be used as follows:

julia> XRT.@sync_buffers Run(kernel, xa)

The XRT.BOArray xa then contains the values returned by the kernel. Optionally, the synchronisation for a single direction can be handled manually. In the following case the termination of Run is not asured by the macro and has to be handled manually:

julia> XRT.@sync_buffers direction=XRT.TO_DEVICE r = Run(kernel, xa)

julia> XRT.wait(r)

julia> sync!(xa, XRT.FROM_DEVICE)

In the opposite case, the termination of wait is handled after all:

julia> sync!(xa, XRT.TO_DEVICE)

julia> XRT.@sync_buffers direction=XRT.FROM_DEVICE r = Run(kernel, xa)

xbutil program has the same functionality as load_xclbin!

reset!(index::Integer) -> XRT.XilinxDevice

Function for resetting a device.

Caution: Calling the function cann kill the current Julia instance, if different device allocations are present. Make sure that all device allocations of the device to be reset are deallocated. To do this, set all device allocations to nothing and call up the garbage collector.

julia> d = XRT.XRTWrap.Device(0); d = nothing; GC.gc()

validate!(bdf::AbstractString, tests::Union{XRT.XbutilTest.Type, AbstractString}...; output) -> String
validate!(tests::Union{XRT.XbutilTest.Type, AbstractString}...; device, output) -> String

This function validates the selected device by running precompiled tests on it. See XbutilTest.Type for available tests.

The following example will run two selected tests on the current active device.

julia> XRT.validate!(XRT.XbutilTest.AUX_CONNECTION, XRT.XbuitlTest.PCIE_LINK)

Keywords

device A XilinxDevice to execute the tests on can be set. Alternatively, the bdf of a device can be specified as the first parameter.

output Output file for test results as JSON format.

version()

Simply report the version of XRT and its drivers by calling xbutil --version.

primitive type Type <: Enum{Int64} 64

Enum representing available preinstalled tests which can be run using XRT.validate!.

device!(id::Int64) -> Union{Nothing, XRT.XilinxDevice}
device!(device::XRT.XilinxDevice) -> XRT.XilinxDevice

Sets the current active device by a id. If emulation mode is set to hw_emu or sw_emu, the only available device is always selected.

The current active device can alternatively set by a XilinxDevice. However, this is not recommended as it can lead to incorrect device allocations.

device() -> Union{Nothing, XRT.XilinxDevice}
devices(id::Int64) -> XRT.XilinxDevice

Returns the current active device or a available device with a given id. Prefered over devices()[id] due to selection when emulation mode is active.

devices() -> Vector{Union{Nothing, XRT.XilinxDevice}}

Specifies a vector that contains all available devices.

emulation_mode() -> XRT.XRTWrap.TargetType.Type

Returns the emulation mode. It is set to either hw, hw_emu, or sw_emu. To change this mode, export XCL_EMULATION_MODE environment variable before loading the package.

functional() -> Bool

Indicates whether XRTWrap was loaded successfully.

versioninfo()
versioninfo(io::IO)

Prints information about XRT and package version, environment variables, and devices to the console.

log(level::XRT.XRTWrap.LogLevel.Type, tag::AbstractString, msg::AbstractString)

This function dispatches a composed log message. The message is ignored if the configured verbosity level is less than specified level.

logf(
    level::XRT.XRTWrap.LogLevel.Type,
    tag::AbstractString,
    format::AbstractString,
    args...
)

This function composes a formatted string using args (similar to printf function) and dispatches this log:

julia> XRT.logf(XRT.LogLevel.WARNING, "myTag", "This is a %1 %2", "log", "message")