Jarvis OS (AOS) - Modern 64-bit Educational Kernel

A high-performance x86_64 monolithic operating system kernel built from scratch in C and Assembly, featuring 64-bit Long Mode, hybrid UEFI & Legacy BIOS boot, 4-level paging, FAT32 filesystem support, APIC interrupt management, preemptive task scheduling, and an interactive shell.

---

📑 Table of Contents

• Features & System Capabilities
• Architecture Overview
• Prerequisites & Dependencies
• Building & Running Locally
• Running on Real Hardware (USB Boot)
• Interactive Shell Commands
• Directory Structure
• Documentation & Learning

---

🚀 Features & System Capabilities

• ⚡ 64-bit Long Mode Execution: Full x86_64 architecture support with 64-bit register set (RAX-R15), 64-bit GDT/IDT descriptors, and 48-bit canonical virtual address translation.
• 📀 Hybrid UEFI & BIOS Boot: GRUB Multiboot2 / Multiboot1 hybrid ISO supporting seamless boot on modern UEFI machines as well as legacy BIOS systems.
• 🗺️ 4-Level Paging (VMM): PML4 → PDPT → PD → PT virtual memory hierarchy mapping higher-half kernel space and physical RAM.
• 🧠 Physical Memory Manager (PMM): Page frame allocation via bitmap manager supporting up to multi-gigabyte RAM configurations.
• 💾 Kernel Heap Allocator (kmalloc/kfree): Dynamic kernel heap allocation supporting scaling for kernel data structures and dynamic objects.
• 📁 FAT32 Filesystem & ATA PIO Driver: Native IDE/ATA hard disk driver with a full FAT32 filesystem implementation.
• 🛠️ Embedded 64MB FAT32 RAM Disk: Boot-loaded RAM filesystem (JARVISFS) populated at startup for zero-hardware disk dependencies.
• ⚙️ Interrupts & Timer: Advanced APIC / IO-APIC logic and 8259 PIC fallback routing with PIT-driven preemptive multitasking.
• 💻 Interactive Kernel Shell: Colorized shell with TAB auto-completion, filesystem commands, and CPU/system diagnostic tools.

---

🏗️ Architecture Overview

+----------------------------------------------------------------+
|                        Jarvis OS Shell                         |
|   (ls, cd, cat, touch, write, rm, mkdir, ps, sysinfo, cpuid)   |
+----------------------------------------------------------------+
|                   Kernel Core Subsystems                       |
|  +--------------------+  +------------------+  +-------------+ |
|  | Task Scheduler     |  | FAT32 Filesystem |  | Heap Alloc  | |
|  | (Round-Robin)      |  | & ATA Driver     |  | (kmalloc)   | |
|  +--------------------+  +------------------+  +-------------+ |
|  +-----------------------------------------------------------+ |
|  |  Virtual Memory (VMM) & Physical Memory Manager (PMM)     | |
|  +-----------------------------------------------------------+ |
|  |  GDT / IDT / APIC Interrupt Routing & Exception Handling   | |
+----------------------------------------------------------------+
|                Hardware Layer / QEMU Emulator                  |
|          x86_64 CPU | 4-Level Paging | GOP / VGA | ATA/RAMDisk   |
+----------------------------------------------------------------+

---

🛠️ Prerequisites & Dependencies

To build and run Jarvis OS on a Linux machine (Ubuntu, Debian, Kali, Fedora, Arch), install the following tools:

Debian / Ubuntu / Kali Linux

sudo apt update
sudo apt install -y \
    build-essential \
    gcc \
    nasm \
    grub-pc-bin \
    grub-efi-amd64-bin \
    xorriso \
    mtools \
    dosfstools \
    qemu-system-x86 \
    ovmf

Fedora / RHEL

sudo dnf install -y \
    gcc \
    make \
    nasm \
    grub2-tools-extra \
    xorriso \
    mtools \
    dosfstools \
    qemu-kvm \
    edk2-ovmf

---

💻 Building & Running Locally

The primary build script is run.sh. It cleans the build environment, assembles Assembly sources (nasm), compiles C sources (gcc), links the 64-bit kernel (ld), generates a 64MB FAT32 RAM disk, builds a hybrid BIOS/UEFI ISO (jarvis.iso), and launches QEMU.

1. Build the OS (Generate ISO & Disk Images)

./run.sh

Outputs generated:

• jarvis.iso / jarvis_uefi.iso — Hybrid BIOS + UEFI bootable ISO image.
• disk.img — 128 MB FAT32 disk image for QEMU testing.
• ramdisk.img — 64 MB FAT32 image embedded into the ISO.

---

2. Run in QEMU (Legacy BIOS Mode)

./run.sh --run

---

3. Run in QEMU (Modern UEFI Mode)

./run.sh --run --uefi

(Uses OVMF firmware to simulate a modern UEFI system with GOP graphical console)

---

4. Run in QEMU (Headless / Terminal Mode)

./run.sh --run --nographic

(Press Ctrl+A then X to exit QEMU in headless mode)

---

🔌 Running on Real Hardware (USB Boot)

Jarvis OS produces a hybrid ISO (jarvis.iso) compatible with both legacy BIOS and modern UEFI hardware.

Flashing via Linux (dd)

Find your USB drive identifier (e.g., /dev/sdX using lsblk), then run:

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

Flashing via Windows

Use Rufus or balenaEtcher:

1. Select jarvis_uefi.iso or jarvis.iso.
2. Target: DD Image mode (or standard ISO mode).
3. Boot your PC into BIOS/UEFI setup and select the USB drive.

---

🖥️ Interactive Shell Commands

Once Jarvis OS boots, you will be greeted by the custom shell prompt:

Command	Description
ls [path]	List files and directories in FAT32 filesystem
cd <path>	Change current working directory
cat <file>	Display contents of a text file
touch <file>	Create a new empty file
write <file> <text>	Write text content to a file
rm <file>	Delete a file
mkdir <dir>	Create a new directory
rmdir <dir>	Delete an empty directory
ps	Display active kernel tasks and process states
mem	Display physical memory & heap stats
sysinfo	Display detailed system hardware & kernel report
cpuid	Query x86_64 CPU vendor, model, features, and Long Mode
arch	Display kernel architecture, paging, and register specs
clear	Clear screen output
reboot	Perform system reboot
help	Show available shell commands

💡 Tip: Press TAB for automatic filename completion in the shell.

---

📁 Directory Structure

AOS/
├── DOCUMENTATION.md           # Comprehensive technical documentation & tutorials
├── README.md                  # Main project guide (this file)
├── .gitignore                 # Excludes build binaries, ISOs, and raw disk images
├── run.sh                     # Automated build and run script
├── link.ld                    # Linker script for 64-bit kernel ELF
├── test_boot.sh               # Quick boot test helper script
├── test_uefi_console.sh       # UEFI GOP console test script
├── include/                   # Kernel C header files
│   ├── acpi.h, ata.h, fat32.h, gdt.h, idt.h, io.h, kmalloc.h
│   ├── math.h, pci.h, pmm.h, screen.h, shell.h, string.h, task.h, timer.h, vmm.h
├── src/                       # Kernel source code
│   ├── arch/x86_64/           # GDT, IDT, ACPI, Assembly loaders (loader.s, interrupts.s)
│   ├── core/                  # Main kernel entry (kernel.c), Shell, Multitasking
│   ├── drivers/               # ATA PIO, PS/2 Keyboard, PCI, VGA Screen
│   ├── fs/                    # FAT32 Driver implementation
│   ├── libc/                  # Builtin math and string helper libraries
│   └── mm/                    # Physical (PMM), Virtual (VMM), and Heap (kmalloc) memory managers
└── iso/                       # Staging directory for GRUB ISO creation

---

📚 Documentation & Tutorials

For a complete breakdown of kernel internals, step-by-step learning paths, and architecture design details, refer to:

• DOCUMENTATION.md — Architectural deep-dive and 12-step educational tutorial index.

---

📄 License

Jarvis OS is open-source software licensed under the MIT License.