m-labs · architeuthidae · Oct 24, 2024
diff --git a/doc/manual/building_developing.rst b/doc/manual/building_developing.rst
@@ -140,7 +140,7 @@ The parallel command does exist for ARTIQ-Zynq: ::
 
 but if you are building ARTIQ-Zynq without intention to change the source, it is not actually necessary to enter the development environment at all; Nix is capable of accessing the official flake remotely for the build itself, eliminating the requirement for any particular environment.
 
-This is equally possible for original ARTIQ, but not as useful, as the development environment (specifically the ``#boards`` shell) is still the easiest way to access the necessary tools for flashing the board. On the other hand, with Zynq, it is normally recommended to boot from SD card, which requires no further special tools. As long as you have a functioning Nix installation with flakes enabled, you can progress directly to the building instructions below.
+This is equally possible for original ARTIQ, but not as useful, as the development environment (specifically the ``#boards`` shell) is still the easiest way to access the necessary tools for flashing the board. On the other hand, Zynq boards can also be flashed by writing to the SD card directly, which requires no further special tools. As long as you have a functioning Nix/Vivado installation with flakes enabled, you can progress directly to the building instructions below.
 
 .. _building:
 
@@ -160,8 +160,9 @@ With KC705, use: ::
 
     $ python -m artiq.gateware.targets.kc705 -V <variant>
 
-This will create a directory ``artiq_kasli`` or ``artiq_kc705`` containing the binaries in a subdirectory named after your description file or variant. Flash the board as described in :ref:`writing-flash`, adding the option ``--srcbuild``, e.g., assuming your board is already connected by JTAG USB: ::
+This will create a directory ``artiq_kasli`` or ``artiq_kc705`` containing the binaries in a subdirectory named after your description file or variant. Flash the board as described in :ref:`writing-flash`, adding the option ``--srcbuild``, e.g., assuming your board is connected by network or JTAG USB respectively: ::
 
+    $ artiq_coremgmt flash --srcbuild artiq_<board>/<variant>
     $ artiq_flash --srcbuild [-t kc705] -d artiq_<board>/<variant>
 
 .. note::
@@ -203,7 +204,11 @@ or you can use the more direct version: ::
 
     to see the list of suitable build targets directly.
 
-Any of these commands should produce a directory ``result`` which contains a file ``boot.bin``. As described in :ref:`writing-flash`, if your core device is currently accessible over the network, it can be flashed with :mod:`~artiq.frontend.artiq_coremgmt`. If it is not connected to the network:
+Any of these commands should produce a directory ``result`` which contains a file ``boot.bin``. If your core device is accessible by network, flash with: ::
+
+    $ artiq_coremgmt flash --srcbuild result
+
+Otherwise:
 
 1. Power off the board, extract the SD card and load ``boot.bin`` onto it manually.
 2. Insert the SD card back into the board.
@@ -244,17 +249,11 @@ For Kasli-SoC:
     $ gateware/kasli_soc.py -g ../build/gateware <description.json>
     $ make TARGET=kasli_soc GWARGS="path/to/description.json" <fw-type>
 
-For ZC706:
+For ZC706 or EBAZ4205:
     ::
 
     $ gateware/zc706.py -g ../build/gateware -V <variant>
-    $ make TARGET=zc706 GWARGS="-V <variant>" <fw-type>
-
-For EBAZ4205:
-    ::
-
-    $ gateware/ebaz4205.py -g ../build/gateware -V <variant>
-    $ make TARGET=ebaz4205 GWARGS="-V <variant>" <fw-type>
+    $ make TARGET=<target> GWARGS="-V <variant>" <fw-type>
 
 where ``fw-type`` is ``runtime`` for standalone or DRTIO master builds and ``satman`` for DRTIO satellites. Both the gateware and the firmware will generate into the ``../build`` destination directory. At this stage, if supported, you can :ref:`boot from JTAG <zynq-jtag-boot>`; either of the ``*_run.sh`` scripts will expect the gateware and firmware files at their default locations, and the ``szl.elf`` bootloader is retrieved automatically.
 

diff --git a/doc/manual/configuring.rst b/doc/manual/configuring.rst
@@ -6,6 +6,9 @@ Networking and configuration
 Setting up core device networking
 ---------------------------------
 
+.. note::
+    Satellite core devices (in a DRTIO setting, see :doc:`using_drtio_subkernels`) do not support independent networking and this section does not apply to them. Follow the instructions on this page for your master core device, and proceed to :ref:`configuring-satellite` once your DRTIO routing table is established.
+
 For Kasli, insert a SFP/RJ45 transceiver (normally included with purchases from M-Labs and QUARTIQ) into the SFP0 port and connect it to an Ethernet port in your network. If the port is 10Mbps or 100Mbps and not 1000Mbps, make sure that the SFP/RJ45 transceiver supports the lower rate. Many SFP/RJ45 transceivers only support the 1000Mbps rate. If you do not have a SFP/RJ45 transceiver that supports 10Mbps and 100Mbps rates, you may instead use a gigabit Ethernet switch in the middle to perform rate conversion.
 
 You can also insert other types of SFP transceivers into Kasli if you wish to use it directly in e.g. an optical fiber Ethernet network. Kasli-SoC already directly features RJ45 10/100/1000 Ethernet.
@@ -130,3 +133,16 @@ Load the DRTIO routing table
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If you are using DRTIO and the default routing table (for a star topology) is not suitable to your needs, you will first need to prepare and load a different routing table. See :ref:`Using DRTIO <drtio-routing>`.
+
+.. _configuring-satellite:
+
+Configuring DRTIO satellites
+----------------------------
+
+Once your DRTIO routing table is established, any satellite devices can be accessed as normal using :mod:`~artiq.frontend.artiq_coremgmt`, e.g.: ::
+
+  $ artiq_coremgmt -s <destination_number> log
+
+The destination number corresponds to the number assigned to that satellite both in the device database and, earlier, in the system configuration file. See the notes in :ref:`drtio-routing` if you are not sure what destination number to use.
+
+It is also possible to set configuration values, reflash, or reboot the device. Notably, :ref:`event spreading <sed-event-spreading>` is a per-device setting considered particularly useful on satellites. Most other configuration settings, e.g. networking, clocking, will not be used in practice in a satellite context -- satellites do not support direct network connections and are always bound to the master's clock.
diff --git a/doc/manual/faq.rst b/doc/manual/faq.rst
@@ -60,13 +60,6 @@ Either reflash your core device with a newer version of ARTIQ (see :doc:`flashin
 
     Minor version mismatches are common, even in stable ARTIQ versions, but should not cause any issues. The ARTIQ release system ensures breaking changes are strictly limited to new release versions, or to the beta branch (which explicitly makes no promises of stability.) Updates that *are* applied to the stable version are usually bug fixes, documentation improvements, or other quality-of-life changes. As long as gateware and software are using the same stable release version of ARTIQ, even if there is a minor mismatch, no warning will be displayed.
 
-change configuration settings of satellite devices?
----------------------------------------------------
-
-Currently, it is not possible to reach satellites through ``artiq_coremgmt config``, although this is being worked on. On Kasli, use :class:`~artiq.frontend.artiq_mkfs` and :class:`~artiq.frontend.artiq_flash`; on Kasli-SoC, preload the SD card with a ``config.txt``, formatted as a list of ``key=value`` pairs, one per line.
-
-Don't worry about individually flashing idle or startup kernels. If your idle or startup kernel contains subkernels, it will automatically compile as a ``.tar``, which you only need to flash to the master.
-
 fix unreliable DRTIO master-satellite links?
 --------------------------------------------
 

diff --git a/doc/manual/flashing.rst b/doc/manual/flashing.rst
@@ -78,29 +78,25 @@ On Windows
 Writing the flash
 -----------------
 
-First ensure the board is connected to your computer. In the case of Kasli, the JTAG adapter is integrated into the Kasli board; for flashing (and debugging) you can simply connect your computer to the micro-USB connector on the Kasli front panel. For :ref:`Zynq devices <devices-table>`, which use :mod:`~artiq.frontend.artiq_coremgmt` to flash over network, an Ethernet connection and an IP address, supplied either with the ``-D`` option or in your :ref:`device database <device-db>`, are sufficient.
+If your device is already accessible over the network, all you need is an Ethernet connection and a correct IP address (supplied either with the ``-D`` option or in :ref:`your device database <device-db>`). ::
 
-For Kasli-SoC, ZC706 or EBAZ4205:
-    ::
+    $ artiq_coremgmt [-D IP_address] flash <afws_directory>
+    $ artiq_coremgmt [-D IP_address] reboot
 
-        $ artiq_coremgmt [-D IP_address] config write -f boot <afws_directory>/boot.bin
-        $ artiq_coremgmt reboot
+For Zynq devices (Kasli-SoC, ZC706 or EBAZ4205), if the device is not reachable due to corrupted firmware or networking problems, extract the SD card and copy ``boot.bin`` onto it manually.
 
-    If the device is not reachable due to corrupted firmware or networking problems, extract the SD card and copy ``boot.bin`` onto it manually.
+For Kasli or KC705, if the device is not reachable due to corrupted firmware or networking problems, connect the board directly to your computer by JTAG USB and use :mod:`~artiq.frontend.artiq_flash`, as follows: ::
 
-For Kasli:
-    ::
+        $ artiq_flash [-t kc705] -d <afws_directory>
 
-        $ artiq_flash -d <afws_directory>
+Note the micro-USB in the Kasli front panel. For KC705, the SW13 switches need to be set to 00001.
 
-For KC705:
-    ::
+Writing to satellite devices
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-        $ artiq_flash -t kc705 -d <afws_directory>
+Satellite devices can at any time be flashed directly through the SD card or :mod:`~artiq.frontend.artiq_flash`, as applicable. Satellite devices do not support individual networking and do not have IP addresses. If your DRTIO system is up and running and the routing table is in place, on the other hand, they can be flashed through the master's network connection: ::
 
-    The SW13 switches need to be set to 00001.
-
-Flashing over network is also possible for Kasli and KC705, assuming IP networking has already been set up. In this case, the ``-H HOSTNAME`` option is used; see the entry for :mod:`~artiq.frontend.artiq_flash` in the :ref:`Utilities <flashing-loading-tool>` reference.
+  $ artiq_coremgmt [-D IP_address] -s <destination_number> flash <afws_directory>
 
 .. _connecting-uart: