Warning! Almost nothing is complete yet. Everything here is experimental AND in VERY ACTIVE development. Proceed with caution.

Motivation

Computers are weird. Weird in the sense that they feel magical if you don't know how they work. If, and when, you start learning how it works, that magical feeling fades away. You will either end up with "Wow! This is brillaint" or "Wow... this is shit."

So, you have basically two options:

• Take the blue pill: Continue using the computer like normal. Magical feeling!
• Take the red pill: Go on a learning frenzy. Risk of ending up as mad men +45%

In case it wasn't obvious yet, I took the latter.

Basically, I wanted to learn more about "computers". Working on the relatively high-level software is pretty fun, but I have a bad habit of ending up looking at low-level internels and workings of stuff.

"Oh, so my calls to malloc() and new ends up calling the syscall mmap()? Let's check it's implementation.. Oh, what's VMA? What's a MMU? What's a TLB?? What's the TCR and the MAIR??? How did I get here? Why am I here.. Just to suffer..? :("

There was these layers of abstraction that I had no idea of! I should've stopped there, but no. Instead, I said: "Okay. I really like the call-of-the-void feeling of low-level stuff. Let's go wild and try to learn all the abstractions by writing a 'simple' operating system. What could go wrong?" And now, here I am.

WesterOS

Work-in-progress hobbyist operating system /w "hand-made" microkernel. The name is from the most political & messed-up continent in the world of Game of Thrones.[^2] I really like GoT (yeah, judge me all you want) and the political messiness of it felt similar to my own goals with this project. Everything is all over the place and nothing makes sense.

This project exists only to help me learn about operating systems and to have some fun along the way. I don't claim to know much about OS development. So, the practices, design chocies and some implementations you see here WILL scare you.

I suggest to kepp your expectations LOW >.<

Important Note: WesterOS is in very early development. Stuff WILL change, brake or straight-up be stupid. I am still yet to define an end goal. Until then expect Everything, Everywhere, All at Once.

Features

• ARM64 Microkernel design /w non-preemptive RR scheduling
• Unix-like syscalls (still yet to be determined)
• Virtual File System like /dev and /proc (idk if this is possible?)
• Virtual Memory Management /w 4K page sizes (wow. what a feature, eh?!)
• CLI based interface /w basic shell commands like mkdir, touch & cat
• Simple userland apps (Hmm.. What kind of games should I "make"?)

Overview

Let's dive a bit more into inner working of things. The target machine is very specific & static. I wanted to keep it as simple as possible by supporting only the ARM64 architecture (ARMv8) and QEMU's ARM Virt machine.

Here's the target machine.

Only the must basic peripherals are defined. Sadly, this means no USB, NVME and NIC. :( Maybe in the future?

Here's the peripherals that I plan to support.

• ARM PrimeCell RTC PL031
• ARM PrimeCell UART PL011
• ARM PrimeCell GPIO PL061
• QEMU RAM FrameBuffer (?)

The kernel follows a simple microkernel design (like the L4-family). I wanted to make a simple kernel that is easy to understand and help me learn as much as possible during the process.

I initially followed the MIT's xv6. However, when asked, people told me that it was a bit too "naive/cheap" and would probably not help me IRL (they are amazing people btw). So, I decided to take their advice and go with a microkernel design. it also seems more interesting o.o

Warning! My hand-made microkernel design WILL trigger you. For example, I put the device drivers in the user space AND the scheduler inside the kernel space (basically not really following a "proper/acedemic" design).

Just give me some time. I am still learning as I go >.<

Here's an overall overview of the kernel.

TODO: Overall OS specifications. What is what and the future goals.

Directory Structure

|-- Build              <- Compiled objects, binaries & debug files
|-- Documents          <- Reference documents
|-- Emulation          <- QEMU scripts & Device Tree Structure
|-- Kernel             <- The source code. Headers, C and C++ files
|   `-- Arch           <- Architecture related code
|   `-- Drivers        <- Driver source and header files
|   `-- Library        <- Library source and header files
|   `-- Include        <- Kernel header files
|-- Media              <- Images and other media
|-- Toolchain          <- Cross-compiling environment
|-- Userland           <- User level source code
|   `-- Dir.           <- TBD.
|-- .gitignore         <- Good ol' .gitignore
|-- Makefile           <- Makefile
`-- README.md          <- Main README

Bootstrapping

TODO: How does everything starts? Why the things I do are the way they are?

Kernel

TODO: Tell everyone why I choose to follow a simple_microkernel_ design approach instead of a generic/typical monolothic one (maybe even seL4?)

Userland

TODO: Some fun stuff. What awaits someone one they launch the OS?

Installation

To build & run the operating system you need three main things: ARM GNU Toolchain, QEMU and a little bit of Patience™.

It is possible to build everything on your favorite operating system. ARM GNU Toolchain is available on both Windows, macOS and GNU/Linux. However, I have NOT tested Windows yet. So, you are alone in that space. Sorry :(

The below steps are for GNU/Linux (Aarch64) hosts.

0. Make sure you have git and make

$ apt install git make # if using `apt`
$ pacman -S git make # if using `pacman`

1. Clone this repository

$ git clone https://github.com/TunaCici/WesterOS.git

2. Download the latest ARM GNU Toolchain

Navigate to ARM GNU Toolchain Downloads web page.

Choose the appropriate Aarch64 bare-matel target to download. The version should not matter, so choose the latest one. However, which hosted toolchain you download DOES matter. Choose the one that is created for your OWN operating system.

For example, if your OS is GNU/Linux (x86_64) then you download:

https://developer.arm.com/-/media/Files/downloads/gnu/12.2.rel1/binrel/arm-gnu-toolchain-12.2.rel1-x86_64-aarch64-none-elf.tar.xz

$ cd WesterOS/Toolchain
$ wget https://developer.arm.com/-/media/Files/downloads/gnu/12.2.rel1/binrel/arm-gnu-toolchain-12.2.rel1-aarch64-aarch64-none-elf.tar.xz

It is your responsibility to verify the "integrity" and "signature" of the downloaded file. Use the SHA256 keys provided in the downloads page.

3. Extract the downloaded ARM GNU Toolchain

Make sure to extract it while in Westeros/Toolchain.

$ tar -xvf arm-gnu-toolchain-12.2.rel1-aarch64-aarch64-none-elf.tar.xz

4. Modify the TOOLCHAIN_PATH in the Makefile

The TOOLCHAIN_PATH should point to your newly downloaded and extracted ARM GNU Toolchain. Since your host OS and toolchain version might be different than mine, you MUST edit the PATH variable.

If not set correctly, the make process WILL fail with an error message like:

make[1]: Toolchain/arm-gnu-toolchain-12.2.rel1-darwin-arm64-aarch64-none-elf/bin/aarch64-none-elf-as: No such file or directory

So, make sure to edit the TOOLCHAIN_PATH.

# Open the main Makefile /w your favorite text editor
$ vim Makefile

# And change the `TOOLCHAIN_PATH` accordingly. For example..
> TOOLCHAIN_PATH=Toolchain/arm-gnu-toolchain-12.2.rel1-darwin-arm64-aarch64-none-elf

# Save & exit

5. Build using make

$ make all

The build ends with a message Build complete. Enjoy life <3. If you don't see it, contact me. I'll try the fix the issue >.<

Run/Emulate

WesterOS can ONLY be run using QEMU. I have no plans to make a fully-bootable image for real-world hardware. Originally my idea was to emulate a Raspberrry Pi 4b, but I realized it might not that be "beginner friendly" when testing and deubgging. So, QEMU it is!

Shameless plug time! If you want more about QEMU, visit my QEMU_Starter GitHub thingy.

0. Make sure you have qemu-system-aarch64 installed

$ apt install qemu-system qemu-utils # if using `apt`
$ pacman -S qemu-full # if using `pacman`

1. Launch WesterOS

$ make run

As of 9 July 2023, the WesterOS is straight-up empty! So, you can't do anything except to see some very basic kernel messages on the terminal :/

Then again, WesterOS is a hobbyist operating system and a learning process. You should really try to explore it's source code. I'm sure you will have more fun there.

Explore

TODO: Navigate the user to another README which is basically the documentation.