Utilities¶
Local running tool¶
Local experiment running tool
usage: artiq_run
[-h]
[--version]
[--device-db DEVICE_DB]
[--dataset-db DATASET_DB]
[-c CLASS_NAME]
[-o HDF5]
FILE
[ARGUMENTS ...]
Positional Arguments¶
- FILE
file containing the experiment to run
- ARGUMENTS
run arguments
Named Arguments¶
- --version
print the ARTIQ version number
- --device-db
device database file (default: ‘“device_db.py”’)
Default: “device_db.py”
- --dataset-db
dataset file (default: ‘“dataset_db.pyon”’)
Default: “dataset_db.pyon”
- -c, --class-name
name of the class to run
- -o, --hdf5
write results to specified HDF5 file (default: print them)
Static compiler¶
This tool compiles an experiment into a ELF file. It is primarily used to prepare binaries for the default experiment loaded in non-volatile storage of the core device.
Experiments compiled with this tool are not allowed to use RPCs, and their run
entry point must be a kernel.
ARTIQ static compiler
usage: artiq_compile
[-h]
[--version]
[--device-db DEVICE_DB]
[--dataset-db DATASET_DB]
[-c CLASS_NAME]
[-o OUTPUT]
FILE
[ARGUMENTS ...]
Positional Arguments¶
- FILE
file containing the experiment to compile
- ARGUMENTS
run arguments
Named Arguments¶
- --version
print the ARTIQ version number
- --device-db
device database file (default: ‘“device_db.py”’)
Default: “device_db.py”
- --dataset-db
dataset file (default: ‘“dataset_db.pyon”’)
Default: “dataset_db.pyon”
- -c, --class-name
name of the class to compile
- -o, --output
output file
Flash storage image generator¶
This tool compiles key/value pairs into a binary image suitable for flashing into the flash storage space of the core device.
ARTIQ flash storage image generator
usage: artiq_mkfs
[-h]
[-s KEY STRING]
[-f KEY FILENAME]
output
Positional Arguments¶
- output
output file
Named Arguments¶
- -s
add string
Default: []
- -f
add file contents
Default: []
Flashing/Loading tool¶
ARTIQ flashing/deployment tool
usage: artiq_flash
[-h]
[--version]
[-n]
[-H HOSTNAME]
[-J JUMP]
[-t TARGET]
[-I PREINIT_COMMAND]
[-f STORAGE]
[-d DIR]
[--srcbuild]
[--no-rtm-jtag]
[ACTION ...]
Positional Arguments¶
- ACTION
actions to perform, default: flash everything
Default: []
Named Arguments¶
- --version
print the ARTIQ version number
- -n, --dry-run
only show the openocd script that would be run
Default: False
- -H, --host
SSH host where the board is located
- -J, --jump
SSH host to jump through
- -t, --target
target board, default: “kasli”, one of: kasli sayma metlino kc705
Default: “kasli”
- -I, --preinit-command
add a pre-initialization OpenOCD command. Useful for selecting a board when several are connected.
Default: []
- -f, --storage
write file to storage area
- -d, --dir
look for board binaries in this directory
- --srcbuild
board binaries directory is laid out as a source build tree
Default: False
- --no-rtm-jtag
do not attempt JTAG to the RTM
Default: False
Valid actions:
gateware: write main gateware bitstream to flash
rtm_gateware: write RTM gateware bitstream to flash
bootloader: write bootloader to flash
storage: write storage image to flash
firmware: write firmware to flash
load: load main gateware bitstream into device (volatile but fast)
rtm_load: load RTM gateware bitstream into device
erase: erase flash memory
start: trigger the target to (re)load its gateware bitstream from flash
Prerequisites:
Connect the board through its/a JTAG adapter.
Have OpenOCD installed and in your $PATH.
Have access to the JTAG adapter’s devices. Udev rules from OpenOCD: ‘sudo cp openocd/contrib/99-openocd.rules /etc/udev/rules.d’ and replug the device. Ensure you are member of the plugdev group: ‘sudo adduser $USER plugdev’ and re-login.
Core device management tool¶
The artiq_coremgmt utility gives remote access to the core device logs, the Flash storage, and other management functions.
To use this tool, you need to specify a device_db.py
device database file which contains a comm
device (an example is provided in examples/master/device_db.py
). This tells the tool how to connect to the core device and with which parameters (e.g. IP address, TCP port). When not specified, the artiq_coremgmt utility will assume that there is a file named device_db.py
in the current directory.
To read core device logs:
$ artiq_coremgmt log
To set core device log level and UART log level (possible levels are TRACE
, DEBUG
, INFO
, WARN
and ERROR
):
$ artiq_coremgmt log set_level LEVEL
$ artiq_coremgmt log set_uart_level LEVEL
Note that enabling the TRACE
log level results in small core device slowdown, and printing large amounts of log messages to the UART results in significant core device slowdown.
To read the record whose key is mac
:
$ artiq_coremgmt config read mac
To write the value test_value
in the key my_key
:
$ artiq_coremgmt config write -s my_key test_value
$ artiq_coremgmt config read my_key
b'test_value'
You can also write entire files in a record using the -f
parameter. This is useful for instance to write the startup and idle kernels in the flash storage:
$ artiq_coremgmt config write -f idle_kernel idle.elf
$ artiq_coremgmt config read idle_kernel | head -c9
b'\x7fELF
You can write several records at once:
$ artiq_coremgmt config write -s key1 value1 -f key2 filename -s key3 value3
To remove the previously written key my_key
:
$ artiq_coremgmt config remove my_key
You can remove several keys at once:
$ artiq_coremgmt config remove key1 key2
To erase the entire flash storage area:
$ artiq_coremgmt config erase
You do not need to remove a record in order to change its value, just overwrite it:
$ artiq_coremgmt config write -s my_key some_value
$ artiq_coremgmt config write -s my_key some_other_value
$ artiq_coremgmt config read my_key
b'some_other_value'
ARTIQ core device management tool
usage: artiq_coremgmt
[-h]
[--version]
[--device-db DEVICE_DB]
[-D DEVICE]
{log,config,reboot,debug}
...
Positional Arguments¶
- tool
Possible choices: log, config, reboot, debug
Named Arguments¶
- --version
print the ARTIQ version number
- --device-db
device database file (default: ‘“device_db.py”’)
Default: “device_db.py”
- -D, --device
use specified core device address instead of reading device database
Sub-commands:¶
log¶
read logs and change log levels
artiq_coremgmt log
[-h]
{clear,set_level,set_uart_level}
...
Positional Arguments¶
- action
Possible choices: clear, set_level, set_uart_level
Sub-commands:¶
clear¶
clear log buffer
artiq_coremgmt log clear
[-h]
set_level¶
set minimum level for messages to be logged
artiq_coremgmt log set_level
[-h]
LEVEL
Positional Arguments¶
- LEVEL
log level (one of: OFF ERROR WARN INFO DEBUG TRACE)
set_uart_level¶
set minimum level for messages to be logged to UART
artiq_coremgmt log set_uart_level
[-h]
LEVEL
Positional Arguments¶
- LEVEL
log level (one of: OFF ERROR WARN INFO DEBUG TRACE)
config¶
read and change core device configuration
artiq_coremgmt config
[-h]
{read,write,remove,erase}
...
Positional Arguments¶
- action
Possible choices: read, write, remove, erase
Sub-commands:¶
read¶
read key from core device config
artiq_coremgmt config read
[-h]
KEY
Positional Arguments¶
- KEY
key to be read from core device config
write¶
write key-value records to core device config
artiq_coremgmt config write
[-h]
[-s KEY STRING]
[-f KEY FILENAME]
Named Arguments¶
- -s, --string
key-value records to be written to core device config
Default: []
- -f, --file
key and file whose content to be written to core device config
Default: []
remove¶
remove key from core device config
artiq_coremgmt config remove
[-h]
...
Positional Arguments¶
- KEY
key to be removed from core device config
Default: []
erase¶
fully erase core device config
artiq_coremgmt config erase
[-h]
reboot¶
reboot the running system
artiq_coremgmt reboot
[-h]
debug¶
specialized debug functions
artiq_coremgmt debug
[-h]
{allocator}
...
Positional Arguments¶
- action
Possible choices: allocator
Sub-commands:¶
allocator¶
show heap layout
artiq_coremgmt debug allocator
[-h]
Core device logging controller¶
ARTIQ controller for core device logs
usage: aqctl_corelog
[-h]
[--simulation]
CORE_ADDR
Positional Arguments¶
- CORE_ADDR
hostname or IP address of the core device
Named Arguments¶
- --simulation
Simulation - does not connect to device
Default: False
Moninj proxy¶
ARTIQ moninj proxy
usage: aqctl_moninj_proxy
[-h]
CORE_ADDR
Positional Arguments¶
- CORE_ADDR
hostname or IP address of the core device
Core device RTIO analyzer tool¶
artiq_coreanalyzer
is a tool to convert core device RTIO logs to VCD waveform files that are readable by third-party tools such as GtkWave. This tool extracts pre-recorded data from an ARTIQ core device buffer (or from a file with the -r
option), and converts it to a standard VCD file format. See RTIO analyzer for an example, or artiq.test.coredevice.test_analyzer
for a relevant unit test.
ARTIQ core device RTIO analysis tool
usage: artiq_coreanalyzer
[-h]
[--device-db DEVICE_DB]
[-r READ_DUMP]
[-p]
[-w WRITE_VCD]
[-d WRITE_DUMP]
[-u]
Named Arguments¶
- --device-db
device database file (default: ‘“device_db.py”’)
Default: “device_db.py”
- -r, --read-dump
read raw dump file instead of accessing device
- -p, --print-decoded
print raw decoded messages
Default: False
- -w, --write-vcd
format and write contents to VCD file
- -d, --write-dump
write raw dump file
- -u, --vcd-uniform-interval
emit uniform time intervals between timed VCD events and show RTIO event interval (in SI seconds) and timestamp (in machine units) as separate VCD channels
Default: False
Note
The RTIO analyzer does not support SAWG.
DRTIO routing table manipulation tool¶
ARTIQ DRTIO routing table manipulation tool
usage: artiq_route
[-h]
FILE
{init,show,set}
...
Positional Arguments¶
- FILE
target file
- action
Possible choices: init, show, set
Sub-commands:¶
init¶
create a new empty routing table
artiq_route init
[-h]
show¶
show contents of routing table
artiq_route show
[-h]
set¶
set routing table entry
artiq_route set
[-h]
DESTINATION
[HOP ...]
Positional Arguments¶
- DESTINATION
destination to operate on
- HOP
hop(s) to the destination