Reviewing and Layered Repair of AI-Generated Firmware Graphics Code
This article documents the review and staged repair of automatically generated UEFI graphics code that failed to run reliably or produced no screen output. Using EDK II and the UEFI Graphics Output Protocol (GOP), it explains how to turn vague failures into testable hypotheses, identify stale mode data and protocol lookup errors, and apply targeted fixes while validating return values and resource lifetimes.
1. Background: Taking Over Graphics Code That Would Not Run
Firmware development is very different from application-layer development. Debuggers and breakpoints are often difficult to use, and it can be hard to inspect the system state after a runtime failure. A single invalid pointer can leave the entire machine unresponsive.
This article documents a real code handoff. The code had been generated by an automation tool. Its structure was complete and its modules were clearly separated, but it either exited immediately after startup on the target platform or started without producing any screen output. The goals were to make the program stable and ensure that the rendering result was correct.
The key to handling this type of failure is to break the vague symptom “it does not run” into several independently testable hypotheses. Each hypothesis can then be verified or eliminated in sequence. The sections below cover the code review, two rounds of fixes, and the underlying methodology. The examples use the UEFI Graphics Output Protocol (GOP) in an EDK II environment.
2. Step One: Perform a Structured Code Review
Running the code immediately usually produces only one signal: failure. A more effective approach is to perform a structured review first, list possible causes, and then determine the debugging order.
The review should cover the following five areas:
- Entry point and initialization: Verify that protocol discovery, mode selection, and frame buffer mapping occur in the correct order.
- Main loop and exit handling: Check whether the loop has a clear termination condition and whether exceptional branches emit diagnostic information.
- Module interfaces: Confirm that function signatures and data structures are consistent across modules.
- Protocol calls: Verify that the GUID comes from a reliable source, that
QueryModeandSetModeare called in the correct order, and that every call checks its return status. - Resource lifetime: Check whether memory allocated by
QueryModeis released and whether data accessed through a pointer is still valid when used.
The review findings from this case are summarized below.
| Symptom | Suspected hypothesis | Verification method |
|---|---|---|
| The program exits immediately after startup | Mode data becomes stale after switching modes | Print fields in Gop->Mode before and after SetMode |
| The screen remains blank | The GUID does not match the protocol installed on the platform | Check the return value from LocateProtocol |
| Graphics are misaligned or contain remnants | The resolution, stride, or pixel format does not match the active mode | Print the mode information and compare it with the rendering code |
| Some keys do not respond | The scan-code mapping table is incomplete | Record ScanCode and UnicodeChar for each key |
The value of this review is that it connects each symptom to a verifiable hypothesis. From that point, each step can test one hypothesis, and each fix can target a confirmed issue.
3. First Round of Fixes: From Failure to Basic Operation
3.1 Immediate Exit: Reading Stale Data After a Mode Switch
During the first run, the console printed the startup message and then the process exited. Serial debug output showed that the failure occurred after the SetMode call.
The original code called QueryMode, cached the mode information, called SetMode to switch modes, and then continued using the cached frame buffer address from before the switch.
After SetMode returns successfully, the firmware updates the Gop->Mode structure. This structure includes the current mode number, the pointer to the mode information, FrameBufferBase, and FrameBufferSize. Data cached before the switch may therefore no longer be current. Writing to the frame buffer through an outdated address can cause the program to fail. The fundamental issue is stale data; it is not that SetMode necessarily invalidates every pointer.
The repair principle is to reread any required data after an operation that may change the protocol’s internal state. For example:
// Incorrect: cache the frame buffer base before switching modes// and continue using it afterwardFrameBuffer = Gop->Mode->FrameBufferBase;Status = Gop->SetMode (Gop, ModeNumber);// FrameBuffer may now be stale// Correct: switch modes first, then read the current state// from Gop->ModeStatus = Gop->SetMode (Gop, ModeNumber);if (EFI_ERROR (Status)) {DEBUG ((DEBUG_ERROR, "SetMode failed: %r\n", Status));return Status;}FrameBuffer = Gop->Mode->FrameBufferBase;FrameBufferSize = Gop->Mode->FrameBufferSize;
If the resolution, stride, and pixel format are also required, call QueryMode:
EFI_GRAPHICS_OUTPUT_MODE_INFORMATION *Info;UINTN SizeOfInfo;Status = Gop->QueryMode (Gop, ModeNumber, &SizeOfInfo, &Info);if (EFI_ERROR (Status)) {DEBUG ((DEBUG_ERROR, "QueryMode failed: %r\n", Status));return Status;}HorizontalResolution = Info->HorizontalResolution;VerticalResolution = Info->VerticalResolution;PixelsPerScanLine = Info->PixelsPerScanLine;PixelFormat = Info->PixelFormat;FreePool (Info);
The Info structure returned by QueryMode is allocated by the firmware. The caller must call FreePool after using it. Info contains the resolution, stride, and pixel format, but it does not contain the frame buffer base address. That address is available through Gop->Mode->FrameBufferBase.
After this fix, the program entered the main loop, but the screen was still blank.
3.2 Blank Screen: Protocol Discovery Failed
Serial logs showed that LocateProtocol returned EFI_NOT_FOUND. All subsequent graphics operations depended on the Gop pointer, so the entire graphics path was skipped.
The original code used a custom GUID constant from the project that did not match the standard GOP identifier installed by the platform. In EDK II, the standard GOP protocol is identified by the standard EFI_GRAPHICS_OUTPUT_PROTOCOL_GUID; protocol discovery must use the correct GUID and its return status must be checked before the resulting interface is used.
