mintOS Developer Handbook

Table of Contents

1. Boot Process
2. Screen Driver
3. Keyboard Driver
4. Input System
5. Kernel Library
6. Parser & Shell

Tool Purpose

GCC Compiles C code
NASM Assembler
QEMU Emulator for testing OS
GRUB Bootloader
xorriso Creates bootable ISO

kernal.c

void kernel_main() {
    char* video = (char*) 0xB8000;

    const char* text = "Hello from mintOS";

    for (int i = 0; text[i] != '\0'; i++) {
        video[i * 2] = text[i];
        video[i * 2 + 1] = 0x07;
    }

    while (1);
}

This C program displays text on the screen using VGA text mode.

VGA Video Memory

0xB8000 is a special memory address: the VGA text-mode video
memory in older PCs.\
VGA uses a reserved area of RAM that the display hardware reads to
show text and graphics.

In VGA text mode, each character cell uses two bytes:

video[i * 2];
video[i * 2 + 1];

Here: - video[0] = 'H' places the character 'H' in the first
screen position. - video[1] sets the color attribute for that
character.

Example:

1 byte = character
1 byte = color info
video[0] = 'H';   // character
video[1] = 0x07;  // color

Configuration Files and GRUB

Create a .cfg file\
A .cfg file is a configuration file that contains settings or
instructions for a program.

GRUB (Grand Unified Bootloader) is a bootloader that: - Shows a boot
menu - Loads the kernel - Starts the operating system

In short, GRUB helps boot the OS.

GRUB = helper that knows where everything is stored

Without GRUB, you would manually tell the computer: - "Go to this disk
location." - "Read these sectors." - "Load this data into memory."

So GRUB saves you from doing that low-level work manually.

• .cfg → instructions/settings a program reads\
• .sh → shell script with commands the computer executes (starts programs, runs commands in the terminal)

Program start sequence:

Program starts
   ↓
Reads .cfg file
   ↓
Uses those settings/instructions

Boot Process: BIOS/UEFI → GRUB → OS

BIOS/UEFI is firmware built into the motherboard. Every time you
turn on a computer:

1. BIOS/UEFI firmware runs automatically.
2. It starts the bootloader.
3. The bootloader starts the operating system.

Basic boot flow:

Power On
→ BIOS/UEFI
→ GRUB starts
→ GRUB reads grub.cfg
→ GRUB loads the OS
→ OS starts

boot.asm -- Multiboot Entry Point

Create boot.asm:

section .multiboot
    align 4
    dd 0x1BADB002
    dd 0x00
    dd -(0x1BADB002 + 0x00)

section .text
    global _start
    extern kernel_main

_start:
    call kernel_main

hang:
    jmp hang

boot.asm is the initial startup code that helps GRUB start
your kernel.\
It: - Tells GRUB this is a valid multiboot kernel - Calls
kernel_main() (from kernal.c) after the kernel is loaded into
RAM

dd 0x1BADB002 is a special magic number used by GNU GRUB.\
A magic number is a fixed value used to identify a file format or
type.

Boot code: → runs directly on hardware before any OS exists\
Normal software: → runs on top of the operating system

The magic number does not specify where to load the kernel. It
only identifies the file type to the bootloader.

Full Boot Flow So Far

Power On
→ BIOS/UEFI starts
→ GRUB starts
→ GRUB reads grub.cfg
→ GRUB loads kernel (using boot.asm + kernel.bin) into RAM
→ boot.asm starts
→ kernel_main() runs
→ Your OS runs

Tools and Concepts

• GNU Compiler Collection (GCC)\
  Converts C/C++ code into machine code the computer can run.

• Linker script\
  Defines how the final kernel binary is laid out in memory.

• QEMU\
  An emulator/virtual machine that creates a virtual computer
  inside your real computer so you can run operating systems
  safely.\
  QEMU provides a virtual machine where this minimal OS runs.

Now you have created a basic mini OS that prints a static message.

├── Makefile
├── MintOS.iso
├── boot
│   └── boot.asm
├── boot.o
├── iso
│   └── boot
│       ├── grub
│       │   └── grub.cfg
│       └── kernel.bin
├── kernel
│   ├── kernel.c
│   ├── screen.c
│   └── screen.h
├── kernel.bin
├── kernel.o
├── linker.ld
└── screen.o

Makefile → instructions for building the OS automatically boot/boot.asm
→ startup assembly code for the kernel iso/ → folder used to create the
bootable ISO iso/boot/grub/grub.cfg → GNU GRUB boot configuration file
kernel/kernel.c → main kernel C code kernel/screen.c → screen display
functions kernel/screen.h → declarations for screen functions linker.ld
→ tells how to arrange the kernel in RAM

Makefile -----------------------------
all:
        nasm -f elf32 boot/boot.asm -o boot.o
        gcc -m32 -ffreestanding -c kernel/kernel.c -o kernel.o
        gcc -m32 -ffreestanding -c kernel/screen.c -o screen.o

        ld -m elf_i386 -T linker.ld -o kernel.bin boot.o kernel.o screen.o

        cp kernel.bin iso/boot/kernel.bin

        grub-mkrescue -o mintOS.iso iso

        qemu-system-x86_64 -cdrom mintOS.iso

## boot.asm ----------------------------------

section .multiboot
    align 4
    dd 0x1BADB002
    dd 0x00
    dd -(0x1BADB002 + 0x00)

section .text
    global _start
    extern kernel_main

_start:
    call kernel_main

hang:
    jmp hang

grub.cfg -----------------------------------

menuentry "mintOS" {
    multiboot /boot/kernel.bin
    boot
}

kernel.c -------------------------------------------

#include "screen.h"

void kernel_main() {

    clear_screen();

    print("Welcome to MintOS!");

    while (1);

screen.c -------------------------------------------------

#include "screen.h"

char* video = (char*) 0xB8000;
int cursor = 0;

void clear_screen() {
    for (int i = 0; i < 80 * 25; i++) {
        video[i * 2] = ' ';
        video[i * 2 + 1] = 0x07;
    }

    cursor = 0;
}

void print(const char* str) {
    int i = 0;

    while (str[i] != '\0') {
        video[cursor++] = str[i++];
        video[cursor++] = 0x07;
    }


screen.h --------------------------------------------------

#ifndef SCREEN_H
#define SCREEN_H

void print(const char* str);
void clear_screen();

#endif

linker.ld ------------------------------------------

ENTRY(_start)

SECTIONS
{
    . = 1M;

    .text :
    {
        *(.multiboot)
        *(.text)
    }

    .rodata :
    {
        *(.rodata)
    }

    .data :
    {
        *(.data)
    }

    .bss :
    {
        *(.bss)
    }
}

Phase 3 --- Keyboard Driver

Until now, mintOS could only display text. It could not receive
any input from the user.

The goal of this phase is to make the keyboard interactive.

How the Keyboard Works

A keyboard does not send characters like 'A' or 'B'.

Instead, it sends scan codes.

Key Scan Code

A 0x1E
B 0x30
C 0x2E
Enter 0x1C
Space 0x39
Backspace 0x0E

Example:

Press A
   ↓
Keyboard sends
0x1E

The operating system converts the scan code into an ASCII character.

0x1E
   ↓
'a'

Memory-Mapped vs Port-Mapped I/O

Previously, we wrote directly to VGA memory.

0xB8000

This is called Memory-Mapped I/O.

The keyboard is different.

It communicates through I/O Ports.

CPU
 │
 ├── Memory
 │      0xB8000
 │
 └── I/O Ports
        0x60

• Memory-mapped I/O → Access hardware through memory addresses.
• Port-mapped I/O → Access hardware through I/O ports.

The keyboard uses:

Port 0x60

Reading an I/O Port

The CPU provides a special instruction:

in

Since C cannot execute CPU instructions directly, we use inline
assembly.

The helper function:

inb(0x60)

reads one byte from keyboard port 0x60.

New Files Added

kernel/
    keyboard.c
    keyboard.h
    ports.h

Every hardware component gets its own driver.

Examples:

keyboard.c
timer.c
mouse.c
disk.c

Scancode Lookup Table

The keyboard driver contains a lookup table.

static const char scancode_table[128];

This converts scan codes into ASCII characters.

Example:

Scan Code Character

0x02 '1'
0x03 '2'
0x1E 'a'
0x30 'b'

The array index is the scan code.

Example:

scancode_table[0x1E]

returns

'a'

Keyboard Flow

Press Key
     ↓
Keyboard
     ↓
Port 0x60
     ↓
inb(0x60)
     ↓
Scan Code
     ↓
Lookup Table
     ↓
ASCII Character
     ↓
kernel.c
     ↓
Print on Screen

Continuous Polling

The kernel continuously checks for keyboard input.

while (1)
     ↓
keyboard_get_char()
     ↓
Print Character

This method is called Polling.

The kernel repeatedly asks:

Any key?

Any key?

Any key?

Key Press vs Key Release

Every key usually generates two scan codes.

Example:

Press A
↓
0x1E

Release A
↓
0x9E

Notice:

0x9E = 0x1E + 0x80

To detect a key release:

if (scancode & 0x80)

Meaning:

• Result = 0 → Key Press
• Result ≠ 0 → Key Release

This works because the highest bit (MSB) is set only for release
scan codes.

Current Limitation

Currently, the kernel continuously reads from port 0x60.

It does not first check whether the keyboard has produced a new
scan code.

Therefore, pressing a key once may repeatedly print the same character.

Example:

Press F

ffffffffffffffff...

The next improvement is to check the keyboard status port (0x64)
before reading from 0x60.

Summary

• Keyboard sends scan codes, not characters.
• Scan codes are read from I/O port 0x60.
• inb() reads data from an I/O port.
• A lookup table converts scan codes → ASCII.
• The kernel continuously polls the keyboard.
• Each key generates Press (Make Code) and Release (Break Code) scan codes.
• The next step is to check port 0x64 to avoid reading the same scan code repeatedly.

Phase 4 --- Input System

Until now, the keyboard could only display characters on the screen.

The next step was to store everything the user types inside an input
buffer so the shell can execute complete commands.

Input Flow

Keyboard
    ↓
keyboard_get_char()
    ↓
Input Buffer
    ↓
Press Enter
    ↓
shell_execute()

Input Buffer

The input buffer stores every character typed by the user.

Example:

help

↓

h e l p \0

Functions added:

input_add_char()
input_backspace()
input_submit()
input_clear()
input_get_buffer()

Enter Key

When Enter is pressed:

Input Buffer
      ↓
input_submit()
      ↓
shell_execute()

Backspace

Backspace removes the last character from the input buffer.

Phase 5 --- Kernel Library

The kernel now has its own standard library.

Current structure:

kernel/
├── include/
│   ├── string.h
│   └── memory.h
└── lib/
    ├── string.c
    └── memory.c

Functions implemented:

strlen()
strcmp()
strcpy()
strncpy()
strchr()

memcpy()
memset()
memcmp()

These functions will be reused by every subsystem in mintOS.

Phase 6 --- Parser & Shell

Until now, the shell compared the entire input string.

Example:

echo Hello World

This would never equal:

echo

So we introduced a parser.

Goal

Transform:

echo Hello World

into:

Command:
echo

Argument:
Hello World

Parser Flow

Input Buffer
      │
      ▼
Tokenizer
      │
      ▼
Parser
      │
      ▼
Commands

strchr()

The parser uses:

char *strchr(const char *str, char ch);

to find the first space.

Example:

echo Hello World
    ^

The space is replaced with:

'\0'

Memory changes from:

e c h o _ H e l l o \0

to:

e c h o \0 H e l l o \0

Now we have two strings:

command  -> "echo"
argument -> "Hello World"

ParsedCommand

The parser returns:

typedef struct
{
    char *command;
    char *argument;
} ParsedCommand;

Example:

ParsedCommand parsed = parse_command(input);

Shell Layout

shell/
├── shell.c
├── parser.c
├── parser.h
├── commands.c
└── commands.h

Responsibilities:

• parser.c → Split the input.
• shell.c → Execute commands.
• commands.c → Implement each command.

Echo Command

> echo Hello World

Hello World

Implementation:

void cmd_echo(const char *text)
{
    print(text);
    print("\n");
}

Current mintOS Structure

kernel/
├── arch/
├── drivers/
├── include/
├── input/
├── lib/
└── shell/

Next Roadmap

• Improve parser
• Command table
• GDT
• IDT
• Interrupts
• Memory Manager
• PIT Timer