From 20bd9928766a0561a0c7fac7981746fd213fd6de Mon Sep 17 00:00:00 2001 From: subhobhai943 Date: Tue, 18 Aug 2026 12:16:19 +0530 Subject: [PATCH] docs: Update README.md with multi-architecture support, Kconfig TUI, drivers & release details --- README.md | 252 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 138 insertions(+), 114 deletions(-) diff --git a/README.md b/README.md index f9e84d1..dc798a8 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# SUB-OS: 64-Bit Production Modular Monolithic Operating System +# SUB-OS: Modular Monolithic Linux-Compatible Operating System ```text _____ _ _ ____ ____ _____ @@ -9,158 +9,182 @@ |_____/ \____/|____/ \____/|_____/ ``` -[![Architecture](https://img.shields.io/badge/arch-x86__64%20Long%20Mode-blue.svg?style=flat-square)]() +[![Architectures](https://img.shields.io/badge/arch-x86__64%20%7C%20aarch64%20%7C%20armv8i-blue.svg?style=flat-square)]() [![Kernel](https://img.shields.io/badge/kernel-Modular%20Monolithic-red.svg?style=flat-square)]() -[![Version](https://img.shields.io/badge/version-v0.2.0--lts%20(Enterprise)-purple.svg?style=flat-square)]() -[![Userland](https://img.shields.io/badge/userland-LazyBox%20v2.0.0%20%2B%20Nano%20%2B%20Sh-orange.svg?style=flat-square)]() -[![Networking](https://img.shields.io/badge/network-Intel%20E1000%20%7C%20HTTPD%20%7C%20NetFilter%20Firewall-green.svg?style=flat-square)]() -[![Services](https://img.shields.io/badge/services-systemctl%20%7C%20syslogd%20%7C%20crond-yellow.svg?style=flat-square)]() +[![Configuration](https://img.shields.io/badge/config-Linux%20Kconfig%20lxdialog%20TUI-cyan.svg?style=flat-square)]() +[![Version](https://img.shields.io/badge/version-v0.2.0--lts-purple.svg?style=flat-square)]() +[![Release](https://img.shields.io/badge/release-v0.0.1--beta-brightgreen.svg?style=flat-square)](https://github.com/subhobhai943/SUB-OS/releases/tag/v0.0.1-beta) +[![Userland](https://img.shields.io/badge/userland-LazyBox%20%2B%20Nano%20%2B%20Sh-orange.svg?style=flat-square)]() +[![Networking](https://img.shields.io/badge/network-TCP%2FIP%20%7C%20SSHD%20%7C%20HTTPD%20%7C%20NetFilter-green.svg?style=flat-square)]() [![License](https://img.shields.io/badge/license-MIT-lightgrey.svg?style=flat-square)](LICENSE) -**SUB-OS** is an open-source, production-grade 64-bit modular monolithic operating system engineered from the ground up for the `x86_64` architecture. Designed for both **cloud/bare-metal servers** and **interactive workstation use**, SUB-OS features a lightweight, high-performance modular kernel without unnecessary bloat. - -It comes fully equipped with a bare-metal driver tree, **SLAB Object Allocator**, an advanced virtual file system (VFS) with FAT32, ext2, sysfs, and devfs, **Lightweight Process & Container Namespaces**, **Kernel Event Tracing (FTrace ringbuffers)**, **Stateful Packet Inspection (NetFilter Firewall)**, an **Embedded Micro HTTP Web Server & REST API (`httpd`)**, **Systemd-style Service Unit Manager (`systemctl`)**, **RFC 5424 Syslog Telemetry**, **Cron Background Job Scheduler**, **Multi-User SHA-256 Authentication (`su`, `passwd`, `useradd`)**, **Ramdisk (`/dev/ram0`)**, a full L2-L4 networking protocol stack with BSD Sockets, **8-Bit Retro Melody Synth & Formant Text-to-Speech (TTS)** voice synthesizer, AC'97 sound architecture, full-screen visual `nano` editor, and the **LazyBox** multi-call userland environment with **65+ Linux-compatible utilities** and shell scripting (`sh`). +**SUB-OS** is a multi-architecture, production-grade modular monolithic operating system kernel engineered in C and Assembly. Built for high performance, modularity, and Unix/Linux compatibility, SUB-OS supports **64-bit x86 (`x86_64`)**, **64-bit ARM (`aarch64`)**, and **32-bit ARM (`armv8i` / AArch32)** targets. --- -## 🏛️ Comprehensive System Architecture +## 🌟 Key Architecture & Capabilities + +- 🎯 **Multi-Architecture HAL**: + - **`x86_64` (AMD64 / Intel 64)**: Custom 2-stage MBR bootloader, E820 BIOS memory mapping, 4-level PML4 48-bit paging, GDT, 256-entry IDT, 8259 PIC, 8254 PIT timer. + - **`aarch64` (ARMv8-A 64-Bit)**: Exception levels (EL1), 16-entry vector table, ARM Generic Interrupt Controller (GICv2), ARM Generic Arch Timer (100 Hz), Stage-1 39-bit VA MMU, PL011 UART. + - **`armv8i` (ARM32 / AArch32)**: Banked exception mode stacks (IRQ, ABT, UND, SVC), VMSAv7 1MB Section MMU, GICv2 distributor, CP15 Generic Timer, VFP/NEON FPU, PL011 UART. +- 🎛️ **Linux-Style Kconfig TUI Configurator (`make configure`)**: + - Full interactive `lxdialog` GUI interface (Royal Blue backdrop, floating modal windows, drop shadows, and menu hierarchy). + - Dynamic Kbuild-style selective compilation based on `.config` and `include/config/autoconf.h`. +- 📁 **Storage & Filesystem Layer**: + - **FAT32 (VFAT)** storage driver with directory traversal and `/mnt/fat32` auto-mounting. + - **Second Extended (EXT2)** Linux filesystem driver. + - **Virtual File System (VFS)**: POSIX `open`, `read`, `write`, `close`, `seek`, `mount` interface. + - Synthetic **DevFS** (`/dev`), **ProcFS** (`/proc`), and **Sysfs KObject Hierarchy** (`/sys`). + - Dynamic in-memory RAM disk (`/dev/ram0`). +- 🖧 **Hardware Device Drivers**: + - **Storage Controllers**: NVMe PCIe SSD, AHCI SATA 6Gb/s, IDE/ATA Hard Disks, VirtIO-Block. + - **Network Adapters**: Intel 82540EM Gigabit Ethernet, Realtek RTL8139 Fast Ethernet, VirtIO-Net 10GbE. + - **Multimedia & Display**: Bochs/VBE dynamic resolution video adapter, 2D TrueColor Canvas Rasterizer, Intel High Definition Audio (Azalia HDA), AC'97 sound codec, Formant TTS synthesizer, 8-Bit Melody player. + - **Bus & Sensors**: PCI bus enumerator, USB 3.0 Extensible Host Controller (xHCI), HWMON CPU temperature and fan tachometer sensors, VirtIO-RNG hardware entropy generator, Unix98 PTY subsystem. +- 🌐 **Networking, Firewalls & Daemons**: + - Full L2–L4 IPv4 protocol stack with dynamic ARP, ICMP Echo (`ping`), UDP, and full 3-way handshake TCP state machine. + - **NetFilter** stateful packet inspection firewall (iptables). + - Built-in **OpenSSH 2.0 Daemon (`sshd`)** on port 2222. + - Built-in **Micro HTTP REST API Server (`httpd`)** on port 8080. +- 🔒 **Kernel Security & Async Engine**: + - **Linux Security Module (LSM)** enforcing POSIX capabilities and DAC. + - **X.509 Cryptographic Keyring** with signature verification. + - In-Kernel **eBPF Register Virtual Machine** and verifier. + - **io_uring** lockless asynchronous Submission/Completion ring buffers. + - Preemptive multi-tasking scheduler with Round-Robin quantum and spinlock synchronization. + - Systemd-style unit manager (`systemctl`), cron background scheduler (`crond`), and RFC 5424 Syslog engine. +- 🧰 **LazyBox Userland Suite (70+ Linux Applets)**: + - Interactive shell with history, tab autocompletion, ANSI cursor editing, and script runner (`sh`). + - GNU-compatible **Nano** visual text editor. + - Full utilities: `ls`, `cat`, `touch`, `mkdir`, `rm`, `cp`, `pwd`, `cd`, `grep`, `wc`, `head`, `tail`, `stat`, `df`, `mkfs.vfat`, `hexdump`, `neofetch`, `uname`, `free`, `uptime`, `top`, `ps`, `dmesg`, `netstat`, `ifconfig`, `ping`, `curl`, `ssh`, `tts`, `alsamixer`, `sensors`, `lsdev`, `lsmod`, and more. + +--- + +## 🏛️ Comprehensive Architecture ```text +------------------------------------------------------------------------------------+ | USERLAND & SYSTEM SUITE | -| Interactive Shell | GNU Nano 2.0.0 | Script Runner (sh) | LazyBox (65+ Tools) | -| Micro HTTP Server | Service Manager (systemctl) | Syslog Reader | Multi-User Auth | +| Interactive Shell | GNU Nano | Script Runner (sh) | LazyBox Suite (70+ Tools) | +| Micro HTTP Server | SSH 2.0 Daemon | Service Manager (systemctl) | Syslog Engine | +------------------------------------------------------------------------------------+ | VIRTUAL FILE SYSTEM LAYER (VFS) | | vfs_namei | RAMFS (/) | /dev (devfs) | /proc (procfs) | /sys (sysfs) | FAT32 | ext2| +------------------------------------------------------------------------------------+ | NAMESPACES, INTER-PROCESS COMMUNICATION & ASYNC I/O ENGINE | -| PID & UTS Isolation | Anonymous Pipes | Message Queues | SHM | Semaphores | io_uring| +| PID/UTS Isolation | Pipes | Message Queues | Shared Memory | Semaphores | io_uring| +------------------------------------------------------------------------------------+ | CORE KERNEL SERVICES, SECURITY & TRACING | -| Preemptive Scheduler | Task Control | POSIX Signals | Fast Syscalls | Workqueues | -| High-Res Timer Wheel | Dynamic Module Loader | Kernel Event Tracer | LSM Security | -| System Metrics Telemetry | Cron Scheduler Daemon | RFC 5424 Kernel Syslog Engine | +| Preemptive Scheduler | Fast Syscalls | Dynamic Modules | eBPF Virtual Machine | +| LSM POSIX Capabilities | X.509 Keyring | Workqueues | Telemetry & Kernel Tracer | +------------------------------------------------------------------------------------+ | NETWORKING, NETFILTER FIREWALL & SOUND ARCHITECTURE | -| Ethernet L2 | ARP | IPv4 | ICMP | UDP | TCP | DHCP | DNS | Sockets | NetFilter FW | -| Embedded HTTP Server & REST API | AC'97 Audio | Formant TTS | 8-Bit Melody Engine | +| Ethernet | ARP | IPv4 | ICMP | UDP | TCP | DHCP | DNS | Sockets | NetFilter FW | +| Embedded HTTP Server (8080) | SSH Server (2222) | Intel HDA | AC'97 | Formant TTS | +------------------------------------------------------------------------------------+ -| MEMORY MANAGEMENT (MM) | -| Physical Page Allocator (PMM) | Dynamic Heap | SLAB / SLUB Object Cache | -+------------------------------------------------------------------------------------+ -| DEVICE DRIVER TREE & VIRT | -| VGA / TTY1-4 | 16550 UART Serial | PS/2 Keyboard | PS/2 Mouse | ATA Hard Disk | -| PCI Enumerator | Intel E1000 NIC | Ramdisk (/dev/ram0) | VESA FB | CMOS RTC | +| DEVICE DRIVER TREE | +| NVMe PCIe SSD | AHCI SATA | ATA IDE | VirtIO-Blk | Ramdisk (/dev/ram0) | +| Intel E1000 NIC | RTL8139 NIC | VirtIO-Net | USB 3.0 xHCI | HWMON Sensors | +| Bochs VBE Display | 2D Canvas | VGA / TTY1-4 | 16550 Serial | PL011 UART | +------------------------------------------------------------------------------------+ | HARDWARE ABSTRACTION LAYER (HAL) | -| x86_64 Long Mode | GDT / TSS | IDT / ISRs | Dual 8259A PIC | 8254 PIT Timer | +| x86_64 (AMD64/PML4) | aarch64 (ARMv8-A/GICv2/MMU) | armv8i (AArch32/Section MMU) | +------------------------------------------------------------------------------------+ ``` --- -## ⚡ 18-Step Master Boot Pipeline +## 🚀 Quick Start Guide -| Step | Subsystem | Description | -|:---:|:---|:---| -| **[1/18]** | **64-Bit GDT & TSS** | Configures flat kernel/user code & data segments and Task State Segment with dedicated 64KB kernel stack. | -| **[2/18]** | **IDT & ISR Table** | Populates 256-entry interrupt descriptor table with CPU exception handlers and hardware IRQ routing. | -| **[3/18]** | **Dual 8259A PIC** | Remaps master (IRQ 0-7 -> 0x20-0x27) and slave (IRQ 8-15 -> 0x28-0x2F) interrupt controllers. | -| **[4/18]** | **PIT & Timer Wheel** | Configures 8254 PIT channel 0 for 100 Hz (10ms resolution) driving quantum preemption & timer wheel. | -| **[5/18]** | **Input & ACPI** | PS/2 Keyboard scancode decoder, PS/2 Mouse packet tracker, and ACPI power management subsystem. | -| **[6/18]** | **PMM, Heap & SLAB** | 64-bit bitmap frame allocator, 4 MB kernel heap, and high-performance SLAB object cache layer. | -| **[7/18]** | **Block Layer, Ramdisk & ATA** | Generic Block Layer with request queues, Ramdisk (`/dev/ram0`), 'noop' elevator, and ATA driver. | -| **[8/18]** | **PCI, VirtIO, FB & USB** | PCI bus enumerator, VirtIO core, Linear 32-bit Framebuffer graphics, and USB host controller. | -| **[9/18]** | **L2-L4 Network & NetFilter** | Intel E1000 NIC, NetFilter stateful firewall, ARP, IPv4 routing, ICMP Ping, UDP, TCP, DHCP, DNS & HTTPD. | -| **[10/18]** | **Sound & Melody Synth** | Audio core driver, AC'97 soundcard, 8-Bit Melody player, and Formant Text-to-Speech synthesizer. | -| **[11/18]** | **Keyring, Auth & Namespaces**| Loads X.509 trusted keyring, SHA-256 Shadow Authentication, POSIX Capabilities LSM, and namespaces. | -| **[12/18]** | **IPC Engine** | Anonymous Pipes, System V & POSIX Message Queues, Shared Memory segments, and Semaphore sets. | -| **[13/18]** | **io_uring Subsystem** | Lockless Submission Queue Entry (SQE) & Completion Queue Entry (CQE) asynchronous I/O engine. | -| **[14/18]** | **Multi-VFS Mount** | Root RAMFS, synthetic `/dev` devfs, `/proc` procfs, `/sys` sysfs, FAT32 driver, ext2 driver & initramfs. | -| **[15/18]** | **Services, Syslog & Telemetry**| Starts RFC 5424 Syslog daemon, Telemetry Metrics, Cron scheduler, and Systemd Service Unit Manager. | -| **[16/18]** | **Scheduler & LazyBox** | Starts round-robin preemptive scheduler and launches LazyBox interactive userland environment. | -| **[17/18]** | **Hardware Interrupts** | Enables processor interrupts (`sti`) and transitions to userland shell. | -| **[18/18]** | **Interactive Shell** | Launches multi-TTY interactive terminal console on TTY1 with dynamic CWD prompt. | +### 1. Prerequisites + +Install the standard build essentials and cross-compilers: + +```bash +# Ubuntu / Debian +sudo apt update +sudo apt install build-essential nasm qemu-system-x86 qemu-system-arm \ + gcc-aarch64-linux-gnu binutils-aarch64-linux-gnu \ + gcc-arm-linux-gnueabihf binutils-arm-linux-gnueabihf \ + dialog python3 +``` --- -## 🧰 LazyBox Multi-Call Userland Suite (65+ Utilities) +### 2. Linux-Style TUI Configuration + +Launch the interactive Kconfig configurator: + +```bash +make configure +``` +*(Also available via `make menuconfig`)* + +#### Fast Architecture Presets: +```bash +make x86_64_defconfig # Configure for x86_64 (Intel / AMD 64-Bit) +make aarch64_defconfig # Configure for 64-bit ARM (Cortex-A57) +make armv8i_defconfig # Configure for 32-bit ARM (Cortex-A15) +``` + +--- + +### 3. Compilation & Live Emulation + +#### Target: `x86_64` (Default) +```bash +make x86_64_defconfig +make +make run +``` +*Port forwardings automatically configured in QEMU:* +- **SSH Server**: `ssh root@localhost -p 2222` (Password: `root`) +- **HTTP REST API**: `http://localhost:8080/api/status` + +#### Target: `aarch64` (ARMv8-A 64-Bit) +```bash +make aarch64_defconfig +make ARCH=aarch64 +make run ARCH=aarch64 +``` + +#### Target: `armv8i` (ARM32 / AArch32) +```bash +make armv8i_defconfig +make ARCH=armv8i +make run ARCH=armv8i +``` + +#### Graphical Window Emulation (Optional SDL/GTK GUI) +```bash +make run-gui +``` + +--- + +## 🧰 LazyBox Command Matrix (70+ Utilities) | Category | Commands Included | |---|---| -| **Core & Scripting** | `lazybox`, `sh` (Script runner), `echo`, `env`, `export`, `whoami`, `id`, `date` (CMOS RTC), `cal` | -| **Filesystem & Editor** | `nano`, `ls`, `cat`, `touch`, `mkdir`, `pwd`, `cd`, `wc`, `head`, `tail`, `stat`, `cp`, `grep`, `hexdump`, `basename`, `dirname` | -| **Server & Web** | `httpd` (Micro Web Server), `curl`, `wget`, `systemctl` / `service` (Daemon Manager), `crontab` | -| **Security & Logging** | `logger`, `logread` (Syslog viewer), `su`, `passwd`, `useradd`, `certcheck`, `capsh`, `ipcs` | -| **Sound & Voice** | `tts` (Phonetic Formant Voice Synthesizer), `tune` (8-Bit Melody Player), `alsamixer` | -| **Kernel & Tracing** | `lsmod`, `insmod`, `rmmod`, `slabinfo`, `trace`, `unshare` (Namespace containers) | -| **Crypto & Hashes** | `sha256sum`, `md5sum`, `crc32`, `rand` | -| **Network & Firewall** | `ifconfig`, `ping`, `arp`, `dhclient`, `nslookup`, `iptables` (Stateful Firewall), `netstat` | -| **Storage & Devices** | `hdparm`, `lspci`, `speaker`, `mouse` | -| **Virtualization & Async**| `virtinfo`, `io_uring_test` | -| **Monitoring & Telemetry**| `uname`, `free`, `uptime`, `vmstat`, `iostat`, `htop`, `top`, `dmesg`, `ps`, `sleep`, `reboot`, `poweroff` | -| **Terminal** | `clear`, `neofetch`, `help` | +| **Core & Shell** | `lazybox`, `sh`, `echo`, `env`, `export`, `whoami`, `id`, `date`, `cal` | +| **Filesystem & Edit** | `nano`, `ls`, `cat`, `touch`, `mkdir`, `rm`, `cp`, `pwd`, `cd`, `wc`, `head`, `tail`, `stat`, `df`, `mkfs.vfat`, `grep`, `hexdump` | +| **Networking & Servers** | `ifconfig`, `ping`, `arp`, `dhclient`, `nslookup`, `netstat`, `iptables`, `httpd`, `sshd`, `curl`, `wget`, `ssh` | +| **Hardware & Devices** | `lspci`, `lsdev`, `lsblk`, `hdparm`, `sensors`, `speaker`, `mouse`, `alsamixer`, `tts`, `virtinfo` | +| **Security & SysAdmin** | `su`, `passwd`, `useradd`, `certcheck`, `capsh`, `ipcs`, `logger`, `logread`, `systemctl`, `service`, `crontab` | +| **Kernel & Tracing** | `lsmod`, `insmod`, `rmmod`, `slabinfo`, `trace`, `unshare`, `io_uring_test` | +| **Diagnostics & Metrics**| `neofetch`, `uname`, `free`, `uptime`, `top`, `htop`, `ps`, `dmesg`, `vmstat`, `iostat`, `calc`, `matrix` | +| **System Control** | `clear`, `help`, `sleep`, `reboot`, `shutdown`, `poweroff`, `tty` | --- -## 🌐 Server Operations Demonstration +## 📦 Official Release -### 1. Launching Micro HTTP Server & Testing REST API -```text -sub-os:/> httpd start 80 -HTTPD: Web Server listening on 0.0.0.0:80 (HTTP/1.1) - -sub-os:/> curl /api/status -HTTP/1.1 200 OK -Server: SUB-OS/0.2.0 (x86_64) -Content-Type: application/json -Content-Length: 159 -Connection: close - -{"os":"SUB-OS","version":"0.2.0-lts (x86_64)","arch":"x86_64","uptime_sec":1,"mem_total_kb":130944,"mem_free_kb":122752,"requests_served":1,"status":"HEALTHY"} -``` - -### 2. Managing System Services -```text -sub-os:/> systemctl - UNIT LOAD ACTIVE SUB DESCRIPTION - syslogd.service loaded active running System Logging Daemon - networking.service loaded active running IPv4 Network Interface Manager - httpd.service loaded active running Embedded Micro HTTP Web Server - crond.service loaded active running Periodic Command Scheduler Daemon - firewall.service loaded active running NetFilter Stateful Packet Inspection -``` - -### 3. Multi-User Authentication & Switching -```text -sub-os:/> whoami -root - -sub-os:/> su admin -Switched to user 'admin' - -sub-os:/> whoami -admin - -sub-os:/> id -uid=1000(admin) gid=1000(admin) groups=1000(admin) - -sub-os:/> su root -Switched to user 'root' -``` +Download precompiled kernel binaries and bootable disk images from GitHub: +👉 **[SUB-OS v0.0.1-beta Release](https://github.com/subhobhai943/SUB-OS/releases/tag/v0.0.1-beta)** --- -## 🚀 Building & Running +## 📄 License -### Compilation -```bash -make clean -make -``` - -### Emulation in QEMU -```bash -qemu-system-x86_64 -drive format=raw,file=SUB-OS.img -nic model=e1000 -serial stdio -audiodev id=snd0,driver=pa -machine pcspk-audiodev=snd0 -``` +SUB-OS is distributed under the open-source **MIT License**. See [`LICENSE`](LICENSE) for details.