HighlightOS

x86_64 OS (kernel) made completely from scratch in Assembly & Rust

This documentation includes only the "main kernel" (inside the /kernel directory).

Documentation for bleeding-edge main can be found at https://os.adamperkowski.dev/main.

Keep in mind that this website is still a WIP.

Contributors

Usage

Running in QEMU on Linux

Requirements:

Steps:

  1. cd into directory that contains the binary.
  2. Run the following command:
qemu-system-x86_64 -drive format=raw,file=<your_binary_filename>.bin

Replace <your_binary_filename> with the actual name of the HighlightOS binary.

Running on real hardware

You can also flash the binary image onto a USB stick and boot it on a real machine.

You can flash it by running the following command:

dd if=<your_binary_filename>.bin of=/dev/sdX && sync

Make sure to replace <your_binary_filename>.bin with your downloaded/compiled binary name and make sure to replace /dev/sdX with your USB's actual partition number.
Any data on it will be lost!

You can choose the device to boot off of from your BIOS boot menu (accessible by pressing F2, F8 or F12 - depending on your motherboard).

Double-check that your motherboard is capable of booting legacy media(s), as HighlightOS is not UEFI-compatible yet.

Building from source

Main kernel (on x86_64 Linux)

Requirements:

Steps:

  1. Install the nightly toolchain:
rustup toolchain install nightly
  1. Install required components:
rustup component add rust-src --toolchain nightly-x86_64-unknown-linux-gnu && rustup component add llvm-tools-preview --toolchain nightly-x86_64-unknown-linux-gnu && cargo install bootimage
  1. Create a local clone of the repository:
git clone [email protected]:adamperkowski/highlightos.git && cd highlightos
  1. cd into the kernel/ directory:
cd kernel
  1. Build the bootable binary:
cargo bootimage --release

This command will create a target/target/release directory in which you'll find the bootimage-hlkernel.bin binary file.

Core structure

Prompt input

Current buffer can be interrupted by pressing F1.

The shell keeps a history of all commands executed.
History can be browsed with the history command or ↑ and ↓ keys.

Command return codes

  • 0 > executed successfully
  • 1 > "silent" return code - doesn't show the message
  • 2 > returned general error (minor)
  • 3 > returned critical error (could not recover)
  • 4 > returned user error (ex. incorrect input)

Colors

Currently available colors (user):

  • black
  • blue
  • green
  • cyan
  • red
  • magenta
  • brown
  • lightgray
  • lightgreen
  • lightcyan
  • lightred
  • yellow
  • white

Built-in commands

  • clrs > clears the screen
  • help > shows the list of built-in commands
  • test > this one always returns 2 (see return codes)
  • cc > displays copyright info (see license)
  • getdoc [cmd] > displays a short summary of provided command
  • chcolor [fg] [bg] > changes console text colors (see available colors)

DEBUG commands:

  • crash_kernel > panic!s the system