BrewKernel User Manual

IMPORTANT: Running this kernel on real hardware is at YOUR OWN RISK. This software comes with ABSOLUTELY NO WARRANTY. The developer is not liable for any damage to your system.

System Overview

Welcome to the BrewKernel, a simple hobby operating system kernel designed for x86_64 architecture. This manual provides an overview of the system, its features, and available commands.

BrewKernel boots into a VGA text mode display (80x25 characters). It initializes a custom color palette and provides basic keyboard input handling. The primary user interface is a simple command-line interface (CLI).

Hardware Requirements

Tested Configuration:: HP EliteDesk 705 G4 DM 65W SBKPF
CPU:: AMD Ryzen 5 PRO 2400G (8) @ 3.600GHz
GPU:: AMD ATI Radeon Vega Series (VGA ONLY)
Display:: VGA port required - No other display outputs are supported
Boot:: Legacy boot mode required (NOT UEFI)

Building from Source

Prerequisites

Docker is required for building the kernel in a consistent environment.

Build Steps

# Build the Docker container
cd BrewKernel
docker build buildenv -t brewkernel

# Run the build script
docker run --rm -it -v "$(pwd)":/root/env -w /root/env --platform linux/amd64 brewkernel make build-x86_64

Build outputs:

dist/x86_64/kernel.bin - Kernel binary
dist/x86_64/kernel.iso - Bootable ISO image

Installation on Real Hardware

Steps to Install

Install BalenaEtcher on your device
Use BalenaEtcher to flash kernel.iso to a USB drive
Ensure you have a compatible x86_64 system
Enable legacy boot in BIOS
Boot from USB using legacy boot option (NOT UEFI)

Technical Details

Memory Map

Kernel Load Address: 0x100000 (1MB) Stack Size: 16KB Page Tables: Identity Mapping VGA Buffer: 0xB8000

VGA Text Mode

Resolution: 80x25 characters
16-color palette with RGB customization
Hardware cursor support
Automatic screen scrolling
Text wrapping at screen boundaries

Text Input & Display

256-character input buffer
Backspace handling with cursor movement
Case-insensitive commands
Color attributes for text and background

Real-Time Clock & Timezone Support

RTC driver with BCD conversion
Global timezone database
Support for half-hour offsets
System uptime tracking

Features

VGA Text Mode Driver: Full control over text and background colors.
PS/2 Keyboard Driver: Handles key presses, including modifier keys like Shift.
Simple CLI: A basic shell to interact with the kernel.
Command History (Use arrow keys to select previous commands).

How to Use the CLI

Upon boot, you can type 'CLI' and press Enter to start the command-line interface. Once in the CLI, you can type commands followed by Enter. Commands are case-insensitive.

Available Commands

Command	Description
HELP	Displays a short list of available commands.
MAN	Shows this detailed user manual. Use UP/DOWN arrow keys to scroll and 'q' to quit the manual viewer.
ABOUT	Displays information about the kernel, including version, build date, architecture, and compiler.
MATH	A simple calculator for basic arithmetic operations (add, subtract, multiply, divide) on integers.
DATE	Displays the current date and time, with an option to select your timezone.
CLEAR	Clears the entire screen and moves the cursor to the top-left.
EXIT	Exits the CLI mode and returns to the initial kernel screen.
LICENSE	Displays the full GNU General Public License v3. Use UP/DOWN to scroll, 'q' to quit.
UPTIME	Shows how long the system has been running since boot.