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 [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 [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]
       [-V VARIANT]
       [-I PREINIT_COMMAND]
       [-f STORAGE]
       [-d DIR]
       [--srcbuild]
       [--no-rtm-jtag]
       [ACTION [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”

-V, --variant

board variant. Autodetected if only one is installed.

-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

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 [HOP ...]]
Positional Arguments
DESTINATION

destination to operate on

HOP

hop(s) to the destination