A research-oriented operating system kernel built from scratch to explore low-level systems programming, x86 architecture, interrupts, process management, scheduling, memory management, and kernel design.
- About
- Project Goals
- Current Status
- Features
- Architecture
- Boot Flow
- Technology Stack
- Repository Structure
- Development Phases
- Building AyushOS
- Running in QEMU
- Debugging with GDB
- Kernel Subsystems
- Development Workflow
- Testing Strategy
- Roadmap
- Research Direction
- Learning Outcomes
- Limitations
- Contributing
- License
AyushOS is an experimental operating-system kernel developed from scratch for learning and researching how computers work at the hardware/software boundary.
The project starts at the bootloader and kernel-entry level and progressively introduces fundamental operating-system concepts:
- CPU execution
- x86 protected mode
- Kernel initialization
- Global Descriptor Table (GDT)
- Interrupt Descriptor Table (IDT)
- CPU exceptions
- Programmable Interrupt Controller (PIC)
- Hardware IRQs
- Timer interrupts
- Keyboard input
- Process management
- CPU context switching
- Physical memory management
- Scheduling
- User/kernel separation
- System calls
- Virtual memory
- Filesystems
- Networking
- Kernel security
- Multicore execution
The primary goal is understanding how an operating system works internally, rather than creating a production replacement for Linux or another mature operating system.
AyushOS follows a bottom-up systems-engineering approach:
Understand
↓
Design
↓
Implement
↓
Boot
↓
Test
↓
Debug
↓
Measure
↓
Document
↓
Research
Each major subsystem is intended to eventually include:
- Implementation
- Architecture documentation
- Validation/testing
- Debugging support
- Performance measurements
- Design notes
AyushOS is currently an experimental development kernel.
The repository already contains the foundational x86 kernel infrastructure including:
- GRUB boot path
- x86 assembly bootstrap
- Kernel entry point
- VGA terminal output
- Kernel logging
- GDT
- IDT
- Interrupt/exception infrastructure
- PIC
- IRQ handling
- Timer infrastructure
- Keyboard driver
- Process-management infrastructure
- Assembly-backed context switching
The repository currently contains 14 commits and is actively structured around incremental OS-development phases.
| Phase | Component | Status |
|---|---|---|
| 0 | Development Environment | ✅ |
| 1 | Boot + Kernel Entry | ✅ |
| 2 | Terminal + Logging | ✅ |
| 3 | GDT | ✅ |
| 4 | IDT + Exceptions | ✅ |
| 5 | PIC + IRQ | ✅ |
| 6 | Timer + Keyboard | ✅ |
| 7 | Physical Memory | 🔄 |
| 8 | Process Management | 🔄 |
| 9 | Preemptive Scheduler | 🔄 |
| 10 | User Mode + System Calls | ⏳ |
| 11 | Virtual Memory | ⏳ |
| 12 | Kernel Heap | ⏳ |
| 13 | Virtual File System | ⏳ |
| 14 | Filesystem | ⏳ |
| 15 | Shell | ⏳ |
| 16 | ELF Loader | ⏳ |
| 17 | Networking | ⏳ |
| 18 | Security Research | ⏳ |
| 19 | SMP / Multicore | ⏳ |
| 20 | OS Research Platform | ⏳ |
Legend: ✅ Implemented foundation 🔄 Currently being developed ⏳ Planned / future work
The status above reflects implementation maturity rather than simply whether a source file exists.
AyushOS uses GRUB to load the kernel and transfer execution to the kernel entry point.
BIOS / Firmware
↓
GRUB
↓
boot.asm
↓
Kernel Entry
↓
kernel_main()
The kernel provides low-level terminal functionality using VGA text memory.
Current functionality includes:
- Character output
- String output
- Integer formatting
- Kernel logging
- Diagnostic messages
- Debug output
Example:
[ OK ] Terminal initialized
[ OK ] GDT initialized
[ OK ] IDT initialized
[ OK ] PIC initialized
[INFO] Kernel boot complete
The Global Descriptor Table establishes the segmentation model required by the x86 protected-mode environment.
The architecture includes descriptors for:
GDT
├── Null Descriptor
├── Kernel Code Segment
├── Kernel Data Segment
├── User Code Segment
└── User Data Segment
The Interrupt Descriptor Table provides the foundation for CPU exceptions and hardware interrupts.
CPU
│
├── Exception
│
└── Interrupt
↓
IDT
↓
ISR / Handler
↓
Kernel
The design includes infrastructure for handling common CPU exceptions such as:
- Divide Error
- Debug
- Breakpoint
- Invalid Opcode
- Double Fault
- General Protection Fault
- Page Fault
AyushOS uses the traditional x86 Programmable Interrupt Controller infrastructure.
Hardware Device
↓
8259 PIC
↓
IRQ
↓
IDT Vector
↓
IRQ Handler
↓
Kernel
Initial hardware mapping includes:
IRQ0 → Timer
IRQ1 → Keyboard
IRQ2 → Cascade
The timer subsystem receives periodic interrupts from the PIT.
PIT
↓
IRQ0
↓
Timer Handler
↓
Tick Counter
↓
Kernel Time
Timer infrastructure is important for future preemptive scheduling.
AyushOS includes a PS/2 keyboard input path.
PS/2 Keyboard
↓
IRQ1
↓
Keyboard Handler
↓
Scancode Decoder
↓
Keyboard Buffer
The current architecture supports:
- Keyboard interrupts
- Scancode processing
- Character input
- Input buffering
The kernel contains an early process-management subsystem.
A process is represented using concepts such as:
- PID
- Process state
- Process table
- Kernel stack
- CPU context
- Runtime information
Process states are designed around:
NEW
↓
READY
↓
RUNNING
├── BLOCKED
├── SLEEPING
└── TERMINATED
The repository also contains an assembly-backed context-switching path. The next major step is turning this foundation into a complete preemptive scheduler.
┌──────────────────┐
│ GRUB │
│ Bootloader │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ x86 Boot Code │
│ NASM │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Kernel Entry │
│ kernel_main() │
└────────┬─────────┘
│
┌─────────────────┼─────────────────┐
│ │ │
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│ GDT │ │ IDT │ │ PIC │
└────────┘ └────┬───┘ └────┬───┘
│ │
└────────┬────────┘
▼
┌────────────────┐
│ IRQ Subsystem │
└───────┬────────┘
│
┌──────────────┼──────────────┐
│ │ │
▼ ▼ ▼
┌────────┐ ┌──────────┐ ┌──────────┐
│ Timer │ │ Keyboard │ │ Future │
│ IRQ0 │ │ IRQ1 │ │ Devices │
└────┬───┘ └─────┬────┘ └──────────┘
│ │
└───────┬───────┘
▼
┌────────────────────┐
│ Process Management │
│ │
│ PID │
│ Process State │
│ Kernel Stack │
│ CPU Context │
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ Context Switching │
│ NASM │
└─────────┬──────────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
Process A Process B Idle
The intended complete architecture is:
USER APPLICATIONS
│
▼
USER SPACE
│
▼
SYSTEM CALL ABI
│
▼
┌────────────────────────────────────────────────────┐
│ KERNEL SPACE │
│ │
│ Process Manager Scheduler │
│ │ │ │
│ └────────┬────────┘ │
│ ▼ │
│ Memory Manager │
│ │ │
│ ┌────────┴────────┐ │
│ ▼ ▼ │
│ Virtual Memory Kernel Heap │
│ │
│ VFS → Filesystems → Storage │
│ │
│ Network Stack → NIC Drivers │
│ │
│ Security / Isolation / IPC │
│ │
│ Hardware Drivers │
└───────────────────────┬────────────────────────────┘
│
▼
x86 HARDWARE
| Component | Technology |
|---|---|
| Target Architecture | x86 32-bit |
| Kernel | Custom experimental kernel |
| Kernel Language | C |
| Low-Level Assembly | NASM |
| Bootloader | GRUB |
| Compiler | GCC |
| Linker | GNU ld |
| Build System | GNU Make |
| Emulator | QEMU |
| Debugger | GDB |
| Host Development OS | Arch Linux |
| Version Control | Git / GitHub |
The repository currently targets a 32-bit x86 environment and uses C, NASM, GRUB, GCC, GNU Make, QEMU and GDB as its primary development stack.
AyushOS/
│
├── arch/
│ └── x86/
│ ├── boot.asm
│ ├── context_switch.asm
│ ├── gdt_flush.asm
│ ├── idt_flush.asm
│ ├── interrupts.asm
│ └── irq.asm
│
├── include/
│ └── kernel/
│ ├── gdt.h
│ ├── idt.h
│ ├── irq.h
│ ├── keyboard.h
│ ├── kprintf.h
│ ├── pic.h
│ ├── process.h
│ ├── terminal.h
│ └── timer.h
│
├── kernel/
│ ├── kernel.c
│ ├── gdt.c
│ ├── idt.c
│ ├── irq.c
│ ├── pic.c
│ ├── process.c
│ ├── timer.c
│ │
│ ├── drivers/
│ │ ├── keyboard.c
│ │ └── terminal.c
│ │
│ └── lib/
│ └── kprintf.c
│
├── scripts/
│ └── linker.ld
│
├── iso/
│ └── boot/
│
├── Makefile
├── README.md
└── .gitignore
This structure cleanly separates architecture-specific assembly, kernel subsystems, headers, drivers, libraries, and build/linker configuration.
- GCC
- NASM
- GNU Binutils
- GRUB
- Xorriso
- QEMU
- GDB
- GNU Make
- GRUB boot
- Assembly bootstrap
- Kernel entry
- Linker script
- Bootable ISO
- VGA text mode
- Character output
- String output
- Integer formatting
- Kernel logging
- Debug messages
- GDT structure
- Segment descriptors
- Kernel code/data segments
- User code/data segment preparation
- Assembly reload
- IDT
- ISR stubs
- Exception handlers
- Interrupt frames
- Diagnostic output
- PIC initialization
- PIC remapping
- IRQ registration
- IRQ dispatch
- End-of-interrupt handling
- PIT timer
- Timer ticks
- Keyboard IRQ
- Scancode decoding
- Character input
- Input buffer
Planned/under development:
- Physical memory map
- Frame allocator
- Bitmap allocator
- Frame allocation/freeing
- Memory statistics
Under development:
- PID allocation
- Process table
- Process states
- Process creation
- Process termination
- Kernel stacks
- CPU context
- Context switching
Target:
Timer IRQ
↓
Scheduler
↓
Save Context
↓
Select Process
↓
Context Switch
↓
Run Process
Initial scheduler:
Round Robin
Future experiments:
- Priority scheduling
- Multilevel Feedback Queue
- Real-time scheduling
- Fair scheduling
Target system calls:
write()
read()
exit()
yield()
sleep()
getpid()
Main objectives:
- Ring 3 execution
- User stack
- TSS
- System-call entry
- System-call dispatcher
- Syscall table
- User processes
- Paging
- Page directories
- Page tables
- Address spaces
- Page faults
- Kernel virtual memory
- User virtual memory
Introduce dynamic kernel allocation:
kmalloc()
kfree()
krealloc()
Possible allocator implementations:
- First Fit
- Best Fit
- Buddy
- Slab
Create a generic filesystem abstraction:
Application
↓
System Call
↓
VFS
↓
┌───┼──────────┐
▼ ▼ ▼
FAT EXT2 DevFS
Initial target:
RAM Filesystem
Future target:
FAT32
Research target:
Custom AyushOS Filesystem
Target architecture:
Keyboard
↓
Input Buffer
↓
Command Parser
↓
Shell
↓
System Calls
↓
Kernel
Example future commands:
AyushOS> help
AyushOS> clear
AyushOS> echo hello
AyushOS> ps
AyushOS> mem
AyushOS> uptime
AyushOS> uname
Load actual executable programs:
ELF Binary
↓
ELF Parser
↓
Program Headers
↓
Virtual Memory
↓
User Process
↓
Ring 3
Potential stack:
Application
↓
Socket API
↓
TCP/IP
↓
Ethernet
↓
NIC Driver
↓
QEMU Network
Potential protocols:
- ARP
- IPv4
- ICMP
- UDP
- TCP
Potential research areas:
- Kernel isolation
- User/kernel privilege separation
- Memory protection
- Capability systems
- Process sandboxing
- Secure syscall validation
- Stack protection
- Address-space randomization experiments
- Control-flow integrity
- Kernel attack-surface analysis
- Secure boot experiments
Future work:
- SMP boot
- APIC
- Per-CPU data
- Spinlocks
- Atomic operations
- Parallel scheduling
- Inter-processor interrupts
The long-term objective is to use AyushOS as a controlled environment for experimenting with operating-system design.
Potential research areas include:
Compare:
Round Robin
Priority Scheduling
MLFQ
Real-Time Scheduling
Measure:
Context-switch overhead
Scheduling latency
Throughput
Fairness
CPU utilization
Compare:
Bitmap Allocator
Buddy Allocator
Slab Allocator
Measure:
Allocation latency
Fragmentation
Memory utilization
Frame distribution
Experiment with:
Process isolation
Memory isolation
Sandboxing
Capability systems
Kernel hardening
A suitable development environment should provide:
GCC
NASM
GNU Binutils
GRUB
Xorriso
QEMU
GDB
GNU Make
The project is currently documented around an Arch Linux development environment.
git clone https://github.com/AyushjhaDevops/AyushOS.git
cd AyushOSmakeThe Makefile is responsible for compiling the kernel sources, assembling low-level x86 code, linking the kernel, and preparing the bootable image.
After building the project, boot the generated image using QEMU.
Typical workflow:
makeThen launch the generated kernel/ISO with your QEMU configuration.
For example:
qemu-system-i386 -cdrom build/ayushos.isoThe exact output image path depends on the current Makefile configuration. Verify the generated artifact before running the command.
AyushOS is designed to be debugged at the kernel level using QEMU and GDB.
Typical workflow:
AyushOS
↓
QEMU
↓
GDB
├── Breakpoints
├── Registers
├── Stack
├── Memory
└── Instruction Trace
Useful debugging targets include:
- Kernel entry
- GDT initialization
- IDT initialization
- Interrupt handlers
- Timer IRQ
- Keyboard IRQ
- Process creation
- Context switching
- Scheduler
- Page faults
- System calls
The project is organized around the following major subsystem boundaries:
| Subsystem | Purpose |
|---|---|
| Boot | Starts the kernel |
| GDT | x86 segmentation |
| IDT | Interrupt/exception dispatch |
| PIC | Hardware interrupt routing |
| IRQ | Hardware interrupt handling |
| Timer | Periodic kernel interrupts |
| Keyboard | Hardware input |
| Terminal | Kernel display |
| Logging | Kernel diagnostics |
| Process Manager | Process lifecycle |
| Context Switcher | CPU context switching |
| Memory Manager | Physical memory management |
| Scheduler | CPU time allocation |
| Syscall Layer | User/kernel interface |
| VMM | Virtual memory |
| Heap | Dynamic kernel allocation |
| VFS | Filesystem abstraction |
| Network Stack | Network communication |
| Security | Kernel isolation/hardening |
| SMP | Multicore support |
AyushOS follows a low-level iterative development cycle:
Create Feature
↓
Design Architecture
↓
Implement
↓
Compile
↓
Boot in QEMU
↓
Test
↓
Debug with GDB
↓
Benchmark
↓
Document
↓
Commit
↓
Push
Verify:
Source Compilation
Object Generation
Kernel Linking
ISO Generation
Verify:
GRUB
Kernel Entry
GDT
IDT
PIC
Timer
Keyboard
Future validation should cover:
Process Creation
Process Termination
Memory Allocation
Context Switching
Scheduling
System Calls
Planned stress tests include:
100+ process creation
Rapid context switching
Memory allocation/free loops
Scheduler fairness
Interrupt load
Syscall load
The project is intended to evolve from a functional educational kernel into a measurable research platform.
Potential metrics include:
| Metric | Purpose |
|---|---|
| Context Switch Time | Scheduler overhead |
| Interrupt Latency | Hardware responsiveness |
| Scheduler Latency | Process responsiveness |
| CPU Utilization | Scheduler efficiency |
| Memory Fragmentation | Allocator quality |
| Allocation Latency | Memory performance |
| Syscall Overhead | User/kernel transition cost |
| IPC Latency | Process communication |
| Network Throughput | Network performance |
AyushOS intentionally starts from the lowest level rather than beginning with an application framework.
CPU
↓
Assembly
↓
Bootloader
↓
Kernel
↓
Interrupts
↓
Memory
↓
Processes
↓
Scheduler
↓
System Calls
↓
Applications
The purpose is to understand the layers that normally remain hidden behind mature operating systems.
Working on AyushOS provides practical experience with:
- Operating-system architecture
- Computer architecture
- C programming
- x86 assembly
- CPU registers
- CPU privilege levels
- Interrupts
- Hardware IRQs
- Device drivers
- Process management
- CPU scheduling
- Memory management
- Virtual memory
- System calls
- Filesystems
- Networking
- Kernel debugging
- Concurrency
- Systems security
- Performance engineering
AyushOS is an experimental educational kernel, not a production operating system.
Current limitations include:
- 32-bit x86 target
- Limited hardware support
- Early-stage process management
- Incomplete scheduler
- No complete user-space environment yet
- Virtual memory still planned
- Filesystem support still planned
- Networking still planned
- SMP/multicore support still planned
- Limited automated testing infrastructure
These limitations are intentional milestones in the project's development rather than claims of production readiness.
Build from the hardware upward. Understand every layer. Measure what you build.
AyushOS is not primarily about making another operating system.
It is about understanding:
What happens after the computer turns on?
How does the CPU enter the kernel?
How does the kernel handle interrupts?
How does memory get allocated?
How are processes created?
How does the CPU switch between processes?
How does user code communicate with the kernel?
How does a filesystem reach a storage device?
How does a network packet reach an application?
How can all of these components be isolated and secured?
The project attempts to answer these questions by implementing the underlying mechanisms directly.
Contributions, experiments, documentation improvements, bug fixes, and architectural discussions are welcome.
Before contributing:
- Understand the affected subsystem.
- Document the intended design.
- Implement the smallest testable change.
- Build the kernel.
- Boot it in QEMU.
- Test the affected subsystem.
- Debug with GDB when necessary.
- Document important architectural decisions.
Suggested commit style:
feat: add physical frame allocator
feat: implement round robin scheduler
feat: add user mode transition
fix: correct IRQ acknowledgement
fix: repair process stack initialization
refactor: separate scheduler from process manager
test: add scheduler stress test
docs: document memory architecture
perf: reduce context switch overhead
The immediate development direction is:
Physical Memory
↓
Process Management
↓
Preemptive Scheduler
↓
User Mode
↓
System Calls
↓
Virtual Memory
↓
Kernel Heap
↓
Filesystem
↓
Shell
↓
ELF Programs
↓
Networking
↓
Security
↓
SMP
↓
OS Research Platform
See the repository for the current license information.
Ayush Jha
GitHub:
https://github.com/AyushjhaDevops
Project:
https://github.com/AyushjhaDevops/AyushOS
AyushOS is a journey from:
Bare Metal
↓
Boot
↓
Kernel
↓
Interrupts
↓
Hardware
↓
Memory
↓
Processes
↓
Scheduling
↓
User Space
↓
Applications
The objective is not simply to produce a bootable kernel.
The objective is to understand why an operating system works the way it does.
Build it. Boot it. Break it. Debug it. Measure it. Understand it.