linux: Add instructions for running linux on or1ksim

Author: stffrdhrn

docs/linux-on-or1ksim.md

@@ -0,0 +1,111 @@
+---
+title: Linux on or1ksim
+layout: page
+parent: Linux
+nav_order: 2
+---
+
+# Prerequisites
+
+#### System
+
+ - An x86 Linux workstation
+ - The `curl` and `telnet` command line utilities
+ - 2.5 GB of disk space
+
+#### 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)
+ - [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
+
+# Linux on or1ksim Tutorial
+
+In this tutorial we will cover building a Linux kernel and booting it on or1ksim
+with a [busybox](https://busybox.net) root filesystem.  This is a typical environment which can be used
+to test and develop userspace binaries or do Linux Kernel development.
+
+QEMU is also a good alternative simulator, QEMU provides SMP support and runs much faster.  However,
+or1ksim is an [instruction set simulator](https://en.wikipedia.org/wiki/Instruction_set_simulator) which
+provides more accurate tracing.
+
+We break this tutorial down into parts:
+
+ - Downloading the pieces
+ - Comping the kernel
+ - Running the kernel
+ - Interacting with the simulator
+ - Adding custom userspace programs
+
+## 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/linux-on-or1ksim/
+cd /tmp/linux-on-or1ksim/
+
+# Download linux source, or1ksim, a busybox rootfs and our toolchain
+curl -L -O https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.15.5.tar.xz
+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-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
+
+# Extract everything
+tar -xf linux-6.15.5.tar.xz
+tar -xf or1ksim-2025-04-27.tar.gz
+tar -xf busybox-small-rootfs-20250708.tar.xz
+tar -xf or1k-none-linux-musl-15.1.0-20250621.tar.xz
+
+export PATH=$PATH:$PWD/or1k/bin:$PWD/or1k-none-linux-musl/bin
+```
+
+Building linux
+
+```bash
+make -C linux-6.15.5 \
+  ARCH=openrisc \
+  CROSS_COMPILE=or1k-none-linux-musl- \
+  defconfig
+make -C linux-6.15.5 \
+  -j12 \
+  ARCH=openrisc \
+  CROSS_COMPILE=or1k-none-linux-musl- \
+  CONFIG_INITRAMFS_SOURCE="$PWD/busybox-small-rootfs-20250708/initramfs/ $PWD/busybox-small-rootfs-20250708/initramfs.devnodes"
+```
+
+Booting linux
+
+#### 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
+```
+
+Logging in
+
+#### Terminal 2
+
+In a second terminal while or1ksim is running login to the simulator
+using `telnet`.
+
+```bash
+telnet localhost 10084
+```
+
+## Further Reading
+
+ - [openrisc/or1ksim](https://github.com/openrisc/or1ksim) - The or1ksim home page and git repo
+ - [or1ksim Releases](https://github.com/openrisc/or1ksim/releases) - Nightly build and point release
+ - [Linux Releases](https://kernel.org) - Linux release tarballs
+ - [OpenRISC toolchain Releases](https://github.com/stffrdhrn/or1k-toolchain-build/releases) - Toolchain point releases
+ - [OpenRISC rootfs Releases](https://github.com/stffrdhrn/or1k-rootfs-build/releases) - Rootfs point release