manual

doc/programmers_manual.md

@@ -125,6 +125,11 @@ made up of Yosys (synthesis) and nextpnr (place and route).
 
 # Compile Process
 
+Although each component uses a different build system, you can run everything
+with
+1. `make` (compile everything in this folder)
+2. `make clean` (clean up all compiled files)
+
 ## Setting up the Toolchain
 
 The toolchain is primarily designed around modern Linux. It may not work
@@ -202,6 +207,12 @@ For the Arty A7, the bitstream is `firmware/build/digilent_arty/gateware/digilen
 
 ## Software Build System
 
+The software build system uses files that are generated by the FPGA compile
+process. The number one reason why software won't work when loaded onto the
+FPGA is because it is compiled for a different FPGA bitstream. If you have
+an issue where software that you know should work does not, run `make clean`
+in the FPGA build system and rebuild it from scratch.
+
 This requires at least CMake 3.20.0 (you can install this using `conda`).
 Afterwards just run `make` and everything should work. Everything is
 managed by the `CMakeLists.txt` and the `prj.conf`, see the Zephyr OS
@@ -228,6 +239,11 @@ managed switch). You can even retrofit an old computer into a router
 
 The default TFTP client connects to 192.168.1.50.
 
+## Connecting to the FPGA Over USB
+
+Connect to the FPGA over USB and run `litex_term /dev/ttyUSB1` (or whatever
+connection it should be) and you should see the LiteX BIOS come up. 
+
 ## Loading the Firmware
 
 Connect the FPGA to a computer using a Micro-USB to USB cable. Run
@@ -240,6 +256,15 @@ better thing to do is to use TFTP boot, which goes over Ethernet.
 CONNECTED NETWORK INTERFACE. THIS IS A BIG SECURITY RISK. ONLY RUN
 TFTP FOR THE AMOUNT OF TIME REQUIRED TO BOOT THE CONTROL SOFTWARE.**
 You can read about how to setup a TFTP server on the [OpenWRT wiki][owrt_wiki].
+On Linux, run
+
+	dnsmasq --port=0 --enable-tftp --tftp-root=/path/to/firmware/directory --user=root --group=root --interface=$INTERFACE
+
+Do not use `--tftp-no-blocksize`. The controller will only read the first
+512 bytes of the kernel.
+
+In the root of the TFTP server, have `boot.bin` be the kernel binary
+(`zephyr.bin`).
 
 [owrt_wiki]: https://openwrt.org/docs/guide-user/troubleshooting/tftpserver
 
@@ -467,7 +492,7 @@ can do that, great. Otherwise you will need to configure your computer with a
 static ip.
 
 1. Remove your computer from the DHCP list that the router has.
-2. Run `ip link set eth-interface down`.
+2. Run `ip link set eth-interface up`.
 3. Then run `ip addr` and run `ip addr remove del [ip] dev eth-interface` on
    each ip on the ethernet interface that is connected to the controller.
 3. Run `ip addr add 192.168.1.100/24 dev eth-interface` (or whatever ip + subnet