posts/000001: fix confusing description about ext clk on Kasli

posts/000001.md

@@ -22,12 +22,13 @@ is_draft: true
 
 1. *All possible combinations of supported clock frequencies are defined in the [firmware](https://github.com/m-labs/artiq/blob/master/artiq/firmware/runtime/rtio_clocking.rs).*
 2. *For all controllers, the source clock signal always passes through several clock buffers. The table above only reflects the starting point, while the actual clock distribution system is more involved.*
-3. *For standalone or master variants that use Si5324 for clock synthesis, in absence of an external clock, the RTIO clock is generated from the crystal connected to Si5324 (at pins XA/XB). Si5324 would enter "Free Run" mode (see Section 6.5 of [Si53xx Reference Manual](https://www.silabs.com/documents/public/reference-manuals/si53xx-reference-manual.pdf)) to select the crystal as the input clock in place of CLKIN2.*
+3. *For standalone or master variants that use Si5324 for clock synthesis, if the firmware is configured to operate without external clocking, the RTIO clock is generated from the crystal connected to Si5324 (at pins XA/XB). Si5324 would enter "Free Run" mode (see Section 6.5 of [Si53xx Reference Manual](https://www.silabs.com/documents/public/reference-manuals/si53xx-reference-manual.pdf)) to select the crystal as the input clock in place of CLKIN2.*
 4. *For standalone or master variants that use Si5324 for clock synthesis, the conversion from the external clock to the RTIO clock involves the use of Si5324's internal PLL. This introduces two major non-deterministic side effects to external clocking on these systems:*
    - *There is additional phase noise at certain frequencies during the conversion (consult Section 3.3 of [Si5324 datasheet](https://www.silabs.com/documents/public/data-sheets/Si5324.pdf)).*
    - *On each reboot, the internal PLL needs to perform an internal self-calibration (ICAL), which introduces an input-to-output phase skew that is uncontrolled and random per calibration (consult Section 3.3 of [Si5324 datasheet](https://www.silabs.com/documents/public/data-sheets/Si5324.pdf)).*
 5. *For satellite variants that use Si5324 for clock distribution, the clock source is selected by the firmware at the [`SiPhaser`](https://github.com/m-labs/artiq/blob/master/artiq/gateware/drtio/siphaser.py) logic submodule based on the uplink status. For simplicity, the table above uses "external" and "internal" to indicate the presence and absence of an established uplink respectively. The internal clock source is fed to the FPGA's internal frequency synthesizer (e.g. Xilinx's MMCM), which produces a clock at the same frequency as the target RTIO frequency for clock alignment with uplink. The fully recovered clock is then fed to Si5324's CLKIN1 while it is in "Free Run" mode, producing a jitter-attenuated RTIO clock for DRTIO transceivers.*
 6. *In Kasli v1 and v2, there is a difference in the path connecting the external clock at the SMA connectors and the RTIO clock. In v1, the external clock is connected to Si5324's CLKIN2. In v2, the external clock goes through the FPGA's internal buffers and registers and is then forwarded to Si5324's CLKIN1.*
 7. *In a Kasli standalone or master variant, the RTIO clock must operate at 125 MHz. If the external clock is at 125 MHz, the firmware allows the user to bypass Si5324's internal PLL, and directly feed the external clock to the output buffers. The output RTIO clock signal will generally have reduced phase noise comparing with the output synthesized without bypassing. If the external clock is not equal to 125 MHz, it cannot be used to bypass Si5324 to create the RTIO clock.*
+   * *Note that toggling on and off the bypass mode is done with a configuration key `rtio_clock` in the storage area of the flash memory. This key **cannot** be used to determine whether or not the firmware can operate **without** external clocking. See the subsection in [#000002](./000002.html#rtio_clock) for details about setting `rtio_clock`.*
 8. *In a ZC705 standalone variant, clock generation is done by the PS (Processing System) of the Zynq-7000 SoC, which takes the on-board 33.3 MHz oscillator as the source (`PS_CLK`) and gives FCLKs (frequency-programmable clocks) to the PL (Programmable Logic, belonging to 7 series FPGA family). The RTIO frequency is generated within the PL.*
 

posts/000002.md

@@ -22,6 +22,7 @@ The following table shows the identifiers and input types for a non-exhasutive l
 | IPv6 address  | `ip6`           | String, in `w:x:y:z` format                                 |
 | Routing table | `routing_table` | Binary file, generated from `artiq_route `                  |
 | Idle kernel   | `idle_kernel`   | Binary file (in ELF format), generated from `artiq_compile` |
+| Clocking mode | `rtio_clock`    | String, one of: `i` ("internal"), `e` ("external")          |
 
 #### Preparing the routing table
 
@@ -44,6 +45,17 @@ $ artiq_compile <path-to-input-experiment-script> -o <path-to-output-elf>
 
 Note that the idle kernel loops until the controller exits the idle state. Consult [this manual section](https://m-labs.hk/artiq/manual-beta/utilities.html#static-compiler) for the usage of `artiq_compile`.
 
+#### Special notes on other settings
+
+##### <a id="rtio_clock">`rtio_clock`</a>
+
+This is a configuration key providing the mode of clock synthesis on the Si5324 chip (if present). Its value determines how the RTIO clock is generated from external clocking:
+
+* `i` (default value): The RTIO clock is an "internal" signal converted from the external clock at the Si5324.
+* `e`: The RTIO clock is fed directly from an "external" source at matching RTIO frequency, done by bypassing Si5324.
+
+This setting is effective only if the firmware is configured to operate with external clocking. If the firmware is configured to operate otherwise, since Si5324 must be used to convert the internal oscillator to the RTIO clock, `rtio_clock` is always effectively `i` ("internal"). See Note 7 of [#000001](./000001.html) for technical details of Si5324 bypass.
+
 ### Using `artiq_coremgmt` (with Ethernet connection)
 
 When you use `artiq_coremgmt` to write the settings to the flash memory on the controller, make sure that the device database file (e.g. `device_db.py`) and the input files for settings with **file**-type input are properly prepared (see sub-sections above). Then, follow the basic steps below to construct the command running `artiq_coremgmt`: