Writing BIOS Graphics Programs with AI: A Practical Approach for UEFI Development
This article walks through an experiment in using an AI coding tool to build a graphics program—a Tetris-style game—that runs directly in the UEFI environment, before an operating system or display driver exists. It documents how AI took over half-finished code left by another AI tool, first eliminating fatal bugs through code review and serial-port logging, then refining performance, rendering, and code structure. Along the way it covers the common pitfalls of UEFI graphics development: locating the graphics output protocol, managing the lifetime of mode information, calculating pixel offsets by stride, and driving the main loop with events. It closes with reusable practices for collaborating with AI on low-level firmware work, where the real difficulty lies in long debugging loops, slow feedback, and hidden errors.
1. Background: Why Writing a “Moving Program” in the BIOS Is Hard
Running a graphics program directly during the boot phase is a direction many low-level developers find compelling: there is no operating system, no display driver, and you have to light up the entire screen yourself. Programs like this are usually packaged as EFI applications that run in the UEFI Shell—referred to throughout this article as UEFI programs. They are small, boot fast, and are often used for hardware self-tests, pre-boot animations, and visualization tools.
This kind of development has to clear at least three hurdles:
- Development environment: You need a complete firmware build toolchain. A GNU toolchain, for example, requires matching binaries from the firmware platform to produce image files the firmware can load, and the compilation target has to match the firmware’s bit width.
- Debugging feedback: Once a graphical interface freezes, all you see is usually a black screen or a frozen frame, and error messages have to be read slowly over a serial port.
- Interface details: When the graphics output protocol’s mode information becomes invalid, how the protocol is located by its identifier, and how key events are awaited—these details get little coverage in books and are easy to overlook in documentation.
So it helps to break the task down by difficulty first:
| Level | Completion Mark | Typical Sticking Point |
|---|---|---|
| L1 Environment ready | Validate the toolchain with an empty program that prints text in the Shell | Build script doesn’t match the toolchain, bit-width mismatch |
| L2 Can draw | Successfully switch resolution and draw a square at a fixed coordinate | Can’t find the output device, mode switch fails, pixel offset miscalculated |
| L3 Animates | Game loop advances at a fixed cadence | CPU spins idle, refresh speed depends on machine performance |
| L4 Playable | Keys respond instantly, exits cleanly | Lost keys, wrong key values read after WaitForEvent ends |
Using this as a baseline, we can run a follow-on experiment: have an AI coding tool take over half-finished code left by another AI tool, and see whether it can walk the whole path. The reason for choosing a “follow-on” rather than pure generation from scratch is that the most common scenario in real projects is exactly taking over code that someone else wrote halfway and that doesn’t run. This kind of scenario tests a model’s comprehension, debugging ability, and engineering habits all at once.
2. Experiment Design: Letting AI Take Over AI-Written Code
Input material: Earlier, another AI tool had attempted to write a Tetris game in a firmware environment. After several hours of struggling, it still couldn’t set up a build environment and produced no runnable program. But the code it left behind looked solid: seven files, clearly layered, with logic, rendering, and input kept separate. Rewriting a set from scratch wasn’t necessarily more cost-effective than understanding and fixing it, so this “raw material” had value.
Execution tool: A coding tool with terminal-execution capability (referred to below as the AI coding tool). This kind of tool can read and write files, run commands, and feed compiler output and serial logs back to the model.
Comparison baseline: In the same environment, a Chinese-language brick-breaker program had already been built and run. It took about 2.5 hours, compiled on the first try, and ran successfully on the first launch.
Two rounds:
- Round 1 (from “runs after fixes” to “actually runs”): Review the code and fix fatal issues one by one, with the completion criteria being “doesn’t crash on launch, displays correctly, and responds to keys.”
- Round 2 (from “runs” to “playable”): Refine the rhythm, visual quality, and code structure, with the completion criteria being “consistent performance and clearly improved maintainability.”
It is worth noting that the two tasks are not equivalent: brick-breaker is “ball + paddle + bricks,” while Tetris also has to handle piece rotation, line-clear detection, and progressive speed increase, so it is inherently harder. This is therefore not a simple speed comparison. The focus is instead on observing whether AI can understand someone else’s code, trace vague symptoms back to root causes, and make modifications that are restrained and non-destructive to the existing structure.
3. Round 1: From “Runs After Fixes” to “Actually Runs”
1. Do a code review first, rather than editing directly
The first instruction was: Review this code, find possible problems, list them by “fatal / important / suggested” severity, and explain the reasoning. A few minutes later, the tool produced a list, summarized below:
| Severity | Issue | Possible Consequence |
|---|---|---|
| Fatal | Build script only links the main source file, omitting the logic and rendering modules | Link failure or incomplete behavior |
| Fatal | Unreasonable order for retrieving mode info during graphics init | Reads invalid memory at runtime, program crashes |
| Fatal | Protocol location uses a custom GUID | Can’t find the device, can’t get a valid output handle |
| Important | Main loop busy-waits instead of waiting for events | CPU maxed out, refresh speed fluctuates with hardware |
| Suggested | Color format hardcoded to 32-bit pixels | Corrupted image on 16-bit color-depth devices |
The value of this list is that it broke the vague outcome “won’t run” into concrete hypotheses that can be verified one by one. Compared to a one-shot full rewrite, the change surface is small, each step has an expected effect, and it is easy to roll back when something goes wrong.
Practice Tip: When asking AI to do a review, require every issue to include four elements: location, symptom, reasoning, and suggested fix. A list that gives only conclusions without reasoning simply shifts all the verification cost onto the developer.
2. Problem one: The UI renders, but the program crashes on any keypress
After launch, the main menu appeared, but pressing any key exited immediately because GameMain returned a non-zero value. After feeding this back to the AI, it proposed a three-step approach:
- Add ASCII-encoded error logs before each failure branch in
GameMain, and output them to the serial port via the Lushan logging function; - Refresh the logs in the serial monitor and reproduce the problem;
- Locate the cause from the logs, then fix it.
The logs showed that the game’s main loop returned an error at the initialization stage. The problem was in the graphics module:
/* Problem code (illustrative) */Status = gGop->QueryMode(gGop, mode_index, &info_size, &mode_info);GopSetMode(gGop, mode_index); /* Switch to the game resolution */screen = (UINT32 *)mode_info->FrameBufferBase;screen_stride = mode_info->PixelsPerScanLine; /* Used as row offset when drawing pixels */gBS->FreePool(mode_info); /* This memory is still in use throughout drawing */
The conclusion: the information returned by QueryMode is usually just a temporary copy, and once freed, that memory can be reused by other code; switching modes also changes the underlying display configuration. In the original logic, the entire drawing phase accessed that already-freed memory through screen and screen_stride, and the problem was deferred until GameMain first used the frame data.
Following the principle of “keep changes minimal, keep responsibility clear,” the fix was:
EFI_GRAPHICS_OUTPUT_MODE_INFORMATION *ModeInfo = NULL;UINTN ModeInfoSize = 0;UINT32 ModeIndex = 0;Status = gGop->QueryMode(gGop, 0, &ModeInfoSize, &ModeInfo);if (EFI_ERROR(Status)) {AsciiPrint("query mode 0 failed: %r\n", Status); /* %r prints the status code meaning directly */return Status;}ModeIndex = ModeInfo->Mode;Status = gGop->SetMode(gGop, ModeIndex);if (EFI_ERROR(Status)) {AsciiPrint("set mode %d failed: %r\n", ModeIndex, Status);FreePool(ModeInfo);return Status;}/* Fetch frame buffer address and stride only after the mode switch completes */screen = (UINT32 *)(UINTN)gGop->Mode->FrameBufferBase;screen_stride = (UINTN)gGop->Mode->Info->PixelsPerScanLine;gBS->FreePool(ModeInfo); /* Free immediately; not referenced afterward */
After recompiling, the program successfully entered the game loop and the blocks began to fall. The hardest hurdle of Round 1 was cleared.
Practice Tip: This kind of use-after-free is a frequent problem when AI generates low-level code: memory allocation and deallocation are written in the same function, but the object’s lifetime far exceeds that function. During review, specifically check whether “a pointer outlives its lifetime boundary.”
3. Problem two: The graphics module initializes, but no output device is found
Next, the interface needed to be drawn. The AI wired the game module up to the graphics interface, and at runtime the “graphics module initialization” step failed. Continuing to check the serial logs, the problem was traced to protocol location:
/* Problem code (illustrative): HandleProtocol was called with gEfiCallerIdGuid */Status = gBS->HandleProtocol(gImageHandle, &gEfiCallerIdGuid,(VOID **)&gGop);
The reasoning:
- The second parameter of
HandleProtocolidentifies the interface type; locating graphics output requires passinggEfiGraphicsOutputProtocolGuid. gEfiCallerIdGuidis an identifier the image registers for itself in the loaded-image protocol; it is commonly used to uniquely identify this image, and is not the protocol GUID for any feature.- When the program started in the emulator, the second parameter happened to be the image handle itself—this “coincidentally works” behavior further masked the error.
The fix replaced only the identifier parameter, left the rest of the code untouched, and added logging and exit logic to the failure branch:
Status = gBS->HandleProtocol(gImageHandle, &gEfiGraphicsOutputProtocolGuid,(VOID **)&gGop);if (EFI_ERROR(Status) || (gGop == NULL)) {AsciiPrint("locate GOP failed: %r\n", Status);CleanUp(); /* Release key-wait events and other resources */return EFI_NOT_FOUND;}
The program then entered the graphical interface normally, and all the core goals of Round 1 were achieved.
Practice Tip: If a message like “Graphics output module: not available” appears in the logs, or the frame buffer address is 0, first check whether the protocol GUID was passed correctly. Note that behavior in an emulator and on physical hardware isn’t always the same—trust the serial logs, not “it looks fine on my end.”
4. Round 2: From “Runs” to “Playable”
The goal of this round was no longer just “make it run,” but “make it stable, make it legible, make it easy to change.” I listed six requirements and had the AI improve the existing architecture against them one by one.
1. Define the goal: Break “better experience” into verifiable metrics
| Dimension | Acceptance Criteria |
|---|---|
| Performance | Consistent frame rate on physical hardware and in the emulator, no longer dependent on machine performance |
| Visuals | Legible Chinese dot-matrix text; clean block edges; prompts for line clears and game over |
| Interaction | Keys respond instantly; rotation, left/right movement, and soft drop are accurate; clean return to the Shell on exit |
| Resources | No memory leaks throughout a run |
| Maintainability | Game parameters configurable; performance data toggleable; code layering preserved |
2. Visuals: Chinese dot-matrix and pixel details
The default text output can’t display Chinese in graphics mode, so the AI added 16×16 dot-matrix data for common prompt strings and encapsulated a text-drawing function. It also unified how pixels are written:
/* Compute pixel offset by stride, compatible with non-standard-width resolutions */static VOID PutPixel(UINT32 x, UINT32 y, UINT32 color){if ((x >= (UINT32)gScreenWidth) || (y >= (UINT32)gScreenHeight)) {return; /* Clip before drawing to avoid writing out of video-memory bounds */}screen[y * gStride + x] = color;}
Another detail was the boolean return value. In the original code, some functions used TRUE/FALSE to indicate success, but the interface documentation specified a BOOLEAN parameter. After confirmation, this was unified so that TRUE means the function succeeded and FALSE means it failed.
3. Rhythm: Timer-driven updates and CPU usage
The original main loop relied on busy-waiting to maintain its cadence, and CPU usage was close to 100%. The AI added a periodic timer and separated “waiting for events” from “updating the frame”:
while (!quit) {UINTN Index;EFI_INPUT_KEY Key;/* Wait on both key and timer at once: sleep when there's no input, no more spinning */Status = gBS->WaitForEvent(2, wait_list, &Index);if (Index == 0) {/* Read the key value only when the event was triggered by a keypress */if (EFI_ERROR(gST->ConIn->ReadKeyStroke(&Key))) {continue;}handle_key(Key.ScanCode, Key.UnicodeChar);continue;}if (gBS->CheckEvent(gTimer) == EFI_SUCCESS) { /* Confirm the timer has expired */gBS->SignalEvent(gTimer);if (gPerf) {/* Measure this frame's elapsed time and accumulate the frame count */}update_game();render();}}
The effect was immediate: CPU usage dropped noticeably, and on physical hardware the blocks fell at basically the same speed as in other environments. One point worth raising here: the original ReadKeyStroke ignored EFI_NOT_READY (meaning a key isn’t ready yet), and after the loop exited the WaitForEvent event list was invalidated—yet the code still called the key read afterward, which is “formally able to end, but logically not clean.” After the change, the exit path retains only normal resource release.
4. Boundaries and robustness: line clears, spawn position, out-of-bounds
- Line-clear detection: When checking for full rows, first determine whether one exists, then decide whether to shift down or destroy, avoiding a repeated full scan every frame;
- Spawn position: A new piece generated at the top could be pushed outside the play area because it collided before being written; this was changed to pre-check for collisions before writing;
- Scoring and level: Score accumulates by the number of lines cleared, the level rises with the score, and the fall interval shortens accordingly.
The AI also left one minor flaw in the prompt text for the disabled performance toggle. Issues like this are best caught manually during code review, then fixed in one consolidated text pass at the end.
5. Resource configuration: Make parameters configurable
Parameters such as the number of piece types, the initial fall interval, and the pixel size per cell were changed from hardcoded values to configuration items, making them easy to adjust later on devices with different resolutions. The changes didn’t introduce any new global variables; instead they reused the existing configuration structure.
5. Retrospective: Three Reusable Collaboration Practices
Looking back at this follow-on experiment, what actually made the difference wasn’t some “prompt template,” but three basic practices.
1. Describe the task as an “interactive process,” not a “static interface”
AI tends to write code that “looks correct,” because training data contains far more examples of static interfaces than interactive programs. When describing requirements, lay out the runtime flow in full:
- On launch, show the main menu prompting “Press Enter to start, Press Esc to quit”; at this point, don’t create the game and don’t occupy graphics resources;
- Press Enter to switch resolution and start the game, showing the initial piece, the score, and the next piece;
- Left/right arrows move, up arrow rotates clockwise, down arrow accelerates the fall, spacebar pauses or resumes;
- When the game ends, show the score and prompt to press R to restart or Esc to return to the menu;
- Exiting from the menu releases all resources, clears the screen, and returns to the Shell.
A clearly described state machine often determines generation quality more than the instruction “write a Tetris game.” The runtime logic above isn’t complex in itself, but once it’s written as a “state → event → feedback” list, the AI has a goal it can implement item by item.
2. Closing the runtime-feedback loop is the most effective “context”
- Give conclusions: The AI said “it’ll run after the fixes.” The actual result was that it launched, but exited on any keypress;
- Give logs: Connect serial output so it can locate the game-initialization failure itself;
- Give constraints: Require the smallest possible change scope, and explain why each change is made.
A single serial log often carries more information than several hundred words of natural-language description. So it’s worth spending half an hour up front to set up serial logging and remote debugging—every subsequent iteration will benefit from it.
3. When letting AI take over code, build “understanding” before acting
- Put code review first: The larger the codebase, the more essential this is, and let the checklist itself become the basis for discussion;
- Layer the changes: Apply fatal issues as minimal patches; put refactoring, configuration, and performance toggles in the second round, and keep them aligned with the original structure;
- Leave the last step to the human: Architectural tradeoffs, boundary conditions, and wording details still require human judgment.
6. Practical Advice for Teams
1. Environment first: validate the toolchain
Start with a minimal “Hello UEFI”–level program to prove out the full chain of compile → emulated run → physical-machine boot, and only then write the graphics logic. If your team’s build and verification workflows aren’t yet standardized, you can also lean on general-purpose capabilities such as the container services and pipelines offered by Baidu AI Cloud to turn build, test, and log collection into a repeatable, automated process where every iteration leaves a clear trail.
2. Layer the debugging methods
| Method | Purpose |
|---|---|
| Build-time static checks | Catch format-string, argument, and type problems at compile time |
| Serial logging | Record key milestones and error codes during startup |
| Emulated run | Quickly verify logic without depending on hardware |
| Physical-machine verification | Finally confirm resolution, input, and color rendering |
3. Build a checklist
- Is mode info held only for its period of use, and released promptly afterward?
- Are the frame buffer address and stride re-read after the mode switch?
- Is the protocol GUID correct, and are the return value and null pointer checked?
- Is the pixel offset computed by stride, and is clipping done before drawing?
- Is the main loop event-driven, and is CPU usage normal?
- Is there any flicker, and is a temporary frame buffer needed?
- Does the exit path fully release resources and events?
- Is text output ASCII, and does any prompt need Chinese dot-matrix rendering?
7. Conclusion
Developing graphics programs in a firmware environment is hard not because of the amount of code, but because the debugging path is long, feedback is slow, and errors are hidden. AI coding tools can significantly shorten the distance “from idea to something runnable,” but the prerequisite is that requirements are described clearly enough and runtime feedback is fed back to the AI promptly. In this experiment, the AI took over code generated by another AI: it first did a review, then used serial logs to turn vague symptoms like “crashes” and “no image” into concrete root causes, and finally, in the second round, pushed things from “runs” to “playable.” Throughout this process, the AI’s value showed up mostly in “translation” and “execution”—turning the developer’s vague ideas into an executable plan, and turning interface conventions scattered across documentation into correct code. For developers, three questions must be held firmly in their own hands: what the requirement is, whether the environment is trustworthy, and whether the result has actually been verified. Only by getting these three right can AI’s potential in low-level development genuinely translate into delivery quality.
