Skip to content

About

Create your bootloader with Go.

Topics

Resources

Stars

10 stars

Watchers

1 watching

Forks

Repository files navigation

Gootloader logo

Gootloader

Create bootloaders with Go.

Gootloader turns Go code into NASM-compatible x86 BIOS bootloader assembly. It supports both the classic 512-byte “hello world” and a multi-stage graphical bootloader with images, a mouse cursor and clickable buttons.

Features

  • Single-sector text bootloaders — BIOS teletype output, properly padded and signed with 0xAA55.
  • Automatic multi-stage loading — a 512-byte stage 1 reads a larger stage 2 from disk using BIOS CHS reads with retry and DMA-boundary handling.
  • 256-color graphics — VGA 320×200 (mode 13h) or VBE 640×480 (mode 0x101) with bank-switching support.
  • Embedded PNG/JPEG/GIF images — decoded, resized, palette-quantized and Floyd–Steinberg dithered by Go at build time.
  • PS/2 mouse input — i8042 initialization, IRQ12 packet decoding and a composited arrow cursor.
  • Clickable buttons — labels rendered with a bitmap font, pressed states, release-inside click semantics and pre-generated actions.
  • Headless runtime tests — boots images in QEMU, captures the framebuffer and injects real mouse movements/clicks.

Button clicks run bootloader actions, not Go callbacks (Go code cannot run in this generated assembly without a Go runtime). See Actions below. For the wider map of what bootloaders can do, read docs/CAPABILITIES.md.

Documentation

  • Trace-by-trace walkthrough — follow Go configuration, image conversion, assembly, BIOS loading, graphics and mouse clicks, with architecture/sequence diagrams, memory layouts and debug checkpoints.
  • Bootloader capabilities — implemented features and the wider BIOS, protected-mode and UEFI landscape.

Requirements

  • Go 1.24+
  • NASM to assemble generated output
  • QEMU to boot images and run runtime tests (qemu-system-i386)

On macOS: brew install nasm qemu

Installation

go get github.com/mohammadhb/gootloader

Hello World: a 512-byte text bootloader

package main

import (
    "log"

    gootloader "github.com/mohammadhb/gootloader"
)

func main() {
    bl := gootloader.Bootloader{
        Name:     "MyFirstBootloader",
        ModeBit:  16,     // optional, default 16
        Loaddest: 0x7C00, // optional, default 0x7C00
    }

    bl.Print("Hello World!")
    if err := bl.Create(); err != nil {
        log.Fatal(err)
    }
}

Run, assemble and boot:

go run main.go
nasm MyFirstBootloader.asm -f bin -o boot.bin
qemu-system-i386 -fda boot.bin

A runnable version is in examples/helloworld:

go run ./examples/helloworld

You may call Print multiple times. Each message gets unique labels and a null-terminated string; a final infinite halt loop prevents execution from running into message data.

Graphics, images and clickable buttons

Calling Graphics switches output to a multi-stage bootloader. Mouse support starts with Mouse, or automatically when a button is registered.

bl := gootloader.Bootloader{Name: "gui"}
bl.Graphics(gootloader.Mode640x480x256) // or Mode320x200x256

logo, err := bl.Image("logo.png", 16, 16)
if err != nil {
    log.Fatal(err)
}

bl.Button(gootloader.Button{
    Label: "Blue screen", X: 400, Y: 30, W: 200, H: 40,
    OnClick: gootloader.FillScreen(gootloader.RGB(30, 60, 160)),
})
bl.Button(gootloader.Button{
    Label: "Show logo", X: 400, Y: 90, W: 200, H: 40,
    OnClick: gootloader.ShowImage(logo),
})
bl.Button(gootloader.Button{
    Label: "Say hello", X: 400, Y: 150, W: 200, H: 40,
    OnClick: gootloader.PrintAction("Hello from a clickable bootloader!"),
})

if err := bl.Create(); err != nil {
    log.Fatal(err)
}

Create writes:

File Purpose
gui_stage1.asm 512-byte disk loader boot sector
gui_stage2.asm graphics, images, mouse driver and GUI
gui_imgN.bin palette-indexed image payloads, one per Image call
gui_build.sh assembles both stages and makes gui.img

Then:

sh gui_build.sh
qemu-system-i386 -vga std -fda gui.img

A complete demo using this repository's logo is available:

go run ./examples/gui   # run from the repository root
sh gui_build.sh
qemu-system-i386 -vga std -fda gui.img

Actions

A button's OnClick is one of:

Constructor Effect
PrintAction(text) draws text on the next text line (max 64 chars), white on the current background
ShowImage(id) redraws an image registered with Image (which returns its id)
FillScreen(color) changes the background color, resets the text line and repaints buttons
Halt() stops in an infinite loop
Reboot() jumps to the BIOS reset vector

Colors are palette indices. RGB(r, g, b) picks the nearest index in the fixed palette: a 216-color RGB cube plus 40 gray levels. Using one shared palette avoids conflicts between independently generated images.

Button FaceColor, TextColor, PressColor and BorderColor fields may override the default light-gray/white/gray scheme. Leaving a color field zero selects its default.

Coordinates and sizing

  • Button positions/sizes and image positions are pixels, with (0, 0) at the top-left.
  • Buttons must fit on screen and fit their labels plus a one-pixel border (minimum size 8×10 pixels). Labels must be printable ASCII, at most 64 characters.
  • Action text must be printable ASCII and fit on one screen line (at most 64 characters, or 39 in the 320-pixel mode).
  • Images are automatically downscaled (nearest neighbor) to fit below/right of their (x, y) origin and dithered onto the shared palette. Transparent pixels are composited over black.
  • Large images become large stage-2 files and therefore large boot images; this is expected. A full-screen 640×480 indexed image is about 300 KB.

How it works

For the complete execution trace and diagrams, read the walkthrough.

Text mode

Create emits one org 0x7C00 NASM source file. BIOS teletype services print messages, after which execution remains in a spin loop. Tests check the assembly and verify multiple messages in QEMU.

Graphics mode

The generated stage 1 loads stage 2 at physical address 0x8000 using BIOS int 0x13, respecting track, cylinder/head and 64 KB DMA limits. The build script assembles stage 2 first so it can pass the exact sector count to stage 1 via PAYLOAD_SECTORS.

Stage 2 uses org 0x8000 with zero-based code/data segments. Pixel copies convert physical image pointers to segment:offset pairs to safely address data beyond 64 KB without unreal mode. Images, buttons, glyph scanlines and the mouse cursor all share one banked framebuffer implementation; framebuffer work never crosses a 64 KB VBE window mid-copy.

The mouse is PS/2 only: the i8042 controller is configured for IRQ12, the interrupt handler decodes three-byte packets, clamps the pointer to the screen and allows the main loop to repaint the cursor and dispatch clicks. USB mice require a USB host-controller stack and are out of scope.

Testing

go test ./...

Unit and assembly tests always run when NASM is installed. QEMU runtime tests are added automatically when qemu-system-i386 is on PATH; they boot real images headlessly, assert screen pixels, inject mouse clicks and verify click semantics. Without QEMU those tests skip rather than fail.

Generated QEMU debug markers (port 0xE9) make boot progress observable without affecting normal hardware. Expected markers include B (stage 2 entry), G (graphics ready), I (initial images drawn), M (mouse setup complete), C (click accepted) and A (action finished).

Limits

  • BIOS/NASM x86 only; no UEFI/PE output.
  • Two 256-color video modes; no true-color linear framebuffer.
  • PS/2 mouse only, no USB drivers, filesystem or kernel-loading protocol.
  • Graphics-mode text comes from actions, not text-mode Print.
  • Graphics requires 16-bit mode and the standard 0x7C00 boot address. Raw Instructions are text-mode only. ModeBit: 32 changes assembler encoding; it does not switch the CPU into protected mode.
  • Output names may contain only ASCII letters, digits, underscores and hyphens, and must not start with a hyphen.
  • Stage 2 is limited to 592 KiB; its code and tables must fit below physical address 0x10000. The build script checks these memory limits.
  • Palette color fields left at zero mean “use the default”.
  • Go is the build-time generator; generated bootloaders are pure assembly and do not require a Go runtime.

Repository layout

Generated demo outputs are intentionally not kept as project sources. To remove them after running the examples:

rm -f gui.img gui_build.sh gui_img0.bin \
  gui_stage1.asm gui_stage1.bin gui_stage2.asm gui_stage2.bin \
  MyFirstBootloader.asm boot.bin

Rerun the examples and their build commands to recreate these files. Keep myBootloader.asm: it is the checked-in sample covered by an assembly test. The legacy/ prototypes are retained for history, not used in the Go build. See the walkthrough's artifact guide for the source/output distinction.

  • gootloader.go — public API, validation and text-mode generation
  • stage1.go, stage2.go — multi-stage assembly generation
  • image.go, palette.go, font.go — image/color/font pipeline
  • actions.go — video modes, buttons and actions
  • *_test.go — unit, assembly and QEMU runtime tests
  • examples/ — runnable examples
  • docs/CAPABILITIES.md — advanced bootloader capability map
  • docs/WALKTHROUGH.md — trace-by-trace internals, diagrams and debugging guide
  • myBootloader.asm — sample single-sector output
  • legacy/ — early C/C++/assembly prototypes kept for history

About

Create your bootloader with Go.

Topics

Resources

Stars

10 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages