AI-Assisted Development and Troubleshooting of Pre-Boot Firmware Graphics Programs
Pre-boot graphics programs run without a mature OS, so memory layout, protocol discovery, and display mode switching are provided directly by firmware services. Handed to AI coding assistants, these programs rarely fail at writing a loop; they fail at setting up the environment, running stably after compiling once, or producing correct graphical output. This article shows how to take a structurally reasonable but non-functional codebase and fix it into something demonstrable, then iterate it into something maintainable—covering two-round goal setting, code review before editing, build setup ahead of gameplay, two common failures (dangling pointers after mode switches and wrong protocol identifiers), and a disciplined, log-driven process for constraining AI assistant iterations.
Graphics programs in the pre-boot phase are different from ordinary desktop applications: there are no mature operating system services, and memory layout, protocol discovery, and display mode switching are all provided directly by firmware services. When you hand this kind of program to an AI coding assistant, the common failure is not an inability to write a loop. It is that the environment cannot be set up, that the program compiles once but does not run stably, or that the UI logic looks complete but never produces correct graphical output. The sections below follow engineering practice to explain how to fix a codebase that is structurally reasonable but non-functional into something you can demonstrate, and then iterate it into something maintainable.
Set Goals First, Then Split Into Two Rounds
Don’t demand a “perfect game” from the start. Break acceptance into two rounds.
The first round only pursues a minimal closed loop: the project can be configured, compiled, and turned into a loadable image in the target firmware build environment; the entry point can print a startup marker; the main loop can keep running instead of returning immediately; and at least a static graphic or a simple dynamic element can be drawn on screen. Only in the second round do you handle game feel, collision, scoring, Chinese or bitmap glyphs, resolution adaptation, and code cleanliness.
The reason to separate the two rounds is that failures in pre-boot programs usually concentrate in protocol discovery, resources becoming invalid after a mode switch, and the build system—not in gameplay algorithms. If you change gameplay and low-level code at the same time, the logs cannot be traced back to a single change, and the assistant tends to bounce between multiple assumptions and keep patching.
Review Existing Code Before Editing
If you already have several modular source files where the entry point, main loop, logic, drawing, and input are separated, preserve those boundaries instead of rewriting the whole directory. The first instruction to the assistant should be scoped to review: list, by module, the places that may fail to link, may fail to locate a protocol, or may have null-pointer or lifecycle errors, and explain the reasoning—without changing code yet.
The review checklist is best fixed as the following items.
- Whether the entry point correctly installs or locates the required boot services and the graphics output protocol, and whether the failure path prints and returns a clear status instead of continuing to use a null handle.
- Whether the information structure obtained from the display mode query is still treated as a valid pointer after the mode is set.
- Whether the protocol identifiers match the definitions in the current firmware headers, and whether an identifier with the same name but a different purpose has been used by mistake.
- Whether the main loop’s exit condition is too broad—for example, any keypress, an uninitialized event, or an error state being treated as “game over”.
- Whether the build description includes graphics, console, and the necessary libraries, and whether the include paths point to the current tree rather than leftover paths from another toolchain.
- Whether heap and pool allocations have matching frees, and whether the loop repeatedly allocates large buffers.
The output of this step should be a list of problems and a fix order, not a large block of new gameplay generated on the spot. The order is usually: get compilation and loading working first, then eliminate the exit-on-startup, and only then fix “it runs but shows no picture”.
Get the Build Environment Working Before Gameplay
Many assistants will write game logic first while ignoring the firmware project’s build description, package dependencies, and output format. If the build environment itself does not hold up, no subsequent logic can be verified. In practice, you should require the assistant to first give repeatable build steps: which firmware build tooling to use, how to set up the workspace, how to compile only the target package, what the output filename is, and how to load it in a pre-boot environment on a virtual machine or real hardware. When the steps are unclear, do not move on to the second round.
At the same time, agree on a logging channel. The graphics console may become unavailable after a mode switch, so prefer serial or debug output for short markers: entering the entry point, protocol located successfully or failed, mode queried, mode set, frame buffer re-acquired, entering the main loop, and each class of error code. The markers should be short and unique, to avoid the assistant masking the real failure point with large strings.
Typical Failure: Dangling Pointer After Mode Switch
A high-frequency crash is: the program has printed that it entered the main loop, and then immediately exits or resets. The call sequence is often to first query the current or target display mode, obtain a structure describing the resolution, pixel format, and frame buffer base address, then set the mode, and then write pixels through the old pointer.
Setting the mode may renegotiate display resources. By definition, the information buffer returned earlier should no longer be held long-term; continuing to dereference it is equivalent to using a dangling pointer. The symptom may be an exception while writing pixels, or a subsequent drawing function receiving the wrong scanline length and soon reaching an illegal access.
The fix principle is simple: after any call that changes the display mode or may cause the controller to reallocate the buffer, discard the old information, query the current mode again, and use the new base address, bytes per pixel, and bytes per row for subsequent drawing. Both the query and set return statuses must be checked; on failure, print the status code over serial and stop on a safe path, and do not enter the main loop with a null pointer.
The sample code below only expresses the sequence and does not represent a proprietary interface of any specific firmware stack:
int use_mode(Graphics *g, unsigned mode) {ModeInfo *info = NULL;if (g->query(g, mode, &info) != OK || info == NULL)return ERR;/* Use info only to decide whether to switch; do not keep it past the switch */if (g->set_mode(g, mode) != OK)return ERR;info = NULL;if (g->query(g, g->current_mode(g), &info) != OK || info == NULL)return ERR;g->fb = info->frame_base;g->pitch = info->pixels_per_scanline * bytes_per_pixel(info);return OK;}
The drawing layer should depend only on the re-acquired fb and pitch. If the assistant caches mode information in a global structure, the review should explicitly flag that “the mode information must be invalidated entirely after a mode switch”.
Typical Failure: Wrong Protocol Identifier Causes No Output
The program no longer crashes, but the screen still shows the firmware’s original image or is all black—this is often because the wrong protocol was located. The graphics output, text console, and pointer device have different identifiers in the headers; some are for installation, some for opening by handle, and some for testing. An identifier that is off by one bit will make the open call fail; if the code treats the failure as “optional functionality” and continues, the main loop still spins, it just never writes any pixels.
The way to handle this is: have the assistant check against the protocol headers actually included in the current project, and list every identifier this program opens, the call site, and the status code on failure, forbidding writing constant bytes from memory. A failed open must abort and log; it must not degrade into an empty drawing. If multiple versions of the same graphics capability exist, the choice rationale should be written in a comment as “provided by this firmware and able to query the mode”, not “the names look similar”.
When there is no picture, you can also verify the chain with a minimal probe: after setting the mode successfully, fill a few scanlines with a solid color. If the solid color is visible, the problem is in the sprites or font; if the solid color is not visible, the problem is still in the frame buffer base address, the pixel format, or writing to a buffer that is not scanned. This step pulls the assistant back from “rewriting the whole renderer” to a single observable experiment.
How to Constrain the Assistant’s Iterations
An assistant tends to change protocol, memory, and gameplay all at once after a failure. You should require that each round fixes only one class of problem and keeps a reversible diff. The recommended rhythm is as follows.
- Fix only the build and entry-point logging, and confirm the image loads.
- Fix only the lifecycle of the mode query and set, and confirm it no longer exits abnormally.
- Verify only the protocol identifiers and pixel format, and confirm the solid color bar is visible.
- Restore the game logic on top of the above baseline: blocks or paddles, collision, timing.
- Finally do input debounce, frame-rate cap, resource release, and module comments.
Each round’s prompt should include: the current symptom, the last serial marker, the files allowed to be modified, and the interfaces forbidden to change. For example, “only allowed to modify the information acquisition after the mode set in the display module; do not change collision”. The narrower the scope, the less likely the assistant is to introduce new wild pointers.
For the assistant’s “it will run once fixed”, trust the logs and the picture, not its own account. Compiling only means the symbols are complete; stopping in the main loop only means it did not immediately hit an illegal address; only stable pixel output proves the graphics protocol chain is closed.
Modular Legacy Code Is Worth Fixing, Not Rewriting
A half-finished product with multiple files and separated responsibilities is usually more worth fixing than a “working draft” crammed into a single file. The entry point locates protocols, the logic layer only handles coordinates and state, the drawing layer only consumes the frame buffer description, and the input layer translates keypresses into commands. When fixing defects, the assistant should be required to preserve these boundaries: the logic layer must not directly call set-mode, and the drawing layer must not parse protocol identifiers. This way, in the second round of optimization, changing the resolution or pixel format will not disturb the gameplay.
The polish phase can add, but is not limited to: batch filling per scanline to reduce per-pixel calls; clipping coordinates that exceed the resolution; caching glyph or block templates outside the loop; using a fixed time step in the main loop so gameplay is reproducible across machines of different speeds; and releasing pool memory on the exit path and restoring text mode, making it easy to return to the firmware menu. These are all general engineering practices and do not depend on any special capability of a particular model.
Acceptance and Documentation
It is worth keeping a short record: the target environment, build commands, key serial markers, whether the mode was re-queried before and after switching, the source of the protocol identifiers, and known limitations (for example, only a certain pixel format is supported, or hot-plug display is not handled). The purpose of the record is to let the next assistant session start from facts rather than from chat memory.
If used in a team process, you can put the above checklist into a code review template: lifecycle, identifier provenance, visible failures, and change scope. AI coding assistants are well suited to boilerplate code, cross-checking against headers, and small step-by-step patches guided by logs; humans are responsible for setting acceptance, cutting off overly broad changes, and judging whether the resource constraints of the pre-boot environment are really met. Following the order of “closed loop first, then polish; logs first, then picture”, a firmware graphics utility program can converge from not compiling to running repeatably, without falling into unbounded rewriting.
