{"id":47698791,"url":"https://github.com/zaid-maker/kernel","last_synced_at":"2026-04-02T17:00:08.555Z","repository":{"id":347588573,"uuid":"1194576958","full_name":"Zaid-maker/kernel","owner":"Zaid-maker","description":"A tiny 32-bit freestanding kernel that boots with GRUB and provides a basic text terminal layer.","archived":false,"fork":false,"pushed_at":"2026-03-28T17:14:02.000Z","size":32,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-28T17:16:42.212Z","etag":null,"topics":["kernel","kernel-driver","linux"],"latest_commit_sha":null,"homepage":"https://zaid-maker.github.io/kernel/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Zaid-maker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-28T14:47:01.000Z","updated_at":"2026-03-28T17:14:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Zaid-maker/kernel","commit_stats":null,"previous_names":["zaid-maker/kernel"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/Zaid-maker/kernel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zaid-maker%2Fkernel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zaid-maker%2Fkernel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zaid-maker%2Fkernel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zaid-maker%2Fkernel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Zaid-maker","download_url":"https://codeload.github.com/Zaid-maker/kernel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Zaid-maker%2Fkernel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31310997,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kernel","kernel-driver","linux"],"created_at":"2026-04-02T17:00:06.190Z","updated_at":"2026-04-02T17:00:08.522Z","avatar_url":"https://github.com/Zaid-maker.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Project SigmaBoot\n\n[![Release](https://img.shields.io/github/v/release/Zaid-maker/kernel?label=release)](https://github.com/Zaid-maker/kernel/releases/latest)\n[![Status: Alpha](https://img.shields.io/badge/status-alpha-orange)](https://github.com/Zaid-maker/kernel)\n[![Build Kernel](https://img.shields.io/github/actions/workflow/status/Zaid-maker/kernel/build-kernel.yml?branch=main\u0026label=build)](https://github.com/Zaid-maker/kernel/actions/workflows/build-kernel.yml)\n[![Release Pipeline](https://img.shields.io/github/actions/workflow/status/Zaid-maker/kernel/release-kernel.yml?label=release%20pipeline)](https://github.com/Zaid-maker/kernel/actions/workflows/release-kernel.yml)\n[![Deploy Website](https://img.shields.io/github/actions/workflow/status/Zaid-maker/kernel/deploy-site.yml?branch=main\u0026label=pages)](https://github.com/Zaid-maker/kernel/actions/workflows/deploy-site.yml)\n[![Tests: Enforced](https://img.shields.io/badge/tests-enforced-success)](https://github.com/Zaid-maker/kernel/actions/workflows/build-kernel.yml)\n[![Coverage](https://codecov.io/gh/Zaid-maker/kernel/branch/main/graph/badge.svg)](https://codecov.io/gh/Zaid-maker/kernel)\n\nSigmaBoot is a tiny 32-bit freestanding kernel that boots with GRUB and provides a basic text terminal layer.\n\n\u003e [!WARNING]\n\u003e This project is **experimental alpha software**.\n\u003e Breaking changes can happen between releases, features may be incomplete or unstable,\n\u003e and it is not intended for production or critical systems.\n\n## FAQ\n\n### Why does this project exist?\n\nProject SigmaBoot exists as a learning-first bare metal kernel project.\nThe goal is to build core OS components from scratch in small, understandable steps.\n\n### Who is this for?\n\nAnyone learning low-level systems programming, x86 boot flow, interrupts, and early kernel architecture.\n\n### Is this production ready?\n\nNo. This is alpha-stage experimental software and is expected to change frequently.\n\n### Why date-style versions?\n\nDate-style versions make milestone history easy to track and keep release progression clear during rapid iteration.\n\n### What can I do with it today?\n\nYou can boot in QEMU, use the shell commands, inspect lock state and uptime, and view the Multiboot memory map.\n\n## Features\n\n- Multiboot-compliant boot path with GRUB.\n- VGA text-mode terminal with color support.\n- Newline, tab handling, and automatic scroll when output reaches the screen bottom.\n- Small decimal and hexadecimal print helpers for kernel diagnostics.\n- Heap-backed decimal print formatting buffer with static fallback.\n- PS/2 keyboard input with basic US scancode translation.\n- Caps Lock handling for alphabetic keys and Num Lock handling for keypad digits.\n- Lock key LED synchronization for Caps Lock, Num Lock, and Scroll Lock.\n- Persistent bottom-row lock status bar showing CAPS/NUM/SCRL states.\n- Interrupt-driven keyboard input via IRQ1 using IDT + PIC remap.\n- Heap-backed keyboard IRQ queue with static fallback when allocation is unavailable.\n- CPU exception ISRs (0-31) with fault diagnostics screen showing vector, name, error code, EIP, CS, and EFLAGS.\n- Heap-backed exception diagnostics workspace buffer with static fallback.\n- PIT timer IRQ0 support with uptime display in the status bar.\n- Tiny interactive shell commands: `help`, `clear`, `version`, `locks`, `uptime`, `memmap`, `pmm`, `heap`, `heapcheck`, `heaptriage`, `heapfrag`, `heapstress [rounds]`, `heaphist`, `heapleaks [max]`, `history`.\n- Multiboot memory map viewer command (`memmap`) for physical layout inspection.\n- Heap-backed memmap line scratch buffer with stack fallback.\n- Early physical memory manager (bitmap-based frame tracking) with `pmm` shell stats command.\n- Heap-backed PMM stats line buffer with stack fallback.\n- Heap allocator groundwork with `kmalloc`/`kfree` plus shell diagnostics (`heap`, `heapcheck`, `heaptriage`, `heapfrag`, `heapstress`, `heaphist`, `heapleaks`).\n- Heap-backed heap stats line buffer with stack fallback.\n- Heap-backed dynamic shell input buffer with growth and last-command history (`history`).\n- Dedicated stats utility module (`stats_util`) to consolidate shared stats and diagnostics line formatting.\n- Kernel version string embedded at build time and shown on boot.\n\n## Versioning\n\n- Canonical kernel version is stored in `kernel/VERSION`.\n- Local builds use `kernel/VERSION` automatically.\n- Release pipeline overrides with release tag so shipped assets match the tag exactly.\n- Optional manual override:\n  - `make -C kernel all KERNEL_VERSION=v0.0.20260402`\n\n## Project Website\n\n- Source files are in `site/`.\n- Open `site/index.html` locally to preview.\n- Documentation page is `site/docs.html`.\n- Architecture diagram is included in `site/docs.html`.\n- GitHub Pages deployment is automated by `.github/workflows/deploy-site.yml`.\n\n## Project Layout\n\n- `kernel/src/boot.s`: Multiboot header and assembly entrypoint.\n- `kernel/src/kernel.c`: C kernel entry logic and boot demo output.\n- `kernel/src/terminal.c`, `kernel/src/terminal.h`: VGA terminal driver.\n- `kernel/src/print.c`, `kernel/src/print.h`: tiny printing helpers.\n- `kernel/src/stats_util.c`, `kernel/src/stats_util.h`: shared stats/diagnostics line formatting helpers.\n- `kernel/src/keyboard.c`, `kernel/src/keyboard.h`: PS/2 keyboard IRQ handling, queueing, and scancode mapping.\n- `kernel/src/interrupts.c`, `kernel/src/interrupts.h`: IDT setup, PIC remap, and IRQ dispatch.\n- `kernel/src/timer.c`, `kernel/src/timer.h`: PIT configuration and uptime counters.\n- `kernel/src/multiboot.h`: Multiboot data structures used for boot-time memory map parsing.\n- `kernel/src/pmm.c`, `kernel/src/pmm.h`: Physical memory manager bitmap and frame stats APIs.\n- `kernel/src/heap.c`, `kernel/src/heap.h`: Heap allocator (`kmalloc`/`kfree`) with integrity checks, compact triage output, fragmentation stats, live histogram telemetry, and leak-trace snapshots.\n- `kernel/src/heap_diag.c`, `kernel/src/heap_diag.h`: Heap diagnostics telemetry backend (histograms, trace snapshots, counters).\n- `kernel/src/isr.s`: interrupt service routine stubs.\n- `kernel/linker.ld`: Links the kernel at 1 MiB.\n- `kernel/grub/grub.cfg`: GRUB menu entry.\n- `kernel/Makefile`: Build, ISO, and QEMU run targets.\n\n## Prerequisites\n\nInstall the following tools:\n\n- `i686-elf-gcc`, `i686-elf-as`, `i686-elf-ld`\n- `grub-mkrescue`\n- `xorriso`\n- `qemu-system-i386`\n\n## Build\n\n```bash\nmake -C kernel all\n```\n\n## Build Bootable ISO\n\n```bash\nmake -C kernel iso\n```\n\n## Run in QEMU\n\n```bash\nmake -C kernel run\n```\n\n## Run Unit Tests (Side-By-Side)\n\n```bash\nmake -C kernel test\n```\n\nThis runs host-side unit tests for shared formatting helpers (`src/sbuf.c`) in parallel with kernel feature work.\nIt also runs heap diagnostics tests (`heap_diag_test`) and corruption-injection integrity tests (`heap_integrity_test`).\nIt also runs a runtime heap allocator test (`heap_runtime_test`) against a deterministic PMM stub so `kmalloc`/`kfree` and merge/split paths contribute to coverage.\nBoth CI (`build-kernel.yml`) and release (`release-kernel.yml`) pipelines run this test gate before build/release assets.\n\n## Run Coverage\n\n```bash\nmake -C kernel coverage\n```\n\nThis generates an LCOV report at `kernel/build/coverage/lcov.info` for host-side formatter and heap diagnostics/integrity/runtime test suites.\n\n## Codecov Bundle Analysis (Ready)\n\n- Repo includes `codecov.yml` with Bundle Analysis defaults:\n  - PR comment only when bundle changes (`require_bundle_changes: true`)\n  - 1Kb minimum change threshold for bundle comments\n  - informational bundle status with 5% warning threshold\n- To activate Bundle Analysis output, add a supported bundler plugin (Vite/Webpack/Rollup) in the frontend build path and run that build in CI.\n\n## Quick Regression Checklist\n\n- Boot reaches shell prompt and prints kernel version.\n- `help` lists `heapcheck`, `heaptriage`, `heapfrag`, `heapstress [rounds]`, `heaphist`, and `heapleaks [max]` in the command list.\n- Enter more than 128 characters in one command without crashing (dynamic input growth).\n- Use backspace during long input; cursor and command state remain in sync.\n- Run several commands, then `history` prints recent commands in order.\n- Run more than 16 commands; `history` keeps only the most recent entries.\n- Run `heapfrag` and verify largest/smallest free blocks and external fragmentation are printed.\n- Run `heapcheck` and verify status is `OK` with zero integrity error counters.\n- Run `heaptriage` and verify the one-line summary prints counts for scanned blocks and fault categories.\n- Run `heapstress` (and `heapstress 512`) and verify stress summary counters print without hanging.\n- Run `heaphist` and verify live block/byte buckets are printed.\n- Run `heapleaks` (and `heapleaks 32`) and verify active allocation trace rows are printed.\n- Run `make -C kernel test` and verify `heap_diag_test`, `heap_runtime_test`, and `heap_integrity_test` pass.\n- Status bar continues updating lock states and uptime while typing commands.\n- Keyboard input remains functional if heap queue allocation fails (fallback queue path).\n- Decimal printing remains functional if print-buffer heap allocation fails (fallback path).\n- `memmap` output remains readable if scratch-buffer heap allocation fails (fallback path).\n- Exception diagnostics output remains readable if workspace-buffer heap allocation fails (fallback path).\n- PMM stats output remains readable if stats-buffer heap allocation fails (fallback path).\n- Heap stats output remains readable if stats-buffer heap allocation fails (fallback path).\n- Shared formatting helpers (`sbuf` + `stats_util`) pass host-side unit tests (`make -C kernel test`).\n\n## Clean\n\n```bash\nmake -C kernel clean\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaid-maker%2Fkernel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzaid-maker%2Fkernel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzaid-maker%2Fkernel/lists"}