README: add checklist for hardware detection module modification

README.md

@@ -69,12 +69,41 @@ Refer to [\<matana-chipyard\>/chipyard/generators/chipyard/src/main/scala/config
 
 ### chipyard-bootloader
 
-Normally there is no need to modify <chipyard-bootloader>. However, if you have another way to program DDR Memory (for example JTAG) and to give the right devicetree file to the kernel, you can do not use this bootloader at all.
+Normally there is no need to modify `<chipyard-bootloader>`. However, if you have another way to program DDR Memory (for example JTAG) and to give the right devicetree file to the kernel, you can do not use this bootloader at all.
 In that case, you may want to modify `<matana-chipyard>/bootrom/bootrom.S/BRAM_BASE` to `0x80000000` in order to begin execution directly in DDR after system boot. You can then safely remove BlockRAM present in FPGA, declared and connected in [\<matana-chipyard\>/board/BoardTop.v](../../../../matana-chipyard/-/tree/master/board/BoardTop.v) as `io_mmio`, perhaps setting a 0 `MEM_ADDR_BITS` can help (not tested).
 
-If you only want to perform some embedded test, you can modify <chipyard-bootloader> to contain some embedded code and test without DDR.
+If you only want to perform some embedded test, you can modify `<chipyard-bootloader>` to contain some embedded code and test without DDR.
 
 ### Linux configuration
 
 In <chipyard-linux>, you can find `make linux-menuconfig`, `make busybox-menuconfig`, `make buildroot-menuconfig`. They will modify files in [\<chipyard-linux\>/conf](../../../../chipyard-linux/-/tree/master/conf).
 
+
+# Checklist
+
+## Steps for modify MATANA hardware detection module
+
+1. Modify corresponding files in [\<matana-chipyard\>/src/main/scala](../../../../matana-chipyard/-/tree/master/src/main.scala).
+2. Run `make verilog -j4` in `<chipyard>/sims`.
+3. Copy `...top.v`, `...top.mems.v`, `...harness.v` from `<chipyard>/sims/generated-src/.../` to replace files of the same name in your existing Xilinx project, then generate bistream.
+  - It is recommanded to run it on a powerful machine, you can use `menu > Project > Cleanup Project Files` to reduce folder size).
+4. Open Xilinx `Place & Route > Analyze Timing / Floorplan Design (PlanAhead)`, find locations of memory and put the locations [\<chipyard-bootloader\>/src/](../../../../chipyard-bootloader/-/tree/master/src/)`/bramlayout*.bmm`.
+  - Ctrl+F, Type is Block Memory, "site" X Y of given RAM.
+5. Copy generated bistream in `<chipyard-bootloader>` and rename bistream to `xilinx.bit`.
+6. Run `make clean && make bitgen` in `<chipyard-bootloader>` to get a bistream (`xilinx_new.bit`) with predefined memory content.
+7. (Only if modified MMIO registers) Copy the content of `...0x4000000.0.regmap.json` from `<chipyard>/sims/generated-src/.../` to [\<matana-linux-module\>/regmap.json](../../../../matana-linux-module/-/tree/master/regmap.json).
+  - If the software module needs to be modify, modify it before next step.
+8. (Only if modified MMIO registers) Run `make clean-matana && make -j4` in `<chipyard-linux>`.
+  - Verify that all needed benchmark files are presents in `<linux-chipyard>/work/buildroot_initramfs_sysroot/opt`.
+9. On host, connect to board's terminal via UART with `sudo screen /dev/ttyUSB0 921600` (called remote terminal in the following).
+9. Use Xilinx tool to program the FPGA with `xilinx_new.bit`, press `RST` button on the board.
+  - It should print `Init UART` on remote terminal. If this is not the case, then the hardware configuration has some problem.
+10. Send `<chipyard-linux>/work/riscv-pk/bbl.bin` to the FPGA and begin Linux execution according to [\<chipyard-bootloader\>/README#Usage](../../../../matana-chipyard#usage).
+  - Type `R` on the remote terminal.
+  - Run `sudo bash -c "sx -k work/riscv-pk/bbl.bin < /dev/ttyUSB0 > /dev/ttyUSB0"` (suppose that you're in the `<chipyard-linux>` folder).
+  - Type `J` on the remote terminal to jump to DDR.
+    - It should show Linux boot message, or the Linux configuration have some problems.
+  - Leave remote terminal (for `screen`, type `ctrl+a` then `k`), reopen with `sudo screen /dev/ttyUSB0 115200`
+11. On remote terminal, login (root, matana), run `mknod /dev/matana c 252 0` (suppose that major number is 252) to map matana as character device.
+12. Run tests etc.
+  - For example, `cd /opt`, `./run_bench.sh; ./run_bench_csca.sh`. Then find results in `bench_result*.csv`