doc: Edit of manual reference pages (#2466)

Co-authored-by: architeuthis <[email protected]>

artiq/frontend/artiq_client.py

@@ -40,10 +40,10 @@ def get_argparser():
     parser = argparse.ArgumentParser(description="ARTIQ CLI client")
     parser.add_argument(
         "-s", "--server", default="::1",
-        help="hostname or IP of the master to connect to")
+        help="hostname or IP of the master to connect to (default: %(default)s)")
     parser.add_argument(
         "--port", default=None, type=int,
-        help="TCP port to use to connect to the master")
+        help="TCP port to use to connect to the master (default: %(default)s)")
     parser.add_argument("--version", action="version",
                         version="ARTIQ v{}".format(artiq_version),
                         help="print the ARTIQ version number")
@@ -59,7 +59,8 @@ def get_argparser():
                             help="priority (higher value means sooner "
                                  "scheduling, default: %(default)s)")
     parser_add.add_argument("-t", "--timed", default=None, type=str,
-                            help="set a due date for the experiment")
+                            help="set a due date for the experiment "
+                            "(default: %(default)s)")
     parser_add.add_argument("-f", "--flush", default=False,
                             action="store_true",
                             help="flush the pipeline before preparing "

artiq/frontend/artiq_dashboard.py

@@ -32,31 +32,28 @@ def get_argparser():
                         help="print the ARTIQ version number")
     parser.add_argument(
         "-s", "--server", default="::1",
-        help="hostname or IP of the master to connect to")
-    parser.add_argument(
-        "--port-notify", default=3250, type=int,
-        help="TCP port to connect to for notifications")
+        help="hostname or IP of the master to connect to (default: %(default)s)")
     parser.add_argument(
         "--port-control", default=3251, type=int,
-        help="TCP port to connect to for control")
+        help="TCP port to connect to for control (default: %(default)s)")
     parser.add_argument(
         "--port-broadcast", default=1067, type=int,
-        help="TCP port to connect to for broadcasts")
+        help="TCP port to connect to for broadcasts (default: %(default)s)")
     parser.add_argument(
         "--db-file", default=None,
-        help="database file for local GUI settings")
+        help="database file for local GUI settings (default: %(default)s)")
     parser.add_argument(
         "-p", "--load-plugin", dest="plugin_modules", action="append",
         help="Python module to load on startup")
     parser.add_argument(
         "--analyzer-proxy-timeout", default=5, type=float,
-        help="connection timeout to core analyzer proxy")
+        help="connection timeout to core analyzer proxy (default: %(default)s)")
     parser.add_argument(
         "--analyzer-proxy-timer", default=5, type=float,
-        help="retry timer to core analyzer proxy")
+        help="retry timer to core analyzer proxy (default: %(default)s)")
     parser.add_argument(
         "--analyzer-proxy-timer-backoff", default=1.1, type=float,
-        help="retry timer backoff multiplier to core analyzer proxy")
+        help="retry timer backoff multiplier to core analyzer proxy, (default: %(default)s)")
     common_args.verbosity_args(parser)
     return parser
 

artiq/frontend/artiq_ddb_template.py

@@ -833,7 +833,7 @@ def process(output, primary_description, satellites):
         processor(peripheral)
 
 
-def main():
+def get_argparser(): 
     parser = argparse.ArgumentParser(
         description="ARTIQ device database template builder")
     parser.add_argument("--version", action="version",
@@ -847,8 +847,11 @@ def main():
                         default=[], metavar=("DESTINATION", "DESCRIPTION"), type=str,
                         help="add DRTIO satellite at the given destination number with "
                              "devices from the given JSON description")
+    return parser
+
 
-    args = parser.parse_args()
+def main():
+    args = get_argparser().parse_args()
 
     primary_description = jsondesc.load(args.primary_description)
 

artiq/frontend/artiq_flash.py

@@ -30,7 +30,8 @@ def get_argparser():
     * firmware: write firmware to flash
     * load: load main gateware bitstream into device (volatile but fast)
     * erase: erase flash memory
-    * start: trigger the target to (re)load its gateware bitstream from flash
+    * start: trigger the target to (re)load its gateware bitstream from flash.
+      If your core device is reachable by network, prefer 'artiq_coremgmt reboot'. 
 
 Prerequisites:
 

artiq/frontend/artiq_master.py

@@ -40,21 +40,21 @@ def get_argparser():
 
     group = parser.add_argument_group("databases")
     group.add_argument("--device-db", default="device_db.py",
-                       help="device database file (default: '%(default)s')")
+                       help="device database file (default: %(default)s)")
     group.add_argument("--dataset-db", default="dataset_db.mdb",
-                       help="dataset file (default: '%(default)s')")
+                       help="dataset file (default: %(default)s)")
 
     group = parser.add_argument_group("repository")
     group.add_argument(
         "-g", "--git", default=False, action="store_true",
-        help="use the Git repository backend")
+        help="use the Git repository backend (default: %(default)s)")
     group.add_argument(
         "-r", "--repository", default="repository",
-        help="path to the repository (default: '%(default)s')")
+        help="path to the repository (default: %(default)s)")
     group.add_argument(
         "--experiment-subdir", default="",
         help=("path to the experiment folder from the repository root "
-              "(default: '%(default)s')"))
+              "(default: %(default)s)"))
     log_args(parser)
 
     parser.add_argument("--name",

doc/manual/core_device.rst

@@ -8,9 +8,77 @@ While it is possible to use the other parts of ARTIQ (controllers, master, GUI,
 .. _core-device-flash-storage:
 
 Flash storage
-^^^^^^^^^^^^^
-
-The core device contains some flash storage space which is used to store configuration data. It is one sector (typically 64 kB) large and organized as a list of key-value records, accessible by using ``artiq_coremgmt`` (see :ref:`core-device-management-tool`). The core device IP and MAC addresses, as well as, if present, the startup and/or idle kernels (see :ref:`miscellaneous_config_core_device`) are stored here. 
+-------------
+
+The core device contains some flash storage space which is used to store configuration data and the idle/startup kernels. It is one sector (typically 64 kB) large and organized as a list of key-value records, accessible either through ``artiq_mkfs`` and ``artiq_flash`` or (preferable in most cases) the ``config`` option of the ``artiq_coremgmt`` core management tool (see below). Information can be stored to keys of any name, but the specific keys currently used and referenced by ARTIQ are summarized below:
+
+``idle_kernel``
+  Stores (compiled ``.tar`` or ``.elf`` binary of) idle kernel. See :ref:`miscellaneous_config_core_device`. 
+``startup_kernel``
+  Stores (compiled ``.tar`` or ``.elf`` binary of) startup kernel. See :ref:`miscellaneous_config_core_device`.
+``ip`` 
+  Sets IP address of core device. For this and other networking options see also :ref:`core-device-networking`.
+``mac``
+  Sets MAC address of core device. Unnecessary on Kasli or Kasli-SoC, which can obtain it from EEPROM. 
+``ipv4_default_route``
+  Sets IPv4 default route. 
+``ip6``
+  Sets IPv6 address of core device. Can be set irrespective of and used simultaneously as IPv4 address above.
+``ipv6_default_route``
+  Sets IPv6 default route.
+``sed_spread_enable``
+  If set to ``1``, will activate :ref:`sed-event-spreading` in this core device. Needs to be set separately for satellite devices in a DRTIO setting.
+``log_level``
+  Sets core device log level. Possible levels are ``TRACE``, ``DEBUG``, ``INFO``, ``WARN``, ``ERROR``, and ``OFF``. Note that enabling higher log levels will produce some core device slowdown.
+``uart_log_level``
+  Sets UART log level, with same options. Printing a large number of messages to UART log will produce a significant slowdown. 
+``rtio_clock``
+  Sets the RTIO clock; see :ref:`core-device-clocking`.
+``routing_table``
+  Sets the routing table in DRTIO systems; see :ref:`drtio-routing`. If not set, a star topology is assumed.
+``device_map``
+  If set, allows the core log to connect RTIO channels to device names and use device names as well as channel numbers in log output. A correctly formatted table can be automatically generated with ``artiq_rtiomap``, see :ref:`Utilities<rtiomap-tool>`.
+``net_trace``
+  If set to ``1``, will activate net trace (print all packets sent and received to UART and core log). This will considerably slow down all network response from the core. Not applicable for ARTIQ-Zynq (Kasli-SoC, ZC706).
+``panic_reset`` 
+  If set to ``1``, core device will restart automatically.  Not applicable for ARTIQ-Zynq.
+``no_flash_boot``
+  If set to ``1``, will disable flash boot. Network boot is attempted if possible. Not applicable for ARTIQ-Zynq.
+``boot``
+  Allows full firmware/gateware (``boot.bin``) to be written with ``artiq_coremgmt``, on ARTIQ-Zynq systems only.
+
+Common configuration commands
+-----------------------------
+
+To write, then read, 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 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'
+
+You can write several records at once::
+
+  $ artiq_coremgmt config write -s key1 value1 -f key2 filename -s key3 value3
+
+You can also write entire files in a record using the ``-f`` option. This is useful for instance to write the startup and idle kernels into the flash storage::
+
+    $ artiq_coremgmt config write -f idle_kernel idle.elf
+    $ artiq_coremgmt config read idle_kernel | head -c9
+    b'\x7fELF
+
+The same option is used to write ``boot.bin`` in ARTIQ-Zynq. Note that the ``boot`` key is write-only. 
+
+See also the full reference of ``artiq_coremgmt`` in :ref:`Utilities <core-device-management-tool>`.
+
+Board details 
+-------------
 
 FPGA board ports
 ^^^^^^^^^^^^^^^^
@@ -32,20 +100,20 @@ KC705
 An alternative target board for the ARTIQ core device is the KC705 development board from Xilinx. It supports the NIST CLOCK and QC2 hardware (FMC).
 
 Common problems
----------------
+^^^^^^^^^^^^^^^
 
 * The SW13 switches on the board need to be set to 00001.
 * When connected, the CLOCK adapter breaks the JTAG chain due to TDI not being connected to TDO on the FMC mezzanine.
 * On some boards, the JTAG USB connector is not correctly soldered.
 
 VADJ
-----
+""""
 
 With the NIST CLOCK and QC2 adapters, for safe operation of the DDS buses (to prevent damage to the IO banks of the FPGA), the FMC VADJ rail of the KC705 should be changed to 3.3V. Plug the Texas Instruments USB-TO-GPIO PMBus adapter into the PMBus connector in the corner of the KC705 and use the Fusion Digital Power Designer software to configure (requires Windows). Write to chip number U55 (address 52), channel 4, which is the VADJ rail, to make it 3.3V instead of 2.5V.  Power cycle the KC705 board to check that the startup voltage on the VADJ rail is now 3.3V.
 
 
 NIST CLOCK
-----------
+^^^^^^^^^^
 
 With the CLOCK hardware, the TTL lines are mapped as follows:
 
@@ -89,7 +157,7 @@ The DDS bus is on channel 27.
 
 
 NIST QC2
---------
+^^^^^^^^
 
 With the QC2 hardware, the TTL lines are mapped as follows:
 
@@ -135,7 +203,7 @@ See :mod:`artiq.coredevice.i2c` for more details.
 .. _core-device-clocking:
 
 Clocking
-^^^^^^^^
+--------
 
 The core device generates the RTIO clock using a PLL locked either to an internal crystal or to an external frequency reference. If choosing the latter, external reference must be provided (via front panel SMA input on Kasli boards). Valid configuration options include: