This page documents internal details as well as the public interfaces.
Driver Utilities
General driver utilities
- ska_low_cbf_fpga.driver.ami_fpga_present()[source]
Check if AMI-based FPGA hardware is available.
- Return type:
- Returns:
True if AMI-based FPGA found, False otherwise
- Raises:
RuntimeError – if ami_tool exists but doesn’t exit cleanly
- ska_low_cbf_fpga.driver.create_driver_map_info(logger=None, mem_config='', fpgamap_path=None, xcl_file=None, firmware_path=None, device='0', simulate=None)[source]
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 forArgsSimulator
to 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>.py
file to be usedxcl_file (
Optional
[str
]) – Deprecated, usefirmware_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 addresssimulate (
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 beNone
.info
is only created if XRT FPGA hardware is present. If no XRT FPGA, the return value of info will beNone
.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.driver.xrt_fpga_present()[source]
Check if XRT-based FPGA hardware is available.
- Return type:
- Returns:
True if XRT FPGA present, False if not
- Raises:
FileNotFoundError – if pyxrt is available but xbutil is not
RuntimeError – if xbutil doesn’t exit cleanly
FPGA ICL
Instrument Control Layer
- class ska_low_cbf_fpga.fpga_icl.FpgaPeripheral(driver, map_field_info, fpga_personality=None)[source]
Bases:
FpgaUserInterface
- __getattr__(name)[source]
Attribute access to fields
- Return type:
- __getitem__(item)[source]
Index style access to fields
- Return type:
- __init__(driver, map_field_info, fpga_personality=None)[source]
Base class that provides functions common to all FPGA Peripherals. Creates an instance of
IclFpgaField
for each field defined in the map. Populates_user_attributes
if not set by derived class.- Parameters:
driver (
ArgsFpgaDriver
) – ArgsFpgaDriver instance, used to access FPGAmap_field_info (
Dict
[str
,ArgsFieldInfo
]) – Most likely a portion of an ArgsMap.fpga_personality (
Optional
[NewType
(FpgaPersonality
,FpgaUserInterface
)]) – personality applicable to this peripheral
- __setattr__(key, value)[source]
Pass on attribute writes to the field, where appropriate
- __setitem__(key, value)[source]
Pass on writes to the field
- _field_config = {}
Configuration values for fields read from FPGA. e.g. to indicate to the control system that a field should be treated as an error condition:
_field_config = {"example": IclFpgaField(user_error=True)}
- _not_user_attributes = {}
Attribute names to exclude from auto-discovery for the control system.
- _not_user_methods = {}
Method names to exclude from auto-discovery for the control system.
- _user_attributes = {}
Attributes to be exposed to the control system. Defaults to properties (if configured), or FPGA registers. Set to None if you really want no attributes exposed.
- _user_methods = {}
Methods to be exposed to the control system.
- class ska_low_cbf_fpga.fpga_icl.FpgaPersonality(driver, map_, hardware_info=None, logger=None)[source]
Bases:
FpgaUserInterface
- __getattr__(name)[source]
Access peripherals by attribute syntax
- __getitem__(item)[source]
Index style access to peripheral objects
- Return type:
- __init__(driver, map_, hardware_info=None, logger=None)[source]
Base class that provides functions common to all FPGA Personalities. Creates FpgaPeripheral objects for each peripheral.
- Parameters:
driver (
ArgsFpgaDriver
) – ArgsFpgaDriver instance, used to access FPGAmap – ARGS peripheral/register map.
hardware_info (
Optional
[FpgaHardwareInfo
]) – Hardware monitoring interface (XrtInfo).logger (
Optional
[Logger
]) – Logger to report log messages to. Passed to peripherals.
- _not_user_attributes = {}
Attribute names to exclude from auto-discovery for the control system.
- _not_user_methods = {}
Method names to exclude from auto-discovery for the control system.
- _user_attributes = {}
Attributes to be exposed to the control system. Defaults to properties (if configured), or FPGA registers. Set to None if you really want no attributes exposed.
- _user_methods = {}
Methods to be exposed to the control system.
- property default_interface: ArgsFpgaDriver
Temporary backwards-compatibility layer
- property driver: ArgsFpgaDriver
Access to underlying ArgsFpgaDriver
- 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 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.fpga_icl.FpgaUserInterface[source]
Bases:
object
A common interface used by
FpgaPeripheral
andFpgaPersonality
for exposing attributes and methods to the control system.- __init__()[source]
- _not_user_attributes = {}
Attribute names to exclude from auto-discovery for the control system.
- _not_user_methods = {}
Method names to exclude from auto-discovery for the control system.
- _user_attributes = {}
Attributes to be exposed to the control system. Defaults to properties (if configured), or FPGA registers. Set to None if you really want no attributes exposed.
- _user_methods = {}
Methods to be exposed to the control system.
- class ska_low_cbf_fpga.fpga_icl.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]
Bases:
ArgsFieldInfo
,Generic
[T
]ICL field, probably derived from one or more
IclFpgaField
s- __init__(description=None, address=None, length=1, bit_offset=None, width=None, type_=~T, format='%i', user_write=True, user_error=False, value=None)
-
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.fpga_icl.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]
Bases:
IclField
[ArgsWordType
]An ICL field that is linked to an
ArgsFpgaDriver
.- __getitem__(item)[source]
Array access for multi-word values
- Return type:
- __init__(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)
- __setitem__(key, value)[source]
Array index style access for setting part of a multi-word value. e.g. my_field[4] = 32 my_field[3:6] = np.ones(3, dtype=ArgsWordType)
If using a slice, value must be an array i.e. Don’t do this: my_field[3:4] = 5. Instead, use my_field[3] = 5 or even my_field[3:4] = np.array([5])
- type_
alias of
ArgsWordType
-
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!
ARGS FPGA
Base classes to interface with ARGS-based FPGA
- class ska_low_cbf_fpga.args_fpga.ArgsFpgaDriver(logger=None, mem_config='', **kwargs)[source]
Bases:
ArgsFpgaDriverIface
Base class for ARGS FPGA Drivers.
Extends interface class with startup steps common to all ARGS FPGAs.
- __init__(logger=None, mem_config='', **kwargs)[source]
- Parameters:
logger – a logging object with .debug, .info, etc functions
kwargs – optional extra arguments passed on to the derived class’s _setup function
- get_map_build()[source]
Get the ARGS map build timestamp from the FPGA.
- abstract read(source, length=None)
Read from FPGA register(s).
- Parameters:
source – Start address (bytes)
length – Number of words to read
- abstract read_memory(index, size_bytes=None, offset_bytes=0)
Read a shared memory buffer.
- Parameters:
- Return type:
ndarray
- Returns:
shared memory buffer
- abstract write(destination, values)
Write to FPGA register(s).
- Parameters:
destination – Start address (bytes)
values – One or more values to write to consecutive words
- abstract write_memory(index, values, offset_bytes=0)
Write to a shared memory buffer.
- class ska_low_cbf_fpga.args_fpga.ArgsFpgaDriverIface[source]
Bases:
ABC
Defines a pure-virtual Interface to a FPGA
- abstract read(source, length=None)[source]
Read from FPGA register(s).
- Parameters:
source – Start address (bytes)
length – Number of words to read
- abstract read_memory(index, size_bytes=None, offset_bytes=0)[source]
Read a shared memory buffer.
- Parameters:
- Return type:
ndarray
- Returns:
shared memory buffer
- abstract write(destination, values)[source]
Write to FPGA register(s).
- Parameters:
destination – Start address (bytes)
values – One or more values to write to consecutive words
- abstract write_memory(index, values, offset_bytes=0)[source]
Write to a shared memory buffer.
- class ska_low_cbf_fpga.args_fpga.ArgsWordType(*args, **kwargs)[source]
Bases:
uint32
Data type used for ARGS words.
- __init__(*args, **kwargs)
- ska_low_cbf_fpga.args_fpga.EXCHANGE_BUF_CONFIG = MemConfig(size=131072, shared=True)
ARGS register interchange buffer configuration.
- exception ska_low_cbf_fpga.args_fpga.FpgaRegisterError[source]
Bases:
RuntimeError
- __init__(*args, **kwargs)
- with_traceback()
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- class ska_low_cbf_fpga.args_fpga.MemConfig(size, shared)[source]
Bases:
object
Memory buffer configuration info
- __init__(size, shared)
- ska_low_cbf_fpga.args_fpga.WORD_SIZE = 4
Size of ARGS words, in bytes.
- ska_low_cbf_fpga.args_fpga.mem_config_check(mem_config='')[source]
- ska_low_cbf_fpga.args_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!
- ska_low_cbf_fpga.args_fpga.str_from_int_bytes(n_bytes, precision=2)[source]
Automatically scale a number of bytes for printing.
No decimals are shown for exact conversions, e.g. 1024 -> “1 KiB”
ARGS Map
- class ska_low_cbf_fpga.args_map.AddressInfo(name, length)[source]
Minimal set of information about an FPGA register address. (a collection of these is used for address number -> name lookups)
- __init__(name, length)
- class ska_low_cbf_fpga.args_map.ArgsFieldInfo(description=None, address=None, length=1, bit_offset=None, width=None)[source]
- __init__(description=None, address=None, length=1, bit_offset=None, width=None)
- class ska_low_cbf_fpga.args_map.ArgsMap(spec)[source]
ARGS FPGA map file decoder.
- __setitem__(key, value)[source]
Should only be called internally, during object creation.
- Parameters:
key – peripheral name
value – dict of ArgsFieldInfo
- Raises:
NotImplementedError – if called after ArgsMap init
- _decode_map(fpga_map)[source]
Given an FPGAMAP nested dictionary structure, extract relevant info for its RAM and Register fields.
- ska_low_cbf_fpga.args_map.all_register_addresses(fpga_map)[source]
Creates a lookup table that can be used to convert byte based addresses to full register names.
- ska_low_cbf_fpga.args_map.get_name_and_offset(registers, address)[source]
Get register name and offset into register for a given address. Looks up the nearest lesser address and finds the relative offset. Checks that this is within the defined register length.
- ska_low_cbf_fpga.args_map.load_fpgamap_from_file(map_file_path)[source]
Load the FPGAMAP variable from a specified python file.
- ska_low_cbf_fpga.args_map.load_map(build, map_dir)[source]
Load FPGA register map file from a directory.
Looks for a file named with the build date of the running firmware image.
ARGS AMI
ARGS FPGA driver using ami_tool
.
- class ska_low_cbf_fpga.args_ami_tool.ArgsAmi(logger=None, mem_config='', **kwargs)[source]
Bases:
ArgsFpgaDriver
FPGA driver that wraps
ami_tool
.- __init__(logger=None, mem_config='', **kwargs)
- Parameters:
logger – a logging object with .debug, .info, etc functions
kwargs – optional extra arguments passed on to the derived class’s _setup function
- _check_magic()[source]
Check that FPGA contains the correct ‘Magic Number’.
- _init_buffers()[source]
Initialise memory buffers.
- _load_firmware()[source]
Load a firmware file into the FPGA.
- _setup(device='0', pdi_file=None, **kwargs)[source]
Set up the FPGA driver.
- get_map_build()
Get the ARGS map build timestamp from the FPGA.
- read_memory(index, size_bytes=None, offset_bytes=0)[source]
Read from HBM.
- Return type:
ndarray
- write_memory(index, values, offset_bytes=0)[source]
Write to HBM.
- ska_low_cbf_fpga.args_ami_tool._parse_read_string(read)[source]
Decode the output from an
ami_tool bar_rd
command.- Return type:
ARGS XRT
- class ska_low_cbf_fpga.args_xrt.ArgsXrt(logger=None, mem_config='', **kwargs)[source]
Bases:
ArgsFpgaDriver
pyxrt-based FPGA Driver. Requires a .xclbin file.
- MINUS_ONE_16BIT = 65535
-1 as a 16 bit signed integer (0xFFFF)
- __init__(logger=None, mem_config='', **kwargs)
- Parameters:
logger – a logging object with .debug, .info, etc functions
kwargs – optional extra arguments passed on to the derived class’s _setup function
- _check_magic()
Check that FPGA contains the correct ‘Magic Number’.
- _init_buffers()[source]
Create XRT & Numpy buffers.
- _load_firmware()[source]
Load the binary to the FPGA (if required) and initialise our kernel object.
- _read_args_page(address_start, n_bytes=None)[source]
Read one block of register values into host memory buffer.
- _setup(xcl_file, mem_config='', device='0', **kwargs)[source]
- _write_args_page(destination, values)[source]
Write one block of register values from host buffer to FPGA.
- Parameters:
destination – Byte address to start writing to
values – Array of values to be written to consecutive words
- get_map_build()
Get the ARGS map build timestamp from the FPGA.
- read(source, length=1)[source]
Read values from FPGA.
- 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 FPGA.
- write_memory(index, values, offset_bytes=0)[source]
Write to a shared memory buffer.
- ska_low_cbf_fpga.args_xrt.XRT_TIMEOUT = 5
Timeout for FPGA read/write actions (milliseconds)
- ska_low_cbf_fpga.args_xrt._wait_for_completion(kernel_task, timeout)[source]
Wait for FPGA register transaction to complete.
Similar purpose to
pyxrt.run.wait()
except we throw an exception for errors or timeouts rather than failing silently.TODO: If timeouts do happen sometimes, should they be handled gracefully e.g retry?
- Parameters:
kernel_task (
run
) – pyxrt kernel run object to monitortimeout (
int
) – timeout in milliseconds
- Raises:
RuntimeError – if the command does not succeed in a timely manner
XRT Info
- class ska_low_cbf_fpga.xrt_info.XrtInfo(device)[source]
Bases:
FpgaHardwareInfo
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.- _INFO_PARAMS = {'bdf': <class 'str'>, 'dynamic_regions': 'json', 'electrical': 'json', 'host': 'json', 'interface_uuid': <class 'str'>, 'kdma': <class 'bool'>, 'm2m': <class 'bool'>, 'max_clock_frequency_mhz': <class 'int'>, 'mechanical': 'json', 'memory': 'json', 'name': <class 'str'>, 'nodma': <class 'bool'>, 'offline': <class 'bool'>, 'pcie_info': 'json', 'platform': 'json', 'thermal': 'json'}
Mapping from known hardware info item keys to their data types.
- __getitem__(item)[source]
Access info parameters via item index syntax.
- Parameters:
item (
str
) – probably one of the values defined in_INFO_PARAMS
- __init__(device)[source]
- __weakref__
list of weak references to the object (if defined)
- property xclbin_uuid: str
Get the UUID of the active xclbin firmware.
Hardware Info
Hardware monitoring interface
- class ska_low_cbf_fpga.hardware_info.FpgaHardwareInfo(device=None)[source]
Hardware monitoring interface definition.
- _INFO_PARAMS = {'bdf': <class 'str'>, 'dynamic_regions': 'json', 'electrical': 'json', 'host': 'json', 'interface_uuid': <class 'str'>, 'kdma': <class 'bool'>, 'm2m': <class 'bool'>, 'max_clock_frequency_mhz': <class 'int'>, 'mechanical': 'json', 'memory': 'json', 'name': <class 'str'>, 'nodma': <class 'bool'>, 'offline': <class 'bool'>, 'pcie_info': 'json', 'platform': 'json', 'thermal': 'json'}
Mapping from known hardware info item keys to their data types.
- abstract __init__(device=None)[source]
- __weakref__
list of weak references to the object (if defined)
Logging
Logging configuration & translation functions
- class ska_low_cbf_fpga.log.ConversionFormat(value)[source]
Log conversion output formats.
- class ska_low_cbf_fpga.log.LogEntry(time, mode, name, offset, values, length, address, level, source)[source]
Details of one log entry.
- __init__(time, mode, name, offset, values, length, address, level, source)
- ska_low_cbf_fpga.log._write_log_entry(conversion_format, entry, file_out, hex_vals)[source]
Write one log entry in the requested format.
- ska_low_cbf_fpga.log.convert_log()[source]
Command-Line Interface - convert a log file.
- ska_low_cbf_fpga.log.convert_log_contents(log, register_lookup, conversion_format, file_out, include_reads=False, include_others=False, hex_vals=False, filter_spec=None)[source]
Convert the contents of a log file.
- Parameters:
log (
TextIO
) – input log fileconversion_format (
ConversionFormat
) – choice of output formatfile_out (
TextIO
) – output file to write toinclude_reads (
bool
) – include FPGA reads in output?include_others (
bool
) – include non-FPGA register log lines in output?hex_vals (
bool
) – convert values to hex? (only relevant for HUMAN mode)filter_spec (
Union
[dict
,TextIO
,None
]) –filtering configuration as dict or JSON in file. e.g.
{ "select_words": { # word address range to keep (inclusive) "spead_sdp.spead_params.data": [0, 7167], "spead_sdp_2.spead_params.data": [0, 7167], }, "ignore": [ "spead_sdp.spead_ctrl.trigger_packet", "spead_sdp_2.spead_ctrl.trigger_packet", ], "keep_only_last": True, }
- Return type:
- ska_low_cbf_fpga.log.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!