From 422f84949dd3d2e02e70936ee2b6e4741c70a6de Mon Sep 17 00:00:00 2001 From: Amlal El Mahrouss Date: Tue, 3 Jun 2025 15:36:05 +0200 Subject: meta: Update `/README.md` Signed-off-by: Amlal El Mahrouss --- README.md | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 101 insertions(+), 22 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index f4902e1a..685781df 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,120 @@
- Logo + NeKernel Logo +

NeKernel

+

+ Modern, Modular, and Secure Microkernel for Next-Generation Systems +

+

+ CI + CI + License + QEMU Tested +

-
+--- -![CI](https://github.com/amlel-el-mahrouss/nekernel/actions/workflows/boot-pio.yml/badge.svg) -![CI](https://github.com/amlel-el-mahrouss/nekernel/actions/workflows/kernel-ahci.yml/badge.svg) -[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue.svg)](LICENSE) -[![QEMU Tested](https://img.shields.io/badge/QEMU-Tested-success)](#) +## Overview -## Notice for Doxygen: +**NeKernel** is a modern, multi-platform microkernel designed for security, modularity, and performance. It features a custom VFS, advanced memory management, a flexible DDK (Driver Development Kit), and robust userland tooling. NeKernel is built for research, education, and next-generation OS development. -Use the doxygen command to build documentation. -
-A documentation for NeKernel is available here: https://nekernel-org.github.io/docs/ +--- -## Requirements: +## Features -- [MINGW-W64](https://www.mingw-w64.org/) -- [CLANG](https://clang.llvm.org/) -- [NASM](https://nasm.us/) -- [GIT](https://git-scm.com/) -- [BTB](https://github.com/nekernel-org/btb) +- **Modular Microkernel Architecture**: Clean separation of kernel, drivers, userland, and frameworks. + +- **Custom Filesystems**: (HeFS), catalog/fork model (NeFS), and metadata handling. + +- **Memory Management**: Custom heap manager, page manager, and safe memory utilities. Kernel heap allocations are protected with metadata and CRCs. Userland and kernel memory separation. + +- **Device and Driver Model**: Abstracted device interfaces for storage, network, and more. DDK (Device Driver Kit) for writing drivers in C/C++ with kernel RPC and memory-safe APIs. + +- **Userland Tooling**: CLI tools for formatting, checking, and managing filesystems, disk image utilities, and system utilities. All tools interact with kernel or disk images using well-defined APIs. + +- **System Call Interface**: low-level syscall ABI, with a stable high-level SDK for user applications. System calls are routed through a syscall manager and abstracted by `libSystem`. + +- **Security and Robustness**: kernel and tooling (bounds checks, safe memory copy/set, error codes). Kernel panics and error reporting for critical failures. No dynamic code loading in kernel space. + +- **Documentation and Specs**: Full LaTeX specifications for HeFS and NeFS, with on-disk structure diagrams and API documentation. Markdown docs for tooling and usage. -## Notice for Contributors: +- **Cross-Platform Boot Support**: Bootloader and platform code for AMD64 and ARM64, with handover and hardware abstraction layers. -- Run `format.sh` before commiting, it formats the code according to the .clang-format. +- **Testing and Debugging**: Logging, debug output, and kernel test framework headers. (Note: Fuzzing/sanitizer support is planned but not fully implemented.) -## Getting Started: +--- + +## Getting Started + +### **Requirements** +- [MINGW-W64](https://www.mingw-w64.org/) (cross-compiling) +- [CLANG](https://clang.llvm.org/) +- [NASM](https://nasm.us/) +- [BTB](https://github.com/nekernel-org/btb) (build system) + +### **Build & Run** ```sh -git clone git@github.com:nekernel-org/nekernel.git +git clone https://github.com/nekernel-org/nekernel.git cd nekernel ./setup_x64.sh -./debug_ata_x64.sh # Generic ATA PIO target +./debug_ata_x64.sh # For generic ATA PIO target (QEMU) ``` -###### Copyright (C) 2024-2025 Amlal El Mahrouss, All rights reserved. +- For ARM64 or other targets, see the scripts in `dev/boot/`. + +--- + +## Structure + +- `dev/kernel/` — Core kernel source (scheduling, memory, VFS, drivers) +- `dev/boot/` — Bootloader, platform bring-up, and early system code +- `dev/ddk/` — Driver Development Kit (DDK) and sample drivers +- `dev/libSystem/` — Userland system call interface and runtime +- `public/tools/` — CLI tools (mkfs, fsck, open, manual, etc.) +- `public/frameworks/` — Userland frameworks (CoreFoundation, DiskImage, etc.) +- `docs/` — Specifications, design docs, and diagrams + +--- + +## Security + +- **Vulnerability Disclosure:** + Please report security issues privately via email or GitHub Security Advisories. + +--- + +## Documentation + +- [API Reference (Doxygen)](https://nekernel-org.github.io/docs/) +- [Filesystem Specifications](docs/tex/) + +--- + +## Contributing + +- Please run `format.sh` before committing (uses `.clang-format`). +- All contributions (code, docs, fuzzing, security) are welcome! + +--- + +## Authors & Credits + +- **Amlal El Mahrouss** — Lead developer, kernel architect +- [Full contributor list](https://github.com/nekernel-org/nekernel/graphs/contributors) + +--- + +## License + +This project is licensed under the [GPL-3.0 License](LICENSE). + +--- + +
+ + © 2024-2025 Amlal El Mahrouss & NeKernel contributors. All rights reserved. + +
-- cgit v1.2.3