Public Interfaces
Module init code.
- class ska_low_cbf_fpga.AmiInfo(hwmon_dir, sys_dir_0)[source]
Hardware monitoring for AMI devices via sysfs.
- class ska_low_cbf_fpga.ArgsAmi(logger=None, mem_config='', **kwargs)[source]
FPGA driver that wraps
ami_tool.- read_memory(index, size_bytes=None, offset_bytes=0)[source]
Read from HBM.
Note: Unlike
ArgsXrt, we do not care if the memory buffer is marked as ‘shared’ in the memory configuration string.- Parameters:
size_bytes (
Optional[int]) – Number of bytes to transfer. Should be a multiple ofWORD_SIZE, will be rounded down to a multiple ofWORD_SIZE. (transfers the whole buffer if not specified or None)offset_bytes (
int) – Starting address.index (
int) – Index of the HBM buffer to read. For compatibility withArgsXrt, theindexof the first HBM buffer is 1.
- Return type:
ndarray- Returns:
HBM contents, as
ArgsWordType
- class ska_low_cbf_fpga.ArgsFieldInfo(description=None, address=None, length=1, bit_offset=None, width=None)[source]
- class ska_low_cbf_fpga.ArgsFpgaDriver(logger=None, mem_config='', **kwargs)[source]
Base class for ARGS FPGA Drivers.
Extends interface class with startup steps common to all ARGS FPGAs.
- exception ska_low_cbf_fpga.ArgsMagicError[source]
Exception raised when FPGA does not report ARGS magic number.
- class ska_low_cbf_fpga.ArgsSimulator(logger=None, mem_config='', **kwargs)[source]
FPGA Simulation driver.
- read(source, length=1)[source]
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)[source]
Read a shared memory buffer.
- Parameters:
- Return type:
ndarray- Returns:
shared memory buffer
- write(destination, values)[source]
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)
- class ska_low_cbf_fpga.ArgsXrt(logger=None, mem_config='', **kwargs)[source]
pyxrt-based FPGA Driver. Requires a .xclbin file.
- MINUS_ONE_16BIT = 65535
-1 as a 16 bit signed integer (0xFFFF)
- read_memory(index, size_bytes=None, offset_bytes=0)[source]
Read a shared memory buffer.
- Parameters:
- Return type:
ndarray- Returns:
shared memory buffer
- class ska_low_cbf_fpga.FpgaHardwareInfo[source]
Hardware monitoring interface definition.
The properties defined here must be implemented in driver-specific derived classes.
- class ska_low_cbf_fpga.FpgaPersonality(driver, map_, hardware_info=None, logger=None)[source]
- property default_interface: ArgsFpgaDriver
Temporary backwards-compatibility layer
- property driver: ArgsFpgaDriver
Access to underlying ArgsFpgaDriver
- exception ska_low_cbf_fpga.FpgaRegisterError[source]
Exception raised when FPGA register read fails.
- class ska_low_cbf_fpga.FpgaUserInterface[source]
A common interface used by
FpgaPeripheralandFpgaPersonalityfor exposing attributes and methods 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)[source]
ICL field, probably derived from one or more
IclFpgaFields
- 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)[source]
An ICL field that is linked to an
ArgsFpgaDriver.- type_
alias of
ArgsWordType
- class ska_low_cbf_fpga.XrtInfo(device)[source]
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.
- ska_low_cbf_fpga.create_driver_map_info(logger=None, mem_config='', fpgamap_path=None, firmware_path=None, device='0', partition=None, simulate=None, verify_registers=None, qdma_read=None, qdma_write=None)[source]
Create
ArgsFpgaDriver,ArgsMap,FpgaHardwareInfoWill use real FPGA hardware if present, unless simulate is explicitly set to True. If simulate is
Trueor no FPGA is present,fpgamap_pathmust be provided forArgsSimulatorto use.- Parameters:
logger (
Optional[Logger]) – Logger object to pass along for log outputsmem_config (
Union[list,str]) – FPGA memory access configurationfpgamap_path (
Optional[str]) – Path tofpgamap_<numbers>.pyfile to be usedfirmware_path (
Optional[str]) – path to a .pdi FPGA image (for AMI FPGA cards), or .xclbin FPGA kernel (for XRT FPGA cards). Optional for AMI FPGA cards (will use whatever is active on the card), required for XRT FPGA cards.device (
str) – PCIe Board:Device.Function addresspartition (
Optional[PartitionSpec]) – Partition number and boot device type to use for AMI FPGA cards.simulate (
Optional[bool]) – if True, simulate FPGA register/memory accessverify_registers (
Optional[dict[str,dict[str,int]]]) – Register values used to verify that we have loaded the correct firmware image. Allows bypassing the long programming step for AMI cards without relying on UUIDs. e.g.{"system": {"commit_short_hash": 0x12345678} }This option may disappear if we can get the .pdi file UUID working. Not checked for XRT FPGAs - underlying driver relies on UUID.qdma_read (
Optional[str]) – Path to QDMA read (c2h) character device. AMI only.qdma_write (
Optional[str]) – Path to QDMA write (h2c) character device. AMI only.
- Return type:
tuple[ArgsFpgaDriver,Optional[ArgsMap],Optional[FpgaHardwareInfo]]- Returns:
(driver, map, info)driveris only created when either:fpgamap_path is supplied or
an FPGA is present, firmware_path is supplied, and simulate is False.
To guarantee creation of driver, supply both fpgamap_path and a firmware file!
mapis only created when an fpgamap is present (either explicitly specified or implicitly in the firmware directory). If no fpgamap provided or found, the return value of map will beNone.infois only created if XRT FPGA hardware is present. If no XRT FPGA, the return value of info will beNone.simulatehas 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), unknown file extension in
firmware_path, or mismatch betweenverify_registersand FPGA
- ska_low_cbf_fpga.describe_firmware(driver, map_dir='./', personality_to_package=<function <lambda>>)[source]
Describe the firmware in use by an FPGA driver.
- Parameters:
driver (
ArgsFpgaDriver) – An instance of ArgsFpgaDriver used to interact with the FPGA.map_dir (
str) – The directory to check for the ARGS FPGA register map file. Defaults to the current working directory. Note that subdirectories will be searched as well.personality_to_package (
Callable[[str],str]) – A callable that converts the FPGA personality four-letter code to the corresponding canonical package name. Defaults to a no-op lambda function that returns the input value unchanged.
- Return type:
- Returns:
A dictionary containing entries:
”available”: A boolean indicating if the firmware is ready to use.
”map_build”: The ARGS map build timestamp, as a hexadecimal string. This value identifies the corresponding FPGA map file, which is required to access FPGA registers. If the driver fails to read the map build register, this value will be
None(suggests an error in the underlying FPGA driver or hardware).”package”: The package name for the firmware image, or
Noneif unavailable (probably caused by a missing map file).”version”: The firmware version or
Noneif unavailable (probably caused by a missing map file).
- ska_low_cbf_fpga.describe_partitions(device, map_dir='./', personality_to_package=<function <lambda>>)[source]
Describe the firmware in each partition of a given AMI-based FPGA device.
This function inspects the partitions of an FPGA device, attempting to read information about the firmware in each partition. It compiles this data into a list of dictionaries, with one dictionary representing each partition’s details.
Warning
All partitions must be programmed with a valid ARGS firmware image. This function will boot from each partition to inspect it, and booting from an un-programmed flash partition can make the card unusable. A host reboot will be required to recover in this circumstance.
- Parameters:
device (
str) – The PCIe device identifier of the FPGA to inspect.map_dir (
str) – The directory containing ARGS FPGA register map files. Defaults to the current working directory.personality_to_package (
Callable[[str],str]) – A callable that converts the FPGA personality four-letter code to the corresponding canonical package name. Defaults to a no-op lambda function that returns the input value unchanged.
- Return type:
- Returns:
A list of dictionaries, each containing information about a partition on the device. Each dictionary contains entries:
”partition”: The partition index.
”available”: A boolean indicating if the firmware is ready to use.
”map_build”: The ARGS map build timestamp, as a hexadecimal string. This value identifies the corresponding FPGA map file, which is required to access FPGA registers. If the driver fails to read the map build register, this value will be
None(suggests an error in the underlying FPGA driver or hardware).”package”: The package name for the firmware image, or
Noneif unavailable (probably caused by a missing map file).”version”: The firmware version or
Noneif unavailable (probably caused by a missing map file).
- ska_low_cbf_fpga.log_to_file(logger, filename, level=10, hex_vals=False)[source]
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!
- ska_low_cbf_fpga.mem_parse(memory_config='')[source]
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!