Utilities

ARTIQ Firmware Service (AFWS) client

This tool serves as a client for building tailored firmware and gateware from M-Lab’s servers and downloading the binaries in ready-to-flash format. It is necessary to have a valid subscription to AFWS to use it. Subscription also includes general helpdesk support and can be purchased or extended by contacting sales@. One year of support is included with any Kasli carriers or crates containing them purchased from M-Labs. Additional one-time use is generally provided with purchase of additional cards to facilitate the system configuration change.

usage: afws_client [-h] [--server SERVER] [--port PORT] [--cert CERT]
                   username {build,passwd,get_variants,get_json} ...

Positional Arguments

username: user name for logging into AFWS
action: Possible choices: build, passwd, get_variants, get_json

Named Arguments

--server: server to connect to (default: ‘afws.m-labs.hk’)
--port: port to connect to (default: 80)
--cert: SSL certificate file used to authenticate server (default: use system certificates)

Sub-commands

build

build and download firmware

afws_client build [-h] [--major-ver MAJOR_VER] [--rev REV] [--log]
                  [--experimental EXPERIMENTAL]
                  directory [variant]

Positional Arguments

directory: output directory
variant: variant to build (can be omitted if user is authorised to build only one)

Named Arguments

--major-ver: ARTIQ major version
--rev: revision to build (default: currently installed ARTIQ revision)
--log: Display the build log
--experimental: enable an experimental feature (can be repeatedly specified to enable multiple features)

passwd

change password

Warning

After receiving your credentials from M-Labs, it is recommended to change your password as soon as possible. It is your responsibility to set and remember a secure password. If necessary, passwords can be reset by contacting helpdesk@.

afws_client passwd [-h]

get_variants

get available variants and expiry dates

afws_client get_variants [-h]

get_json

get JSON description file of variant

afws_client get_json [-h] [-o OUT] [-f] [variant]

Positional Arguments

variant: variant to get (can be omitted if user is authorised to build only one)

Named Arguments

-o, --out: output JSON file
-f, --force: overwrite file if it already exists

Static compiler

Compiles an experiment into a ELF file (or a TAR file if the experiment involves subkernels). It is primarily used to prepare binaries for the startup and idle kernels, 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.

usage: artiq_compile [-h] [--version] [-v] [-q] [--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’’)
--dataset-db: dataset file (default: ‘’dataset_db.mdb’’)
-c, --class-name: name of the class to compile
-o, --output: output file

verbosity

-v, --verbose: increase logging level
-q, --quiet: decrease logging level

Flash storage image generator

Compiles key/value pairs (e.g. configuration information) into a binary image suitable for flashing into the storage space of the core device. It can be used in combination with artiq_flash to configure the core device, but this is normally necessary at most to set the ip field; once the core device is reachable by network it is preferable to use artiq_coremgmt config. Not applicable to ARTIQ-Zynq, where preconfiguration is better achieved by loading config.txt onto the SD card.

usage: artiq_mkfs [-h] [-s KEY STRING] [-f KEY FILENAME] output

Positional Arguments

output: output file

Named Arguments

-s: add string
-f: add file contents

Flashing/Loading tool

Allows for flashing and loading of various files onto the core device. Not applicable to ARTIQ-Zynq, where gateware and firmware should be loaded onto the core device with artiq_coremgmt, directly copied onto the SD card, or (for developers) using the ARTIQ netboot utility.

usage: artiq_flash [-h] [--version] [-v] [-q] [-n] [-H HOSTNAME] [-J JUMP]
                   [-t TARGET] [-I PREINIT_COMMAND] [-f STORAGE] [-d DIR]
                   [--srcbuild]
                   [COMMANDS ...]

Positional Arguments

COMMANDS: run cmd(s), for write and erase command, use format: CMD=REGION | for other commands, use format: CMD | default: flash gateware, firmware and bootloader and restart the FPGA device

Named Arguments

--version: print the ARTIQ version number
-n, --dry-run: only show the openocd script that would be run
-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 efc kc705
-I, --preinit-command: add a pre-initialization OpenOCD command. Useful for selecting a board when several are connected.
-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

verbosity

-v, --verbose: increase logging level
-q, --quiet: decrease logging level

Valid commands:

write: write the binary or image file(s) to the specified flash region(s).

erase: erase the specified flash region(s).

load: load the main gateware bitstream into device (volatile but fast).

start: trigger the target to (re)load its gateware bitstream from flash. If your core device is reachable by network, prefer ‘artiq_coremgmt reboot’.

Valid regions for write and erase actions:

gateware

bootloader

storage

firmware

Example: gateware,bootloader,storage,firmware

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 core management utility gives remote access to the core device logs, the core device flash storage, and other management functions.

To use this tool, it is necessary to specify the IP address your core device can be contacted at. If no option is used, the utility will assume there is a file named device_db.py in the current directory containing the device database; otherwise, a device database file can be provided with --device-db or an address directly with --device (see also below).

usage: artiq_coremgmt [-h] [--version] [-v] [-q] [--device-db DEVICE_DB]
                      [-D DEVICE] [-s DRTIO_DEST]
                      {log,config,reboot,flash,debug} ...

Positional Arguments

tool: Possible choices: log, config, reboot, flash, debug

Named Arguments

--version: print the ARTIQ version number
--device-db: device database file (default: ‘’device_db.py’’)
-D, --device: use specified core device address instead of reading device database
-s, --drtio-dest: specify DRTIO destination that receives this command

verbosity

-v, --verbose: increase logging level
-q, --quiet: decrease logging level

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] [-f KEY FILENAME] [-s KEY]

Named Arguments

-f, --file: write contents of read from key to file
-s, --string: print contents of read from key to stdout

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
-f, --file: key and file whose content to be written to core device config

remove

remove key from core device config

artiq_coremgmt config remove [-h] ...

Positional Arguments

KEY: key to be removed from core device config

erase

fully erase core device config

artiq_coremgmt config erase [-h]

reboot

reboot the running system

artiq_coremgmt reboot [-h]

flash

flash the core device and reboot into the new system

artiq_coremgmt flash [-h] [--srcbuild] PATH

Positional Arguments

PATH: binary file or directory that contains the binaries

Named Arguments

--srcbuild: board binaries directory is laid out as a source build tree

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]

Device database template generator

This tool generates a basic template for a device database given the JSON description file(s) for the system. Entries for controllers are not generated.

usage: artiq_ddb_template [-h] [--version] [-o OUTPUT]
                          [-s DESTINATION DESCRIPTION]
                          PRIMARY_DESCRIPTION

Positional Arguments

PRIMARY_DESCRIPTION: JSON system description file for the primary (standalone or master) node

Named Arguments

--version: print the ARTIQ version number
-o, --output: output file, defaults to standard output if omitted
-s, --satellite: add DRTIO satellite at the given destination number with devices from the given JSON description

RTIO channel name map tool

This tool encodes the map of RTIO channel numbers to names in a format suitable for writing to the config key device_map. See Set up resolving RTIO channels to their names.

usage: artiq_rtiomap [-h] [--version] [-v] [-q] [--device-db DEVICE_DB]
                     [--show]
                     FILE

Positional Arguments

FILE: write the result into the specified file, or read from it to show the map (see –show)

Named Arguments

--version: print the ARTIQ version number
--device-db: device database file (default: ‘’device_db.py’’)
--show: show the channel mapping from the specified file, instead of writing to it

verbosity

-v, --verbose: increase logging level
-q, --quiet: decrease logging level

Core device RTIO analyzer tool

This tool retrieves core device RTIO logs either as raw data or as VCD waveform files, which are readable by third-party tools such as GtkWave. See RTIO analyzer for an example, or artiq.test.coredevice.test_analyzer for a relevant unit test.

Using the management system, the respective functionality is provided by aqctl_coreanalyzer_proxy and the dashboard’s ‘Waveform’ tab; see Waveform.

usage: artiq_coreanalyzer [-h] [-v] [-q] [--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’’)
-r, --read-dump: read raw dump file instead of accessing device
-p, --print-decoded: print raw decoded messages
-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

verbosity

-v, --verbose: increase logging level
-q, --quiet: decrease logging level

DRTIO routing table manipulation tool

This tool allows for manipulation of a DRTIO routing table file, which can be transmitted to the core device using artiq_coremgmt config write; see Configuring the routing table.

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

ARTIQ RTIO monitor

Command-line interface for monitoring RTIO channels, as in the Monitor capacity of dashboard MonInj. See Using MonInj.

usage: artiq_rtiomon [-h] CORE_ADDR CHANNEL [CHANNEL ...]

Positional Arguments

CORE_ADDR: hostname or IP address of the core device
CHANNEL: channel(s) to monitor

MonInj proxy

ARTIQ moninj proxy

usage: aqctl_moninj_proxy [-h] [-v] [-q] [--bind BIND] [--no-localhost-bind]
                          [--port-proxy PORT_PROXY]
                          [--port-control PORT_CONTROL]
                          CORE_ADDR

Positional Arguments

CORE_ADDR: hostname or IP address of the core device

verbosity

-v, --verbose: increase logging level
-q, --quiet: decrease logging level

network server

--bind: additional hostname or IP address to bind to; use ‘*’ to bind to all interfaces (default: [])
--no-localhost-bind: do not implicitly also bind to localhost addresses
--port-proxy: TCP port for proxying connections (default: 1383)
--port-control: TCP port for control connections (default: 1384)

Core device RTIO analyzer proxy

ARTIQ core analyzer proxy

usage: aqctl_coreanalyzer_proxy [-h] [-v] [-q] [--bind BIND]
                                [--no-localhost-bind]
                                [--port-proxy PORT_PROXY]
                                [--port-control PORT_CONTROL]
                                CORE_ADDR

Positional Arguments

CORE_ADDR: hostname or IP address of the core device

verbosity

-v, --verbose: increase logging level
-q, --quiet: decrease logging level

network server

--bind: additional hostname or IP address to bind to; use ‘*’ to bind to all interfaces (default: [])
--no-localhost-bind: do not implicitly also bind to localhost addresses
--port-proxy: TCP port for proxying connections (default: 1385)
--port-control: TCP port for control connections (default: 1386)

Core device logging controller

ARTIQ controller for core device logs

usage: aqctl_corelog [-h] [-v] [-q] [--bind BIND] [--no-localhost-bind]
                     [-p PORT] [--simulation] [-s DRTIO_DEST]
                     CORE_ADDR

Positional Arguments

CORE_ADDR: hostname or IP address of the core device

Named Arguments

--simulation: Simulation - does not connect to device
-s, --drtio-dest: specifies the DRTIO destination

verbosity

-v, --verbose: increase logging level
-q, --quiet: decrease logging level

network server

--bind: additional hostname or IP address to bind to; use ‘*’ to bind to all interfaces (default: [])
--no-localhost-bind: do not implicitly also bind to localhost addresses
-p, --port: TCP port to listen on (default: 1068)