MetalOS/docs/DEVELOPMENT.md

MetalOS Development Guide

Getting Started

Repository Structure

MetalOS/
├── bootloader/          # UEFI bootloader code
│   ├── src/            # Bootloader source
│   ├── include/        # Bootloader headers
│   └── Makefile        # Bootloader build
├── kernel/             # MetalOS kernel
│   ├── src/            # Kernel source
│   │   ├── core/      # Core kernel (memory, scheduler)
│   │   ├── hal/       # Hardware abstraction layer
│   │   ├── drivers/   # Device drivers
│   │   └── syscall/   # System call interface
│   ├── include/        # Kernel headers
│   └── Makefile        # Kernel build
├── userspace/          # User space components
│   ├── runtime/        # C/C++ runtime
│   ├── init/          # Init process
│   └── apps/          # Applications (QT6 hello world)
├── drivers/            # Additional drivers
│   ├── gpu/           # GPU drivers (Radeon RX 6600)
│   ├── input/         # Input device drivers
│   └── pci/           # PCI bus drivers
├── docs/              # Documentation
├── scripts/           # Build and utility scripts
├── tests/             # Test suite
└── tools/             # Development tools

Coding Standards

C/C++ Style

• Indentation: 4 spaces, no tabs
• Naming:
  • Functions: snake_case
  • Types: PascalCase
  • Constants: UPPER_SNAKE_CASE
  • Variables: snake_case
• Comments: Use // for single-line, /* */ for multi-line
• Headers: Include guards with METALOS_<PATH>_<FILE>_H

Example:

#ifndef METALOS_KERNEL_MEMORY_H
#define METALOS_KERNEL_MEMORY_H

#include <stdint.h>

#define PAGE_SIZE 4096
#define KERNEL_BASE 0xFFFF800000000000

typedef struct {
    uint64_t physical_addr;
    uint64_t virtual_addr;
    uint64_t size;
} MemoryRegion;

// Initialize memory management subsystem
int memory_init(void);

// Allocate physical page
void* allocate_page(void);

#endif // METALOS_KERNEL_MEMORY_H

Assembly Style

• Syntax: Intel syntax preferred
• Comments: Explain non-obvious operations
• Labels: Descriptive names

Example:

; Set up initial GDT
setup_gdt:
    mov rax, gdt_pointer
    lgdt [rax]
    ret

Development Workflow

1. Create Feature Branch

git checkout -b feature/my-feature

2. Make Changes

• Follow coding standards
• Add comments for complex logic
• Update documentation

3. Build and Test

make clean
make
make qemu

4. Commit Changes

git add .
git commit -m "Add feature: description"

5. Submit Pull Request

• Describe changes clearly
• Reference any related issues
• Ensure CI passes

Debugging

Serial Console Output

Add serial debugging output:

#include <kernel/serial.h>

void my_function(void) {
    serial_printf("Debug: value=%d\n", some_value);
}

QEMU Monitor

Access QEMU monitor during execution:

• Press Ctrl+Alt+2 to switch to monitor
• Press Ctrl+Alt+1 to return to guest
• Use info registers to inspect CPU state

GDB Debugging

# Terminal 1: Start QEMU with GDB
make qemu-gdb

# Terminal 2: Connect GDB
gdb kernel/metalos.bin
(gdb) target remote localhost:1234
(gdb) break kernel_main
(gdb) continue

Useful GDB commands:

• break <function> - Set breakpoint
• continue - Resume execution
• step - Step one instruction
• next - Step over function
• info registers - Show CPU registers
• x/10x <addr> - Examine memory
• backtrace - Show call stack

Testing

Unit Tests

Run kernel unit tests:

cd tests
make test

Integration Tests

Test full system boot:

make test-integration

Hardware Tests

Test on real hardware (advanced):

make usb-image
# Then boot from USB on test machine

Common Tasks

Adding a New Driver

1. Create driver file: kernel/src/drivers/mydriver.c
2. Create header: kernel/include/drivers/mydriver.h
3. Add to build: Edit kernel/Makefile
4. Initialize in kernel: Call from kernel_main()

Adding System Call

1. Define syscall: kernel/include/syscall/syscall.h
2. Implement handler: kernel/src/syscall/handlers.c
3. Add to syscall table: kernel/src/syscall/table.c
4. Update userspace wrapper: userspace/runtime/syscall.c

Modifying Memory Layout

1. Update linker script: kernel/linker.ld
2. Update memory map: kernel/src/core/memory.c
3. Update documentation: docs/ARCHITECTURE.md

Performance Profiling

Boot Time Analysis

# Enable boot time logging
make DEBUG=1 ENABLE_BOOTTIME=1
make qemu
# Check serial output for timing information

CPU Profiling

Use QEMU's built-in profiling:

qemu-system-x86_64 -enable-kvm -cpu host \
    -d cpu_reset -D qemu.log \
    -drive file=build/metalos.img,format=raw

Continuous Integration

Our CI pipeline:

1. Build Check: Ensure code compiles
2. Unit Tests: Run test suite
3. Boot Test: Verify kernel boots in QEMU
4. Code Style: Check formatting
5. Documentation: Verify docs build

Resources

Specifications

• UEFI 2.10 Specification
• AMD64 Programmer's Manual
• Intel SDM

OS Development

• OSDev Wiki
• Linux Kernel Source (for reference)
• SerenityOS (good example)

Graphics/GPU

• AMD GPU Documentation
• Linux DRM/KMS

QT6

• QT6 Documentation
• QT Platform Abstraction

Getting Help

• Documentation: Check docs/ directory
• Issues: Search existing GitHub issues
• Discussions: Use GitHub Discussions for questions
• IRC: #metalos on libera.chat (planned)

Contributing

We welcome contributions! Please:

1. Follow the coding standards
2. Write clear commit messages
3. Add tests for new features
4. Update documentation
5. Be respectful and constructive

See CONTRIBUTING.md for detailed guidelines.