SystemK

Just a heads up:

Everything in this repository outside of the actual source code is a work in progress. The README, roadmap, and other documentation will be revised. Eventually.

SystemK is a hobby Unix-like operating system implemented in C. It is not intended for actual daily use.

This repository is just an excuse for me to learn about OS development, as well as to write something that can run on older, lower-end hardware. Don't expect anything groundbreaking here.

Compatibility

SystemK is built for the i386 architecture and should run on any x86-compatible CPU. It is tested primarily in QEMU and Bochs, but it should also work on real hardware.

Requirements

• At least Pentium-class CPU (i386 or later).
  • i386 and i486 are not possible at the moment due to SystemK's reliance on GRUB as a bootloader.
• A graphics card that supports either VGA or a framebuffer (VESA BIOS Extensions).
  • Framebuffer support requires at least a 640x480x8 display mode, but higher resolutions are supported as well.
  • 1024x768x32 is the default resolution for the framebuffer build, and a generic 1280x720 widescreen build is also available (continue below for the "Build instructions" section).
• At least 8MB of RAM (assuming you are using the default 1024x768x32 build)
  • Expect this to rise in the future as more features are added, general recommendation is at least 32MB of RAM
  • 640x480 builds require at least 5MB of RAM (GRUB prevents booting with 4MB or less)
  • 1920x1080 builds require at least 16MB of RAM
• A bootable CD-ROM drive or USB drive (for real hardware).
  • For more information on how to properly burn the ISO image, see the "Build instructions" section below.
• Any keyboard should do. No mouse is needed for now.

Tested hardware

• QEMU version 10.0.11 (default CPU, default video, 16MB RAM) (works perfectly)
• Bochs 3.0 (tested with default settings, CPU: Pentium I) (works perfectly)
  • Located in extras is a sample Bochs configuration file that can be used to test SystemK in Bochs.
  • For currently unknown reasons, uptime is not accurate in Bochs, but everything else works perfectly.
• Dell Latitude D520 (Core 2 Duo T7200, 4GB RAM, GMA 950) (works perfectly)

Roadmap

Stuff currently done:

• Kernel boots on virtual and real hardware
• Basic memory management with paging and heap allocation
• Ramdisk and temporary storage support
  • The system itself is still just one kernel.bin file, in the future it will be split into a kernel and a root filesystem.
• A bash-inspired shell with command history and tab completion
• GNU-ish command-line utilities (ls, cat, echo, etc.) and a text editor
• VGA and framebuffer graphics support
  • Includes standard (1024x768) and widescreen (1280x720) modes
  • Boot splash screen for framebuffer displays
• Rudimentary keyboard support
  • Not all keys are mapped yet, but the most common ones are.
  • No mouse support yet
• Serial console support (just for debugging, not for user input)
• Basic timer support and preemptive multitasking scheduling
• CPUID support (for CPU feature detection)
• Modular driver framework for device drivers
• Storage device support (IDE, AHCI SATA, and USB drives) with MBR and GPT partitioning
• Virtual File System (VFS) with FAT32 read and write support
• Process control and background jobs (Ctrl+C, Ctrl+Z, background execution)
• Executable binary loading (ELF)
• ACPI and PCI hardware detection with device name lookup

Stuff planned:

• Ctrl+C for interrupting processes
• Drawing directly to the framebuffer with simple commands
• Implement ACPI support for power management and device enumeration
• Multitasking with multiple processes and threads
  • Ctrl+Z for suspending processes in the background
  • kill command for terminating processes
  • ps command for listing processes
• Split hardware support into separate drivers
• Implement an actual persistent filesystem (FAT32)
  • Once created, we can finally split the kernel and root filesystem into separate files
• Implement a basic windowing system (K Windowing System)
• Sound support (will likely be limited to PC speaker and QEMU AC97 for simplicity)
  • beep command for making sounds with the PC speaker
• Networking (will likely be limited to QEMU's rtl8139 or e1000 for simplicity)
  • A curl-like or wget-like command for downloading files over the internet
  • ping command for testing network connectivity
  • ssh command for connecting to remote servers
  • ftp command for transferring files over the internet
  • scp command for securely copying files over the internet
• ...and more?

More stuff will probably be added to the roadmap when it comes to mind. If you have any suggestions, feel free to open an issue.

Known issues

• Uptime calculation is botched in Bochs despite it working fine in QEMU and on real hardware, will look into later.

Wontfix

• UEFI support
  • i am currently prioritising the functionality and usability of SystemK, so UEFI support is essentially being shelved for now.
• Support for i386 and i486 CPUs
  • SystemK relies on GRUB as a bootloader, which requires a Pentium-class CPU or later. This means that i386 and i486 CPUs are not supported at the moment.
  • I may look into adding support for these CPUs in the future, but it is not a priority at the moment.
• VGA builds have an issue where the cursor and any text input by the user does not appear.
  • The current fix is to clear the console after booting.
  • This is a wontfix because VGA builds will eventually be deprecated in favor of framebuffer builds, which do not have this issue.

Build instructions

These instructions currently assume a Debian-based Linux distribution. Adjust package names and commands for other distributions as needed.

Additionally, no Windows support is provided at this time for building SystemK. If you wish to build it on Windows, you must use a virtual machine or WSL2.

Firstly, install the required dependencies:

sudo apt update
sudo apt install build-essential nasm make qemu-system-x86 xorriso grub-pc-bin dosfstools mtools

After that, you can then clone the repository:

git clone https://git.thesillysociety.net/kooper/systemk.git
cd systemk

The following generic make targets are available (there are more make targets in general however most people do not need to care about them):

Please note that VGA builds have been deprecated as of prerelease 0.0.9, and will eventually be removed entirely.

Additionally, to build SystemK with a different resolution (outside of the defaults) please see the "Make variables" section below.

• make all - builds the standard and widescreen framebuffered ISO images
• make iso-fb (or make fb) - builds the standard framebuffer ISO image (1024x768)
• make iso-fb-720p (or make widescreen) - builds the widescreen framebuffer ISO image (1280x720)
• make iso-vga (or make vga) - builds the VGA fallback ISO image
• make disk (or make disk-fb) - builds a bootable partitioned MBR disk image with FAT32 containing SystemK (1024x768 framebuffer)
• make disk-widescreen (or make disk-720p) - builds a bootable FAT32 disk image (1280x720 framebuffer)
• make disk-vga - builds a bootable FAT32 disk image (VGA fallback)
• make run-disk (or make run-disk-vga) - boots the FAT32 disk image as a hard disk in QEMU
• make run-usb (or make run-usb-vga) - boots the FAT32 disk image attached as a USB mass storage drive in QEMU
• make host-tests - runs a comprehensive host unit and subsystem test suite
• make test-disk - tests booting the FAT32 disk image in QEMU via serial
• make clean - cleans the build directory

The following make variables are available for customizing the build:

• BUILD_TYPE - build profile to use. Options include staging (default), release, staging+debug, and release+debug. Output files will include the build type in their filenames (e.g. build/systemk-staging-fb.iso, build/systemk-staging-fb.img). Builds with +debug enable debug logging and skip the boot splash screen.
• DISK_SIZE_MB - total size of the bootable FAT32 disk image in MiB (defaults to 64)
• DISK_LABEL - FAT32 volume label for the boot partition (defaults to SYSTEMK)
• FRAMEBUFFER_WIDTH - the width of the framebuffer in pixels (at least 640, ideally a multiple of 8, defaults to 1024)
• FRAMEBUFFER_HEIGHT - the height of the framebuffer in pixels (at least 480, ideally a multiple of 16, defaults to 768)
• FRAMEBUFFER_BPP - the bits per pixel of the framebuffer (8, 16, 24, or 32, defaults to 32)
• MEMORY - guest memory size for make run targets (defaults to 32M; numbers without a unit suffix default to KB, e.g. MEMORY=8192 allocates 8192 KB)
• CPU - QEMU CPU model for make run targets (e.g. CPU=pentium, CPU=486)

Now, you should have bootable ISO images (e.g. build/systemk-fb.iso) or bootable FAT32 disk images (e.g. build/systemk-fb.img) in the build/ directory. You can run them in QEMU or Bochs, or burn them to a CD, USB drive, or hard drive/SSD to run on real hardware.

Running SystemK in QEMU

Instructions are for QEMU only.

TODO:

• Add Bochs instructions
• Add instructions for other emulators (e.g. VirtualBox, VMware, etc.)

# Framebuffered build from ISO (standard 1024x768)
make run

# Framebuffered build from FAT32 hard disk image
make run-disk

# Framebuffered build booting from emulated USB flash drive (EHCI)
make run-usb

# Headless runs (serial output directed to terminal)
make run-headless
make run-headless-disk
make run-headless-usb

Running SystemK on real hardware

1. Write the bootable image to a USB flash drive, hard drive, SSD, or CD/DVD:
   • For USB flash drives and hard drives/SSDs, write the .img (or .iso in DD mode) directly to the target block device.
   • If using Rufus on Windows, select the .img file or use "DD Mode" for the ISO.
2. Boot from the USB drive or hard disk and enjoy SystemK!
   • SystemK supports booting from BIOS MBR partitioned disks and USB drives formatted with FAT32.
   • SystemK currently targets legacy BIOS booting. Enable "Legacy Boot" or "CSM" in your UEFI motherboard settings.

# For USB flash drives, hard drives, or SSDs, replace /dev/sdX with your destination block device:
sudo dd if=build/systemk-fb.img of=/dev/sdX bs=4M status=progress && sync

# For CD/DVD:
sudo xorriso -as cdrecord -v dev=/dev/srX -eject build/systemk-fb.iso

Contributing

If you want to contribute, please follow these guidelines:

• Linux only, since we depend on some toolchains that Windows doesn't provide as easily.
• When creating issues or PRs, include steps to reproduce, expected behavior, and actual behavior.
• AI usage is not inherently forbidden, but do not use it to blindly generate code or documentation. Pull requests which are suspected of being "vibecoded" (i.e. majority generated by AI with a lack of understanding) will be closed without review. Use AI to assist, but not to replace your own knowledge and effort.

Credits

Credits go to:

• OSDev.org for their invaluable resources on OS development

The following outside files are included in this repository

• fonts/bizcat.psf: The original 8x16 bitmap font used by SystemK: https://robey.lag.net/2020/02/09/bizcat-bitmap-font.html
  • This font is licensed under the Creative Commons By 4.0 International License.
• fonts/zap-ext-light16.psf: The current 8x16 bitmap font used by SystemK: https://www.zap.org.au/projects/console-fonts-zap/
  • This font is licensed under the GNU General Public License v3.0.

License

This project is licensed under the MIT License. For questions or contributions, please open an issue or submit a pull request.

The source code of SystemK contains a snapshot of the PCI ID Repository database, which is licensed here under GNU GPL v3.0 (said repository accepts both GPL >= v2.0 and BSD-3-Clause). The PCI ID Repository database is maintained by Martin Mares and is available at https://pci-ids.ucw.cz/.