Binbows for Developers

Binbows is open source. You can read it, build it, break it, and open a pull request that makes it worse in an interesting way. That last one is the intended workflow.

The whole thing is one main.c of about 1,600 lines, a minimal uefi.h with only the protocol definitions it actually needs, a generated font header, and a Makefile. There is no SDK, no GNU-EFI, no EDK2, and no build system beyond make.

The entry point

A UEFI application starts at efi_main with two arguments: a handle representing itself, and the system table, which is the door to everything else. The real thing does more than this, but this is the shape of it.

/* main.c — how Binbows starts */
EFI_STATUS EFIAPI efi_main(EFI_HANDLE ImageHandle,
                           EFI_SYSTEM_TABLE *SystemTable)
{
    BS    = SystemTable->BootServices;
    ConIn = SystemTable->ConIn;

    fs_init(ImageHandle);       /* Loaded Image → device → drive C: */
    read_cpu_brand();           /* cpuid 0x80000002-4, for FETCH   */

    /* Locate the framebuffer. No GOP, no picture, nothing to say. */
    BS->LocateProtocol(&gopGuid, NULL, (void **)&Gop);
    if (!Gop) for (;;) __asm__ volatile("hlt");

    show_splash(4000);          /* C:\LOGO.SYS, four seconds       */
    draw_bsod();
    wait_key();
    shell();                    /* never returns                   */
}

Note the hlt loop. There is no operating system to return an error to and no console to print one on, so a missing GOP is the end of the story.

The protocols it uses

Everything Binbows can do, it does through four UEFI protocols. That is the complete list — there is no fifth one, and there is nothing underneath them.

The shell loop

No message queue, no event dispatch, no window manager. The application reads a line and runs it, forever, and it is the only thing running on the machine.

static void shell(void) {
    con_init(make_color(192, 192, 192), make_color(0, 0, 0));

    con_line("Michaelsoft Binbows 98");
    con_line("   (C) Copyright Michaelsoft Corp 1981-1998.");
    con_line("Recovery console. Type HELP for a list of commands.");

    char line[LINE_MAX];
    for (;;) {
        con_put_cwd();
        con_putc('>');
        read_line(line);
        run_command(line);
    }
}

/* If you exit this loop, there is nothing to exit to.
   Which is why EXIT does not. */

Building from source

The repository builds a bootable ISO. On a modern machine this takes about a second, which would have been science fiction to the people this project is imitating.

# dependencies (macOS)
brew install llvm lld xorriso mtools

# clone and build
git clone https://github.com/lucya-astralis/binbows.git
cd binbows
make

# boot it under QEMU with OVMF firmware
make run

Neither mtools nor xorriso has a Windows build, so the repository carries tools/mkfat.py and tools/gptify.py — byte-for-byte substitutes for those two steps, both producing images that have been booted under OVMF.

Contributing

Contributions are welcome. The bar is not "is this good," it is "does this make the project more itself."

• Refusals. The lowest-friction contribution in the repository: one line in refusals[], one joke, done. Keep it dry.
• Bugs: open an issue with the machine, the firmware and what you saw. A photo of the screen is a completely valid bug report here, because there is nowhere to copy text to.
• Features: discuss first. Some things are deliberately broken and fixing them is a regression. The roadmap says which.
• Docs: the most valuable and least submitted kind of pull request, as is tradition.
• Tests: there are none. There is a person who boots it under OVMF and looks at it. You can be that person.

API questions go to [email protected], patches to [email protected], and anything involving a lawyer to [email protected]. The first two are the same inbox. So is the third, spiritually.

Coding style

Match what is there. In case that is ambiguous, what is there is:

Open the repository   Downloads