Add more formal support for VF2 board using config options in param.h. Update the README files with detail on how to configure.

Author: ipacman

Makefile

@@ -39,7 +39,8 @@ OBJS += \
 ifeq ($(runtime_config), sbi)
 OBJS += \
    $K/sbi.o \
-   $K/ram_disk.o
+   $K/ram_disk.o \
+   $K/sbi_uart.o
 else
 OBJS += \
   $K/plic.o \
@@ -177,7 +178,7 @@ fs.img: mkfs/mkfs README $(UPROGS)
 clean: 
 	rm -f *.tex *.dvi *.idx *.aux *.log *.ind *.ilg \
 	*/*.o */*.d */*.asm */*.sym \
-	$U/initcode $U/initcode.out $K/kernel fs.img \
+	$U/initcode $U/initcode.out $K/kernel $K/kernel.bin fs.img \
 	mkfs/mkfs .gdbinit \
         $U/usys.S \
 	$(UPROGS)

README-opensbi-unmatched.md

@@ -2,25 +2,34 @@
 
 This branch captures changes made to support a sifive-unmatched board running opensbi (its default configuration).
 
-The code also appears to run unmodified on StarFive Vision 5 2 (v1.30 board). See additional notes on that in
-README-opensbi-vision5-2.md.
+The code can run on StarFive VisionFive 2 (v1.30 board). See additional notes on that in README-opensbi-vision5-2.md and select the desired configuration option in param.h as further described below.
 
 The default xv6 release supports machine mode (only) so this would not run on unmatched without replacing its Uboot-SPL
 
-While that may be a useful exercise, this approach allows a user to run/debug a stock/unmodified unmatched board
-or (hopefully) any board that runs uboot (with sbi). 
+While that may be a useful exercise, this approach allows a user to run xv6 using the platform distributed uboot without change. 
 
 The other problem with messing with the SPL is it contains all the board (e.g. DDR ram) initialization code. So, effectively,
-what we are doing here is interrupting Linux boot by pressing a key while it is in uboot and loading this image
-instead of Linux. Either run in RISCV supervisor mode and make use of the memory resident sbi that uboot and Linux uses.
+what we are doing here is interrupting Linux boot by pressing a key while it is in uboot and loading this image instead of Linux. 
 
-The modifications are fairly minor with a define selection in Makefile and a corresponding one in param.h. 
+Both xv6 and Linux run in supervisor mode and have no direct access to RISCV machine mode.
 
-- RUNTIME_SBI -- enables branch specific changes relating to OpenSBI  
+The modifications (from distribution xv6) are fairly minor with a define selection in Makefile and a corresponding one in param.h: 
+```
+RUNTIME_SBI -- enables branch specific changes relating to the OpenSBI port
+```
 
 # Quick Start
 
-Interrupt the Unmatched boot process by pressing a key on the USB UART debug terminal while it is in Uboot. This starts
+Prior to make, in param.h, select BOARD_UNMATCHED and deselect BOARD_VF2 for the Unmatched version.
+```
+#define BOARD_UNMATCHED
+//#define BOARD_VF2
+```
+In param.h, optionally select POLL_UART0_DIRECT to poll UART0 for console receive characters within xv6 (rather than use SBI for console polling). Either option works on the Unmatched board but it does make a difference on the VF2 board depending on its SBI version.
+
+For convenience, the v0.2 release contains both "pure SBI" and "Uart0 direct" binaries (and elf files in case using Jtag). See the README file in the release for additional comments.
+
+To run, interrupt the Unmatched boot process by pressing a key on the USB UART debug terminal while it is in Uboot. This starts
 the uboot command interface where it is possible to load and run a binary file (the xv6 kernel binary given as a release or
 produced via recompile of the source code).
 
@@ -99,7 +108,7 @@ done in this version.
 
 Here I list stuff that I have not yet resolved
 
-## An oddity with SMP
+## A possible oddity with SMP
 
 This version launches all 4 U74 cores (Harts) and they seem functional. But I'm not yet sure if there is a problem. I would have expected
 the cores to be at a "wfi" instruction awaiting an interrupt (keypress or timer) when idle. I believe the initial core
@@ -115,6 +124,7 @@ are cleverly written with expected results (including for faults).
 
 I've met my match with the failure of one particular test on unmatched: sbrkmuch() within usertests.c. This test runs fine:
 
+- on the VF2 board
 - occasionally (unmodified). Run the test a few times in a row from the command prompt.
 - when run standalone (via command line parameter to just run sbrkmuch).
 - when its moved or called differently from its original version.

README-opensbi-vision5-2.md

@@ -1,16 +1,23 @@
 # Notes about this branch and StarFive Vision 5 (2) or VF2 board
 
-The exact same binary as released for the unmatched appears to run on this board. Very little testing has been done so far but I wanted to note the following:
+Prior to make, in param.h, select BOARD_VF2 and deselect BOARD_UNMATCHED for the VF2 version.
+```
+//#define BOARD_UNMATCHED
+#define BOARD_VF2
+```
+In param.h, also select POLL_UART0_DIRECT to poll UART0 for console receive characters within xv6 (rather than use SBI for console polling). 
+
+Early versions of VF2 firmware supported pure SBI but this option sidesteps the issue by talking directly to the UART for console receive characters.
 
-- The usertests issues described in the unmatched README either do not happen or happen with less frequency. In other words, the problem with sbrkmuch() has not yet been observed.
-- Its possible/likely that the interrupt rate is different on this board and therefore an adjustment is needed to 'TIMERINTCNT' in param.h.
-- To date, I've only tried loading the code with Jtag. But I have no reason to believe that the uboot binary load/run will not work. Issue is my VF2 board is not as well controlled as the version on the unmatched board.
+For convenience, the v0.2 release contains both "pure SBI" and "Uart0 direct" binaries (and elf files in case using Jtag). See the README file in the release for additional comments.
+
+- The usertests issues described in the unmatched README do not happen on VF2 board.
+- Selecting BOARD_VF2 adjusts the timer interrupt rate to compensate for observed higher timer clock frequency.
 - I'm using a different Jtag adapter for the VF2 board since I didnt want to move the Jlink EDU (old version) off of the unmatched yet. I'm specifically using an FTDI FT2232H-56Q minimodule. I'll include a working Jtag config that I'm using in the Jtag directory.
 
-## Errata (hopefully temporary)
+## Errata
 
-While trying to verify that the binary (non-Jtag) xv6 kernel.bin file runs, I managed to boot my SD card into Linux, transfer the kernel.bin file to the
-SD card and attempt to boot it from next uboot startup.
+As described above, the 'pure sbi' VF2 configuration does not process console keyboard input correctly with recent board firmare.
 
 While it boots, there is something wrong with the keyboard input -- I get an SBI error with each keypress:
 
@@ -28,18 +35,15 @@ This one works fine:
 U-Boot SPL 2021.10 (Feb 12 2023 - 18:15:33 +0800)
 ```
 
-Versus the newer version:
-This one reports the aforementioned error.
+The newer version reports the aforementioned error.
 
 ```
 U-Boot SPL 2021.10 (Sep 19 2024 - 15:43:53 +0800)
 ```
 
-I'll try to figure out what is different. Also, the interrupt rate is faster, so in test code I changed TIMERINTCNT to 400000 (not checked in) to reduce the interrupt rate to approximately 10x per second.
-
-Finally, the VF2 board has a different DDR memory map from siFive unmatched board but its kernel.bin load address (0x80400000) is still within valid space with plenty of headroom. The code really should be recompiled for something around 0x40xxxxxx where xxxxxx leaves room for SBI that loads at 0x40000000.
+The VF2 board has a different DDR memory map from siFive unmatched board but its kernel.bin load address (0x80400000) is still within valid space with plenty of headroom. The code really should be recompiled for something around 0x40xxxxxx where xxxxxx leaves room for SBI that loads at 0x40000000.
 
-I dont know why, but it took a long time to find the memory map published, it was in the JH7110 "Technical Reference Manual" 
+I dont know why, but it took a long time to locate the VF2 memory map. It is in the JH7110 "Technical Reference Manual" 
 
 ```
 https://doc-en.rvspace.org/JH7110/TRM/JH7110_TRM/system_memory_map.html

kernel/defs.h

@@ -189,6 +189,9 @@ void            virtio_disk_intr(void);
 void            ram_disk_init(void);
 void            ram_disk_rw(struct buf*, int write);
 
+// sbi_uart.c
+void            sbi_poll_uart0(void);
+
 // start.c
 void timerinit(void);
 

kernel/memlayout.h

@@ -18,8 +18,9 @@
 // PHYSTOP -- end RAM used by the kernel
 
 // qemu puts UART registers here in physical memory.
+#include "param.h"
 
-#ifdef RUNTIME_SBI
+#ifdef BOARD_UNMATCHED
 #define UART0 0x10010000L
 #define UART0_IRQ 32
 #else

kernel/param.h

@@ -22,7 +22,26 @@
 #define MAXPATH      128   // maximum file path name
 #define USERSTACK    1     // user stack pages
 #define BSIZE        1024  // block size
+
+// SBI default uses API for console input. However
+// POLL_UART0_DIRECT is needed on VF2 board due to SBI bug (polls Uart register directly)
+// The scheme also works on UNMATCHED board, but select proper BOARD to remap hardware
+
+#define POLL_UART0_DIRECT
+
+// Choose either BOARD_VF2 or BOARD_UNMATCHED but not both else #error
+//#define BOARD_UNMATCHED
+#define BOARD_VF2
+
+// The following enforces either-or seletion of board (else redefined error)
+#ifdef BOARD_VF2
+#define TIMERINTCNT  400000 // counter increment until next interrupt -- JH7110
+#endif
+
+#ifdef BOARD_UNMATCHED
 #define TIMERINTCNT  100000 // counter increment until next interrupt
+#endif
+
 #else
 #define NPROC        64  // maximum number of processes
 #define NCPU          8  // maximum number of CPUs