Device¶

The Device class is a container representing a Xilinx device. Device has methods for programming, memory access, and contains the detected collection of debug cores. The collection of detected devices is held in the session.

see chipscopy.Session.devices

class chipscopy.api.device.device.Device(*, hw_server, cs_server, device_spec, device_node)[source]¶

Bases: abc.ABC

The Device class represents a single device. It is the base class for other Xilinx or Generic devices. Depending on the device type, some features may be available or unavailable.

Device has the kitchen sink of properties functions to make documentation and type hints easy. Child classes raise FeatureNotAvailable for functions they do not support.

property chipscope_node: Optional[chipscopy.client.core.CoreParent]¶

Low level TCF node access - For advanced use

Return type: Optional[CoreParent]

property context: str¶

Returns the unique context for this device. Normally this is the jtag node context. If this device is not on a jtag chain, the top level device context will be a non-jtag node.

Return type: str

abstract property ddrs: chipscopy.api.containers.QueryList[chipscopy.api.ddr.ddr.DDR]¶

Returns: list of detected DDRMC cores in the device

Return type: QueryList[DDR]

property debugcore_node: Optional[chipscopy.dm.Node]¶

Low level TCF node access - For advanced use

Return type: Optional[Node]

abstract discover_and_setup_cores(*, hub_address_list=None, ltx_file=None, **kwargs)[source]¶

Scan device for debug cores. This may take some time depending on what gets scanned.

Parameters

hub_address_list (Optional[List[int]]) – List of debug hub addresses to scan
ltx_file (Optional[str]) – LTX file (which contains debug hub addresses)

Keyword Arguments

ila_scan – True=Scan Device for ILAs
vio_scan – True=Scan Device for VIOs
ibert_scan – True=Scan Device for IBERTs
pcie_scan – True=Scan Device for PCIEs
noc_scan – True=Scan Device for NOC
ddr_scan – True=Scan Device for DDRs
hbm_scan – True=Scan Device for HBMs
sysmon_scan – True=Scan Device for System Monitor

abstract get_program_log(memory_target=None)[source]¶

Returns: Programming log read from hardware (None=Use default transport)

Parameters: memory_target – Optional name of memory target such as APU, RPU, DPC
Return type: str

abstract property hbms: chipscopy.api.containers.QueryList[chipscopy.api.hbm.hbm.HBM]¶

Returns: list of detected HBM cores in the device

Return type: QueryList[HBM]

abstract property ibert_cores: chipscopy.api.containers.QueryList[chipscopy.api.ibert.ibert.IBERT]¶

Returns: list of detected IBERT cores in the device

Return type: QueryList[IBERT]

abstract property ila_cores: chipscopy.api.containers.QueryList[chipscopy.api.ila.ila.ILA]¶

Returns: list of detected ILA cores in the device

Return type: QueryList[ILA]

property is_programmed: bool¶

Returns True if this Device is programmed, False otherwise.

Return type: bool

property is_valid: bool¶

Returns True if this Node is valid, False otherwise.

Return type: bool

property jtag_cable_node: Optional[chipscopy.client.jtagdevice.JtagCable]¶

Low level TCF node access - For advanced use

Return type: Optional[JtagCable]

property jtag_node: Optional[chipscopy.client.jtagdevice.JtagDevice]¶

Low level TCF node access - For advanced use

Return type: Optional[JtagDevice]

abstract property memory: chipscopy.api.containers.QueryList[chipscopy.api.memory.Memory]¶

Returns: the memory access for the device

Return type: QueryList[Memory]

abstract memory_read(address, num=1, *, size, target=None)[source]¶

Read num values from given memory address. This method is slow because it locates the memory context in the target tree every time. If you want to execute a large number of memory operations, grab a memory context and do all the operations in batch. Note: This method should not be used in inner loops. It is not the fastest because it looks up the memory target every time. Inner loops should just call the find_memory_target once.

Return type: List[int]

abstract property memory_target_names¶: Returns: list of supported memory targets

abstract memory_write(address, values, *, size, target=None)[source]¶: Write list of values to given memory address. This method is slow because it locates the memory context in the target tree every time. If you want to execute a large number of memory operations, grab a memory context and do the operations in batch. Note: This method should not be used in inner loops. It is not the fastest because it looks up the memory target every time. Inner loops should just call the find_memory_target once.

abstract property noc_core: chipscopy.api.containers.QueryList[chipscopy.api.noc.noc.NocPerfmon]¶

Returns: List with NOC roots for the device

Return type: QueryList[NocPerfmon]

abstract property pcie_cores: chipscopy.api.containers.QueryList[chipscopy.api.pcie.PCIe]¶

Returns: list of detected PCIe cores in the device

Return type: QueryList[PCIe]

abstract program(programming_file, *, skip_reset=False, show_progress_bar=True, done=None)[source]¶

Program the device with a given programming file (bit or pdi).

Parameters

programming_file (Union[str, Path]) – PDI file path
skip_reset (bool) – False = Do not reset device prior to program
show_progress_bar (bool) – False if the progress bar doesn’t need to be shown
done (Optional[NewType()(DoneFutureCallback, Callable[[ForwardRef], None])]) – Optional async future callback

abstract reset()[source]¶: Reset the device to a non-programmed state.

abstract property sysmon_root: chipscopy.api.containers.QueryList[chipscopy.api.sysmon.Sysmon]¶

Returns: List with one SysMon core for the device

Return type: QueryList[Sysmon]

to_dict()[source]¶

Returns a dictionary representation of the device data

Return type: Dict

to_json()[source]¶

Returns a json representation of the device data

Return type: str

abstract property trace_cores: chipscopy.api.containers.QueryList[chipscopy.api._detail.trace.Trace]¶

Returns: list of detected Trace cores in the device

Return type: QueryList[Trace]

abstract property vio_cores: chipscopy.api.containers.QueryList[chipscopy.api.vio.VIO]¶

Returns: list of detected VIO cores in the device

Return type: QueryList[VIO]

exception chipscopy.api.device.device.FeatureNotAvailableError[source]¶: Bases: Exception

class chipscopy.api.device.device.FpgaDevice(*, hw_server, cs_server, device_spec, disable_core_scan, device_node)[source]¶

Bases: chipscopy.api.device.device.Device, abc.ABC

property ddrs: chipscopy.api.containers.QueryList[chipscopy.api.ddr.ddr.DDR]¶

Returns: list of detected DDRMC cores in the device

Return type: QueryList[DDR]

discover_and_setup_cores(*, hub_address_list=None, ltx_file=None, **kwargs)[source]¶

Scan device for debug cores. This may take some time depending on what gets scanned.

Parameters

hub_address_list (Optional[List[int]]) – List of debug hub addresses to scan
ltx_file (Optional[str]) – LTX file (which contains debug hub addresses)

Keyword Arguments

ila_scan – True=Scan Device for ILAs
vio_scan – True=Scan Device for VIOs
ibert_scan – True=Scan Device for IBERTs
pcie_scan – True=Scan Device for PCIEs
noc_scan – True=Scan Device for NOC
ddr_scan – True=Scan Device for DDRs
hbm_scan – True=Scan Device for HBMs
sysmon_scan – True=Scan Device for System Monitor

get_program_log(memory_target=None)[source]¶

Returns: Programming log read from hardware (None=Use default transport)

Parameters: memory_target – Optional name of memory target such as APU, RPU, DPC
Return type: str

property hbms: chipscopy.api.containers.QueryList[chipscopy.api.hbm.hbm.HBM]¶

Returns: list of detected HBM cores in the device

Return type: QueryList[HBM]

property ibert_cores: chipscopy.api.containers.QueryList[chipscopy.api.ibert.ibert.IBERT]¶

Returns: list of detected IBERT cores in the device

Return type: QueryList[IBERT]

property ila_cores: chipscopy.api.containers.QueryList[chipscopy.api.ila.ila.ILA]¶

Returns: list of detected ILA cores in the device

Return type: QueryList[ILA]

property is_programmed: bool¶

Returns True if this Device is programmed, False otherwise.

Return type: bool

property memory: chipscopy.api.containers.QueryList[chipscopy.api.memory.Memory]¶

Returns: the memory access for the device

Return type: QueryList[Memory]

memory_read(address, num=1, *, size, target=None)[source]¶

Read num values from given memory address. This method is slow because it locates the memory context in the target tree every time. If you want to execute a large number of memory operations, grab a memory context and do all the operations in batch. Note: This method should not be used in inner loops. It is not the fastest because it looks up the memory target every time. Inner loops should just call the find_memory_target once.

Return type: List[int]

property memory_target_names¶: Returns: list of supported memory targets

memory_write(address, values, *, size, target=None)[source]¶: Write list of values to given memory address. This method is slow because it locates the memory context in the target tree every time. If you want to execute a large number of memory operations, grab a memory context and do the operations in batch. Note: This method should not be used in inner loops. It is not the fastest because it looks up the memory target every time. Inner loops should just call the find_memory_target once.

property noc_core: chipscopy.api.containers.QueryList[chipscopy.api.noc.noc.NocPerfmon]¶

Returns: List with NOC roots for the device

Return type: QueryList[NocPerfmon]

property pcie_cores: chipscopy.api.containers.QueryList[chipscopy.api.pcie.PCIe]¶

Returns: list of detected PCIe cores in the device

Return type: QueryList[PCIe]

program(programming_file, *, skip_reset=False, show_progress_bar=True, done=None)[source]¶

Program the device with a given programming file (bit or pdi).

Parameters

programming_file (Union[str, Path]) – PDI file path
skip_reset (bool) – False = Do not reset device prior to program
show_progress_bar (bool) – False if the progress bar doesn’t need to be shown
done (Optional[NewType()(DoneFutureCallback, Callable[[ForwardRef], None])]) – Optional async future callback

reset()[source]¶: Reset the device to a non-programmed state.

property sysmon_root: chipscopy.api.containers.QueryList[chipscopy.api.sysmon.Sysmon]¶

Returns: List with one SysMon core for the device

Return type: QueryList[Sysmon]

to_dict()[source]¶

Returns a dictionary representation of the device data

Return type: Dict

property trace_cores: chipscopy.api.containers.QueryList[chipscopy.api._detail.trace.Trace]¶

Returns: list of detected Trace cores in the device

Return type: QueryList[Trace]

property vio_cores: chipscopy.api.containers.QueryList[chipscopy.api.vio.VIO]¶

Returns: list of detected VIO cores in the device

Return type: QueryList[VIO]

class chipscopy.api.device.device.GenericDevice(*, hw_server, cs_server, device_spec, device_node)[source]¶

Bases: chipscopy.api.device.device.Device

property ddrs: chipscopy.api.containers.QueryList[chipscopy.api.ddr.ddr.DDR]¶

Returns: list of detected DDRMC cores in the device

Return type: QueryList[DDR]

discover_and_setup_cores(*, hub_address_list=None, ltx_file=None, **kwargs)[source]¶

Scan device for debug cores. This may take some time depending on what gets scanned.

Parameters

hub_address_list (Optional[List[int]]) – List of debug hub addresses to scan
ltx_file (Optional[str]) – LTX file (which contains debug hub addresses)

Keyword Arguments

ila_scan – True=Scan Device for ILAs
vio_scan – True=Scan Device for VIOs
ibert_scan – True=Scan Device for IBERTs
pcie_scan – True=Scan Device for PCIEs
noc_scan – True=Scan Device for NOC
ddr_scan – True=Scan Device for DDRs
hbm_scan – True=Scan Device for HBMs
sysmon_scan – True=Scan Device for System Monitor

get_program_log(memory_target=None)[source]¶

Returns: Programming log read from hardware (None=Use default transport)

Parameters: memory_target – Optional name of memory target such as APU, RPU, DPC
Return type: str

property hbms: chipscopy.api.containers.QueryList[chipscopy.api.hbm.hbm.HBM]¶

Returns: list of detected HBM cores in the device

Return type: QueryList[HBM]

property ibert_cores: chipscopy.api.containers.QueryList[chipscopy.api.ibert.ibert.IBERT]¶

Returns: list of detected IBERT cores in the device

Return type: QueryList[IBERT]

property ila_cores: chipscopy.api.containers.QueryList[chipscopy.api.ila.ila.ILA]¶

Returns: list of detected ILA cores in the device

Return type: QueryList[ILA]

property is_programmed: bool¶

Returns True if this Device is programmed, False otherwise.

Return type: bool

property memory: chipscopy.api.containers.QueryList[chipscopy.api.memory.Memory]¶

Returns: the memory access for the device

Return type: QueryList[Memory]

memory_read(address, num=1, *, size, target=None)[source]¶

Read num values from given memory address. This method is slow because it locates the memory context in the target tree every time. If you want to execute a large number of memory operations, grab a memory context and do all the operations in batch. Note: This method should not be used in inner loops. It is not the fastest because it looks up the memory target every time. Inner loops should just call the find_memory_target once.

Return type: List[int]

property memory_target_names¶: Returns: list of supported memory targets

memory_write(address, values, *, size, target=None)[source]¶: Write list of values to given memory address. This method is slow because it locates the memory context in the target tree every time. If you want to execute a large number of memory operations, grab a memory context and do the operations in batch. Note: This method should not be used in inner loops. It is not the fastest because it looks up the memory target every time. Inner loops should just call the find_memory_target once.

property noc_core: chipscopy.api.containers.QueryList[chipscopy.api.noc.noc.NocPerfmon]¶

Returns: List with NOC roots for the device

Return type: QueryList[NocPerfmon]

property pcie_cores: chipscopy.api.containers.QueryList[chipscopy.api.pcie.PCIe]¶

Returns: list of detected PCIe cores in the device

Return type: QueryList[PCIe]

program(programming_file, *, skip_reset=False, show_progress_bar=True, done=None)[source]¶

Program the device with a given programming file (bit or pdi).

Parameters

programming_file (Union[str, Path]) – PDI file path
skip_reset (bool) – False = Do not reset device prior to program
show_progress_bar (bool) – False if the progress bar doesn’t need to be shown
done (Optional[NewType()(DoneFutureCallback, Callable[[ForwardRef], None])]) – Optional async future callback

reset()[source]¶: Reset the device to a non-programmed state.

property sysmon_root: chipscopy.api.containers.QueryList[chipscopy.api.sysmon.Sysmon]¶

Returns: List with one SysMon core for the device

Return type: QueryList[Sysmon]

property trace_cores: chipscopy.api.containers.QueryList[chipscopy.api._detail.trace.Trace]¶

Returns: list of detected Trace cores in the device

Return type: QueryList[Trace]

property vio_cores: chipscopy.api.containers.QueryList[chipscopy.api.vio.VIO]¶

Returns: list of detected VIO cores in the device

Return type: QueryList[VIO]

class chipscopy.api.device.device.UltrascaleDevice(*, hw_server, cs_server, device_spec, disable_core_scan, device_node)[source]¶: Bases: chipscopy.api.device.device.FpgaDevice

class chipscopy.api.device.device.VersalDevice(*, hw_server, cs_server, device_spec, disable_core_scan, device_node)[source]¶

Bases: chipscopy.api.device.device.FpgaDevice

property ddrs¶: Returns: list of detected DDRMC cores in the device

get_program_log(memory_target='APU')[source]¶

Returns: Programming log read from hardware (None=Use default transport)

Parameters: memory_target – Optional name of memory target such as APU, RPU, DPC
Return type: str

property hbms¶: Returns: list of detected HBM cores in the device

property ibert_cores: chipscopy.api.containers.QueryList[chipscopy.api.ibert.ibert.IBERT]¶

Returns: list of detected IBERT cores in the device

Return type: QueryList[IBERT]

property ila_cores: chipscopy.api.containers.QueryList[chipscopy.api.ila.ila.ILA]¶

Returns: list of detected ILA cores in the device

Return type: QueryList[ILA]

property memory: chipscopy.api.containers.QueryList[chipscopy.api.memory.Memory]¶

Returns: the memory access for the device

Return type: QueryList[Memory]

memory_read(address, num=1, *, size='w', target=None)[source]¶

Read num values from given memory address. This method is slow because it locates the memory context in the target tree every time. If you want to execute a large number of memory operations, grab a memory context and do all the operations in batch. Note: This method should not be used in inner loops. It is not the fastest because it looks up the memory target every time. Inner loops should just call the find_memory_target once.

Return type: List[int]

property memory_target_names¶: Returns: list of supported memory targets

memory_write(address, values, *, size='w', target=None)[source]¶: Write list of values to given memory address. This method is slow because it locates the memory context in the target tree every time. If you want to execute a large number of memory operations, grab a memory context and do the operations in batch. Note: This method should not be used in inner loops. It is not the fastest because it looks up the memory target every time. Inner loops should just call the find_memory_target once.

property noc_core: chipscopy.api.containers.QueryList[chipscopy.api.noc.noc.NocPerfmon]¶

Returns: List with NOC roots for the device

Return type: QueryList[NocPerfmon]

property pcie_cores: chipscopy.api.containers.QueryList[chipscopy.api.pcie.PCIe]¶

Returns: list of detected PCIe cores in the device

Return type: QueryList[PCIe]

property sysmon_root: chipscopy.api.containers.QueryList[chipscopy.api.sysmon.Sysmon]¶

Returns: List with one SysMon core for the device

Return type: QueryList[Sysmon]

property trace_cores: chipscopy.api.containers.QueryList[chipscopy.api._detail.trace.Trace]¶

Returns: list of detected Trace cores in the device

Return type: QueryList[Trace]

property vio_cores: chipscopy.api.containers.QueryList[chipscopy.api.vio.VIO]¶

Returns: list of detected VIO cores in the device

Return type: QueryList[VIO]