add sparcv8leon3-gr716 documentation

JIRA: RTOS-251
phoenix-rtos · Jul 21, 2023 · 1e7992e · 1e7992e
1 parent eec6a46
commit 1e7992e
Show file tree

Hide file tree

Showing 17 changed files with 175 additions and 9 deletions.
diff --git a/README.md b/README.md
@@ -16,6 +16,7 @@
     7. [Running system on `ia32-generic-qemu`](quickstart/ia32-generic-qemu.md)
     8. [Running system on `riscv64-generic-qemu`](quickstart/riscv64-generic-qemu.md)
     9. [Running system on `riscv64-generic-spike`](quickstart/riscv64-generic-spike.md)
+    10. [Running system on `sparcv8leon3-gr716-mini`](quickstart/sparcv8leon3-gr716-mini.md)
 5. [Loader](loader/README.md)
     1. [Architecture](loader/architecture.md)
     2. [Command-line interface](loader/cli.md)
@@ -25,6 +26,7 @@
         2. [HAL layer for ARMv7 Cortex-A based based targets](kernel/hal/armv7a.md)
         3. [HAL layer for IA32 based targets](kernel/hal/ia32.md)
         4. [HAL layer for RISC-V 64 based targets](kernel/hal/riscv64.md)
+        5. [HAL layer for SPARCv8 LEON3 based targets](kernel/hal/sparcv8leon3.md)
     2. [Processes and threads](kernel/proc/README.md)
         1. [Processes creation](kernel/proc/forking.md)
         2. [Synchronization primitives](kernel/proc/sync.md)

diff --git a/building/README.md b/building/README.md
@@ -90,6 +90,7 @@ The Phoenix-RTOS reference project supports the following target platforms:
 * ia32-generic-qemu
 * riscv64-generic-qemu
 * riscv64-generic-spike
+* sparcv8leon3-gr716-mini
 
 To get the list of valid targets the `build.sh` script should be launched with an empty `TARGET` variable, eg:
 
@@ -317,24 +318,25 @@ cd phoenix-rtos-project
 (cd phoenix-rtos-build/toolchain/ && ./build-toolchain.sh i386-pc-phoenix ~/toolchains/i386-pc-phoenix)
 (cd phoenix-rtos-build/toolchain/ && ./build-toolchain.sh arm-phoenix ~/toolchains/arm-phoenix)
 (cd phoenix-rtos-build/toolchain/ && ./build-toolchain.sh riscv64-phoenix ~/toolchains/riscv64-phoenix)
+(cd phoenix-rtos-build/toolchain/ && ./build-toolchain.sh sparc-phoenix ~/toolchains/sparc-phoenix)
 ```
 
 Toolchain binaries should be added to the PATH variable:
 
 ```bash
-export PATH=$PATH:$HOME/toolchains/i386-pc-phoenix/i386-pc-phoenix/bin/:$HOME/toolchains/arm-phoenix/arm-phoenix/bin/:$HOME/toolchains/riscv64-phoenix/riscv64-phoenix/bin/
+export PATH=$PATH:$HOME/toolchains/i386-pc-phoenix/i386-pc-phoenix/bin/:$HOME/toolchains/arm-phoenix/arm-phoenix/bin/:$HOME/toolchains/riscv64-phoenix/riscv64-phoenix/bin/:$HOME/toolchains/sparc-phoenix/sparc-phoenix/bin/
 ```
 
 You should keep the `PATH` variable updated. There are various methods to do that, for example you can place the export in `.bashrc` file on `Ubuntu`:
 
   ```bash
-  echo "export PATH=$PATH:$HOME/toolchains/i386-pc-phoenix/i386-pc-phoenix/bin/:$HOME/toolchains/arm-phoenix/arm-phoenix/bin/:$HOME/toolchains/riscv64-phoenix/riscv64-phoenix/bin/" >> $HOME/.bashrc
+  echo "export PATH=$PATH:$HOME/toolchains/i386-pc-phoenix/i386-pc-phoenix/bin/:$HOME/toolchains/arm-phoenix/arm-phoenix/bin/:$HOME/toolchains/riscv64-phoenix/riscv64-phoenix/bin/:$HOME/toolchains/sparc-phoenix/sparc-phoenix/bin/" >> $HOME/.bashrc
   ```
 
 or in `.zshrc` on MacOS:
 
   ```bash
-  echo "export PATH=\$PATH:\$HOME/toolchains/i386-pc-phoenix/i386-pc-phoenix/bin/:\$HOME/toolchains/arm-phoenix/arm-phoenix/bin/:\$HOME/toolchains/riscv64-phoenix/riscv64-phoenix/bin/" >> $HOME/.zshrc
+  echo "export PATH=\$PATH:\$HOME/toolchains/i386-pc-phoenix/i386-pc-phoenix/bin/:\$HOME/toolchains/arm-phoenix/arm-phoenix/bin/:\$HOME/toolchains/riscv64-phoenix/riscv64-phoenix/bin/:\$HOME/toolchains/sparc-phoenix/sparc-phoenix/bin/" >> $HOME/.zshrc
   ```
 
 Read more about the Phoenix-RTOS toolchain [here](toolchain.md).

diff --git a/kernel/hal/README.md b/kernel/hal/README.md
@@ -70,4 +70,5 @@ Context is described using `cpu_contex_t` structure.
 3. [Kernel - HAL for ARMv7 Cortex-A based targets](armv7a.md)
 4. [Kernel - HAL for IA32 targets](ia32.md)
 5. [Kernel - HAL for RISC-V 64 based targets](riscv64.md)
-6. [Table of Contents](../README.md)
+6. [Kernel - HAL for SPARCv8 LEON3 based targets](sparcv8leon3.md)
+7. [Table of Contents](../README.md)
diff --git a/kernel/hal/armv7a.md b/kernel/hal/armv7a.md
@@ -10,4 +10,5 @@ ARMv7m HAL layer supports microcontrollers based on ARM Cortex-Ax architecture.
 2. [Kernel - HAL for ARMv7 Cortex-M based targets](armv7m.md)
 3. [Kernel - HAL for ARMv7 Cortex-A based targets](armv7a.md)
 4. [Kernel - HAL for RISC-V 64 based targets](riscv64.md)
-5. [Table of Contents](../../README.md)
+5. [Kernel - HAL for SPARCv8 LEON3 based targets](sparcv8leon3.md)
+6. [Table of Contents](../../README.md)
diff --git a/kernel/hal/armv7m.md b/kernel/hal/armv7m.md
@@ -43,4 +43,5 @@ Next memory part defines exception and interrupt handlers.
 2. [Kernel - HAL for ARMv7 Cortex-A based targets](armv7a.md)
 3. [Kernel - HAL for IA32 targets](ia32.md)
 4. [Kernel - HAL for RISC-V 64 based targets](riscv64.md)
-5. [Table of Contents](../../README.md)
+5. [Kernel - HAL for SPARCv8 LEON3 based targets](sparcv8leon3.md)
+6. [Table of Contents](../../README.md)
diff --git a/kernel/hal/ia32.md b/kernel/hal/ia32.md
@@ -173,4 +173,5 @@ First part of the context is stored on the kernel stack automatically by CPU. Af
 2. [Kernel - HAL for ARMv7 Cortex-M based targets](armv7m.md)
 3. [Kernel - HAL for ARMv7 Cortex-A based targets](armv7a.md)
 4. [Kernel - HAL for RISC-V 64 based targets](riscv64.md)
-5. [Table of Contents](../../README.md)
+5. [Kernel - HAL for SPARCv8 LEON3 based targets](sparcv8leon3.md)
+6. [Table of Contents](../../README.md)
diff --git a/kernel/hal/riscv64.md b/kernel/hal/riscv64.md
@@ -103,4 +103,5 @@ The above sequence enables paging and pass execution to proper virtual address b
 2. [Kernel - HAL for ARMv7 Cortex-M based targets](armv7m.md)
 3. [Kernel - HAL for ARMv7 Cortex-A based targets](armv7a.md)
 4. [Kernel - HAL for IA32 targets](ia32.md)
-5. [Table of Contents](../../README.md)
+5. [Kernel - HAL for SPARCv8 LEON3 based targets](sparcv8leon3.md)
+6. [Table of Contents](../../README.md)
diff --git a/kernel/hal/sparcv8leon3.md b/kernel/hal/sparcv8leon3.md
@@ -0,0 +1,13 @@
+# HAL for SPARCv8 LEON3 based targets
+
+SPARCv8 LEON3 HAL layer supports microcontrollers based on SPARCv8 architecture.
+Source code is located in `hal/sparcv8leon3` directory.
+
+## See also
+
+1. [Kernel - HAL Subsystem](README.md)
+2. [Kernel - HAL for ARMv7 Cortex-M based targets](armv7m.md)
+3. [Kernel - HAL for ARMv7 Cortex-A based targets](armv7a.md)
+4. [Kernel - HAL for RISC-V 64 based targets](riscv64.md)
+5. [Kernel - HAL for SPARCv8 LEON3 based targets](sparcv8leon3.md)
+6. [Table of Contents](../../README.md)
diff --git a/quickstart/README.md b/quickstart/README.md
@@ -13,4 +13,5 @@ This chapter presents how to run Phoenix-RTOS on supported targets. It is assume
 7. [Running system on `ia32-generic-qemu`](ia32-generic-qemu.md)
 8. [Running system on `riscv64-generic-qemu`](riscv64-generic-qemu.md)
 9. [Running system on `riscv64-generic-spike`](riscv64-generic-spike.md)
-10. [Table of Contents](../README.md)
+10. [Running system on `sparcv8leon3-gr716-mini`](sparcv8leon3-gr716-mini.md)
+11. [Table of Contents](../README.md)
diff --git a/quickstart/_images/gr716-copy.png b/quickstart/_images/gr716-copy.png
diff --git a/quickstart/_images/gr716-help.png b/quickstart/_images/gr716-help.png
diff --git a/quickstart/_images/gr716-ls.png b/quickstart/_images/gr716-ls.png
diff --git a/quickstart/_images/gr716-phoenixd.png b/quickstart/_images/gr716-phoenixd.png
diff --git a/quickstart/_images/gr716-plo.png b/quickstart/_images/gr716-plo.png
diff --git a/quickstart/_images/gr716-ps.png b/quickstart/_images/gr716-ps.png
diff --git a/quickstart/_images/gr716-start.png b/quickstart/_images/gr716-start.png
diff --git a/quickstart/sparcv8leon3-gr716-mini.md b/quickstart/sparcv8leon3-gr716-mini.md
@@ -0,0 +1,143 @@
+# Running system on `sparcv8leon3-gr716-mini`
+
+These instructions describe how to run Phoenix-RTOS on the `sparcv8leon3-gr716-mini` target. Note that the build
+artifacts, including the system image should be provided in the `_boot` directory.If you have not built the system
+image yet, please refer to the [Building Phoenix-RTOS image](../building/README.md) section.
+
+## Connecting the board
+
+Connect the board to the computer using a USB cable. The board provides a 4-channel USB-UART bridge, of which three may
+be used:
+
+- Channel 0 - `if00` - used for `GRMON` debug connection, interfaces to `AHBUART1` on the board
+- Channel 2 - `if02` - used for console, interfaces to `UART2` on the board
+- Channel 3 - `if03` - used for interfacing with the `phoenixd` server, interfaces to `UART3` on the board
+
+## Flashing the Phoenix-RTOS system image
+
+The process comes down to a few steps, described below.
+
+### Using `GRMON` to upload Phoenix-RTOS loader (`PLO`) to RAM
+
+First, check on which port the board is connected to the computer. To do this, run the following command:
+
+```bash
+ls -l /dev/serial/by-id
+```
+
+<img src="_images/gr716-ls.png" width="700px">
+
+In this case, the debug UART is connected to the `ttyUSB0` port.
+Launch the `GRMON` monitor using the following command:
+
+```bash
+grmon -uart /dev/ttyUSB0 -baud 115200
+```
+
+<details>
+<summary>How to get GRMON</summary>
+
+- Download the GRMON software from the [official website](https://www.gaisler.com/index.php/downloads/debug-tools).
+- After downloading the archive, extract it and optionally add the `grmon` binary to the `PATH` variable.
+
+</details>
+</br>
+
+The `-baud` parameter specifies the baud rate of the `AHBUART1` interface.
+Optionally you can pass  the `-gdb` parameter, which enables the GDB server on port 2222.
+Default CPU clock frequency is 50 MHz.
+
+To load the bootloader (`plo`) to the RAM, run the following commands in the `GRMON` monitor:
+
+```bash
+load phoenix-rtos-project/_boot/sparcv8leon3-gr716-mini/plo-ram.img 0x31000000
+```
+
+To verify that the file has been loaded correctly, run the following command:
+
+```bash
+verify phoenix-rtos-project/_boot/sparcv8leon3-gr716-mini/plo-ram.img 0x31000000
+```
+
+Set the entry point of the bootloader:
+
+```bash
+ep 0x31000000
+```
+
+Open a new terminal window and run the following command:
+
+```bash
+picocom -b 115200 --imap lfcrlf /dev/ttyUSB2
+```
+
+This will connect to the `UART2` interface, which is used for the console.
+To start the bootloader, execute the following command in the `GRMON` monitor:
+
+```bash
+go
+```
+
+The bootloader interface should appear in the console.
+
+<img src="_images/gr716-plo.png" width="700px">
+
+### Copying flash image using PHFS (phoenixd)
+
+To flash the disk image, first, you need to verify to which port the `plo` serial interface is connected using the
+following command:
+
+```bash
+ls -l /dev/serial/by-id
+```
+
+To provide the disk image to the bootloader, `phoenixd` has to be launched with the following arguments
+(choose suitable ttyUSBx device, in this case, `ttyUSB3`):
+
+```bash
+sudo ./phoenixd -p /dev/ttyUSB3 -b 115200 -s .
+```
+
+<img src="_images/gr716-phoenixd.png" width="700px">
+
+To start copying a file, write the following command in the console with the `plo` interface:
+
+```bash
+copy uart3 phoenix.disk flash0 0x0 0x0
+```
+
+<img src="_images/gr716-copy.png" width="700px">
+
+The `flash0` is an external flash memory.
+
+After copying is done, reset the board to start the operating system. To reboot, write `reboot` command in the `plo`
+console.
+
+## Using Phoenix-RTOS
+
+After reboot, Phoenix-RTOS will be launched and the `psh` shell command prompt will appear in the terminal.
+
+<img src="_images/gr716-start.png" width="700px">
+
+- Note: You can also enter `plo` by pressing any button within some time after reset.
+
+To get the available command list type:
+
+```bash
+help
+```
+
+<img src="_images/gr716-help.png" width="700px">
+
+To get the list of working processes type:
+
+```bash
+ps
+```
+
+<img src="_images/gr716-ps.png" width="700px">
+
+## See also
+
+1. [Running system on targets](README.md)
+2. [Table of Contents](../README.md)