You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Refactor the codebase structure to improve organization, maintainability, and development workflow. This reorganization will establish a clean, modular architecture that makes the kernel easier to navigate, understand, and extend.
Context
The current code structure mixes core kernel functionality, architecture-specific code, drivers, and filesystem components. A systematic reorganization will:
Separate concerns properly (core, arch-specific, drivers, filesystems)
Remove all in-tree build artifacts that are now produced in build/:
Actions:
# Find and remove all .o files in source tree
find src/ -name '*.o' -delete
# Find and remove all .d dependency files
find src/ -name '*.d' -delete
# Update .gitignore to only ignore build/ directoryecho"build/"> .gitignore
echo"*.iso">> .gitignore
echo".vscode/">> .gitignore
Verification:
# Ensure source tree is clean
git status
# Should show only modified Makefiles, moved files# Rebuild from scratch
make clean
make build
# All artifacts should be in build/ only
Definition of Done:
All .o files removed from src/
All .d files removed from src/
.gitignore updated
Clean build verified
No build artifacts in git status
Phase 9: Documentation and Guidelines
Timeline: 2 days
Document the new structure and establish contribution guidelines:
# 1. Unit tests
make test# Should pass all existing tests# 2. Coverage validation
make coverage
# Coverage should remain stable or improve# 3. Boot test
make run
# Should boot to shell prompt# 4. Userland tests# In QEMU shell:
cat /dev/null
echotest> /tmp/file
ls -l /dev
doom
# 5. Build system tests
make clean
make build # Full build
make userland # Partial build
make -j4 build # Parallel build# 6. Cross-platform# On macOS with Docker
make build
# Should work identically
Verification Checklist:
All unit tests pass
Coverage metrics stable
Boots successfully
Shell works (mosh)
Userland tools work (cat, echo, ls)
Doom launches and runs
FAT32 read/write works
Device files accessible
Clean builds reproducible
Parallel builds work
Timeline Summary
Phase
Task
Duration
1 ✅
Define layout & move core
2-3 days
2 ✅
Segregate arch-specific
2-3 days
3 ✅
Restructure drivers
3-4 days
4 ✅
Organize filesystem
3-4 days
5 ✅
Character device registry
2-3 days
6 ✅
Normalize naming
2-3 days
7
Fix build system
2-3 days
8
Clean artifacts
1 day
9
Documentation
2 days
10
Regression testing
2 days
Total: 21-28 days (4-6 weeks) Completed: ~14-18 days (phases 1-6) Remaining: ~7-10 days (phases 7-10)
Definition of Done
Code Organization
All core kernel code in src/kernel/core/
All arch-specific code in src/kernel/arch/x86_64/
Drivers organized by category in src/kernel/drivers/
Filesystem code split into focused modules in src/kernel/fs/
Character device registry infrastructure in place
Build System
All build artifacts in build/ directory
No .o or .d files in source tree
Makefile has explicit source lists (no catch-all wildcards)
Parallel builds work correctly
Clean builds reproducible
Naming Conventions
Consistent function naming (subsystem_action() pattern)
Medium-High - This refactoring improves long-term maintainability and creates the foundation for #170 (character device infrastructure). While not blocking immediate features, it should be done before the codebase grows significantly larger.
Recommendation: Complete phases 7-10 to finalize the refactoring, then proceed with #352 (Makefile modularization) which builds on this work.
Current Status
Phases 1-6 Complete ✓
The following phases have been successfully completed:
Remaining phases:
Goal
Refactor the codebase structure to improve organization, maintainability, and development workflow. This reorganization will establish a clean, modular architecture that makes the kernel easier to navigate, understand, and extend.
Context
The current code structure mixes core kernel functionality, architecture-specific code, drivers, and filesystem components. A systematic reorganization will:
Implementation Plan
Phase 1: Define Target Layout and Move Core Boot Code
Timeline: 2-3 days ✅ COMPLETE
Create the foundational directory structure and move core initialization code:
Actions:
src/kernel/init.c→src/kernel/core/init.csrc/kernel/boot.c→src/kernel/core/boot.c(if exists)Definition of Done:
make buildsucceedsPhase 2: Segregate Architecture-Specific Code
Timeline: 2-3 days ✅ COMPLETE
Move x86-64 specific code to
src/kernel/arch/x86_64/:Files to Move:
Header Organization:
Definition of Done:
include/kernel/arch/x86_64/Phase 3: Restructure Driver Code
Timeline: 3-4 days ✅ COMPLETE
Organize drivers by category with proper subdirectories:
Target Structure:
Actions:
driver.cDefinition of Done:
Phase 4: Organize Filesystem Layer
Timeline: 3-4 days ✅ COMPLETE
Split the monolithic
file.cinto focused modules:Current Problem:
src/kernel/file.cis 1000+ lines mixing VFS, device ops, and syscallsTarget Structure:
Refactoring Strategy:
Definition of Done:
file.csplit into logical modulesPhase 5: Introduce Character Device Registry
Timeline: 2-3 days (coordination with #170) ✅ COMPLETE
Add infrastructure for dynamic character device registration:
Location Options:
src/kernel/fs/char/- Alongside devfs (recommended)src/kernel/drivers/char/- With character driversRecommendation:
src/kernel/fs/char/because device registration is a filesystem concern.New Files:
Example Code:
Definition of Done:
Related: Issue #170 (Character Device Infrastructure)
Phase 6: Normalize Naming Conventions
Timeline: 2-3 days ✅ COMPLETE
Establish and apply consistent naming across the kernel:
Conventions:
Example Renames:
Definition of Done:
Phase 7: Fix Build System
Timeline: 2-3 days
Update Makefile to support new structure and move build artifacts out of source tree:
Current Problems:
src/kernel/**/*.crules.oand.dfiles in source directoriesTarget Build Structure:
Makefile Changes:
Definition of Done:
build/directory.oor.dfilesmake -j)Phase 8: Clean Up Ignored Artifacts
Timeline: 1 day
Remove all in-tree build artifacts that are now produced in
build/:Actions:
Verification:
Definition of Done:
.ofiles removed fromsrc/.dfiles removed fromsrc/.gitignoreupdatedgit statusPhase 9: Documentation and Guidelines
Timeline: 2 days
Document the new structure and establish contribution guidelines:
New Documentation:
Definition of Done:
docs/architecture/code_structure.mdwrittenPhase 10: Regression Check and Validation
Timeline: 2 days
Comprehensive testing to ensure nothing broke:
Test Matrix:
Verification Checklist:
Timeline Summary
Total: 21-28 days (4-6 weeks)
Completed: ~14-18 days (phases 1-6)
Remaining: ~7-10 days (phases 7-10)
Definition of Done
Code Organization
src/kernel/core/src/kernel/arch/x86_64/src/kernel/drivers/src/kernel/fs/Build System
build/directory.oor.dfiles in source treeNaming Conventions
subsystem_action()pattern)init_*orsetup_*names remainDocumentation
docs/architecture/code_structure.mdcreatedTesting & Validation
make test)Related Issues
Priority
Medium-High - This refactoring improves long-term maintainability and creates the foundation for #170 (character device infrastructure). While not blocking immediate features, it should be done before the codebase grows significantly larger.
Recommendation: Complete phases 7-10 to finalize the refactoring, then proceed with #352 (Makefile modularization) which builds on this work.