Merge branch 'master' into shuttler_efc

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,57 @@
 }
 ```
 
+## 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).
+
+### 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 +100,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 +148,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 0.3.1+ (with fixes) must be flashed onto Mirny.