Add clocking and device_db guides

Signed-off-by: Egor Savkin <es@m-labs.hk>
This commit is contained in:
Egor Savkin 2023-10-27 17:34:43 +08:00
parent ba8f21d9c2
commit c5d48d2e2f
4 changed files with 92 additions and 0 deletions

View File

@ -24,3 +24,5 @@
- [UART Logs](./sw_sup/uart_logs.md) - [UART Logs](./sw_sup/uart_logs.md)
- [Flashing the Firmware](./sw_sup/flashing_firmware.md) - [Flashing the Firmware](./sw_sup/flashing_firmware.md)
- [Moninj](./sw_sup/moninj.md) - [Moninj](./sw_sup/moninj.md)
- [Clocking](sw_sup/clocking.md)
- [device_db.py](sw_sup/device_db.md)

View File

@ -1 +1,2 @@
ip=192.168.1.75 ip=192.168.1.75
rtio_clock=int_125

68
src/sw_sup/clocking.md Normal file
View File

@ -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.

21
src/sw_sup/device_db.md Normal file
View File

@ -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
```