Skip to content

Commit

Permalink
doc: Refactor coremgmt specifics to Core device page, list configs
Browse files Browse the repository at this point in the history
  • Loading branch information
architeuthis committed Jul 2, 2024
1 parent f17cabf commit 0100189
Showing 1 changed file with 113 additions and 8 deletions.
121 changes: 113 additions & 8 deletions doc/manual/core_device.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,114 @@ 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 in one or another form are summarized below:

+-----------------------+-----------------------------------------------------------+
| Key | Use |
+=======================+===========================================================+
| ``idle_kernel`` | Stores (compiled ``.elf`` binary of) idle kernel. See |
| | |
| | :ref:`miscellaneous_config_core_device`. |
+-----------------------+-----------------------------------------------------------+
| ``startup_kernel`` | Stores (compiled ``.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. |
+-----------------------+-----------------------------------------------------------+
| ``log_level`` | Sets core device log level. Possible levels are ``TRACE``,|
| | |
| | ``DEBUG``, ``INFO``, ``WARN`` and ``ERROR``. Note that |
| | |
| | enabling higher log levels will produce some core device |
| | |
| | slowdown. |
+-----------------------+-----------------------------------------------------------+
| ``uart_log_level`` | Sets UART log level, with same options. Printing many log |
| | |
| | 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, ZC705). |
+-----------------------+-----------------------------------------------------------+
| ``panic_reset`` | If set to ``1``, core device will restart automatically |
| | |
| | upon panic. 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. |
+-----------------------+-----------------------------------------------------------+

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 full reference of ``artiq_coremgmt`` can be found in :ref:`Utilities <core-device-management-tool>`.

Board details
-------------

.. _board-ports:

Expand All @@ -34,20 +139,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:

Expand Down Expand Up @@ -91,7 +196,7 @@ The DDS bus is on channel 27.


NIST QC2
--------
^^^^^^^^

With the QC2 hardware, the TTL lines are mapped as follows:

Expand Down Expand Up @@ -137,7 +242,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:

Expand Down

0 comments on commit 0100189

Please sign in to comment.