📄 nanochess/bootOS/architecture/overview

File: overview.md | Updated: 11/18/2025

System Overview

A comprehensive look at bootOS architecture and design.

Design Philosophy

bootOS demonstrates that a complete operating system can fit in just 512 bytes while providing:

  • Interactive command-line interface
  • Filesystem with file operations
  • Program execution environment
  • Standard I/O services
  • Persistent storage

System Components

1. Boot Loader

Location: Initially at 0x7C00, relocates to 0x7A00

The boot loader is responsible for:

  • Setting up segment registers (DS, ES, SS to 0)
  • Initializing stack pointer to 0x7700
  • Self-relocation from 0x7C00 to 0x7A00
  • Installing interrupt service vectors

2. Command Processor

Code: os.asm:214-248

The command processor provides an interactive shell:

  • Displays $ prompt
  • Reads user input
  • Parses commands
  • Dispatches to command handlers
  • Falls through to program execution if not a built-in command

3. Filesystem Manager

Code: os.asm:326-465

Handles all disk operations:

  • Directory reading/writing
  • File lookup by name
  • Sector allocation
  • File deletion

4. I/O Subsystem

Code: os.asm:510-565

Provides character and line-based I/O:

  • Keyboard input with echo
  • Screen output with formatting
  • Line buffering
  • String output routines

5. Service API

Code: os.asm:639-653

Six interrupt services for programs:

  • INT 0x20: Exit to OS
  • INT 0x21: Input key
  • INT 0x22: Output character
  • INT 0x23: Load file
  • INT 0x24: Save file
  • INT 0x25: Delete file

Boot Process

Phase 1: BIOS Load

1. BIOS POST completes
2. BIOS reads sector 0, track 0, head 0
3. Loads 512 bytes to 0x7C00
4. Checks for signature 0x55AA
5. Jumps to 0x7C00

Phase 2: System Initialization

; Code at os.asm:178-200
xor ax,ax       ; Zero all segments
mov ds,ax
mov es,ax
mov ss,ax
mov sp,stack    ; Setup stack

cld             ; Clear direction flag
mov si,boot     ; Copy from 0x7C00
mov di,osbase   ; To 0x7A00
mov cx,512
rep movsb       ; Relocate bootOS

Phase 3: Vector Installation

; Code at os.asm:194-200
mov si,int_0x20       ; Service table
mov di,0x0020*4       ; Int 0x20 vector
mov cl,6              ; 6 services
.load_vec:
    movsw             ; IP address
    stosw             ; CS address (0)
    loop .load_vec

Phase 4: Command Loop

; Code at os.asm:214-248
restart:
    ; Initialize segments and stack
    mov al,'$'        ; Prompt
    call input_line   ; Get command
    ; Parse and execute
    jmp restart       ; Repeat

Command Processing Flow

User Input → Line Buffer → Command Parser
                              ↓
                ┌─────────────┴─────────────┐
                ↓                           ↓
        Built-in Command              Try Execute File
                ↓                           ↓
        Execute & Return              Load from Disk
                ↓                           ↓
        Jump to restart               Jump to 0x7C00
                                            ↓
                                      Program Runs
                                            ↓
                                      INT 0x20 to exit
                                            ↓
                                      Jump to restart

Program Execution Model

Loading Programs

  1. User types program name
  2. Command parser doesn't find built-in command
  3. Falls through to exec_from_disk (os.asm:250)
  4. Calls INT 0x23 to load file to 0x7C00
  5. Jumps to 0x7C00 if found

Program Environment

Programs execute with:

  • CS:IP pointing to 0x0000:0x7C00
  • Stack at 0x7700 (grows down)
  • Services available via INT 0x20-0x25
  • Full control of system until INT 0x20

Exiting Programs

; Program ends with:
int 0x20        ; Exit to bootOS

; This jumps to restart routine
; Returns to command prompt

Memory Management

Memory Regions

| Address | Size | Purpose | |---------|------|---------| | 0x0000-0x03FF | 1KB | BIOS interrupt vectors | | 0x0400-0x04FF | 256B | BIOS data area | | 0x0500-0x76FF | ~29KB | Free/unused | | 0x7700-0x777F | 128B | Stack (grows down) | | 0x7780-0x77FF | 128B | Line input buffer | | 0x7800-0x79FF | 512B | Directory sector | | 0x7A00-0x7BFF | 512B | bootOS code | | 0x7C00-0x7DFF | 512B | Program execution | | 0x7E00+ | | Available |

Stack Usage

The stack at 0x7700 is used for:

  • Return addresses from subroutine calls
  • Temporary data storage
  • Interrupt frame storage
  • Parameter passing

Stack grows downward, so corruption is possible if programs use memory below 0x7700.

Interrupt Vector Table

bootOS installs its services in the IVT:

Address    Interrupt  Service
0x0080     INT 0x20   restart         (Exit to OS)
0x0084     INT 0x21   input_key       (Input with echo)
0x0088     INT 0x22   output_char     (Character output)
0x008C     INT 0x23   load_file       (Load file)
0x0090     INT 0x24   save_file       (Save file)
0x0094     INT 0x25   delete_file     (Delete file)

Each entry contains:

  • IP (offset) - 2 bytes
  • CS (segment) - 2 bytes

Since CS is 0, the IP values point directly to code in the first 64KB.

Size Optimization Techniques

1. Code Reuse

Functions are designed to serve multiple purposes:

; Same routine used for read and write
disk:
    ; AH determines operation
    ; 0x02 = read, 0x03 = write

2. Register Efficiency

Clever register usage avoids unnecessary moves:

xor ax,ax       ; Zero AX (2 bytes)
; vs
mov ax,0        ; (3 bytes)

3. Implicit Values

Leveraging known states:

; After movsb, SI is already incremented
; No need for explicit inc si

4. BIOS Services

Using BIOS instead of implementing:

  • Disk I/O (INT 0x13)
  • Keyboard input (INT 0x16)
  • Video output (INT 0x10)

Error Handling

Due to size constraints, error handling is minimal:

  • Carry flag indicates success/failure
  • "Oops" message for all errors
  • Disk operations retry on failure
  • No specific error codes

Security Considerations

bootOS has no security features:

  • No memory protection
  • No privilege levels
  • Programs have full system access
  • Files can be deleted by any program

This is acceptable for a single-user, single-tasking educational OS.

Performance Characteristics

  • Boot Time: ~1 second
  • Command Response: Instant
  • File Operations: Limited by floppy speed (~500ms)
  • Memory Access: Zero overhead (direct addressing)

Limitations

  1. File Size: Maximum 512 bytes per file
  2. File Count: Maximum 32 files
  3. No Subdirectories: Flat filesystem only
  4. Single Tasking: One program at a time
  5. No Pipes/Redirection: Simple command execution
  6. Limited Error Messages: "Oops" for all errors

Future Enhancement Ideas

While bootOS is complete, possible enhancements include:

  • Compression for larger programs
  • Simple paging for >512 byte files
  • Command history
  • More detailed error messages
  • Support for hard disk
  • Network boot capability

However, all enhancements must fit in 512 bytes!

Related Documents