diff options
| -rw-r--r-- | CLAUDE.md | 284 |
1 files changed, 0 insertions, 284 deletions
diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 1db43bc2..00000000 --- a/CLAUDE.md +++ /dev/null @@ -1,284 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Build System - -NeKernel uses a combination of **NeBuild** (JSON-based build tool) and **Make** for building different components. - -### Initial Setup - -```sh -# Setup x64 project (builds libSystem, DDK, and boot components) -./scripts/setup_x64_project.sh - -# Setup ARM64 project -./scripts/setup_arm64_project.sh -``` - -### Building & Running - -```sh -# Build boot modules (SysChk, BootNet) -./scripts/modules_ahci_x64.sh - -# Build and run with AHCI support in QEMU (debug mode) -./scripts/debug_ahci_x64.sh - -# Build and run with ATA PIO support -./scripts/debug_ata_x64.sh - -# Release builds -./scripts/release_ahci_x64.sh -``` - -### Component-Specific Builds - -```sh -# Build kernel only (from src/kernel/) -make -f amd64-desktop.make all - -# Build bootloader (from src/boot/) -make -f amd64-desktop.make efi -make -f amd64-desktop.make epm-img - -# Build libSystem (from src/libSystem/) -nebuild libSystem.json - -# Build DDK (from src/ddk/) -nebuild ddk.json -``` - -### Testing - -Tests use the KernelTest.fwrk framework: - -```sh -# Test files are in test/<component>_test/ -# Example: test/kout_test/kout.test.cc - -# Test structure: -KT_DECL_TEST(TestName, []() -> bool { /* test logic */ }); -KT_TEST_MAIN() { KT_RUN_TEST(TestName); return KT_TEST_SUCCESS; } -``` - -### Code Formatting - -**Always run before committing:** - -```sh -./format.sh -``` - -Uses `.clang-format` config (Google style, 100 column limit, 2-space indent). - -## Architecture Overview - -NeKernel is a modern microkernel-style OS with clean separation between kernel, drivers (DDK), and userland (libSystem). - -### Boot Flow - -``` -Firmware (UEFI/EFI) → Bootloader (BootKit) → Handover Protocol → Kernel Init -``` - -**Handover Protocol** (`FirmwareKit/Handover.h`): -- Passes `BootInfoHeader` with kernel/libSystem addresses, 4GB memory bitmap, GOP framebuffer, firmware tables -- Magic: `0xBADCC`, Version: `0x0117` - -### Core Architecture - -**Three-Layer Design:** - -``` -Userland (libSystem.dll) - ↓ System Calls (hash-based routing) -Kernel (DDK/DriverKit) - ↓ HAL abstraction -Hardware -``` - -### Kernel Organization ("Kit" Modules) - -Located in `src/kernel/`: - -- **NeKit**: Foundation (ErrorOr<T>, Ref, Array, Stream, JSON/TOML, Vettable concept) -- **KernelKit**: Schedulers (ProcessScheduler, UserProcessScheduler, KernelTaskScheduler), process trees (Red-Black tree), PCI/DMA -- **HALKit**: Hardware abstraction (AMD64, ARM64, PowerPC, RISC-V) -- **FSKit**: Filesystems (NeFS, Ext2+IFS, OpenHeFS) -- **StorageKit**: Device drivers (AHCI, ATA, SCSI, NVME) -- **DeviceMgr**: Template-based device interface `IDevice<T>` with `IOBuf<T>` for DMA -- **DriveMgr**: Drive abstraction with `DriveTrait` structs -- **FileMgr**: VFS abstraction `IFilesystemMgr`, `FileStream<Encoding>` template -- **FirmwareKit**: EFI/UEFI, GPT/EPM partition schemes -- **NetworkKit**: IPC protocol (128-bit addressing: ProcessID:Team, CRC32 validation) -- **SignalKit**: Signal generation (SIGKILL, SIGPAUSE, SIGSEGV, etc.) -- **CodeMgr**: Executable formats (PE, PEF, PE32, XCOFF, ZXD) -- **HeapMgr, SwapKit, DmaKit**: Memory management -- **UserMgr**: User/privilege management (Ring 1, 2, 3) -- **TraceSrv**: Tracing and debugging - -### System Calls (libSystem API) - -Located in `src/libSystem/SystemKit/System.h`. Uses reference types (`Ref` with hash+pointer). - -Key APIs: -- **File I/O**: `IoOpenFile`, `IoReadFile`, `IoWriteFile`, `IoSeekFile`, `IoCtrlFile` -- **Process**: `RtlSpawnProcess`, `RtlExitProcess`, `RtlSpawnIB` (threads) -- **Memory**: `MmCreateHeap`, `MmDestroyHeap`, `MmCopyMemory` -- **Threading**: `ThrCreateThread`, `ThrYieldThread`, `ThrJoinThread` -- **Filesystem**: `FsCopy`, `FsMove`, `FsCreateDir`, `IfsMount`, `DrvMountDrive` -- **Dynamic Loading**: `LdrOpenDylibHandle`, `LdrGetDylibSymbolFromHandle` -- **Power**: `PwrReadCode`, `PwrSendCode` (shutdown/reboot) -- **Scheduler**: `SchedSetAffinity`, `SchedFireSignal`, `SchedGetCurrentProcessID` -- **Events**: `EvtAddListener`, `EvtDispatchEvent` - -### DDK (Device Driver Kit) - -Located in `src/libDDK/DriverKit/`: - -**C API**: -- `ke_call_dispatch()` - kernel dispatch -- `ke_set_syscall(slot, function_pointer)` - register syscalls -- `kalloc/kfree` - kernel heap -- `DDK_DEVICE` struct with function pointers (read/write/open/close/seek) -- `DDK_OBJECT_MANIFEST` for exposing kernel objects via `ke_get_obj`/`ke_set_obj` - -**C++ Wrapper**: `IDriverBase` concept with `IsValidDriver` template concept - -### Error Handling - -Uses `ErrorOr<T>` template pattern (`src/kernel/NeKit/ErrorOr.h`): - -```cpp -ErrorOr<T> result = someFunction(); -if (result) { - auto value = result.Value(); -} else { - auto error = result.Error(); // kErrorFileNotFound, kErrorHeapOutOfMemory, etc. -} -``` - -37+ error codes defined in `KernelKit/KPC.h`. - -## Key Architectural Patterns - -### Vettable Concept (New API) - -Replaces old `IsAcceptable` concept for marking schedulable vs non-schedulable entities: - -```cpp -// Mark a type as schedulable -#define NE_VETTABLE static constexpr BOOL kVettable = YES - -// Mark as non-schedulable (kernel-only) -#define NE_NON_VETTABLE static constexpr BOOL kVettable = NO - -// Concept usage -template <class Type> -concept IsVettable = requires(Type) { (Type::kVettable); }; -``` - -**UserProcess** is `NE_VETTABLE`, **KernelTask** is `NE_NON_VETTABLE`. - -### Process Scheduling - -Multi-threaded scheduler with Team model (`KernelKit/UserProcessScheduler.h`): -- **Process Teams**: Low, Mid, High, RealTime priority -- **Affinities**: VeryLow, Low, Standard, High, VeryHigh, RealTime (nanosecond-level time slicing) -- **Process Status**: Starting, Running, Killed, Frozen, Finished -- **Subsystems**: Security, User, Service, Driver, Kernel -- **Resource Trees**: Red-Black tree for heap/file/special resources per process -- **Limits**: 128GB memory limit, 8KB stack size per process - -### NeFS Filesystem - -Custom filesystem inspired by HFS+ (`FSKit/NeFS.h`): -- **Fork Model**: Separate data and resource forks -- **Catalog-Based**: Similar to Mac HFS catalog structure -- **Buddy Allocation**: With sibling tracking -- **Catalog Kinds**: File, Directory, Alias, Executable, Device, etc. -- **Framework Convention**: `.fwrk/`, `.app/` directory suffixes - -### IPC (Inter-Process Communication) - -128-bit addressing model (`NetworkKit/IPC.h`): -- **Address**: ProcessID (64-bit) + Team (64-bit) -- **Message**: No payload limit, CRC32 validation -- **Endianness**: Configurable (LE/BE/mixed) - -## Important Files for Understanding Architecture - -1. `src/kernel/FirmwareKit/Handover.h` - Boot protocol and firmware handover -2. `src/kernel/KernelKit/UserProcessScheduler.h` - Process scheduling model -3. `src/kernel/KernelKit/DriveMgr.h` - Device abstraction layer -4. `src/kernel/FSKit/NeFS.h` - Custom filesystem implementation -5. `src/libSystem/SystemKit/System.h` - Userland system call API -6. `src/kernel/NeKit/Vettable.h` - Type concept system for schedulability -7. `src/kernel/NetworkKit/IPC.h` - Inter-process communication -8. `src/kernel/NeKit/ErrorOr.h` - Error handling pattern - -## Development Notes - -- **Language**: C++20 with concepts, templates, and no exceptions/RTTI -- **Compiler**: MinGW GCC (x86_64-w64-mingw32-g++), Clang for some targets -- **Assembler**: NASM -- **Build Tools**: NeBuild (custom JSON-based) + Make -- **Supported ISAs**: AMD64, ARM64, PowerPC, RISC-V -- **Partition Schemes**: EPM (custom), GPT, MBR -- **Subsystem**: Windows subsystem 17 for libSystem.dll - -## Common Patterns to Follow - -### Template-Based Abstractions - -```cpp -// Device abstraction -IDevice<T> → IDevice<IMountpoint*> - -// File streams with encoding -FileStream<Encoding, FSClass> - -// DMA buffers -IOBuf<T> -``` - -### Reference Types - -System calls use reference-based handles (hash + pointer) instead of raw integers for type safety. - -### Concept-Based Constraints - -- `IsVettable` - Marks schedulable types -- `IsValidDriver` - Validates driver implementations - -## Tools & Utilities - -Located in `tools/` and `public/tools/`: - -- **mkfs.hefs.cc** - Create HeFS filesystems -- **chk.hefs.cc** - Check/repair HeFS filesystems -- **kimg.py** - Create disk images -- **mkfwrk.py** - Package frameworks (.fwrk) -- **mkapp.py** - Package applications (.app) - -## Debugging - -```sh -# Run with GDB -./gdb.sh - -# Run with LLDB -./scripts/lldb.sh -``` - -## CI/CD - -```sh -# Kernel CI build (x64) -./scripts/kernel_ci_x64.sh -``` - -GitHub Actions run on commits: -- `boot-ahci-dev.yml` - Boot tests with AHCI -- `kernel-ahci-dev.yml` - Kernel tests with AHCI |