From e67bcfb36e6029a7adcb1e86f8e83b00acaa11c6 Mon Sep 17 00:00:00 2001 From: architeuthidae Date: Mon, 22 Jul 2024 14:54:29 +0800 Subject: [PATCH] doc: Add links for ddb_template and afws_client --- doc/manual/environment.rst | 2 +- doc/manual/flashing.rst | 2 +- doc/manual/utilities.rst | 4 ++++ 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/manual/environment.rst b/doc/manual/environment.rst index 2da039eec..ba16bcf5d 100644 --- a/doc/manual/environment.rst +++ b/doc/manual/environment.rst @@ -43,7 +43,7 @@ Note that the key (the name of the device) is ``led`` and the value is itself a Adding or removing new real-time hardware is a difference in *system configuration,* which must be specified at compilation time of gateware and firmware. For Kasli and Kasli-SoC, this is managed in the form of a JSON usually called the *system description* file. The device database generally provides that information to ARTIQ which can change from instance to instance ARTIQ is run, e.g., device names and aliases, network addresses, clock frequencies, and so on. The system configuration defines that information which is *not* permitted to change, e.g., what device is associated with which EEM port or RTIO channels. Insofar as data is duplicated between the two, the device database is obliged to agree with the system description, not the other way around. -If you obtain your hardware from M-Labs, you will always be provided with a ``device_db.py`` to match your system configuration, which you can edit as necessary to add remote devices, aliases, and so on. In the relatively unlikely case that you are writing a device database from scratch, the ``artiq_ddb_template`` utility can be used to generate a template device database directly from the JSON system description used to compile your gateware and firmware. This is the easiest way to ensure that details such as the allocation of RTIO channel numbers will be represented in the device database correctly. +If you obtain your hardware from M-Labs, you will always be provided with a ``device_db.py`` to match your system configuration, which you can edit as necessary to add remote devices, aliases, and so on. In the relatively unlikely case that you are writing a device database from scratch, the ``artiq_ddb_template`` utility can be used to generate a template device database directly from the JSON system description used to compile your gateware and firmware. This is the easiest way to ensure that details such as the allocation of RTIO channel numbers will be represented in the device database correctly. See also the corresponding entry in :ref:`Utilities `. Local devices ^^^^^^^^^^^^^ diff --git a/doc/manual/flashing.rst b/doc/manual/flashing.rst index 316d50620..221185b1d 100644 --- a/doc/manual/flashing.rst +++ b/doc/manual/flashing.rst @@ -15,7 +15,7 @@ Run the command:: $ afws_client build -Replace ```` with the login name that was given to you with the subscription, ```` with the name of your system variant, and ```` with the name of an empty directory, which will be created by the command if it does not exist. Enter your password when prompted and wait for the build (if applicable) and download to finish. If you experience issues with the AFWS client, write to the helpdesk@ email. +Replace ```` with the login name that was given to you with the subscription, ```` with the name of your system variant, and ```` with the name of an empty directory, which will be created by the command if it does not exist. Enter your password when prompted and wait for the build (if applicable) and download to finish. If you experience issues with the AFWS client, write to the helpdesk@ email. For more information about ``afws_client`` see also the corresponding entry on the :ref:`Utilities ` page. For certain configurations (KC705 or ZC706 only) it is also possible to source firmware from `the M-Labs Hydra server `_ (in ``main`` and ``zynq`` respectively). diff --git a/doc/manual/utilities.rst b/doc/manual/utilities.rst index ae1bec0f0..7abfeaaaa 100644 --- a/doc/manual/utilities.rst +++ b/doc/manual/utilities.rst @@ -4,6 +4,8 @@ Utilities .. Sort these tool by some subjective combination of their typical sequence and expected frequency of use. +.. _afws-client: + ARTIQ Firmware Service (AFWS) client ------------------------------------ @@ -74,6 +76,8 @@ Core device logging controller :prog: aqctl_corelog :nodefault: +.. _ddb-template-tool: + Device database template generator ----------------------------------