artiq/doc/manual/utilities.rst

189 lines
6.9 KiB
ReStructuredText
Raw Normal View History

2015-01-23 00:52:13 +08:00
Utilities
=========
2016-01-19 12:41:42 +08:00
.. Sort these tool by some subjective combination of their
typical sequence and expected frequency of use.
.. As in main_frontend_reference, automodule directives display nothing and are here to make :mod: links possible
.. _afws-client:
ARTIQ Firmware Service (AFWS) client
------------------------------------
.. automodule:: artiq.frontend.afws_client
2024-07-19 18:07:46 +08:00
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.
2024-07-19 18:07:46 +08:00
.. argparse::
:ref: artiq.frontend.afws_client.get_argparser
2024-07-19 18:07:46 +08:00
:prog: afws_client
:nodescription:
:nodefault:
passwd
.. 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@.
Static compiler
---------------
.. automodule:: artiq.frontend.artiq_compile
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.
.. argparse::
:ref: artiq.frontend.artiq_compile.get_argparser
:prog: artiq_compile
:nodescription:
2024-07-19 18:07:46 +08:00
:nodefault:
2015-04-30 20:03:11 +08:00
Flash storage image generator
-----------------------------
.. automodule:: artiq.frontend.artiq_mkfs
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.
2015-04-30 20:03:11 +08:00
.. argparse::
:ref: artiq.frontend.artiq_mkfs.get_argparser
:prog: artiq_mkfs
2024-07-19 18:07:46 +08:00
:nodescription:
:nodefault:
2024-07-19 18:07:46 +08:00
.. _flashing-loading-tool:
2016-01-19 12:41:42 +08:00
Flashing/Loading tool
---------------------
.. automodule:: artiq.frontend.artiq_flash
2024-08-13 15:47:27 +08:00
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 :mod:`~artiq.frontend.artiq_coremgmt`, directly copied onto the SD card, or (for developers) using the :ref:`ARTIQ netboot <zynq-jtag-boot>` utility.
2016-01-19 12:41:42 +08:00
.. argparse::
:ref: artiq.frontend.artiq_flash.get_argparser
:prog: artiq_flash
:nodescription:
2024-07-19 18:07:46 +08:00
:nodefault:
2016-01-19 12:41:42 +08:00
.. _core-device-management-tool:
Core device management tool
---------------------------
.. automodule:: artiq.frontend.artiq_coremgmt
2024-08-20 15:55:54 +08:00
The core management utility gives remote access to the core device logs, the :ref:`core device flash storage <configuration-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 :ref:`device database <device-db>`; otherwise, a device database file can be provided with ``--device-db`` or an address directly with ``--device`` (see also below).
.. argparse::
:ref: artiq.frontend.artiq_coremgmt.get_argparser
:prog: artiq_coremgmt
:nodescription:
2024-07-19 18:07:46 +08:00
:nodefault:
.. _ddb-template-tool:
Device database template generator
----------------------------------
.. automodule:: artiq.frontend.artiq_ddb_template
This tool generates a basic template for a :ref:`device database <device-db>` given the JSON description file(s) for the system. Entries for :ref:`controllers <environment-ctlrs>` are not generated.
2022-03-18 17:01:51 +08:00
.. argparse::
:ref: artiq.frontend.artiq_ddb_template.get_argparser
:prog: artiq_ddb_template
:nodescription:
2024-07-19 18:07:46 +08:00
:nodefault:
2022-03-18 17:01:51 +08:00
2022-12-02 16:27:03 +08:00
.. _rtiomap-tool:
RTIO channel name map tool
--------------------------
.. automodule:: artiq.frontend.artiq_rtiomap
2024-08-13 15:47:27 +08:00
This tool encodes the map of RTIO channel numbers to names in a format suitable for writing to the config key ``device_map``. See :ref:`config-rtiomap`.
2022-12-02 16:27:03 +08:00
.. argparse::
:ref: artiq.frontend.artiq_rtiomap.get_argparser
:prog: artiq_rtiomap
:nodescription:
2024-07-19 18:07:46 +08:00
:nodefault:
2022-03-18 17:01:51 +08:00
Core device RTIO analyzer tool
------------------------------
.. automodule:: artiq.frontend.artiq_coreanalyzer
2024-08-14 17:29:43 +08:00
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 :ref:`rtio-analyzer` for an example, or :mod:`artiq.test.coredevice.test_analyzer` for a relevant unit test.
Using the management system, the respective functionality is provided by :mod:`~artiq.frontend.aqctl_coreanalyzer_proxy` and the dashboard's 'Waveform' tab; see :ref:`interactivity-waveform`.
.. argparse::
:ref: artiq.frontend.artiq_coreanalyzer.get_argparser
:prog: artiq_coreanalyzer
2024-07-19 18:07:46 +08:00
:nodescription:
:nodefault:
2015-08-17 15:44:40 +08:00
.. _routing-table-tool:
DRTIO routing table manipulation tool
-------------------------------------
.. automodule:: artiq.frontend.artiq_route
This tool allows for manipulation of a DRTIO routing table file, which can be transmitted to the core device using :mod:`artiq_coremgmt config write<artiq.frontend.artiq_coremgmt>`; see :ref:`drtio-routing`.
.. argparse::
:ref: artiq.frontend.artiq_route.get_argparser
:prog: artiq_route
:nodescription:
:nodefault:
ARTIQ RTIO monitor
------------------
.. automodule:: artiq.frontend.artiq_rtiomon
2024-08-14 17:29:43 +08:00
Command-line interface for monitoring RTIO channels, as in the Monitor capacity of dashboard MonInj. See :ref:`interactivity-moninj`.
2024-08-13 15:47:27 +08:00
.. argparse::
:ref: artiq.frontend.artiq_rtiomon.get_argparser
:prog: artiq_rtiomon
2024-08-13 15:47:27 +08:00
:nodescription:
:nodefault:
2024-08-13 15:47:27 +08:00
.. _utilities-ctrls:
MonInj proxy
------------
.. automodule:: artiq.frontend.aqctl_moninj_proxy
.. argparse::
:ref: artiq.frontend.aqctl_moninj_proxy.get_argparser
:prog: aqctl_moninj_proxy
:nodefault:
2023-12-08 18:55:07 +08:00
Core device RTIO analyzer proxy
-------------------------------
.. automodule:: artiq.frontend.aqctl_coreanalyzer_proxy
2023-12-08 18:55:07 +08:00
.. argparse::
:ref: artiq.frontend.aqctl_coreanalyzer_proxy.get_argparser
:prog: aqctl_coreanalyzer_proxy
2024-07-19 18:07:46 +08:00
:nodefault:
2023-12-08 18:55:07 +08:00
Core device logging controller
------------------------------
.. automodule:: artiq.frontend.aqctl_corelog
.. argparse::
:ref: artiq.frontend.aqctl_corelog.get_argparser
:prog: aqctl_corelog
2024-08-13 15:47:27 +08:00
:nodefault: