Standalone Utility Applications¶
The following command-line utility applications are installed alongside the Rig Python library. These utilities are simple wrappers around the Rig API with an emphasis on common system and debug tasks.
rig-boot
¶
The rig-boot
command lets you quickly and easily boot SpiNNaker systems
from the command line:
$ rig-boot HOSTNAME
If you have one of the smaller SpiNN-1, SpiNN-2 or SpiNN-3 boards, the command
above will result in only the green LED (LED0) being available. The --spinN
arguments may be used when booting such machines to correctly configure the
LEDs, e.g.:
$ rig-boot HOSTNAME --spin3
To get a complete listing of available options and supported SpiNNaker boards, type:
$ rig-boot --help
rig-power
¶
The rig-power
command lets you quickly and easily power on and off
SpiNNaker systems consisting of SpiNN-5 boards via their Board Management
Processors (BMP).
For example, to power cycle a SpiNN-5 board (or a 24-board frame thereof):
$ rig-power BMP_HOSTNAME
To power-off:
$ rig-power BMP_HOSTNAME off
To power-cycle board 3 and the last 12 boards in frame:
$ rig-power BMP_HOSTNAME -b 3,12-23
To get a complete listing of available options:
$ rig-power --help
rig-info
¶
The rig-info
command displays basic information about (booted) SpiNNaker
systems and BMPs. The command accepts a single hostname as an argument and
prints output such as the following:
$ rig-info SPINNAKER_BOARD_HOSTNAME
Device Type: SpiNNaker
Software: SC&MP v2.0.0 (Built 2016-03-17 08:13:18)
Machine dimensions: 8x8
Working chips: 48 (18 cores: 40, 17 cores: 8)
Network topology: mesh
Dead links: 0 (+ 48 to dead/missing cores)
Application states:
scamp-133: 48 run
sark: 808 idle
And for BMPs:
$ rig-info BMP_HOSTNAME
Device Type: BMP
Software: BC&MP v2.0.0 (Built 2016-03-16 14:42:38)
Code block in use: 1
Board ID (slot number): 0
1.2 V supply: 1.24 V, 1.24 V, 1.24 V
1.8 V supply: 1.81 V
3.3 V supply: 3.32 V
Input supply: 11.98 V
Temperature top: 28.9 *C
Temperature bottom: 30.0 *C
rig-discover
¶
The rig-discover
command listens for any attached unbooted SpiNNaker
boards on the network. This can be used to determine the IP address of a
locally attached board. Example:
$ rig-discover
192.168.240.253
If no machines are discovered, the command will exit after a short timeout without printing anything.
rig-iobuf
¶
The rig-iobuf
command prints the messages printed by an application’s calls
to io_printf(IOBUF, ...)
. For example, printing the IOBUF for core 1 on
chip 0, 0:
$ rig-iobuf HOSTNAME 0 0 1
Hello, world!
rig-ps
¶
The rig-ps
command enumerates every application running on a machine. For
example:
$ rig-ps HOSTNAME
X Y P State Application App ID
--- --- --- ----------------- ---------------- ------
0 0 0 run scamp-133 0
0 0 1 sync0 network_tester 66
0 0 2 sync0 network_tester 66
0 0 3 sync0 network_tester 66
0 0 4 sync0 network_tester 66
0 0 5 sync0 network_tester 66
...snip...
The listing can be filtered by:
- Application ID with
--app-id
or-a
- Application name with
--name
or-n
- Application State with
--state
or-s
The above arguments accept regular expressions as their argument. These can be used, for example, to locate misbehaving application cores:
$ rig-ps HOSTNAME --state '(?!run)'
X Y P State Application App ID
--- --- --- ----------------- ---------------- ------
3 6 13 watchdog network_tester 66
Finally, the listings can be carried out for just a particular chip or core by adding the optional ‘x’, ‘y’ and ‘p’ arguments (similar to the ybug ‘ps’ command):
$ rig-ps HOSTNAME 0 0 3
X Y P State Application App ID
--- --- --- ----------------- ---------------- ------
0 0 3 sync0 network_tester 66
rig-counters
¶
The rig-counters
command reads the router diagnostic counters for all chips
in a SpiNNaker system and reports any changes in value. This can be useful, for
example, when checking if (and where) an application is dropping packets.
In the simplest use case, simply call rig-counters
with a SpiNNaker
hostname as an argument, run your application and then press enter to see how
many packets were dropped:
$ rig-counters HOSTNAME
time,dropped_multicast
<press enter>
8.7,234
In the example above, 234 packets were dropped. Note that the output is in the form of a CSV file. You can give the –multiple` option to allow multiple samples to be captured. In the example below we capture four samples:
$ rig-counters HOSTNAME --multiple > out.csv
<press enter>
<press enter>
<press enter>
<press enter>
<press enter> ^C
$ cat out.csv
time,dropped_multicast
1.0,12
1.4,34
2.3,23
2.7,11
Instead of manually pressing enter to trigger a sample, you can use the
--command
argument to report the number of dropped packets during the
execution of your program:
$ rig-counters HOSTNAME --command ./my_program my_args
time,dropped_multicast
10.4,102
You can also report each router’s counter values individually using the
--detailed
option:
$ rig-counters HOSTNAME --detailed
time,x,y,dropped_multicast
<press enter>
10.4,0,0,10
10.4,0,1,2
10.4,0,2,5
...
Other router counter values can be reported too, see rig-counters --help
for more details.
Warning
rig-counters
works by polling the router in every chip in a SpiNNaker
machine. This process takes some time, is not atomic and also results in
P2P messages being sent through the SpiNNaker network.
The system is polled once when the utility is started and then once more for each sample requested (e.g. every time you press enter). As a result, you should be careful to only start or trigger a poll when the machine is otherwise idle, for example, before or after your application runs.