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.
- 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.
- 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.
- 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
go get github.com/mohammadhb/gootloaderpackage 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.binA runnable version is in examples/helloworld:
go run ./examples/helloworldYou 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.
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.imgA 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.imgA 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.
- 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.
For the complete execution trace and diagrams, read the walkthrough.
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.
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.
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).
- 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
0x7C00boot address. RawInstructionsare text-mode only.ModeBit: 32changes 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.
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.binRerun 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 generationstage1.go,stage2.go— multi-stage assembly generationimage.go,palette.go,font.go— image/color/font pipelineactions.go— video modes, buttons and actions*_test.go— unit, assembly and QEMU runtime testsexamples/— runnable examplesdocs/CAPABILITIES.md— advanced bootloader capability mapdocs/WALKTHROUGH.md— trace-by-trace internals, diagrams and debugging guidemyBootloader.asm— sample single-sector outputlegacy/— early C/C++/assembly prototypes kept for history
