SAGE OS Troubleshooting Guide

🔧 Common Issues and Solutions

This guide covers the most frequently encountered issues when building, running, and developing with SAGE OS.

🚀 Boot Issues

Symptoms: - Black screen after QEMU starts - No GRUB menu displayed - System appears to hang

Diagnosis:

# Check if ISO was created properly
ls -la build-output/x86_64/sageos.iso

# Verify GRUB configuration
cat test_iso/boot/grub/grub.cfg

Solutions: 1. Rebuild ISO with proper GRUB config:

make clean
make ARCH=x86_64 iso

Check QEMU command:

# Correct QEMU command
qemu-system-x86_64 -cdrom build-output/x86_64/sageos.iso -m 256M

Verify multiboot header:

# Check multiboot header in kernel
hexdump -C build-output/x86_64/kernel.elf | head -20
# Should show multiboot magic: 0x1BADB002

Issue: Kernel Panic on Boot

Symptoms: - System boots but crashes immediately - Error messages about invalid instructions - CPU exception or triple fault

Diagnosis:

# Enable QEMU debugging
qemu-system-x86_64 -cdrom build-output/x86_64/sageos.iso -m 256M -d int,cpu_reset

Solutions: 1. Check architecture compatibility:

# Verify kernel was built for correct architecture
file build-output/x86_64/kernel.elf

Debug with GDB:

# Start QEMU with GDB server
qemu-system-x86_64 -cdrom build-output/x86_64/sageos.iso -s -S

# In another terminal
gdb build-output/x86_64/kernel.elf
(gdb) target remote :1234
(gdb) continue

Check stack setup:

# Verify stack pointer in boot.S
mov $stack_top, %esp

Issue: Multiboot Header Not Found

Symptoms: - GRUB error: "Multiboot header not found" - Kernel fails to load - GRUB drops to rescue shell

Diagnosis:

# Check multiboot header location
objdump -h build-output/x86_64/kernel.elf | grep -A5 -B5 multiboot

Solutions: 1. Use ELF wrapper approach:

# Rebuild with ELF wrapper
make ARCH=x86_64 clean
make ARCH=x86_64

Verify linking order:

# Ensure boot objects come first
OBJECTS = $(BOOT_OBJ) $(KERNEL_OBJS) $(DRIVER_OBJS)

Check multiboot header placement:

# Header should be within first 8KB
python3 create_elf_wrapper.py kernel.img kernel.elf

🔨 Build Issues

Issue: Cross-Compiler Not Found

Symptoms: - gcc-aarch64-linux-gnu: command not found - gcc-riscv64-linux-gnu: command not found - Build fails for non-x86_64 architectures

Solutions: 1. Install cross-compilation toolchains:

# Ubuntu/Debian
sudo apt update
sudo apt install gcc-aarch64-linux-gnu gcc-riscv64-linux-gnu

# Fedora/RHEL
sudo dnf install gcc-aarch64-linux-gnu gcc-riscv64-linux-gnu

# macOS (using Homebrew)
brew install aarch64-elf-gcc riscv64-elf-gcc

Verify toolchain installation:

aarch64-linux-gnu-gcc --version
riscv64-linux-gnu-gcc --version

Use Docker build if toolchains unavailable:
```
./docker-build.sh
```

Issue: Linker Errors

Symptoms: - Undefined reference errors - Multiple definition errors - Linking fails with symbol conflicts

Diagnosis:

# Check object files
nm build-output/x86_64/objects/*.o | grep -E "(U |T )"

# Verify linker script
cat linker.ld

Solutions: 1. Check symbol definitions:

# Find undefined symbols
nm -u build-output/x86_64/objects/*.o

# Find multiple definitions
nm build-output/x86_64/objects/*.o | sort | uniq -d

Fix missing functions:

// Add missing function implementations
void missing_function(void) {
    // Implementation
}

Resolve symbol conflicts:

// Use static for internal functions
static void internal_function(void);

// Or rename conflicting symbols
void driver_init(void);  // Instead of init()

Issue: Assembly Syntax Errors

Symptoms: - Assembly compilation fails - Syntax errors in boot.S - Architecture-specific assembly issues

Solutions: 1. Check architecture-specific sections:

#ifdef __x86_64__
// x86_64 specific code
#elif defined(__aarch64__)
// AArch64 specific code
#elif defined(__riscv)
// RISC-V specific code
#endif

Verify assembler syntax:

# Check which assembler is being used
gcc -v -c boot/boot.S

Fix syntax for target architecture:

# x86_64 AT&T syntax
movq %rax, %rbx

# AArch64 syntax
mov x0, x1

# RISC-V syntax
mv a0, a1

🐳 Docker Issues

Issue: Docker Build Fails

Symptoms: - Docker build process stops with errors - Permission denied errors - Package installation failures

Solutions: 1. Update Docker and try again:

docker system prune -a
./docker-build.sh

Check Docker daemon:

sudo systemctl status docker
sudo systemctl start docker

Build with verbose output:

docker build --no-cache --progress=plain -t sageos .

Issue: Docker Permission Errors

Symptoms: - Permission denied when accessing Docker - Cannot connect to Docker daemon

Solutions: 1. Add user to docker group:

sudo usermod -aG docker $USER
newgrp docker

Use sudo for Docker commands:
```
sudo docker build -t sageos .
```

Check Docker socket permissions:

ls -la /var/run/docker.sock
sudo chmod 666 /var/run/docker.sock

🧪 QEMU Issues

Issue: QEMU Not Starting

Symptoms: - QEMU command not found - QEMU fails to start - Graphics issues with QEMU

Solutions: 1. Install QEMU:

# Ubuntu/Debian
sudo apt install qemu-system-x86 qemu-system-arm qemu-system-misc

# Fedora/RHEL
sudo dnf install qemu-system-x86 qemu-system-aarch64 qemu-system-riscv

# macOS
brew install qemu

Use correct QEMU binary:

# x86_64
qemu-system-x86_64 -cdrom sageos.iso

# AArch64
qemu-system-aarch64 -M virt -cpu cortex-a57 -kernel kernel.elf

# RISC-V
qemu-system-riscv64 -M virt -kernel kernel.elf

Run QEMU in headless mode:

qemu-system-x86_64 -cdrom sageos.iso -nographic -serial stdio

Issue: QEMU Hangs or Freezes

Symptoms: - QEMU window becomes unresponsive - No output from kernel - System appears to hang

Solutions: 1. Enable debugging output:

qemu-system-x86_64 -cdrom sageos.iso -d int,cpu_reset -D qemu.log

Check kernel output:

# Add debug prints to kernel
printf("Kernel starting...\n");

Use QEMU monitor:

# Press Ctrl+Alt+2 to access QEMU monitor
# Type 'info registers' to see CPU state

🔧 Development Issues

Issue: IDE/Editor Not Recognizing Code

Symptoms: - Syntax highlighting not working - IntelliSense/autocomplete not working - Include paths not found

Solutions: 1. Configure include paths:

// VS Code c_cpp_properties.json
{
    "configurations": [{
        "name": "SAGE OS",
        "includePath": [
            "${workspaceFolder}/kernel",
            "${workspaceFolder}/drivers",
            "${workspaceFolder}/sage-sdk/include"
        ],
        "defines": ["__SAGE_OS__"],
        "compilerPath": "/usr/bin/gcc"
    }]
}

Set up compile_commands.json:

# Generate compilation database
bear -- make ARCH=x86_64

Configure language server:

# Install clangd
sudo apt install clangd

# Or use ccls
sudo apt install ccls

Issue: Debugging Kernel Code

Symptoms: - Cannot set breakpoints in kernel - GDB not connecting properly - Debug symbols not loaded

Solutions: 1. Build with debug symbols:

make ARCH=x86_64 DEBUG=1

Set up GDB properly:

# Start QEMU with GDB server
qemu-system-x86_64 -cdrom sageos.iso -s -S

# Connect GDB
gdb build-output/x86_64/kernel.elf
(gdb) target remote :1234
(gdb) break kernel_main
(gdb) continue

Use QEMU built-in debugger:

# Press Ctrl+Alt+2 for QEMU monitor
(qemu) info registers
(qemu) x/10i $pc

📊 Performance Issues

Issue: Slow Build Times

Symptoms: - Builds take very long time - CPU usage is low during build - Incremental builds not working

Solutions: 1. Enable parallel builds:

make -j$(nproc) ARCH=x86_64

Use ccache for faster rebuilds:

sudo apt install ccache
export CC="ccache gcc"
make ARCH=x86_64

Clean unnecessary files:

make clean
# Or for deep clean
git clean -fdx

Issue: Large Binary Sizes

Symptoms: - Kernel binary is unexpectedly large - ISO image is too big - Memory usage is high

Solutions: 1. Enable optimization:

make ARCH=x86_64 RELEASE=1

Strip debug symbols:
```
strip build-output/x86_64/kernel.elf
```

Check for unused code:

# Use link-time optimization
CFLAGS += -flto
LDFLAGS += -flto

🔍 Diagnostic Commands

System Information

# Check system architecture
uname -m

# Check available memory
free -h

# Check disk space
df -h

# Check CPU information
lscpu

Build Diagnostics

# Check toolchain versions
gcc --version
make --version

# Check build dependencies
which qemu-system-x86_64
which grub-mkrescue

# Verify build output
ls -la build-output/
file build-output/x86_64/kernel.elf

Runtime Diagnostics

# Check QEMU version
qemu-system-x86_64 --version

# Test QEMU functionality
qemu-system-x86_64 -version

# Check virtualization support
grep -E "(vmx|svm)" /proc/cpuinfo

📞 Getting Help

Before Asking for Help

Check this troubleshooting guide
Search existing GitHub issues
Try the suggested solutions
Gather diagnostic information

When Reporting Issues

Include the following information: - Operating system and version - Build command used - Complete error message - Build output/logs - Steps to reproduce

Support Channels

GitHub Issues: SAGE-OS Issues
GitHub Discussions: SAGE-OS Discussions
Email: ashishyesale007@gmail.com

Useful Commands for Bug Reports

# Gather system information
uname -a > system-info.txt
gcc --version >> system-info.txt
make --version >> system-info.txt

# Capture build output
make ARCH=x86_64 2>&1 | tee build-log.txt

# Generate debug build
make ARCH=x86_64 DEBUG=1 2>&1 | tee debug-build.txt

SAGE OS Troubleshooting Guide

🔧 Common Issues and Solutions

🚀 Boot Issues

Issue: GRUB Menu Not Appearing

Issue: Kernel Panic on Boot

Issue: Multiboot Header Not Found

🔨 Build Issues

Issue: Cross-Compiler Not Found

Issue: Linker Errors

Issue: Assembly Syntax Errors

🐳 Docker Issues

Issue: Docker Build Fails

Issue: Docker Permission Errors

🧪 QEMU Issues

Issue: QEMU Not Starting

Issue: QEMU Hangs or Freezes

🔧 Development Issues

Issue: IDE/Editor Not Recognizing Code

Issue: Debugging Kernel Code

📊 Performance Issues

Issue: Slow Build Times

Issue: Large Binary Sizes

🔍 Diagnostic Commands

System Information

Build Diagnostics

Runtime Diagnostics

📞 Getting Help

Before Asking for Help

When Reporting Issues

Support Channels

Useful Commands for Bug Reports