Skip to content

Commit 2eceecd

Browse files
stffrdhrnstffrdhrn
committed
linux: Add instructions for running linux on or1ksim
1 parent d4cf837 commit 2eceecd

1 file changed

Lines changed: 238 additions & 0 deletions

File tree

‎docs/linux-on-or1ksim.md‎

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
---
2+
title: Linux on or1ksim
3+
layout: page
4+
parent: Linux
5+
nav_order: 2
6+
---
7+
8+
# Prerequisites
9+
10+
#### System
11+
12+
- An x86 Linux workstation
13+
- The `curl` and `telnet` command line utilities
14+
- 2.5 GB of disk space
15+
16+
#### Files
17+
18+
- [or1ksim.cfg](or1ksim.cfg) - config needed for or1ksim
19+
- [or1ksim-2025-04-27.tar.gz](https://github.com/openrisc/or1ksim/releases/download/2025-04-27/or1ksim-2025-04-27.tar.gz)
20+
- [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
21+
- [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
22+
- [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
23+
24+
# Linux on or1ksim Tutorial
25+
26+
In this tutorial we will cover building a Linux kernel and booting it on or1ksim
27+
with a [busybox](https://busybox.net) root filesystem. This is a typical environment which can be used
28+
to test and develop userspace binaries or do Linux Kernel development.
29+
30+
QEMU is also a good alternative simulator, QEMU provides SMP support and runs much faster. However,
31+
or1ksim is an [instruction set simulator](https://en.wikipedia.org/wiki/Instruction_set_simulator) which
32+
provides more accurate tracing.
33+
34+
We break this tutorial down into parts:
35+
36+
- Downloading the pieces
37+
- Comping the kernel
38+
- Running the kernel
39+
- Interacting with the simulator
40+
- Adding custom userspace programs
41+
42+
## Downloading the Pieces
43+
44+
To get started we will create a temporary directly and setup our environment, if
45+
you plan to do a lot of OpenRISC development consider adding these tools to your
46+
`PATH` permanently.
47+
48+
To get everything you need run:
49+
50+
```bash
51+
mkdir /tmp/linux-on-or1ksim/
52+
cd /tmp/linux-on-or1ksim/
53+
54+
# Download linux source, or1ksim, a busybox rootfs and our toolchain
55+
curl -L -O https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.15.5.tar.xz
56+
curl -L -O https://github.com/openrisc/or1ksim/releases/download/2025-04-27/or1ksim-2025-04-27.tar.gz
57+
curl -L -O https://github.com/stffrdhrn/or1k-rootfs-build/releases/download/or1k-20250708/busybox-small-rootfs-20250708.tar.xz
58+
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
59+
60+
# Extract everything
61+
tar -xf linux-6.15.5.tar.xz
62+
tar -xf or1ksim-2025-04-27.tar.gz
63+
tar -xf busybox-small-rootfs-20250708.tar.xz
64+
tar -xf or1k-none-linux-musl-15.1.0-20250621.tar.xz
65+
66+
export PATH=$PATH:$PWD/or1k/bin:$PWD/or1k-none-linux-musl/bin
67+
```
68+
69+
## Building Linux
70+
71+
To build a Linux kernel we use the toolchain, kernel source code and rootfs just downloaded
72+
in the following make commands:
73+
74+
```bash
75+
make -C linux-6.15.5 \
76+
ARCH=openrisc \
77+
CROSS_COMPILE=or1k-none-linux-musl- \
78+
defconfig
79+
make -C linux-6.15.5 \
80+
-j12 \
81+
ARCH=openrisc \
82+
CROSS_COMPILE=or1k-none-linux-musl- \
83+
CONFIG_INITRAMFS_SOURCE="$PWD/busybox-small-rootfs-20250708/initramfs/ $PWD/busybox-small-rootfs-20250708/initramfs.devnodes"
84+
```
85+
86+
The first command configures the kernel with the default configuration `defconfig` which is the `or1ksim` configuration. The `make`
87+
arguments are as follows:
88+
89+
* `-C linux-6.15.5` - This saves us from having to change directory, `make` will run from within the Linux source code directory.
90+
* `ARCH=openrisc` - This passes the `ARCH` variable to the build system selecting the OpenRISC architecture.
91+
* `CROSS_COMPILE=or1k-none-linux-musl-` - This passes the `CROSS_COMPILE` variable to the build system selecting our toolchain.
92+
* `defconfig` - The make target, configures the linux kernel for the build.
93+
94+
The second command builds the kernel. The new argument is:
95+
96+
* `CONFIG_INITRAMFS_SOURCE=...` - This configures the built in root filesystem.
97+
98+
When running on machines with no disk capabilities such as `or1ksim` we can use an [initfamfs](https://www.kernel.org/doc/Documentation/filesystems/ramfs-rootfs-initramfs.txt)
99+
that is build directly into our kernel ELF binary. This is one of the most simple ways to boot Linux
100+
but it means that our data will be lost after reset. Also, it means that updating userspace utilties
101+
requires rebuilding the kernel.
102+
103+
## Booting the System
104+
105+
To start Linux on `or1ksim` we run `or1k-elf-sim` passing the kernel as an argument.
106+
This will:
107+
108+
# Initialize the OpenRISC simulator
109+
# Load the kernel image, including the embedded rootfs, into RAM memory
110+
# Reset the simulator CPU to PC 0x100 kicking off the kernel boot process
111+
112+
The `or1ksim` starts a console on port `10084` which we can connect to to access
113+
the system.
114+
115+
#### Terminal 1
116+
117+
```bash
118+
# Download an example config for or1ksim
119+
curl -L -O https://github.com/stffrdhrn/or1k-utils/raw/refs/heads/master/or1ksim.cfg
120+
121+
or1l-elf-sim -f or1ksim.cfg linux-6.15.5/vmlinux
122+
```
123+
124+
In a second terminal while or1ksim is running login to the simulator
125+
using `telnet`.
126+
127+
#### Terminal 2
128+
129+
```bash
130+
telnet localhost 10084
131+
```
132+
133+
To exit `or1ksim` press: `Ctrl+c`
134+
135+
To exit `telnet` press: `Ctrl+]`
136+
137+
## Adding User Space Programs
138+
139+
To add your own programs to the rootfs you can use the [musl](https://musl.libc.org)
140+
toolchain to build executables as follows:
141+
142+
```
143+
or1k-none-linux-musl-gcc hello.c -o busybox-small-rootfs-20250708/initramfs/hello
144+
```
145+
146+
This compiles the `hello.c` program and outputs the binary directly into our rootfs
147+
root directory. The toolchain and rootfs runtime support c and c++ programs.
148+
149+
Once programs are added we must recompile the kernel as done in step 2 above of
150+
*Building Linux*.
151+
152+
## Example Boot Sequence
153+
154+
#### Terminal 1
155+
156+
```
157+
$ or1l-elf-sim -f or1ksim.cfg linux-6.15.5/vmlinux
158+
Seeding random generator with value 0xb89aeeb2
159+
Insn MMU 0KB: 1 ways, 64 sets, entry size 1 bytes
160+
Data MMU 0KB: 1 ways, 64 sets, entry size 1 bytes
161+
Ethernet TAP type
162+
Verbose on, simdebug off, interactive prompt off
163+
Machine initialization...
164+
Clock cycle: 10ns
165+
No data cache.
166+
No instruction cache.
167+
BPB simulation off.
168+
BTIC simulation off.
169+
Or1ksim 2025-04-27
170+
Building automata... done, num uncovered: 0/215.
171+
Parsing operands data... done.
172+
Warning: Failed to set TAP device tap0: Operation not permitted
173+
Or1ksim: Console listening for telnet on port 10084
174+
UART at 0x90000000
175+
Resetting Tick Timer.
176+
Resetting Power Management.
177+
Resetting PIC.
178+
Starting at 0x00000000
179+
loadcode: filename linux-6.15.5/vmlinux startaddr=00000000 virtphy_transl=00000000
180+
...
181+
IP idents hash table entries: 2048 (order: 1, 16384 bytes, linear)
182+
tcp_listen_portaddr_hash hash table entries: 2048 (order: 0, 8192 bytes, linear)
183+
Table-perturb hash table entries: 65536 (order: 5, 262144 bytes, linear)
184+
TCP established hash table entries: 2048 (order: 0, 8192 bytes, linear)
185+
TCP bind hash table entries: 2048 (order: 1, 16384 bytes, linear)
186+
TCP: Hash tables configured (established 2048 bind 2048)
187+
UDP hash table entries: 256 (order: 0, 8192 bytes, linear)
188+
UDP-Lite hash table entries: 256 (order: 0, 8192 bytes, linear)
189+
NET: Registered PF_UNIX/PF_LOCAL protocol family
190+
RPC: Registered named UNIX socket transport module.
191+
RPC: Registered udp transport module.
192+
RPC: Registered tcp transport module.
193+
RPC: Registered tcp-with-tls transport module.
194+
RPC: Registered tcp NFSv4.1 backchannel transport module.
195+
workingset: timestamp_bits=30 max_order=12 bucket_order=0
196+
Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled
197+
printk: legacy console [ttyS0] disabled
198+
90000000.serial: ttyS0 at MMIO 0x90000000 (irq = 2, base_baud = 1250000) is a 16550A
199+
printk: legacy console [ttyS0] enabled
200+
printk: legacy console [ttyS0] enabled
201+
printk: legacy bootconsole [ns16550a0] disabled
202+
printk: legacy bootconsole [ns16550a0] disabled
203+
-- dcache disabled
204+
-- icache disabled
205+
NET: Registered PF_PACKET protocol family
206+
clk: Disabling unused clocks
207+
Freeing unused kernel image (initmem) memory: 5368K
208+
This architecture does not have kernel memory protection.
209+
Run /init as init process
210+
ethoc 92000000.ethoc eth0: Link is Up - 10Mbps/Full - flow control off
211+
212+
Please press Enter to activate this console.
213+
```
214+
215+
#### Terminal 2
216+
217+
```
218+
$ telnet localhost 10084
219+
Trying 127.0.0.1...
220+
Connected to localhost.
221+
Escape character is '^]'.
222+
223+
~ # uname -a
224+
uname -a
225+
Linux openrisc 6.15.5 #2 Tue Jul 8 21:43:25 BST 2025 openrisc GNU/Linux
226+
~ # exit
227+
exit
228+
229+
Please press Enter to activate this console.
230+
```
231+
232+
## Further Reading
233+
234+
- [openrisc/or1ksim](https://github.com/openrisc/or1ksim) - The or1ksim home page and git repo
235+
- [or1ksim Releases](https://github.com/openrisc/or1ksim/releases) - Nightly build and point release
236+
- [Linux Releases](https://kernel.org) - Linux release tarballs
237+
- [OpenRISC toolchain Releases](https://github.com/stffrdhrn/or1k-toolchain-build/releases) - Toolchain point releases
238+
- [OpenRISC rootfs Releases](https://github.com/stffrdhrn/or1k-rootfs-build/releases) - Rootfs point release

0 commit comments

Comments
 (0)