6. gc-info

This tool list detailed information about the IPU present in the hardware platform. To extract some of the information, gc-info will need to lock access to IPUs. Therefore it cannot be used for IPUs that are already in use.

6.1. Sub-commands

A number of sub-commands are available as command line options to gc-info. The most useful are listed below.

6.1.1. List devices

The --list-devices and --list-all-devices command options will list the IPUs in the system. The --list-devices option will list only IPUs directly connected to the server.

6.1.2. Register dump

The --tile-status command dumps the register state from the individual tiles in the IPU. There are lots of options to control what it dumps. This is useful for low-level debugging of an application or IPU fault.

Some examples:

$ gc-info --device-id 0 --tile-status 0  # dumps out all tile registers on device 0
$ gc-info --device-id 0 --tile-status 0 --context SU # dumps out all tile registers on device 0 for the supervisor context
$ gc-info --device-id 0 --tile-status 0 --context SU --register PC # dumps out the PC for the supervisor context on tile 0
$ gc-info --device-id 0 --tile-status - # dumps out the tile status for all tiles.
$ gc-info --device-id 0 --tile-status - -c SU -r PC # Dumps out the PC for the supervisor context from every tile

The SU context displays information from the supervisor execution context used for managing worker threads and exchanges.

The Wn (or just n) context displays information from worker thread n.

There are also commands to display various SoC registers for low-level debugging; for example, --xb-status, --gsp-status, --pci-status.

Note

Several of the options to gc-info are intended primarily for use by Graphcore engineering and support staff. The glossary provides a brief explanation of some of the terminology, in case it is useful,

6.1.3. Dump tile memory

The --dump-mem command displays the contents of memory on the specified tile. It takes three arguments: the tile number, the start address and the number of bytes to display.

For example, the following command dumps 16 bytes of memory from address 0x42000 on tile 0:

$ gc-info --device-id 0 --dump-mem 0 0x42000 16

6.2. Usage

6.2.1. Commands

`-l, --list-devices`	List devices
`-a, --list-all-devices`	List all devices
`-t {tile_id}, --tile-status {tile_id}`	Tile register dump
`-k, --tile-clock-speed`	Tile clock speed
`-i, --device-info`	Device info
`-m {arg}, --dump-mem {arg}`	{tile_num} {start_address} {size_in_bytes}
`--tr-status`	Trunk Router status
`-x, --xb-status`	XB status
`--gsp-status`	GSPs status
`--nlc-status`	NLCs status
`--pci-status`	SoC PCI status registers
`--ss-status`	System services registers
`--sxp-status`	Secure exchange pipe registers
`--ipu-arch`	Display IPU arch name
`--ipu-count`	Display the number of IPUs installed
`-r {arg}, --register {arg}`	Select register to print from tiles (‘-’ is all registers) (default: -)
`-c {arg}, --context {arg}`	Select register context (‘-’ is supervisor and TDI) (default: -)
`--group-output`	Set to group tile status output by value. Only valid with –register
`--phy-summary`	PCI PHY summary
`--phy-dump`	PCI PHY dump
`--show-insn`	List the instruction at the current supervisor’s $PC, for all tiles.
`--fw-pub-keys`	Display part of firmware public keys
`--remote-id {arg}`	Remote device id in format HOSTNAME:DEVICE_ID
`-h, --help`	Produce help message
`--version`	Version number

6.2.2. Command options

`-s, --disassemble`	Disassemble memory dump
`-d {id}, --device-id {id}`	Device id

6.2.3. Examples

gc-info --list-devices
gc-info --device-id {id} --tile-status {tile_num}
gc-info --device-id {id} --tile-status {tile_num} --register {reg}
gc-info --device-id {id} --tile-status {tile_num} --context - --register {reg}
gc-info --device-id {id} --tile-status {tile_num} --context SU --register {reg}
gc-info --device-id {id} --tile-status {tile_num} --context W0 --register {reg}
gc-info --device-id {id} --tile-status {tile_num} --context TDI --register {reg}
gc-info --device-id {id} --tile-status {tile_num} --context 0 --register {reg}
gc-info --device-id {id} --device-info
gc-info --device-id {id} --dump-mem {tile_num} {start_address} {size_in_bytes} [--disassemble]
gc-info --device-id {id} --xb-status
gc-info --device-id {id} --gsp-status
gc-info --device-id {id} --show-insn
gc-info --device-id {id} --fw-pub-keys

6.3. Glossary

External exchange: Data communication between IPUs or between an IPU and the host.
GSP: Global Sync Peripheral. An IPU subsystem that manages the synchronization of IPUs over multiple PCI cards.
NLC: Newman Link Controller. The interface between a PCI controller used for external exchange and a trunk router.
PCI: Peripheral Component Interconnect. The bus standard used for connecting IPUs to the host, and for IPU-Links between IPUs.
SoC: System on Chip. A device, such as the IPU, that contains processor, memory, external interfaces and on-chip peripherals,
SS: System services registers.
TDI: Tile debug interface.
TR: Trunk Router. Connects exchange traffic between the exchange block and the PCI controller.
XB: Exchange block. A subsystem that manages external exchange on behalf of the tiles in the IPU.