Skip to content

toy kernel written in C++ for x86-64 machines with the mere purpose of learning OS development

Notifications You must be signed in to change notification settings

ecomaikgolf/alma

Repository files navigation

alma is a toy kernel written in C++ for x86_64 machines with the mere purpose of learning OS development

alma

  1. f. Sustancia o parte principal de cualquier cosa.

Features

Note: GIF quality is vastly reduced and native executions look clear

alma build system
  • Setup toolchain
    • apt install ...
    • make -C toolchain
    • alma build vm
  • Configure with cmake
    • Out of source builds
    • Recompile only what is needed
  • Build with make or ninja
    • default target (build iso)
    • target run (qemu)
    • target debug (remote gdb)
    • target doc (doxygen)
  • Speedup with ccache if found
alma kernel
  • Tested in real hardware
  • Stivale2 specification
  • Call ctors and dtors
  • Rendering
    • simple rendering
    • fast console rendering
    • PSF1 fonts
  • Segmentation
    • Naive GDT
  • Paging
    • Virtual Memory
    • Page Allocation
  • Keyboard
    • PS2 Keyboard Support
    • symbols & mayus
  • Networking
    • RTL8139 Driver
  • ACPI
    • Query Tables
  • PCI
    • MCFG From ACPI
    • MMIO Configuration
    • Enumerate dev/bus/func
  • Interrupts
    • Manage IDT
    • Register Interrupts
  • Dynamic Memory
    • malloc
    • free
alma bootloader
  • Deprecated
    • alma uses stivale2
    • ships with the limine botloader  
  • posix-uefi
  • Load ELF
    • Parse headers
    • Load segments
  • Initialization tasks
    • GOP
    • Memory Map
    • RSDP
    • PSF1
  • Kernel launch
    • Call ctors
    • Exit UEFI Services
    • Jump to entry point

Run

  1. Install qemu:

Ubuntu:

apt install qemu-system-x86 qemu-system-gui

Arch Linux:

pacman -S qemu qemu-arch-extra
  1. Find a build to test https://ls.ecomaikgolf.com/alma/builds/

  2. Download a build with wget:

wget https://ls.ecomaikgolf.com/alma/builds/CHANGEME.tar.gz
tar xf CHANGEME.tar.gz
cd CHANGEME
  1. Run
qemu-system-x86_64 -machine q35 -cpu qemu64 -m 256M -bios bios.bin -netdev user,id=user.0 -device rtl8139,netdev=user.0,mac=ca:fe:c0:ff:ee:00 -object filter-dump,id=f1,netdev=user.0,file=log.pcap -boot d -cdrom alma.iso

If you want to run it in real hardware, flash it to a USB device:

sudo dd bs=4M if=alma.iso of=/dev/CHANGEME conv=fdatasync status=progress

Remember that you must have certain hardware for it to work (PS2 keyboard, RTL8139 NIC, PCIe...). Even with that, running in real hardware is a dark dark place... things can go wrong.

Build

Virtual Machine (Method 1)

  1. Download the alma build vm .ova (a 6.31GB Xubuntu 20.04 virtualbox VM ready to compile)

  1. Compile with the "Build Alma" icon
  2. Run with the "Run Alma" icon
  3. Update (pull) with the "Update Alma" icon

Manual (Method 2)

Note: Instructions tested on Ubuntu 20.04

  1. Install dependencies
apt install nasm iasl cmake make qemu-system-x86 qemu-system-gui git uuid-dev python python3-distutils bash texinfo bison flex build-essential mtools
  1. make -C toolchain/
  • EDKII build can be manually disabled if a compiled binary is provided or not using UEFI
  • posix-uefi build can be manually disabled if bootloader is not going to be built (default behaviour)
  1. cmake -B build or cmake -B build -GNinja
  2. make -C build run or ninja -C build run

Mirrors

Bugs

Please explain them to me: me 𝒂𝒕 ecomaikgolf ꓒσ𝗍 c0m

Take into acccount this is a Bachelor Final Project and has been developed under the pressure of a deadline among other subjects. Some things could be improved, for example, with better (and more complex) data structures, but it's not the goal of the project.

FAQ

Q: Muh tons of dependencies

A: I'm compiling binutils, gdb, edk2 and posix-uefi from source

Q: 6.31GB VM

A: I can't do more. Xubuntu + "zeroed" free memory before exporting so it can be compressed.

Q: Frequently asked questions?

A: More like preanswered questions

Bibliography

The list is longer but I can't put each site where I read something. This list is a good place to start

Author

Ernesto Martínez García