bal_xilinx¶

bal_xilinx.context¶

class bal_xilinx.context.XilinxContext(converters_by_type, analyzers_by_type, modifiers_by_type, bitstream_format, bytes)¶

Bases: bal.context.BALContext

See the documentation of BALContext for an overview of the purpose of the context class. In addition, the XilinxContext stores a reference to a XilinxFormat instance that defines the format of a Xilinx bitstream.

Parameters

converters_by_type (Dict[Type[ConverterInterface],Type[AbstractConverter]]) – The converter interfaces mapped to their implementation.
analyzers_by_type (Dict[Type[AnalyzerInterface],Type[AbstractAnalyzer]]) – The analyzer interfaces mapped to their implementation.
modifiers_by_type (Dict[Type[ModifierInterface],Type[AbstractModifier]]) – The modifier interfaces mapped to their implementation.
bitstream_format (XilinxFormat) – The Xilinx bitstream format configuration.
bytes (bytes) – The bytes making up the bitstream.

get_data()¶

Get the data object wrapping the bitstream. The returned object starts out packed but may be modified by user call.

Return type: DataObject[XilinxBitstream]

class bal_xilinx.context.XilinxContextFactory(bitstream_format)¶

Bases: bal.context.BALContextFactory

See the documentation of BALContextFactory for an overview of the purpose of the context factory class. In addition, the XilinxContextFactory stores a reference to a XilinxFormat instance that defines the format of a Xilinx bitstream.

Parameters: bitstream_format (XilinxFormat) – The Xilinx bitstream format configuration.

create(data)¶

Create an Xilinx FPGA context from the provided bytes.

Parameters: bytes (bytes) – The bytes for the Xilinx FPGA bitstream
Return type: XilinxContext

bal_xilinx.data_model¶

class bal_xilinx.data_model.XilinxFdriLogicFrame¶

Bases: bal.data_model.DataModel

A single frame of the major of the logic block of an FDRI payload.

class bal_xilinx.data_model.XilinxFdriLogicMajor(items)¶

Bases: bal.data_model.ArrayModel

A single major of the logic block of an FDRI payload.

class bal_xilinx.data_model.XilinxFdriLogicRow(items)¶

Bases: bal.data_model.ArrayModel

A single row of the logic block of an FDRI payload.

class bal_xilinx.data_model.XilinxFdriLogicBlock(items)¶

Bases: bal.data_model.ArrayModel

The logic block of an FDRI payload.

class bal_xilinx.data_model.XilinxFdriRAMBlockInterface¶

Bases: bal.data_model.DataModel

The RAM block of an FDRI payload.

class bal_xilinx.data_model.XilinxFdriIOBlockInterface¶

Bases: bal.data_model.DataModel

The IO block of an FDRI payload.

class bal_xilinx.data_model.XilinxFdriCRCInterface¶

Bases: bal.data_model.DataModel

The CRC tail of an FDRI payload.

class bal_xilinx.data_model.XilinxType2PayloadInterface¶

Bases: bal.data_model.DataModel

The payload of a type 2 packet in the Xilinx bitstream.

class bal_xilinx.data_model.XilinxFdriPayload(logic_block, bram_block, iob_block, crc)¶

Bases: bal_xilinx.data_model.XilinxType2PayloadInterface, bal.data_model.ClassModel

The payload of a type 2 FDRI packet in the Xilinx bitstream. It contains configuration for logic blocks, ram blocks, and io blocks. It also contains a checksum of the blocks config in the tail.

get_logic_block()¶

Get the data object for the logic block of the FDRI payload.

Return type: DataObject[XilinxFdriLogicBlock]

get_ram_block()¶

Get the data object for the RAM block of the FDRI payload.

Return type: XilinxFdriRAMBlockInterface

get_io_block()¶

Get the data object for the IO block of the FDRI payload.

Return type: XilinxFdriIOBlockInterface

get_crc()¶: Get the data object for the CRC tail of the FDRI payload. :rtype: XilinxFdriCRCInterface

set_logic_block(logic_block)¶

set_ram_block(bram_block)¶

set_io_block(iob_block)¶

set_tail(tail)¶

class bal_xilinx.data_model.XilinxType1PayloadAttribute(value, value_name=None, value_description=None)¶

Bases: bal.data_model.ValueModel

An attibute of the payload of a type 1 packet in the Xilinx bitstream. It is parsed automatically using the Xilinx format configuration.

class bal_xilinx.data_model.XilinxType1Payload(attributes)¶

Bases: bal.data_model.DictModel

The payload of a type 1 packet in the Xilinx bitstream. It is parsed automatically from using the Xilinx format configuration. It’s properties are not known until it is unpacked.

class bal_xilinx.data_model.XilinxPacketHeader(packet_type, opcode, register_address, word_count)¶

Bases: bal.data_model.ClassModel

The header of a Xilinx register configuration packet. It contains the type of the packet (1 or 2), the opcode (READ/WRITE/NOOP), the register address and the number of words in the payload.

get_packet_type()¶

Return type: DataObject[ValueModel]

get_opcode()¶

Return type: DataObject[ValueModel]

get_register_address()¶

Return type: DataObject[ValueModel]

get_word_count()¶

Return type: DataObject[ValueModel]

set_packet_type(packet_type)¶

set_opcode(opcode)¶

set_register_address(register_address)¶

set_word_count(word_count)¶

class bal_xilinx.data_model.XilinxPacket(header, payload_size, payload)¶

Bases: bal.data_model.ClassModel

A packet within a Xilinx bitstream. It contains a header and a payload.

get_header()¶

Return type: DataObject[XilinxPacketHeader]

get_payload_size()¶

Return type: DataObject[ValueModel]

get_payload()¶

Return type: DataObject

set_header(header)¶

set_payload(payload)¶

class bal_xilinx.data_model.XilinxPacketsTail¶

Bases: bal.data_model.DataModel

The tail data for the packets. It cannot be detected by the XilinxBitstreamConverter so it must be handled as any other packet.

class bal_xilinx.data_model.XilinxPackets(items)¶

Bases: bal.data_model.ArrayModel

An array of Xilinx register configuration packet.

class bal_xilinx.data_model.XilinxBitstreamHeaderInterface¶

Bases: bal.data_model.DataModel

The Xilinx bitstream header contains unknown information.

class bal_xilinx.data_model.XilinxBitstreamSyncMarker¶

Bases: bal.data_model.DataModel

The Xilinx bitstream sync marker

class bal_xilinx.data_model.XilinxBitstream(header, sync_marker, packets)¶

Bases: bal.data_model.ClassModel

The root model for a Xilinx bitstream. It contains a header and packets data objects.

get_header()¶

Return type: DataObject[XilinxBitstreamHeaderInterface]

get_sync_marker()¶

Return type: DataObject[XilinxBitstreamSyncMarker]

get_packets()¶

Return type: DataObject[XilinxPackets]

get_packets_by_register_name(register)¶

Parameters: register (str) –
Return type: List[XilinxPacket]

set_header(header)¶

Parameters: header (DataObject) –

set_packets(packets)¶

bal_xilinx.defaults¶

bal_xilinx.defaults.register_defaults_context_converters(context)¶

bal_xilinx.defaults.register_defaults_context_analyzers(context)¶

bal_xilinx.defaults.register_defaults_context_modifiers(context)¶

bal_xilinx.defaults.default_xilinx_context(context)¶

bal_xilinx.defaults.default_xilinx_formats(format_builder)¶

Load the default JSON config files for Xilinx fpgas.

Return type: XilinxFormatBuilder

bal_xilinx.format¶

bal_xilinx.format.hex_to_bytes(hex)¶

Convert a hex value to the bytes representation used by the interpreter.

Parameters: hex (str) –
Return type: bytes

class bal_xilinx.format.XilinxAttributeValueDocumentation(value, name, description)¶

Bases: object

Defines the documentation for a specific value of a register attribute.

Parameters

value (int) – The attribute’s value.
name (Optional[str]) – The name for the value of the attribute.
description (Optional[None]) – The description for the value of the attribute.

Variables

value (int) – The attribute’s value.
name (Optional[str]) – The name for the value of the attribute.
description (Optional[None]) – The description for the value of the attribute.

class bal_xilinx.format.XilinxRegisterAttributeFormat(name, bit_size, description, values)¶

Bases: object

Defines the format/documentation of a register payload attribute.

Parameters

name (str) – The name of the attribute.
bit_size (int) – The size of the attribute value in bits.
description (str) – A description of the attribute.
values (List[XilinxAttributeValueDocumentation]) – The documentation for values of the attribute.

Variables

name (str) – The name of the attribute.
bit_size (int) – The size of the attribute value in bits.
description (str) – A description of the attribute.

get_value_documentation(value)¶

Get the documentation for the provided value of the attribute

Parameters: value (int) – The value of the register attribute
Return type: Optional[XilinxAttributeValueDocumentation]

class bal_xilinx.format.XilinxRegisterFormatCtypeLE(raw_bytes)¶: Bases: _ctypes.Union

class bal_xilinx.format.XilinxRegisterFormatCtype(class_name, fields, values=None)¶

Bases: object

get_bytes(*values)¶

from_buffer_copy(raw_bytes)¶

class bal_xilinx.format.XilinxRegisterFormat(address, name, description, attributes)¶

Bases: object

Defines the format/documentation for a register packet.

Parameters

address (int) – The address of the register.
name (str) – The name of the register targeted by a packet.
description (str) – A description of the register.
attributes (List[XilinxRegisterAttributeFormat]) – The attributes to parse in a packet’s data.

Variables

address (int) – The address of the register.
name (str) – The name of the register targeted by a packet.
description (str) – A description of the register.
attributes (List[XilinxRegisterAttributeFormat]) – The attributes to parse in a packet’s data.
size (int) – Ths aggregate bit size of the register payload attributes.
ctype (ctype) – A ctype class definition configured to match the register payload attributes.

class bal_xilinx.format.XilinxFdriMajorFormat(name, frame_size, frame_count, frame_descriptions)¶

Bases: object

Defines the format for a specif major type.

Parameters

name (str) – The name of the major.
frame_size (int) – The size of a frame within the major.
frame_count (int) – The number of frames making up the major.
frame_descriptions (List[str]) – A description of each frame. The length of the list is expected to match the frame_count property.

Variables

name (str) – The name of the major.
frame_size (int) – The size of a frame within the major.
frame_count (int) – The number of frames making up the major.
frame_descriptions (List[str]) – A description of each frame. The length of the list is expected to match the frame_count property.

class bal_xilinx.format.XilinxFdriPinFormat(name, offset, on_value, off_value)¶

Bases: object

Defines the format for a specif io pin.

Parameters

name (str) – The name of the pin.
offset (int) – The offset of the pin.
on_value (str) – The hex representation of the value to turn the pin on.
off_value (str) – The hex representation of the value to turn the pin off.

Variables

name (str) – The name of the pin.
offset (int) – The offset of the pin.
on_value (bytes) – The hex representation of the value to turn the pin on.
off_value (bytes) – The hex representation of the value to turn the pin off

class bal_xilinx.format.XilinxFdriFormat(device_name, logic_block_size, ram_block_size, io_block_size, crc_size, logic_block_format, io_block_format)¶

Bases: object

Defines the format of an FDRI register payload for a specific type of FPGA.

Parameters

device_name (str) – The name of the FPGA.
logic_block_size (int) – The size of the logic block in bytes.
ram_block_size (int) – The size of the ram block in bytes.
io_block_size (int) – The size of the io block in bytes.
crc_size (int) – The size of the CRC checksum in bytes.
logic_block_format (Optional[List[List[XilinxFdriMajorFormat]]Optional[) – A matrix of Major formats that are contained in the logic block..
io_block_format (Optional[List[XilinxFdriPinFormat]]) – A list of pin formats that are contained in the io block.

Variables

device_name (str) – The name of the FPGA.
logic_block_size (int) – The size of the logic block in bytes.
ram_block_size (int) – The size of the ram block in bytes.
io_block_size (int) – The size of the io block in bytes.
crc_size (int) – The size of the CRC checksum in bytes.
logic_block_format (Optional[List[List[XilinxFdriMajorFormat]]Optional[) – A matrix of Major formats.

get_io_pin_by_name(name)¶

Retrieve the IO pin format for the provided IO pin name.

Parameters: name (str) – The name of the IO pin
Return type: XilinxFdriPinFormat|None

class bal_xilinx.format.XilinxFormat(registers, fdri_formats, visualizer_style, sync_word='AA995566')¶

Bases: object

Defines the format of the registers in a Xilinx bitstream. It contains indexes to look up register formats by name or address.

Parameters

registers (List[XilinxRegisterFormat]) – The list of register formats.
fdri_formats (List[XilinxFdriFormat]) – The list of FDRI packets formats targeting different types of FPGA.
visualizer_style (Any) – The style config for the visualizer frontend.
sync_word (str) – The sync word that marks the beginning of the configuration data in hex format.

Variables

sync_word (bytes) – The sync word that marks the beginning of the configuration data.

get_fdri_format(device_name)¶: Lookup the FDRI format for the provided device name :param str device_name: The name of the device :rtype: XilinxFdriFormat | None

get_register_format(address)¶: Lookup a register format by its address :param int address: The register’s address :rtype: XilinxRegisterFormat | None

get_register_format_by_name(name)¶: Lookup a register format by its name :param str name: The register’s name :rtype: XilinxRegisterFormat | None

class bal_xilinx.format.XilinxFormatBuilder¶

Bases: object

set_visualizer_config(visualizer_config)¶

add_fdri_logic_block_formats(logic_block_formats)¶

add_fdri_io_block_formats(io_block_formats)¶

add_register_formats(register_formats)¶

add_fdri_formats(fdri_formats)¶

add_fdri_major_formats(major_formats)¶

set_visualizer_config_json(path)¶

add_fdri_logic_block_formats_json(path)¶

add_fdri_io_block_formats_json(path)¶

add_register_formats_json(path)¶

add_fdri_formats_json(path)¶

add_fdri_major_formats_json(path)¶

build()¶