add fast L2 preload, FPGA flashing targets and FPGA Readme info

fpga/Makefile

@@ -15,12 +15,14 @@ else
 	@echo "Bitstream generation for zcu102 board finished. The bitstream Configuration Memory File was copied to ./pulp_zcu102.bit and ./pulp_zcu102.bin"
 endif
 
+flash_zcu102: ## flashes the ZCU102 bitstream to the board.
+	$(MAKE) -C pulp flash BOARD=zcu102
+
 clean_zcu102: ## Removes all bitstreams, *.log files and vivado related files (rm -rf vivado*) for the zcu102 board.
 	$(MAKE) -C pulp clean BOARD=zcu102
 	rm -f pulp_zcu102.bit
 	rm -f pulp_zcu102.bin
 
-
 vcu118: ## Generates the bitstream for the vcu118 board
 ifdef gui
 	$(MAKE) -C pulp gui BOARD=vcu118
@@ -31,12 +33,14 @@ else
 	@echo "Bitstream generation for vcu118 board finished. The bitstream Configuration Memory File was copied to ./pulp_vcu118.bit and ./pulp_vcu118.bin"
 endif
 
+flash_vcu118: ## flashes the VCU118 bitstream to the board.
+	$(MAKE) -C pulp flash BOARD=vcu118
+
 clean_vcu118: ## Removes all bitstreams, *.log files and vivado related files (rm -rf vivado*) for the vcu118 board.
 	$(MAKE) -C pulp clean BOARD=vcu118
 	rm -f pulp_vcu118.bit
 	rm -f pulp_vcu118.bin
 
-
 clean_ips: ## Cleans the generated IPs
 	$(MAKE) -C pulp clean-ips BOARD=zcu102
 

fpga/README.md

@@ -6,7 +6,18 @@ subdirectory for the various supported boards:
 * Xilinx ZCU102
 * Xilinx VCU118 (untested)
 
-### Bitstream Generation
+## Bitstream Generation and Flashing
+
+### Vivado Versions
+Tested with Vivado 2022.1. If the board part is not found (e.g., `xilinx.com:zcu102:part0:3.3`), you may need to change the version (for older versions of Vivado, for example from `3.3` to `3.2`).
+
+The scripts assume that the `vivado` command points to the vivado binary. On IIS systems using SEPP packages, run commands as 
+```
+vitis-2022.1 make <target>
+```
+using the appropriate `vitis-<VERSION>` or `vivado-<VERSION>` command.
+
+### Generating the Bitstream
 In order to generate the PULP bitstream for a supported target FPGA board, first fetch the required
 dependencies and generate the corresponding scripts with bender in the project root directory. To
 do this, run the followin commands in the project root directory:
@@ -36,12 +47,70 @@ Note: if using a different command to launch vivado, you can set the `$(VIVADO)`
 
 ### Bitstream Flashing
 
-TODO: describe bitstream flashing
+To flash the bitstream, use the `make flash_zcu102` (tested) and `make flash_vcu118` (untested** commands after running the corresponding bitstream generation targets. Of course, make sure the board is correctly:
+* powered on, and
+* connected via USB
+
+## Compiling and Running Programs on FPGA
+
+The following instructions are based on commit `ddebe93` of the PULP SDK. This is an old version. The changes to make it work with FPGA were:
+* The `pos_init_fll` function now returns the `ARCHI_FPGA_FREQUENCY` instead of trying to configure the FLL, and all FLLs are registered as running with that frequency.
+* `ARCHI_FPGA_FREQUENCY` was changed to 10 MHz, matching the configuration of the FPGA port.
+
+To run your program on the FPGA platform, you need the following ingredients:
+* A USB-JTAG adapter connected correctly to the FPGA board
+* A running OpenOCD instance connected to the emulated PULP system via that adapter
+* GNU `gdb` to manage the execution
+
+### Compilation
+
+Using a suitable version of the PULP SDK, run the following command in your software project (`io=uart` is not strictly necessary in the referenced commit but it doesn't hurt to have it there):
+```
+make build platform=fpga io=uart -j4
+```
+### Connecting to the FPGA Board
+To connect an ARM 20-pin JTAG header to the PULP system's JTAG interface on ZCU102/VCU118, connect the following pins:
+
+
+| Signal | ARM Pin | ZCU102/VCU118 PMOD0 Pin |
+|--------|---------|-------------------------|
+| TMS    | 7       | 0                       |
+| TDI    | 5       | 1                       |
+| TDO    | 13      | 2                       |
+| TCK    | 9       | 3                       |
+| TRSTN  | 3       | 4 (not used)            |
+
+
+Now you can connect to the board with OpenOCD (assuming you are using ZCU102 and have an Olimex JTAG interface):
+```
+openocd -f pulp-zcu102/openocd-zcu102-olimex-arm-usb-ocd-h.cfg
+```
 
-### Compiling and running on fpga
+### Running Your Program
 
-TODO: describe compiling and running on fpga
+To flash your program with JTAG, you can now use `gdb` - in the `fpga` folder, an example GDB script that flashes the program is provided as `do.gdb`. You can copy it to your C project for convenience. Then, from your C project directory and with the SDK correctly configured, run:
+```
+alias rvgdb=${PULP_RISCV_GCC_TOOLCHAIN}/bin/riscv32-unknown-elf-gdb
+rvgdb -x do.gdb ${PATH_TO_BINARY}
+```
+where `$PATH_TO_BINARY` is the location of your compiled RISCV binary, usually something like `BUILD/PULP/GCC_RISCV/test/test` if your application name is `test`.
 
+For UART input/output, PULP's UART RX/TX pins are mapped to connect to the onboard USB-UART bridge, so connecting a USB cable to the appropriate USB port is sufficient. On ZCU102, it is connected to UART port 2 of the CP2108 USB-UART chip. To find out which `/dev/ttyUSB*` this corresponds to, run 
+```
+dmesg | grep tty
+```
+to get an output like:
+```
+[...]
+[15626159.946345] usb 1-2: cp210x converter now attached to ttyUSB0
+[15626159.947768] usb 1-2: cp210x converter now attached to ttyUSB2
+[15626159.949614] usb 1-2: cp210x converter now attached to ttyUSB3
+[15626159.951680] usb 1-2: cp210x converter now attached to ttyUSB4
+[...]
+```
 
+In this case, UART0 is `ttyUSB0`, UART1 is `ttyUSB2` and UART2 is `ttyUSB3`. Note that the numbering needn't be linear, depending on what other devices you have attached to your computer.
 
+To connect to PULP with UART using `screen`, in the above case we would thus run:
 
+`screen /dev/ttyUSB3 115200,cs8`

fpga/do.gdb

@@ -0,0 +1,4 @@
+target remote :3333
+tui enable
+layout split
+load

fpga/pulp-vcu118/fpga-settings.mk

@@ -1,6 +1,7 @@
 export BOARD=vcu118
 export XILINX_PART=xcvu9p-flga2104-2L-e
 export XILINX_BOARD=xilinx.com:vcu118:part0:2.0
+export XILINX_FPGA_DEV=xcvu9_0
 export FC_CLK_PERIOD_NS=100
 export CL_CLK_PERIOD_NS=100
 export PER_CLK_PERIOD_NS=100

fpga/pulp-zcu102/fpga-settings.mk

@@ -1,6 +1,7 @@
 export BOARD=zcu102
 export XILINX_PART=xczu9eg-ffvb1156-2-e
-export XILINX_BOARD=xilinx.com:zcu102:part0:3.2
+export XILINX_BOARD=xilinx.com:zcu102:part0:3.3
+export XILINX_FPGA_DEV=xczu9_0
 export FC_CLK_PERIOD_NS=100
 export CL_CLK_PERIOD_NS=100
 export PER_CLK_PERIOD_NS=100

fpga/pulp/Makefile

@@ -12,6 +12,9 @@ VIVADO ?= vivado
 all: ips ## Generate the bitstream for pulpissimo with vivado in batch mode. The vivado invocation command may be overriden with the env variable VIVADO.
 	$(VIVADO) -mode batch -source tcl/run.tcl
 
+flash:
+	$(VIVADO) -mode batch -source tcl/flash_bitstream.tcl
+
 gui: ips ## Generates the bitstream for pulpissimo with vivado in GUI mode. The vivado invocation command may be overriden with the env variable VIVADO.
 	$(VIVADO) -mode gui -source tcl/run.tcl &
 

fpga/pulp/tcl/flash_bitstream.tcl

@@ -0,0 +1,9 @@
+open_hw_manager
+connect_hw_server -allow_non_jtag
+open_hw_target
+set_property PROGRAM.FILE ../pulp_${::env(BOARD)}.bit [get_hw_devices xczu9_0]
+current_hw_device [get_hw_devices $::env(XILINX_FPGA_DEV)]
+set_property PROBES.FILE {} [get_hw_devices $::env(XILINX_FPGA_DEV)]
+set_property FULL_PROBES.FILE {} [get_hw_devices $::env(XILINX_FPGA_DEV)]
+program_hw_devices [get_hw_devices $::env(XILINX_FPGA_DEV)]
+refresh_hw_device [lindex [get_hw_devices $::env(XILINX_FPGA_DEV)] 0]