SunsetOS

Table of Contents

• Overview
• Features
• Project Structure
• How It Works
• Requirements
• Build & Run
• Debugging
• License

---

Overview

SunsetOS is my personal exploration into operating system internals, based on a kernel originally developed by Yegane Gholipour. The goal was to understand bootloaders, interrupts, memory management, CPU architecture, and low-level system programming firsthand.

This kernel runs in 32-bit Protected Mode, boots through GRUB, and includes:

• Timer and keyboard drivers
• Custom heap allocator
• Basic interrupt handling

⚠️ Important: The BASE kernel code itself is not mine. I’ve modified and studied it for learning purposes. Full credit goes to Yegane Gholipour for the original code.

By working on this project, I learned:

• How OSes initialize in stages
• Writing low-level C and assembly
• Why modern OS designs are structured the way they are

---

Features

Base Features (Yegane Gholipour)

• Booting

  • GRUB + Multiboot compliant
  • Custom linker script for memory layout
  • Serial output for debugging
  • VGA text output

• Descriptor Tables

  • Global Descriptor Table (GDT)
  • Interrupt Descriptor Table (IDT)

• Interrupts & PIC

  • CPU exceptions
  • Hardware IRQ handling
  • PIC remapping

• Moon Kits (also know as driver)

  • Keyboard and timer drivers
  • Timer ticks at 100 Hz

• Memory Management

  • Parse Multiboot memory map
  • Print free memory blocks
  • Initialize heap and implement kalloc / kfree
  • Memory alignment for allocations

• Debugging

  • Inspect registers and memory with GDB
  • Test PIC, EFLAGS, and segment registers

New Features

---

Project Structure

.
├── boot/         # Bootloader (Multiboot header)
├── gdt/          # Global Descriptor Table
├── idt/          # IDT and IRQ/ISR handling
├── drivers/      # Keyboard, Timer, Serial drivers
├── kernel/       # Core kernel logic and memory management
├── display/      # VGA text mode output
├── grub/         # GRUB configuration
├── include/      # Header files
├── iso/          # ISO build directory
├── linker/       # Linker script
├── build/        # Compiled objects and ISO
└── Makefile      # Build automation

---

How It Works

The boot process roughly follows these steps:

1. Initialize serial output
2. Set up memory manager
3. Initialize GDT & IDT
4. Remap PIC
5. Install keyboard and timer drivers
6. Set up VGA terminal

---

Requirements

• qemu-system-i386 or qemu-system-x86_64
• i686-elf-gcc cross-compiler
• make
• nasm
• gdb-multiarch (for debugging)

---

Build & Run

Build the kernel and ISO:

make

Run in graphical mode:

qemu-system-i386 -cdrom build/sunsetos.iso

Run headless with serial output (recommended):

qemu-system-i386 -cdrom build/sunsetos.iso -nographic -serial mon:stdio

Log output to a file:

qemu-system-x86_64 -cdrom build/sunsetos.iso -serial stdio -machine isapc > qemu.log 2>&1

---

Debugging

Run QEMU in debug mode:

qemu-system-i386 -cdrom build/sunsetos.iso -nographic -serial mon:stdio -s -S

Attach GDB:

gdb-multiarch build/sunsetos.elf
(gdb) target remote localhost:1234
(gdb) break kernel_main
(gdb) continue

---

License

This project uses the MIT License.

⚠️ Credit: The kernel code is originally authored by Yegane Gholipour. This repository is intended for educational purposes and learning only.

See LICENSE for full MIT License text.