document how to build helloworld soc

README.rst

@@ -0,0 +1,41 @@
+HeavyX
+======
+
+A FPGA SoC framework embracing cutting-edge open source technologies (nMigen, Yosys, SymbiFlow, Minerva, Nix, Rust).
+
+"Hello World" SoC demo
+++++++++++++++++++++++
+
+Softcore RISC-V system-on-chip on the Lattice ECP5 Versa board, built with a 100% Verilog/VHDL-free and 100% open source toolchain. Runs a Rust "hello world" program.
+
+Use nixpkgs unstable (known to work with ae71c13). Check https://nixbld.m-labs.hk/project/fpga for the status of the build with other nixpkgs versions.
+
+Optional: set up the M-Labs key and binary substituter for Nix (otherwise Nix will recompile LLVM, rustc, etc. on your machine).
+Create the file ``~/.config/nix/nix.conf`` with the following contents:
+
+::
+
+  substituters = https://cache.nixos.org https://nixbld.m-labs.hk
+  trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= nixbld.m-labs.hk-1:5aSRVA5b320xbNvu30tqxVPXpld73bhtOeH6uAjRyHc=
+
+Run ``nix-build -A simplesoc_ecp5 release.nix``
+
+Bypass the ispCLOCK device using the jumpers on your board.
+
+Create a ``versa.cfg`` file with:
+
+::
+
+  interface ftdi
+  ftdi_vid_pid 0x0403 0x6010
+  ftdi_channel 0
+  ftdi_layout_init 0xfff8 0xfffb
+  reset_config none
+  adapter_khz 5000
+  jtag newtap ecp5 tap -irlen 8 -expected-id 0x01112043
+
+Load the bitstream ``openocd -f versa.cfg -c "transport select jtag; init; svf result/top.svf; exit"``.
+
+Watch the UART output at 115200bps.
+
+Questions, comments: https://forum.m-labs.hk/