or1ksim: Modernize the tutorial

Author: stffrdhrn

docs/linux-on-or1ksim.md

@@ -15,8 +15,10 @@ nav_order: 2
 
 #### Files
 
- - [or1ksim.cfg](or1ksim.cfg) - config needed for or1ksim
- - [or1ksim-2025-04-27.tar.gz](https://github.com/openrisc/or1ksim/releases/download/2025-04-27/or1ksim-2025-04-27.tar.gz)
+We will download these below.
+
+ - [or1ksim.cfg](https://github.com/stffrdhrn/or1k-utils/raw/refs/heads/master/or1ksim.cfg) - config needed for or1ksim
+ - [or1ksim-2025-04-27.tar.gz](https://github.com/openrisc/or1ksim/releases/download/2025-04-27/or1ksim-2025-04-27.tar.gz) - The OpenRISC simulator source code
  - [or1k-none-linux-musl-15.1.0-20250621.tar.xz](https://github.com/stffrdhrn/or1k-toolchain-build/releases/download/or1k-15.1.0-20250621/or1k-none-linux-musl-15.1.0-20250621.tar.xz) - OpenRISC musl linux userspace toolchain
  - [linux-6.15.5.tar.xz](https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.15.5.tar.xz) - Linux kernel source code
  - [busybox-small-rootfs-20250708.tar.xz](https://github.com/stffrdhrn/or1k-rootfs-build/releases/download/or1k-20250708/busybox-small-rootfs-20250708.tar.xz) - Linux rootfs for userspace programs
@@ -34,7 +36,7 @@ provides more accurate tracing.
 We break this tutorial down into parts:
 
  - Downloading the pieces
- - Comping the kernel
+ - Compiling the kernel
  - Running the kernel
  - Interacting with the simulator
  - Adding custom userspace programs
@@ -57,6 +59,9 @@ curl -L -O https://github.com/openrisc/or1ksim/releases/download/2025-04-27/or1k
 curl -L -O https://github.com/stffrdhrn/or1k-rootfs-build/releases/download/or1k-20250708/busybox-small-rootfs-20250708.tar.xz
 curl -L -O https://github.com/stffrdhrn/or1k-toolchain-build/releases/download/or1k-15.1.0-20250621/or1k-none-linux-musl-15.1.0-20250621.tar.xz
 
+# Download an example config for or1ksim
+curl -L -O https://github.com/stffrdhrn/or1k-utils/raw/refs/heads/master/or1ksim.cfg
+
 # Extract everything
 tar -xf linux-6.15.5.tar.xz
 tar -xf or1ksim-2025-04-27.tar.gz
@@ -115,9 +120,6 @@ the system.
 #### Terminal 1
 
 ```bash
-# Download an example config for or1ksim
-curl -L -O https://github.com/stffrdhrn/or1k-utils/raw/refs/heads/master/or1ksim.cfg
-
 or1l-elf-sim -f or1ksim.cfg linux-6.15.5/vmlinux
 ```
 

or1ksim/index.md

@@ -5,33 +5,98 @@ parent: Platforms
 nav_order: 2
 ---
 
-# Files
+# Prerequisites
+
+#### System
+
+ - An x86 Linux workstation
+ - The `curl` and `telnet` command line utilities
+
+#### Files
+
+We will download these below.
 
  - [or1ksim.cfg](or1ksim.cfg) - config needed for or1ksim
- - [or1ksim-2025-04-27.tar.gz](https://github.com/openrisc/or1ksim/releases/download/2025-04-27/or1ksim-2025-04-27.tar.gz)
+ - [or1ksim-2025-04-27.tar.gz](https://github.com/openrisc/or1ksim/releases/download/2025-04-27/or1ksim-2025-04-27.tar.gz) - The OpenRISC simulator source code
  - [timer.c](./sw/timer/timer.c) - timer program
+
 # or1ksim Tutorial
 
-If you downloaded the tutorials as a release archive, you can directly
-start. If you have cloned the git repository, you instead need to
-follow the instructions for building the hardware and software as
-described below. Please also follow the
-[common tutorial setup](../README.md).
+The or1ksim program is the OpenRISC [instruction set simulator](https://en.wikipedia.org/wiki/Instruction_set_simulator) which
+provides accurate tracing. A simulator is a fast way to debug and ensure
+your software works before deploying it to real hardware.
+
+In this tutorial we will cover getting and building or1ksim, and building simple
+programs to run on or1ksim.
+
+We break this tutorial down into parts:
+
+ - Downloading the pieces
+ - Compiling a program
+ - Running a program
+ - Interacting with the simulator
+
+## Downloading the Pieces
+
+To get started we will create a temporary directly and setup our environment, if
+you plan to do a lot of OpenRISC development consider adding these tools to your
+`PATH` permanently.
+
+To get everything you need run:
+
+```bash
+mkdir /tmp/or1ksim/
+cd /tmp/or1ksim/
 
-To run the demo you need:
+# Download or1ksim, toolchain and a test project
+curl -L -O https://github.com/openrisc/or1ksim/releases/download/2025-04-27/or1ksim-2025-04-27.tar.gz
+curl -L -O https://github.com/stffrdhrn/or1k-toolchain-build/releases/download/or1k-15.1.0-20250621/or1k-elf-15.1.0-20250621.tar.xz
 
-* `or1k-sim` in your `PATH`, check with
+# Download example programs
+curl -L -O https://openrisc.io/tutorials/sw/hello/hello.c
+curl -L -O https://openrisc.io/tutorials/sw/timer/timer.c
 
-	or1k-sim --version
+# Download an example config for or1ksim
+curl -L -O https://github.com/stffrdhrn/or1k-utils/raw/refs/heads/master/or1ksim.cfg
+
+# Extract everything
+tar -xf or1ksim-2025-04-27.tar.gz
+tar -xf or1k-elf-15.1.0-20250621.tar.xz
+
+export PATH=$PATH:$PWD/or1k/bin:$PWD/or1k-elf/bin
+```
+
+## Compiling a program
+
+To compile programs for or1ksim we use the newlib baremetal toolchain. Binaries
+produced by this can run directly on systems with no Operating System.  We use
+the `-mboard=` option to provide newlib with the proper options needed to target
+or1ksim.  This includes RAM size, address loctions for UART and UART baud rates.
+
+```bash
+CFLAGS="-mboard=or1ksim-uart"
+or1k-elf-gcc -g -Og $CFLAGS -o hello.elf hello.c
+or1k-elf-gcc -g -Og $CFLAGS -o timer.elf timer.c
+```
 
 ## Run hello world
 
-	or1k-sim -f or1ksim.cfg hello.elf
+To run the demo you need `or1k-elf-sim` in your `PATH`, check with:
+
+```bash
+or1k-elf-sim --version
+```
+
+We can then run our program with the following:
+
+```bash
+or1k-elf-sim -f or1ksim.cfg hello.elf
+```
 
 You can find that the last output is `Hello World!`. or1ksim can be
 much more verbose and give you a full execution trace:
 
-	or1k-sim -f or1ksim.cfg hello.elf -t
+	or1k-elf-sim -f or1ksim.cfg hello.elf -t
 
 This is of course a lot slower and the simulation exits after a
 while. You can finish the simulation before with `CTRL+C`, which will
@@ -40,25 +105,16 @@ command line with `quit`.
 
 ## Run the timer example
 
-	or1k-sim -f or1ksim.cfg timer.elf
+	or1k-elf-sim -f or1ksim.cfg timer.elf
 
 In the terminal you can see an UART output every *simulated*
 second. You can quit this as described before.
 
-## Boot Linux
-
-You can also boot Linux:
-
-	or1k-sim -f or1ksim.cfg ../vmlinux
-
-## (Re-)build the baremetal software
-
-Some example software is available, that you can (re-)build for the
-DE0 nano board by running
+## Next steps
 
-	make build-sw
+Also checkout our tutorial on how to run [Linux on or1ksim](../docs/linux-on-or1ksim.html).
 
-## Links
+## Further Reading
 
  - [openrisc/or1ksim](https://github.com/openrisc/or1ksim) - The home page and git repo
  - [Releases](https://github.com/openrisc/or1ksim/releases) - Nightly build and point release