Public Interfaces

Module init code.

class ska_low_cbf_fpga.ArgsAmi(logger=None, mem_config='', **kwargs)

FPGA driver that wraps ami_tool.

read(source, length=1)

Read FPGA registers.

Return type:

Union[List[int], int]

read_memory(index, size_bytes=None, offset_bytes=0)

Read from HBM.

Return type:

ndarray

write(destination, values)

Write to FPGA registers.

Return type:

None

write_memory(index, values, offset_bytes=0)

Write to HBM.

class ska_low_cbf_fpga.ArgsFieldInfo(description=None, address=None, length=1, bit_offset=None, width=None)

class ska_low_cbf_fpga.ArgsFpgaDriver(logger=None, mem_config='', **kwargs)

Base class for ARGS FPGA Drivers.

Extends interface class with startup steps common to all ARGS FPGAs.

get_map_build()

Get the ARGS map build timestamp from the FPGA.

class ska_low_cbf_fpga.ArgsMap(spec)

ARGS FPGA map file decoder.

classmethod create_from_file(build, map_dir)

Parameters:

• build (int) – ARGS map build timestamp

• map_dir (str) – directory to find ARGS map file in

class ska_low_cbf_fpga.ArgsSimulator(logger=None, mem_config='', **kwargs)

FPGA Simulation driver.

classmethod create_from_file(fpgamap_path, mem_config=[], **kwargs)

Parameters:

• fpgamap_path (str) – Path to fpgamap_<numbers>.py file to be simulated.

• mem_config (list) – a list of MemConfig tuples (<size in bytes>, <shared?>). The first list item is the ARGS interchange buffer (which would be used to send/receive register values in a real FPGA).

read(source, length=1)

Read values from simulated FPGA register space

Parameters:

• source – Byte address to start reading from

• length (int) – Number of words to read

Returns:

value(s) from simulated registers

read_memory(index, size_bytes=None, offset_bytes=0)

Read a shared memory buffer.

Parameters:

• size_bytes (Optional[int]) – number of bytes to transfer (transfers the whole buffer if not specified or None)

• offset_bytes (int) – starting address

• index (int) – Index of the shared buffer to save. Zero is the ARGS interchange buffer, which you probably don’t want.

Return type:

ndarray

Returns:

shared memory buffer

write(destination, values)

Write values to simulated FPGA registers

Parameters:

• destination – FPGA byte address where writes should start

• values – value(s) to write, if more than one value they must be words, to be written to consecutive words (i.e. byte addresses increment by WORD_SIZE)

write_memory(index, values, offset_bytes=0)

Write to a shared memory buffer.

Parameters:

• index (int) – Index of the shared buffer to write to. Zero is the ARGS interchange buffer, which you probably don’t want.

• values (ndarray) – Data to write.

• offset_bytes (int) – Byte-based offset where values should start in buffer.

class ska_low_cbf_fpga.ArgsWordType(*args, **kwargs)

Data type used for ARGS words.

class ska_low_cbf_fpga.ArgsXrt(logger=None, mem_config='', **kwargs)

pyxrt-based FPGA Driver. Requires a .xclbin file.

MINUS_ONE_16BIT = 65535

-1 as a 16 bit signed integer (0xFFFF)

read(source, length=1)

Read values from FPGA.

Parameters:

• source (int) – Byte address to start reading from

• length (int) – Number of words to read

Returns:

value(s) from FPGA

read_memory(index, size_bytes=None, offset_bytes=0)

Read a shared memory buffer.

Parameters:

• size_bytes (Optional[int]) – number of bytes to transfer (transfers the whole buffer if not specified or None)

• offset_bytes (int) – starting address

• index (int) – Index of the shared buffer to save. Zero is the ARGS interchange buffer, which you probably don’t want.

Return type:

ndarray

Returns:

shared memory buffer

write(destination, values)

Write values to FPGA.

Parameters:

• destination (int) – FPGA byte address where writes should start

• values (Union[int, ndarray]) – value(s) to write, if more than one value they must be words, to be written to consecutive words (i.e. byte addresses increment by WORD_SIZE)

write_memory(index, values, offset_bytes=0)

Write to a shared memory buffer.

Parameters:

• index (int) – Index of the shared buffer to write to. Zero is the ARGS interchange buffer, which you probably don’t want.

• values (ndarray) – Data to write.

• offset_bytes (int) – Byte-based offset where values should start in buffer.

class ska_low_cbf_fpga.FpgaHardwareInfo(device=None)

Hardware monitoring interface definition.

class ska_low_cbf_fpga.FpgaPeripheral(driver, map_field_info, fpga_personality=None)

class ska_low_cbf_fpga.FpgaPersonality(driver, map_, hardware_info=None, logger=None)

property default_interface: ArgsFpgaDriver

Temporary backwards-compatibility layer

property driver: ArgsFpgaDriver

Access to underlying ArgsFpgaDriver

property fw_personality: IclField[str]

Get the FPGA Firmware personality, decoded to a string

property fw_version: IclField[str]

Get the FPGA Firmware Version.

Returns:

version string formatted like the firmware packages: <major>.<minor>.<patch>[-<dev|main|pre|sim>.<commit hash>] “sim” indicates build type was zero (probably we are in simulation)

property peripherals: List[str]

Returns:

List of peripheral names

property read_memory: Callable

Access to read_memory function of underlying ArgsFpgaDriver

property write_memory: Callable

Access to write_memory function of underlying ArgsFpgaDriver

class ska_low_cbf_fpga.FpgaUserInterface

A common interface used by FpgaPeripheral and FpgaPersonality for exposing attributes and methods to the control system.

property user_attributes: Set[str]

Attributes to be exposed to the control system.

property user_methods: Set[str]

Methods to be exposed to the control system.

class ska_low_cbf_fpga.IclField(description=None, address=None, length=1, bit_offset=None, width=None, type_=~T, format='%i', user_write=True, user_error=False, value=None)

ICL field, probably derived from one or more IclFpgaField s

user_error: bool = False

Should the control system treat a non-zero value as an error/alarm?

user_write: bool = True

Should the control system allow writing to this field? Note: not enforced at ICL!

class ska_low_cbf_fpga.IclFpgaField(description=None, address=None, length=1, bit_offset=None, width=None, type_=<class 'ska_low_cbf_fpga.args_fpga.ArgsWordType'>, format='%i', user_write=True, user_error=False, value=<property object>, driver=None)

An ICL field that is linked to an ArgsFpgaDriver .

type_

alias of ArgsWordType

property value: int | numpy.ndarray | bool

Read current value from FPGA interface

class ska_low_cbf_fpga.XrtInfo(device)

Hardware info monitoring via pyxrt xrt_info_device.

Access via item index, e.g. my_xrt_info["thermal"]. Some flattening of data structures is performed.

property fpga_power: IclField[float]

Get FPGA power consumption in Watts.

property fpga_temperature: IclField[int]

Get FPGA temperature in degrees Celsius.

property xclbin_uuid: str

Get the UUID of the active xclbin firmware.

ska_low_cbf_fpga.create_driver_map_info(logger=None, mem_config='', fpgamap_path=None, xcl_file=None, firmware_path=None, device='0', simulate=None)

Create ArgsFpgaDriver, ArgsMap, FpgaHardwareInfo

Will use real FPGA hardware if present, unless simulate is explicitly set to True. If simulate is True or no FPGA is present, fpgamap_path must be provided for ArgsSimulator to use.

Parameters:

• logger (Optional[Logger]) – Logger object to pass along for log outputs

• mem_config (Union[list, str]) – FPGA memory access configuration

• fpgamap_path (Optional[str]) – Path to fpgamap_<numbers>.py file to be used

• xcl_file (Optional[str]) – Deprecated, use firmware_path instead (equivalent)

• firmware_path (Optional[str]) – path to a .pdi FPGA image (for AMI FPGA cards), or .xclbin FPGA kernel (for XRT FPGA cards)

• device (str) – PCIe Board:Device.Function address

• simulate (Optional[bool]) – if True, simulate FPGA register/memory access

Return type:

(ArgsFpgaDriver, Optional[ArgsMap], Optional[FpgaHardwareInfo])

Returns:

(driver, map, info)

driver is only created when either:

• fpgamap_path is supplied or

• an FPGA is present, either xcl_file or pdi_file is supplied, and simulate is False.

To guarantee creation of driver, supply both fpgamap_path and a firmware file!

map is only created when an fpgamap is present (either explicitly specified or implicitly in the xclbin’s directory). If no fpgamap, the return value of map will be None.

info is only created if XRT FPGA hardware is present. If no XRT FPGA, the return value of info will be None. simulate has no effect here, if info is not None then it is real hardware info.

Raises:

• ValueError – if both types of firmware are given

• RuntimeError – if supplied firmware not suitable for detected FPGA (AMI and XRT are mutually exclusive)

ska_low_cbf_fpga.log_to_file(logger, filename, level=10, hex_vals=False)

Add a file handler to a logger, with our predefined log format, and configure numpy to ensure full arrays are printed on a single line. Warning: numpy print options are a global setting!

Parameters:

• logger (Logger) – Logger to configure

• filename (str) – File name to write (append) to

• level (int) – Logging level, defaults to DEBUG to capture driver read/write

• hex_vals (bool) – convert values to hexadecimal?

Return type:

None

ska_low_cbf_fpga.mem_parse(memory_config='')

Convert a string-formatted list of memory configurations to a list of MemConfigs.

The register interchange buffer is automatically included as the first element. Do not list the register buffer in the input string!

Parameters:

memory_config (str) – a colon-separated string <size><unit><s|i> size: int unit: k, M, G (powers of 1024) s: shared i: FPGA internal e.g. ‘128Ms:1Gi’

Return type:

List[MemConfig]

Returns:

list of MemConfigs, decoded from the string

ska_low_cbf_fpga.stop_log_to_file(logger)

Stop register logging.

Parameters:

logger (Logger) – Logger to configure

Return type:

None

ska_low_cbf_fpga.str_from_int_bytes(n_bytes, precision=2)

Automatically scale a number of bytes for printing.

No decimals are shown for exact conversions, e.g. 1024 -> “1 KiB”

Parameters:

• n_bytes (int) – Number of bytes

• precision (int) – decimal places to show

Return type:

str

Returns:

A number and units, e.g. ‘1.5 KiB’