Contributing to Aeolos

Welcome Contributors

Aeolos is a hobby x86_64 operating system project, and contributions are welcome! Whether you’re fixing bugs, adding features, improving documentation, or experimenting with OS concepts, this guide will help you get started.

Getting Started

1. Set Up Your Environment

Before contributing, ensure you have a working development environment:

Install dependencies

Install required build tools: nasm, gcc, mtools, xorriso, and qemu-system-x86.See the Development Setup guide for detailed instructions.

Clone the repository

git clone --recursive https://github.com/chocabloc/aeolos.git
cd aeolos

Build and test

make
make run

Verify that Aeolos builds and boots successfully in QEMU.

2. Explore the Codebase

Familiarize yourself with the project structure:

aeolos/
├── kernel/              # Kernel source code
│   ├── boot/           # Bootloader interface (Stivale2)
│   ├── dev/            # Device drivers (serial, framebuffer, terminal)
│   ├── fs/             # Filesystem implementations (VFS, ramfs, ttyfs)
│   ├── lib/            # Kernel library functions (klog, kmalloc, etc.)
│   ├── mm/             # Memory management (PMM, VMM)
│   ├── proc/           # Process/task management and scheduler
│   ├── sys/            # System-level code (ACPI, APIC, GDT, IDT, SMP)
│   ├── kmain.c         # Kernel entry point
│   ├── Makefile        # Kernel build configuration
│   └── linker.ld       # Linker script
├── initrd/             # Initial ramdisk contents
├── image/              # ISO image structure
│   └── boot/           # Boot files and Limine config
├── thirdparty/         # Third-party dependencies
│   ├── limine-bin/    # Limine bootloader binaries
│   └── saf/           # SAF filesystem tools
├── Makefile            # Top-level build configuration
└── genimg              # ISO generation script

Areas to Contribute

Current Status

From the project README, these areas are in progress and need work:

Usermode Support

Partial implementation - needs completion

Virtual Filesystem

Partial implementation - needs work

Disk Drivers

Not yet implemented

Input Drivers

Mouse and keyboard drivers needed

Suggested Contributions

Complete usermode support

Implement user space memory management
Add system call interface
Create process loading from VFS
Test usermode task switching

Relevant files:

kernel/sys/syscall.c
kernel/proc/task.c
kernel/mm/vmm.c

Implement disk drivers

Add ATA/SATA driver
Implement NVMe support
Create block device abstraction
Integrate with VFS

Create new directory: kernel/dev/disk/

Add input drivers

PS/2 keyboard driver
PS/2 mouse driver
USB HID support (advanced)
Input event queue

Create new directory: kernel/dev/input/

Improve VFS

Complete file operation APIs
Add filesystem mounting
Implement file permissions
Add directory operations

Relevant files:

kernel/fs/vfs/*.c

Enhance memory management

Optimize page allocator
Add memory defragmentation
Implement demand paging
Add memory statistics

Relevant files:

kernel/mm/pmm.c (Physical memory)
kernel/mm/vmm.c (Virtual memory)

Add networking

Network card drivers (e1000, rtl8139)
Network stack (TCP/IP)
Socket API
Create new directory: kernel/net/

Contribution Workflow

1. Fork and Branch

# Fork the repository on GitHub, then:
git clone --recursive https://github.com/YOUR_USERNAME/aeolos.git
cd aeolos

# Create a feature branch
git checkout -b feature/your-feature-name

Use descriptive branch names like feature/usb-keyboard-driver or fix/page-fault-panic.

2. Make Your Changes

Write code

Follow the existing code style:

Use K&R brace style
4-space indentation (no tabs in C code)
Descriptive variable names
Add comments for complex logic

Add logging

Use the kernel logging system:

#include "lib/klog.h"

klog(LOG_INFO, "Initializing feature\n");
klog(LOG_SUCCESS, "Feature initialized successfully\n");

Test thoroughly

Build with make
Test in QEMU with make run
Test with serial logging: qemu-system-x86_64 -cdrom os.iso -serial stdio
Test with multiple CPUs: -smp 4
Test without KVM: -M accel=tcg

3. Commit Your Work

Write clear, descriptive commit messages:

git add .
git commit -m "Add PS/2 keyboard driver

- Implement PS/2 controller initialization
- Add scancode translation table
- Integrate with input event queue
- Add keyboard IRQ handler"

First line: Brief summary (50 chars or less)Followed by blank line, then detailed explanation if needed.

4. Push and Create Pull Request

git push origin feature/your-feature-name

Then create a pull request on GitHub:

Go to your fork on GitHub
Click “Pull request”
Select your branch
Write a clear description of your changes
Reference any related issues

Code Style Guidelines

C Code Style

Follow the existing style in the codebase:

// Function definitions: return type on same line
void my_function(int param)
{
    // K&R brace style
    if (condition) {
        // 4-space indentation
        do_something();
    } else {
        do_other_thing();
    }
}

// Use descriptive names
static uint64_t page_frame_allocator_get_free()
{
    // Implementation
}

// Add comments for complex logic
// Calculate PML4 index from virtual address
// Bits 39-47 of the address
uint64_t pml4_idx = (addr >> 39) & 0x1FF;

Assembly Code Style

For .s files (AT&T syntax):

.global my_function
my_function:
    pushq %rbp
    movq %rsp, %rbp
    
    # Your code here
    
    popq %rbp
    retq

For .nasm files (Intel syntax):

global my_function
my_function:
    push rbp
    mov rbp, rsp
    
    ; Your code here
    
    pop rbp
    ret

Error Handling

Use appropriate error handling:

// Return NULL on failure for pointer returns
void* kmalloc(size_t size)
{
    if (size == 0)
        return NULL;
    // ...
}

// Use kernel panic for critical errors
if (critical_structure == NULL)
    kernel_panic("Critical structure not initialized\n");

// Log errors appropriately
if (operation_failed) {
    klog(LOG_ERROR, "Operation failed: %s\n", reason);
    return -1;
}

Testing Your Changes

Manual Testing

Basic Test
With Serial Output
SMP Testing
Without KVM

# Build and run
make clean
make
make run

# Monitor serial output
qemu-system-x86_64 -cdrom os.iso \
  -m 128 -smp 4 \
  -serial stdio

# Test with different CPU counts
qemu-system-x86_64 -cdrom os.iso -m 128 -smp 1
qemu-system-x86_64 -cdrom os.iso -m 128 -smp 2
qemu-system-x86_64 -cdrom os.iso -m 128 -smp 8

# Test pure emulation (slower but more compatible)
qemu-system-x86_64 -cdrom os.iso \
  -m 128 -smp 4 \
  -M accel=tcg

Debug Testing

Test with debugging enabled:

# Enable QEMU debug output
qemu-system-x86_64 -cdrom os.iso \
  -d int,cpu_reset \
  -D qemu.log \
  -serial stdio

See the Debugging guide for more techniques.

Continuous Integration

Aeolos uses GitHub Actions for CI (.github/workflows/c-cpp.yml:9-26):

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout repo and submodules
      uses: actions/checkout@v2
      with:
        submodules: recursive
    - name: Install dependencies
      run: sudo apt-get install -y nasm gcc mtools xorriso
    - name: make
      run: make
    - uses: actions/upload-artifact@v4
      with:
        name: os.iso
        path: os.iso

Your pull request must pass the CI build:

Checkout with submodules
Install dependencies
Build successfully
Generate os.iso artifact

Ensure your changes build cleanly before submitting a PR. Run make clean && make to verify.

Pull Request Guidelines

Before Submitting

PR Description Template

## Description
Brief description of what this PR does.

## Changes
- Added X feature
- Fixed Y bug
- Updated Z subsystem

## Testing
- Tested in QEMU with 1, 2, and 4 CPUs
- Verified serial output logs
- No kernel panics observed

## Related Issues
Closes #123

Getting Help

GitHub Issues

Ask questions or report bugs

Development Setup

Build environment help

Debugging Guide

Learn debugging techniques

Download Builds

Get latest CI artifacts

Code of Conduct

Be respectful and constructive:

Be welcoming to new contributors
Focus on technical merit of ideas
Provide constructive feedback on PRs
Help others learn and improve
Have fun experimenting with OS development!

Aeolos is a hobby project - it’s a great place to learn OS development concepts. Don’t be afraid to experiment and ask questions!

Recognition

All contributors are valued! Your contributions will be:

Credited in commit history
Visible in GitHub’s contributor list
Part of the Aeolos project history

Thank you for contributing to Aeolos!

Getting Started

Architecture

Kernel Subsystems

Drivers

Development

​Welcome Contributors

​Getting Started

​1. Set Up Your Environment

​2. Explore the Codebase

​Areas to Contribute

​Current Status

Usermode Support

Virtual Filesystem

Disk Drivers

Input Drivers

​Suggested Contributions

​Contribution Workflow

​1. Fork and Branch

​2. Make Your Changes

​3. Commit Your Work

​4. Push and Create Pull Request

​Code Style Guidelines

​C Code Style

​Assembly Code Style

​Error Handling

​Testing Your Changes

​Manual Testing

​Debug Testing

​Continuous Integration

​Pull Request Guidelines

​Before Submitting

​PR Description Template

​Getting Help

GitHub Issues

Development Setup

Debugging Guide

Download Builds

​Code of Conduct

​Recognition

Build docs developers (and LLMs) love

Welcome Contributors

Getting Started

1. Set Up Your Environment

2. Explore the Codebase

Areas to Contribute

Current Status

Suggested Contributions

Contribution Workflow

1. Fork and Branch

2. Make Your Changes

3. Commit Your Work

4. Push and Create Pull Request

Code Style Guidelines

C Code Style

Assembly Code Style

Error Handling

Testing Your Changes

Manual Testing

Debug Testing

Continuous Integration

Pull Request Guidelines

Before Submitting

PR Description Template

Getting Help

Code of Conduct

Recognition