doc: Mention artiq_ddb_template in Environment manual page

doc/manual/environment.rst

@@ -8,21 +8,19 @@ ARTIQ experiments exist in an environment, which consists of devices, arguments,
 The device database
 -------------------
 
-Information about available devices is provided to ARTIQ through a file called the device database. It is generated by a Python script typically called ``device_db.py``, which many of the ARTIQ front-end tools require access to in order to run. The device database specifies: 
+Information about available devices is provided to ARTIQ through a file called the device database, typically called ``device_db.py``, which many of the ARTIQ front-end tools require access to in order to run. The device database specifies: 
 
     * what devices are available to an ARTIQ installation 
     * what drivers to use 
     * what controllers to use
     * how and where to contact each device, i.e. 
 
-      - at which RTIO channel each local device can be reached 
+      - at which RTIO channel(s) each local device can be reached 
       - at which network address each controller can be reached 
 
 as well as, if present, how and where to contact the core device itself (e.g., its IP address, often by a field named ``core_addr``). 
 
-This is stored in a Python dictionary whose keys are the device names, which the script must define as a global variable with the name ``device_db``. Examples for various system configurations can be found inside the subfolders of ``artiq/examples``.
-
-A typical device database entry looks like this: :: 
+This is stored in a Python dictionary whose keys are the device names, which the file must define as a global variable with the name ``device_db``. Examples for various system configurations can be found inside the subfolders of ``artiq/examples``. A typical device database entry looks like this: :: 
 
     "led": {
         "type": "local",
@@ -39,23 +37,27 @@ Note that the key (the name of the device) is ``led`` and the value is itself a
 .. warning:: 
     It is important to understand that the device database does not *set* your system configuration, only *describe* it. If you change the devices available to your system, it is usually necessary to edit the device database, but editing the database will not change what devices are available to your system. 
 
-    Remote (normally, non-realtime) devices must have accessible, suitable controllers and drivers; see :doc:`developing_a_ndsp` for more information, including how to add entries for new remote devices to your device database. Local devices (normally, realtime, e.g. your Sinara hardware) must be factually attached to your system, and more importantly, your gateware and firmware must have been compiled to account for them. 
+    Remote (normally, non-realtime) devices must have accessible, suitable controllers and drivers; see :doc:`developing_a_ndsp` for more information, including how to add entries for new remote devices to your device database. Local devices (normally, realtime, e.g. your Sinara hardware) must be factually attached to your system, and more importantly, your gateware and firmware must have been compiled to account for them, and to expect them at those ports. 
     
-    While controllers can be added and removed to your device database relatively easily, in order to make new real-time hardware accessible, it is often necessary to recompile and reflash your gateware and firmware. (If you purchase your hardware from M-Labs, you will generally be provided with new binaries and necessary assistance.) 
+    While controllers can be added and removed to your device database relatively easily, in order to make new real-time hardware accessible, it is generally also necessary to recompile and reflash your gateware and firmware. (If you purchase your hardware from M-Labs, you will generally be provided with new binaries and necessary assistance.) 
 
-    In other words, adding new real-time hardware is a difference in *system configuration,* which is specified by the JSON system description file used in compilation of gateware and firmware. 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 file provides that information which is *not* permitted to change, e.g. what device is associated with what RTIO channel. Insofar as data is duplicated between the two, the device database is obliged to agree with the system description, not the other way around. 
+    Adding (or removing) new real-time hardware is a difference in *system configuration,* which is specified by the JSON system description file used in compilation of gateware and firmware. 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 file defines that information which is *not* permitted to change, e.g. what device is associated with which EEM port. Insofar as data is duplicated between the two, the device database is obliged to agree with the system description file, 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 file 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. 
+    
 Local devices
 ^^^^^^^^^^^^^
 
 Local device entries are dictionaries which contain a ``type`` field set to ``local``. They correspond to device drivers that are created locally on the master as opposed to using the controller mechanism; this is normally the real-time hardware of the system, including the core, which is itself considered a local device. The ``led`` example above is a local device entry. 
 
-The fields ``module`` and ``class`` determine the location of the Python class of the driver. The ``arguments`` field is another (possibly empty) dictionary that contains arguments to pass to the device driver constructor. ``arguments`` is often used to specify the RTIO channel number of a peripheral, which must match the channel number in gateware (i.e., in the system description file). 
+The fields ``module`` and ``class`` determine the location of the Python class of the driver. The ``arguments`` field is another (possibly empty) dictionary that contains arguments to pass to the device driver constructor. ``arguments`` is often used to specify the RTIO channel number of a peripheral, which must match the channel number in gateware. 
+
+The allocation of RTIO channels to EEM ports is done automatically when the gateware is compiled, and while conceptually simple (channels are assigned one after the other, from zero upwards, for each device entry in the system description file) it is not entirely straightforward (different devices require different numbers of RTIO channels). Again, the easiest way to handle this when writing a new device database is automatically, using ``artiq_ddb_template``.
 
 Controllers
 ^^^^^^^^^^^
 
-Controller entries are dictionaries which contain a ``type`` field set to ``controller``. When an experiment requests such a device, a RPC client (see ``sipyco.pc_rpc``) is created and connected to the appropriate controller. Controller entries are also used by controller managers to determine what controllers to run. For an example, see :ref:`ndsp-integration`.
+Controller entries are dictionaries which contain a ``type`` field set to ``controller``. When an experiment requests such a device, a RPC client (see ``sipyco.pc_rpc``) is created and connected to the appropriate controller. Controller entries are also used by controller managers to determine what controllers to run. For an example, see :ref:`the NDSP development page <ndsp-integration>`.
 
 The ``host`` and ``port`` fields configure the TCP connection. The ``target`` field contains the name of the RPC target to use (you may use ``sipyco_rpctool`` on a controller to list its targets). Controller managers run the ``command`` field in a shell to launch the controller, after replacing ``{port}`` and ``{bind}`` by respectively the TCP port the controller should listen to (matches the ``port`` field) and an appropriate bind address for the controller's listening socket.
 
@@ -87,7 +89,7 @@ Datasets and units
 
 Datasets accept metadata for numerical formatting with the ``unit``, ``scale`` and ``precision`` parameters of ``set_dataset``. 
 
-.. warning:: 
+.. note:: 
     In experiment code, values are assumed to be in the SI base unit. Setting a dataset with a value of ``1000`` and the unit ``kV`` represents the quantity ``1 kV``. It is recommended to use the globals defined by :mod:`artiq.language.units` and write ``1*kV`` instead of ``1000`` for the value. 
     
     In dashboards and clients these globals are not available. However, setting a dataset with a value of ``1`` and the unit ``kV`` simply represents the quantity ``1 kV``.