Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/CRISTOP-bot/cris-os-v2/llms.txt

Use this file to discover all available pages before exploring further.

The CrisOS v2 repository is organized so that each top-level directory has a single, well-defined responsibility: hardware abstraction and kernel logic live in src/, driver implementations in drivers/, host-side tooling in tools/, rootfs content in rootfs/, and GRUB bootloader artifacts in iso/. Two root-level files — linker.ld and Makefile — control the memory layout and build system respectively.

​
Directory Tree

cris-os-v2/
├── boot/          # Multiboot header and start symbol (boot.S)
├── src/           # Kernel C source and headers
├── drivers/       # Hardware driver implementations
├── tools/         # Host-side Python utilities
├── rootfs/        # Content packed into the CRFS rootfs image
├── iso/           # GRUB bootloader config and image files
├── linker.ld      # ELF linker script (loads at 0x00100000)
└── Makefile       # Build system

​
Directory Reference

Contains a single Assembly file, boot.S, which is the very first code executed after GRUB hands control to the kernel.
  • Declares the Multiboot magic header (magic 0x1BADB002, flags 0x00000003, checksum) in the .multiboot section so GRUB can identify and load the image.
  • Defines the global symbol start, which GRUB jumps to at boot.
  • start clears segment registers, sets the stack pointer to stack_top (an 8 KiB .bss region), aligns the stack to a 16-byte boundary, pushes the Multiboot information structure address in %ebx, and calls kmain.
  • If kmain ever returns, start enters an infinite loop to prevent undefined execution.
All kernel C source files and their headers. This directory is passed to the compiler as the include root (-I src).C sources compiled into the kernel:
FileRole
kernel.cEntry point kmain; orchestrates all subsystem initialization in order and then calls shell_run.
kstring.cFreestanding string utilities used throughout the kernel in place of libc: kstrlen, kstrcmp, kstrncmp, kstrcpy, kstrcat, kstrstr, kstrchr, kmemset, kmemcpy, kmemcmp, kitoa. The header also provides the static inline helpers kstreq and kskip_spaces.
gdt.cSets up the Global Descriptor Table with kernel code and data segments and loads it via lgdt.
idt.cPopulates the Interrupt Descriptor Table with ISR stubs for CPU exceptions (0–31) and hardware IRQs (0–15).
fs.cLow-level CRFS image parser: reads the 16-byte header, builds an in-memory file entry table from the CRFS binary blob delivered as a Multiboot module.
vfs.cVirtual File System layer: maintains the current working directory, resolves paths, and exposes the full public API declared in vfs.h: vfs_init, vfs_pwd, vfs_cd, vfs_list, vfs_cat, vfs_read, vfs_get_size, vfs_write, vfs_mkdir, vfs_touch, vfs_remove, vfs_rmdir, vfs_cp, vfs_mv, and vfs_exists.
shell.cInteractive shell loop: reads lines via keyboard_readline, tokenizes input, and dispatches to the appropriate subsystem or built-in handler.
boot.cBoot manager (boot_init, boot_handle_command) — handles bootctl shell commands.
systemd.cService manager (systemd_init, systemd_handle_command) — handles systemctl shell commands.
lcp.cIn-kernel LCP package manager (lcp_init, lcp_handle_command) — parses lcp_repo.txt from the VFS and handles lcp shell commands.
gui.cVGA text-mode GUI: renders bordered windows using box-drawing characters written directly to 0xB8000 via console_putxy; provides an interactive menu for filesystem browsing and system status.
memory.cMinimal kernel heap: kmalloc and kfree.
calc.cExpression evaluator for the calc shell command.
calc_app.cShell-facing wrapper calc_app() that drives the expression evaluator and prints the result.
Assembly sources:
FileRole
asm_utils.SI/O port helpers (inb, outb), arithmetic routines (sub_asm, mul_asm, div_asm), VGA helper (console_putxy, memsetw_asm), CPU control (halt_cpu, reboot_cpu), ISR/IRQ stubs, and gdt_load.
math_asm.Sadd_asm — addition implemented in x86 Assembly, called during kernel boot as a self-test (7 + 5 = 12).
Contains self-contained driver implementations. Each driver is compiled with the same CFLAGS as src/ sources and linked into the kernel binary.
FileSubsystem
console.cVGA text-mode console: console_clear, console_print, console_putchar, console_clear_color. Writes character/attribute pairs to the VGA framebuffer at physical address 0xB8000.
keyboard.cPS/2 keyboard driver: IRQ1 handler, scancode-to-ASCII translation, keyboard_readline blocking read, keyboard_read_char, and layout switching (KB_LAYOUT_US, KB_LAYOUT_ES, KB_LAYOUT_DE).
mouse.cPS/2 mouse driver: initializes the mouse via IRQ12, tracks X/Y position and button state accessible through mouse_get_state.
timer.cPIT (Programmable Interval Timer) driver: timer_init(hz) programs the 8254 timer chip to generate IRQ0 at the requested frequency (100 Hz at boot).
pic.c8259A PIC driver: pic_init remaps IRQs 0–7 to vectors 32–39 and IRQs 8–15 to vectors 40–47; pic_mask controls which IRQ lines are enabled.
Python 3 scripts and data files used on the build host. They are never compiled into the kernel.
FilePurpose
build_rootfs.pyWalks the rootfs/ directory tree, writes a CRFS-format binary image (4-byte magic CRFS, version 1, entry count, per-file records with 64-byte name, offset, and size fields, followed by 4-byte-aligned file data). Invoked as python tools/build_rootfs.py rootfs iso/boot/rootfs.bin.
lcp.pyFull-featured host-side package manager CLI with commands: search, info, install, remove, update, upgrade, list, clean, files, depends, verify, and repo. Reads the default package index from lcp_main_repo.json.
lcp_main_repo.jsonDefault LCP package repository index in JSON format, listing packages such as nano-cris, editor-lite, textpad, libc, and termcap with version, description, dependencies, file paths, and size metadata.
Files and directories that tools/build_rootfs.py packs into the CRFS image (iso/boot/rootfs.bin). The kernel mounts this image at boot as a Multiboot module and exposes its contents through the VFS at the root path /.
PathContent
README.txtWelcome message displayed when the user runs cat README.txt from the shell.
info.txtOne-line OS identification string (MiniOS v0.1, basic filesystem status).
lcp_repo.txtPlain-text LCP package listing used by the in-kernel lcp.c to resolve package metadata without a JSON parser. Lists nano-cris, editor-lite, textpad, libc, and termcap.
bin/hello.txtSample binary-directory file for filesystem browsing tests.
boot/hello.bootSample boot-directory file used by the boot manager subsystem.
share/nano-cris/help.txtHelp text for the nano-cris package, accessible from the VFS.
systemd/hello.serviceSample service unit file read by the service manager (systemd.c).
Pre-built GRUB files and the assembled boot image tree. The make iso target copies build/kernel.bin here; make echo-iso feeds this entire directory to grub-mkrescue.
iso/
└── boot/
     ├── grub/
     │    ├── grub.cfg      # GRUB menu and module load commands
     │    ├── core.img      # Pre-built GRUB core image
     │    ├── eltorito.img  # El Torito boot catalog image
     │    └── theme.txt     # GRUB menu theme configuration
     ├── kernel.bin         # Copied from build/ by make iso
     └── rootfs.bin         # Generated by tools/build_rootfs.py
Controls the memory layout of the final kernel binary. The kernel is loaded at the 1 MiB physical boundary, which is the conventional load address for Multiboot kernels and keeps the binary above BIOS data areas.
OUTPUT_FORMAT("elf32-i386")
ENTRY(start)
SECTIONS
{
  . = 0x00100000;
  .multiboot : { *(.multiboot) }   /* Multiboot header — must come first */
  .text      : { *(.text*)      }  /* Executable code */
  .rodata    : { *(.rodata*)    }  /* Read-only data */
  .data      : { *(.data*)      }  /* Initialized data */
  .bss       : { *(.bss*) *(COMMON) } /* Zero-initialized data + stack */
}
Placing .multiboot at the very start of the image guarantees that GRUB finds the magic number within the first 8 KiB of the file, as required by the Multiboot specification.

​
Source File to Subsystem Mapping

FileSubsystem
boot/boot.SMultiboot header, protected-mode entry, stack setup
src/kernel.cKernel main (kmain), boot sequence orchestration
src/gdt.c / gdt.hGlobal Descriptor Table
src/idt.c / idt.hInterrupt Descriptor Table
src/fs.c / fs.hCRFS raw image parser
src/vfs.c / vfs.hVirtual File System abstraction layer
src/shell.c / shell.hInteractive shell and command dispatch
src/memory.c / memory.hKernel heap (kmalloc / kfree)
src/lcp.c / lcp.hIn-kernel LCP package manager
src/systemd.c / systemd.hService manager
src/boot.c / boot.hBoot manager / bootctl
src/gui.c / gui.hVGA text-mode GUI
src/calc.c / calc.hExpression evaluator
src/calc_app.c / calc_app.hShell-facing calc command wrapper
src/kstring.c / kstring.hFreestanding string utilities
src/asm_utils.S / asm.hI/O ports, arithmetic, ISR/IRQ stubs, CPU control
src/math_asm.Sadd_asm — Assembly addition routine
drivers/console.c / src/console.hVGA text-mode console output
drivers/keyboard.c / src/keyboard.hPS/2 keyboard driver and layout support
drivers/mouse.c / src/mouse.hPS/2 mouse driver
drivers/timer.c / src/timer.hPIT timer driver (IRQ0, 100 Hz)
drivers/pic.c / src/pic.h8259A PIC initialization and IRQ masking
tools/build_rootfs.pyHost tool: pack rootfs/ into CRFS binary
tools/lcp.pyHost tool: full LCP package manager CLI
tools/lcp_main_repo.jsonDefault LCP package repository index
linker.ldELF memory layout, kernel load address 0x00100000
MakefileBuild system: all targets and compiler flags

Build docs developers (and LLMs) love

Get started for freeTalk to us