Understand every byte.

01 / Boot the bits

You need Python 3, Make, and QEMU with x86 system support. The target uses legacy BIOS, not UEFI. Host tools package bytes; QEMU provides a machine that executes them.

git clone https://github.com/OthmaneBlial/bitborn.git
cd bitborn
make build
./tools/bitverify
make run

The boot screen reports bitborn v0.1 and Hello from raw machine code!. The image remains one 512-byte sector. To run the resulting image directly:

qemu-system-i386 -machine pc,accel=tcg \
  -drive file=build/boot.img,format=raw,if=floppy \
  -boot a -serial stdio

Quit QEMU through its window controls. The serial output mirrors the boot text and provides a machine-readable signal for the automated boot test. The QEMU program is a host dependency, not part of the generated target.

Download the latest release and checksums if you want to inspect a packaged artifact first. Direct downloads: 512-byte image, monitor image, shell image, protected-mode experiment, and SHA-256 checksums. All fifteen example guides include complete byte tables and canonical sources.

02 / The canonical source is binary

Each byte is an eight-character token containing only 0 and 1. Whitespace separates tokens. A # begins a comment. Annotated lines use three fields: kind, mnemonic, and explanation.

10111000 00101010 00000000 # instruction | MOV AX,42 | B8 chooses AX; 2A 00 is immediate 42.
11110100 # instruction | HLT | Stop instruction execution.

The mnemonic and hexadecimal notation are comments that explain the bytes. They are never parsed into instructions. bitpack reads the binary tokens, converts each token to its numeric byte value, and writes them in order. It does not select opcodes, resolve labels, or assemble mnemonics.

A byte token such as 10111000 is source notation. The packed byte is a value, 0xB8, not eight ASCII characters. Data, padding, and signatures are also explicitly present in the canonical source. No hidden binary blob supplies the executable instructions.

03 / Three bytes, one instruction

In 16-bit real mode, these bytes load decimal 42 into AX:

The immediate is little-endian: 2A 00 represents 0x002A. The opcode family is B8 + register index. Flipping the low bit of B8 produces B9, which selects CX instead of AX.

Architecture changes interpretation

The same B8 opcode in a different default operand-size environment can consume a different immediate length. The boot image is a 16-bit BIOS program; the Linux examples are x86-64 programs. Their encodings and execution environments must not be mixed.

Relative branches are measured from the end

The boot loop contains EB E0 at offset 85. EB is a short unconditional jump. E0 interpreted as a signed eight-bit number is −32. The next instruction would begin at 87, so 87 − 32 = 55: the next character read.

Instruction boundaries matter

Some instructions are one byte, others include an immediate or a ModR/M byte. The annotations mark those boundaries explicitly. A byte that is an operand in one context could be an opcode if execution starts at the wrong address. The explorer does not pretend to infer arbitrary x86 programs.

Try the bit editor to see valid encodings change and unsupported encodings stop the bounded simulation.

04 / Inside the 512-byte sector

BIOS places the sector at physical address 0x7C00. The first CLI disables maskable interrupts, and a far jump normalizes the code segment. The program then initializes data and stack segments, sets SP below the sector, and clears the direction flag.

The character loop

LODSB reads the byte at DS:SI into AL. TEST AL,AL detects the NUL terminator. The nonzero path saves AX and SI, selects BIOS teletype service AH=0E, and calls INT 10. The program restores those registers, waits for the COM1 transmitter-ready bit, and mirrors the same character to serial.

A controlled ending

When the message ends, the program disables maskable interrupts and executes HLT. A short jump returns to HLT if execution resumes. It does not return to nonexistent caller code or fall into the message data.

The signature is byte order, not a string

The last two bytes are 01010101 10101010, or 55 AA. Read as a little-endian 16-bit word, they are 0xAA55. The signature does not prove that the preceding instructions are safe or correct; it is a BIOS boot-format marker.

Inspect all 512 bytes and their source annotations.

05 / Four small host tools

All four tools are Python programs, with no assembler or compiler dependency for the target instructions.

bitpack / notation to bytes

./tools/bitpack boot/boot.bits build/boot.img

Converts eight-bit tokens directly to bytes. Invalid digits, malformed byte lengths, and malformed annotations produce an error with the source path and line number.

bitinspect / offsets and explanations

./tools/bitinspect build/boot.img \
  --annotations boot/annotations.json

Shows every offset, binary value, hexadecimal value, and known annotated region. These boundaries come from the source annotations, not a general-purpose disassembler.

bitverify / the reproducible contract

./tools/bitverify
./tools/bitverify build/boot.img --size 512 --bios

The project-level command verifies reviewed sizes and SHA-256 checksums, annotation presence, reproducibility, and equality between packed source and build outputs. It also checks the BIOS signature for relevant targets and screens target directories for forbidden compiled-language source extensions. Specific-file checks can use --sha256 HASH.

bitdiff / find the changed bit

./tools/bitdiff build/boot.img modified.img

For each changed byte, displays the old and new binary forms and a caret at every changed bit position. It also represents inserted or removed bytes.

06 / What executes, and what helps

Target side: deliberately direct

The original boot program is a flat raw sector with no ELF header, runtime, linker, symbol table or operating-system syscall interface. It uses real-mode instruction interpretation and BIOS services. The minimal image has no filesystem, scheduler or UEFI loader.

Host side: ordinary, inspectable work

Python packs and validates manually chosen bytes and adds metadata, hashes or container headers. It never synthesizes target instructions. JavaScript renders the instruments and a bounded instruction model. QEMU executes the actual target in an emulated machine.

Raw sectors and ELF are different containers

BIOS loads a raw sector at a conventional address. Linux loads an ELF according to its header and segment table. The Linux examples wrap handwritten payloads in host-generated ELF metadata; their instructions still come from literal binary source.

BIOS and UEFI are different interfaces

The BIOS targets use the 55 AA sector marker and BIOS services on entry. UEFI normally loads an EFI application through a different interface. No UEFI target or physical-hardware compatibility is claimed.

The original image and the new experiments

The original 512-byte image stays in real mode. A separate 568-byte target now loads a GDT, enters 32-bit protected mode, verifies flat memory and returns through one IDT software-interrupt gate. The separate shell remains in BIOS real mode and loads a returning disk app. Paging, general exception handling and hardware IRQ delivery remain research work.

07 / Choose the right environment

The gallery separates Linux x86-64 payloads from BIOS programs. A Linux executable does not boot as a disk sector; a BIOS image does not run as a Linux process.

Use the source README for each example's exact run command, binary path, expected behavior, and test. For the Linux examples on a non-x86 host, use a compatible Linux x86-64 environment; macOS cannot execute Linux ELF binaries directly.

Open the example source and reproduction instructions.

08 / What the browser models

The playground decodes the instruction bytes you select and models a small subset of 16-bit behavior. It exposes register values, zero and carry flags, and a textual explanation. Editing bits can produce an unsupported or truncated instruction; the interface reports that condition rather than inventing a result.

The boot explorer loads the actual 512-byte image and annotations. It checks the byte count, 55 AA marker, annotation coverage, and SHA-256 before enabling execution controls. Its stepper models the setup, output loop, stack saves, relative branches, and halt.

It is a bounded educational simulator. It has a 4,096-step limit. BIOS text mode and teletype output are simplified. COM1 is assumed immediately ready; no UART timing, interrupt delivery, processor fault, hardware device, or general-purpose BIOS is emulated. Unsupported instructions and BIOS services stop the simulation.

The animated hero terminal is a labeled transcript. The separate QEMU screen and recording are captures of actual boot execution. Neither the transcript nor the JavaScript stepper is evidence that an edited image boots correctly.

09 / Reproduction is the proof

make test
node tests/test_site.mjs

The test suite covers binary syntax, packing behavior, boot size and signature, reviewed encodings, reproducibility, and actual QEMU boot output. Site checks cover the decoder and bounded simulator, including the complete boot message. Browser checks exercise actual controls, narrow-screen layout, and local asset loading.

A checksum identifies a reviewed byte sequence; it does not prove correct execution on every machine. A QEMU boot test proves the tested emulator behavior; it does not prove that arbitrary hardware or UEFI will accept the image.

When you edit executable bytes, validate the changed target and update explanations from the instruction architecture references. A green website simulator is useful feedback, not a substitute for a real QEMU test.

10 / Make the next bit understandable

Keep instruction source handwritten. Include every opcode and operand in the .bits file, explain each region, and add a focused automated check for observable behavior. Reproduce the build and boot the relevant example before reporting it as working.

Good contributions include a clearer encoding explanation, a corrected address calculation, a minimal tested instruction experiment, or a more accessible explorer control. Avoid introducing an assembler into the target path or presenting an unverified milestone as complete.

Read the complete contribution guide and report a reproducible issue.

11 / Read the machine's contract

• Intel 64 and IA-32 Architectures Software Developer's Manuals — instruction formats, operand sizes, flags, and real-mode behavior.
• QEMU x86 system documentation — the machine used to execute the BIOS targets.
• Repository documentation — project architecture, annotated encodings, and reproduction details.

The project uses MIT licensing. The architecture is x86's; the educational value is making the encoding choices explicit.