From c5d48d2e2f8111a0730ecfad15d1a51c47cca1bc Mon Sep 17 00:00:00 2001
From: Egor Savkin <es@m-labs.hk>
Date: Fri, 27 Oct 2023 17:34:43 +0800
Subject: [PATCH] Add clocking and device_db guides

Signed-off-by: Egor Savkin <es@m-labs.hk>
---
 src/SUMMARY.md          |  2 ++
 src/extra/CONFIG.TXT    |  1 +
 src/sw_sup/clocking.md  | 68 +++++++++++++++++++++++++++++++++++++++++
 src/sw_sup/device_db.md | 21 +++++++++++++
 4 files changed, 92 insertions(+)
 create mode 100644 src/sw_sup/clocking.md
 create mode 100644 src/sw_sup/device_db.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index 36189e7..ffb1c16 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -24,3 +24,5 @@
   - [UART Logs](./sw_sup/uart_logs.md)
   - [Flashing the Firmware](./sw_sup/flashing_firmware.md)
   - [Moninj](./sw_sup/moninj.md)
+  - [Clocking](sw_sup/clocking.md)
+  - [device_db.py](sw_sup/device_db.md)
\ No newline at end of file
diff --git a/src/extra/CONFIG.TXT b/src/extra/CONFIG.TXT
index 180275f..7aca184 100644
--- a/src/extra/CONFIG.TXT
+++ b/src/extra/CONFIG.TXT
@@ -1 +1,2 @@
 ip=192.168.1.75
+rtio_clock=int_125
diff --git a/src/sw_sup/clocking.md b/src/sw_sup/clocking.md
new file mode 100644
index 0000000..bc0cdc0
--- /dev/null
+++ b/src/sw_sup/clocking.md
@@ -0,0 +1,68 @@
+# Clocking
+
+This page describes ways to set up clocking. Official documentation references:
+
+* [Carrier configuration](https://m-labs.hk/artiq/manual/installing.html#miscellaneous-configuration-of-the-core-device)
+* Devices' [available options](https://m-labs.hk/artiq/manual/core_drivers_reference.html), [Urukul example](https://m-labs.hk/artiq/manual/core_drivers_reference.html#artiq.coredevice.urukul.CPLD)
+
+In general, any RF card and Carriers require some clock source. Most of them have both internal clock signal generator
+and external MMCX and/or SMA connectors to accept the signal. By default the internal clock is used for Carriers,
+and external MMCX is used for RF cards. However, internal clock may be not good enough for the end-user application,
+so the end-user may want to change the clock source at any time.
+
+## Kasli/Kasli-SoC
+
+For setting clocking on the Carriers you will just need to set `rtio_clock` in the core device config. Be aware, that
+setting any external clocking will require appropriate external clock signal to be supplied into `CLK IN` SMA connector
+on the front panel to boot. Therefore, firmware will be halted, the `ERR` LED will be red and **no Ethernet connection
+will be established**. Since the clock signal is distributed by DRTIO, there is generally no need in setting it up on
+satellites.
+
+If you have connection with the Carrier, you can use coremgmt command:
+
+```shell
+artiq_coremgmt config write -s rtio_clock <OPTION>
+```
+
+For available options refer to the official documentation (at the top of the page).
+
+### Setting clocking for Kasli without connection
+
+For RISC-V/legacy Kasli you will just need to connect your PC to the Kasli via _data_ micro-USB cable and run the
+following:
+
+```shell
+# you may also change IP setting here, the default is 192.168.1.75
+artiq_mkfs kasli.config -s ip xx.xx.xx.xx -s rtio_clock <OPTION> 
+# but don't forget to update `core_addr` variable in the device_db.py file if changed
+artiq_flash storage -f kasli.config
+```
+
+Be aware that all other settings will be **erased**, so you may need to restore them in the `artiq_mkfs` command.
+
+### Setting clocking for Kasli-SoC without connection
+
+For this you will need to eject micro-SD card from the Kasli-SoC, either
+by [removing the top panel](../img/rack_urukul_switch_access.jpg) or by gently pulling the Kasli-SoC from the crate,
+possibly with other cards. In any case, be cautious and follow
+the [warnings](../build_test_firmware.md#operating-hints-and-warnings). Once accessed the micro-SD card, simply
+add `rtio_clock=<OPTION>` on a new line to the existing `CONFIG.TXT` file and save it, or if it is absent, just download
+default-ish [CONFIG.TXT](../extra/CONFIG.TXT) to the SD card near (same level) `boot.bin` file.
+
+## RF Devices (Except Clocker)
+
+If you want to set the clock source specifically for RF devices, you will just need to update the JSON file and [regenerate device_db.py file](device_db.md).
+
+For example for Urukul, you will just need to check the manual for available variants and apply them in the JSON file, so Urukul entry may look like this:
+
+```json
+{
+  "type": "urukul", "dds": "ad9910", "ports": [1, 2], "refclk": 10e6, "clk_sel": 1
+}
+```
+
+So basically, `clk_sel` and `refclk` fields need to be set:
+* `clk_sel` selects the source clock, where 0 - internal 100MHz XO; 1 - front-panel SMA; 2 internal MMCX
+* `refclk` - reference clock frequency in Hz
+
+These settings may need to be checked with official manual and may differ from device to device.
\ No newline at end of file
diff --git a/src/sw_sup/device_db.md b/src/sw_sup/device_db.md
new file mode 100644
index 0000000..08eb97d
--- /dev/null
+++ b/src/sw_sup/device_db.md
@@ -0,0 +1,21 @@
+# device_db.py File
+
+`device_db.py` file contains the database of the devices and their respective interfaces within the firmware/gateware.
+It is generated from JSON description file and tied with the configuration and the gateware.
+
+## Generating the device_db.py File
+
+In some cases you may need to regenerate `device_db.py`, like switching clock source or changing the configuration.
+Also it is must-do in most cases once firmware/gateware is being updated (for example, when you add, move or remove EEM
+cards).
+Luckily, it is fairly easy to do. For standalone systems:
+
+```shell
+artiq_ddb_template -o device_db.py <standalone variant>.json
+```
+
+For DRTIO systems:
+
+```shell
+artiq_ddb_template -o device_db.py -s 1 <satellite1>.json -s 2 <satellite2>.json <...> -s N <satelliteN>.json <master>.json
+```