mirny: add legacy almazny firmware

Signed-off-by: Egor Savkin <es@m-labs.hk>

README.md

@@ -33,7 +33,9 @@ Tips for adding hardware instructions:
    for images with transparent background)
 3. Add link to the new chapter to the `src/SUMMARY.md`
 4. Do not forget to tell about all hidden/non-obvious obstacles and pitfalls
-5. Add testing steps, even the "obvious" ones
-6. Add JSON sample if needed
-7. Add hardware setup (e.g. pins, switches) steps if needed
-8. View changed and added pages with `mdbook build` (see building instructions above)
+5. Avoid using uncommon, complex, or hard-to-understand words, phrases, or grammar (e.g., ❌constituent -> ✔️component).
+   Keep in mind that these guides may be used by people with different backgrounds and levels of English proficiency.
+6. Add testing steps, even the "obvious" ones
+7. Add JSON sample if needed
+8. Add hardware setup (e.g. pins, switches) steps if needed
+9. View changed and added pages with `mdbook build` (see building instructions above)

src/hw/mirny_almazny.md

@@ -15,6 +15,59 @@
 }
 ```
 
+## Getting the firmware
+
+Here is [Mirny 0.3.1 firmware](../extra/mirny/mirny-0.3.1.zip). It contains a single ``.jed`` file that can be flashed following [flashing instructions](#flashing). This firmware supports Almazny v1.2+.
+
+If you are using a legacy Almazny (v1.0-1.1), due to different signals routed, you need to flash the older [0.2.4 firmware with Almazny support](../extra/mirny/mirny_0.2.4_legacy_almazny.zip).
+
+### Building firmware (optional)
+
+However, if you need to make chances or build from source, follow these instructions.
+
+Once you get your hands on the firmware source code, you will need to work around few shortcomings of Nix, mainly not being able to run dynamically linked executables.
+
+You will need:
+- Xilinx ISE 14.7 installed on your system (this guide is assuming ``/opt/Xilinx`` path),
+- an environment with Migen.
+
+One way to do it is to create an FHS environment, like ARTIQ does for Vivado, within ARTIQ's ``flake.nix`` (to leverage Migen already being there), by adding these lines:
+
+```
+iseEnv = pkgs.buildFHSEnv {
+  name = "ise-env";
+  targetPkgs = vivadoDeps;
+};
+
+ise = pkgs.buildFHSEnv {
+  name = "ise";
+  targetPkgs = vivadoDeps;
+  profile = "set -e; source /opt/Xilinx/14.7/ISE_DS/settings64.sh";
+  runScript = "ise";
+};
+```
+
+Add them below ``vivadoEnv``. Then add ``iseEnv`` and ``ise`` to the dev shell's build inputs. Call ``nix develop`` on that.
+
+Then you can build Mirny:
+
+```shell
+nix develop
+ise-env
+cd ../mirny  # or wherever your source is at
+source /opt/Xilinx/14.7/ISE_DS/settings64.sh
+python mirny_impl.py
+```
+
+### Flashing
+
+For flashing, you will need Xilinx ISE 14.7 installed on your system (here assuming ``/opt/Xilinx`` path), and ``xc3sprog`` with the appropriate HS2 JTAG adapter.
+
+```shell
+nix-shell -p xc3sprog
+xc3sprog -c jtaghs2 -m /opt/Xilinx/14.7/ISE_DS/ISE/xbr/data -v build/mirny.jed
+```
+
 ## Testing
 
 ### Without Almazny
@@ -49,7 +102,7 @@ After running `artiq_sinara_test`:
 
 ![](../img/mirny_gqrx.png)
 
-### With Almazny
+### With Almazny (ARTIQ 7)
 
 At first, `artiq_sinara_test` will prompt you for testing Mirnies as the would be without Almazny.
 After that, it will prompt you with testing the Almazny:
@@ -97,4 +150,8 @@ You should also see differences in various modes, but that may require disabling
 
 ### Tips
 
-Mirnies often fail `ValueError: MUXOUT not high`, in that case restart the tests or reboot the board(s).
+~~Mirnies often fail `ValueError: MUXOUT not high`, in that case restart the tests or reboot the board(s).~~ - fixed in [9569cfb](https://github.com/m-labs/artiq/commit/9569cfb26329c0acdc1705d3256d2506b7bccce5)
+
+For Almazny v1.0 and 1.1 support, CPLD firmware 0.2.4 (linked above) must be flashed onto Mirny.
+
+For Almazny v1.2+ support, CPLD firmware 0.3.1+ (with fixes) must be flashed onto Mirny.

src/hw/stabilizer.md

@@ -10,9 +10,19 @@ EEM is used for power only, and it can be alternatively powered by 12V barrel ja
 
 Not present in the JSON.
 
-## Building
+## Getting the firmware
 
-Pick your poison - firmware version: older with Pounder support or newer with USB serial console - the first works with a hardcoded MQTT broker and (static or dynamic) IP address, the latter is configured like the booster - through a serial console.
+You can get the firmware from [Hydra](https://nixbld.m-labs.hk/jobset/mcu/mcu-contrib).
+
+* ``stabilizer-dual-iir`` supports Pounder v1.2 - probably you should flash this one,
+* ``stabilizer-dual-iir-pounder_v1_0`` supports Pounder 1.0 and 1.1 (legacy),
+* ``stabilizer-lockin`` is a different application which we do not usually flash.
+
+These all include changes to the mainline code to include Pounder telemetry.
+
+### Building (optional)
+
+Please keep in mind that the firmware from the official Quartiq repository does not include support for Pounder in MQTT, you may need to use a fork for that. But if the stabilizer is without a Pounder, it's also a valid option.
 
 There is no Nix Flake support to make things easier, so you need to set up rust and cargo manually. Start with cloning the stabilizer repository and opening a new shell with dfu-util (for flashing) and rustup (for building).
 
@@ -30,27 +40,18 @@ rustup update
 rustup default stable
 ```
 
-Building the older version:
-
-```
-BROKER="MQTT BROKER IP" cargo build --release
-BROKER="MQTT BROKER IP" cargo objcopy --release --bin dual-iir -- -O binary dual-iir.bin
-```
-
-Building the newer version:
+Building:
 
 ```
 cargo build --release
 cargo objcopy --release --bin dual-iir -- -O binary dual-iir.bin
 ```
 
-The newer version must be configured with USB console later (try ``help`` command first).
-
 ## Flashing
 
-Once you have the binary (either built, or received from someone), you can now flash it.
+Once you have the binary, you can now flash it.
 
-Without firmware on the device or with older firmware, you need to use the jumper method:
+Without firmware on the device or with older firmware (without USB serial console), you need to use the jumper method:
 
 1. Have the Stabilizer disconnected from power.
 2. Use a jumper of some sort to short BOOT pins on the board.
@@ -75,9 +76,11 @@ dfu-util -a 0 -s 0x08000000:leave -R -D dual-iir.bin
 
 7. Look for "File downloaded successfully".
 
+For normal usage, the stabilizer must be configured with USB console later (try ``help`` command first), to set its IP address and MQTT broker address. However, for general testing (like the one below), you don't need to configure it any further.
+
 ## Testing
 
-1. Ensure that the [firmware](https://github.com/quartiq/stabilizer) has been flashed onto the Stabilizer
+1. Ensure that the [firmware](#getting-the-firmware) has been flashed onto the Stabilizer
 2. Turn on the crate/Stabilizer via EEM cable or power supply
 3. Set up the signal generator for an amplitude of 1V, frequency of 10kHz, and a sine wave
 4. Use the splitter to connect the generator's output to ADC0 and to the oscilloscope (refer to the picture below)

src/hw/zotino_fastino.md

@@ -72,3 +72,7 @@ You can flash the gateware with a Kasli/Kasli-SoC, be it in the crate or standal
 5. Run `nix-shell -p python311Packages.pyftdi`.
 6. Run `cd kasli-i2c; python flash_fastino.py 0 EEM<number> write fastino.bin` where `<number>` is the EEM port number on the Kasli/Kasli-SoC side.
 7. If PG and FD LEDs are lit green, the Fastino is ready.
+
+### Fastino output is 10V
+
+Fastinos by default after power up output 10V on all channels if not driven by the test otherwise. Make sure the EEM ports are specified correctly in the JSON and the EEM cable is connected to EEM0 on the Fastino.

src/sw_sup/drtio.md

@@ -45,3 +45,9 @@ During the connection, the clock signal is being distributed, effectively making
 * Wrong setups - master to master, standalone to standalone. Messing up with SFP ports generally makes it unusable,
   but the connection should be established in most cases.
 * The fiber adapters are not symmetrical - if one end has 1270/1330 label, another one should be 1330/1270.
+
+
+### Master-satellite interrupted/unstable connection
+
+This often happens due to overheating issues. Check if the Kasli/SoC fans are working properly and
+try installing rack fans to increase the air flow.