mirny: add build and flashing instructions

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,48 @@
 }
 ```
 
+## Building firmware
+
+Once you get your hands on the firmware, you will need to work around few shortcomings of Nix, mainly not being able to run dynamically linked executables.
+
+You will need:
+- Xilinx ISE installed on your system,
+- an environment with Migen.
+
+One way to do it is to create an FHS environment, like ARTIQ does for Vivado, within ARTIQ (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
+cd ../mirny  # or wherever your source is at
+source /opt/Xilinx/14.7/ISE_DS/settings64.sh
+python mirny_impl.py
+```
+
+### Flashing
+
+```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 +91,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 +139,6 @@ 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.2+ support, CPLD firmware above 0.3.0 (with fixes) must be flashed onto Mirny.

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.