Debugging UEFI GOP Graphics with AI: A Practical Troubleshooting Walkthrough
This article documents a hands-on experiment in using AI to debug a UEFI graphics application built on the Graphics Output Protocol (GOP). Starting from legacy code produced by another model, it walks through two testing rounds: first making the program run, then improving its performance, robustness, and portability. It dissects two high-frequency firmware bugs — dangling pointers triggered by mode-switch invalidation and improper GOP protocol location — and covers frame pacing, key-repeat handling, resource cleanup, and resolution portability. It then distills a transferable human-AI collaboration methodology for firmware debugging: standardizing acceptance criteria, iterating in small steps, prioritizing observability, and keeping humans in the loop for safety-critical code.
Introduction: AI Can Write Code, But That Doesn’t Mean It Runs
Large language models have improved rapidly at code generation. Given a requirements document, a model can produce multiple source files within minutes, with a clear directory structure and reasonable naming that, at first glance, looks close to a commit-ready state. But drop that generated code into a real firmware environment — especially a constraint-heavy one like UEFI — and problems tend to surface all at once.
Firmware has no operating system to fall back on: no complete standard library, no general-purpose exception handling, and none of the debuggers and logging systems developers take for granted on desktop platforms. The callable capabilities come mostly from protocol interfaces provided by the firmware framework; memory is managed by firmware boot services or a protocol manager, and may change as the boot phase progresses. Debugging options are also limited, typically to serial logs, QEMU output, or a few boot-layer tools.
There was an earlier comparison experiment: two large models were asked to write firmware-level graphics programs. The first model produced a Breakout (brick-breaker) program in about 2.5 hours; it compiled on the first try and ran successfully on the first attempt. The second model attempted a Tetris clone, taking nearly 6 hours, and in the early stage couldn’t even get a stable build environment set up. This experiment can’t simply be treated as a model-capability benchmark, because task difficulty, build environment, acceptance criteria, and repetition counts were not fully standardized.
Still, the experiment raised a worthwhile follow-up question: what happens if you have one model fix the code left behind by another? This is essentially “AI troubleshooting for AI.” Compared with generating from scratch, this scenario tends to expose real engineering problems more easily: the code already exists, the task boundaries, runtime environment, and acceptance goals are relatively clear, and the model has to locate defects in unfamiliar code, explain behavior, and verify fixes.
This article reviews a “second-owner” test. The first round aimed to turn the program from “finished writing” into “runs”; the second round aimed to turn it from “runs” into “runs stably and well.” Note that the focus here is not on which model is stronger, but on summarizing a human-AI collaboration method that transfers to firmware graphics debugging.
Test Environment and Methodology
To make the process reproducible, here are the basic conventions first.
Code and Runtime Environment
- Platform: A UEFI application running in the boot phase after the Driver Execution Environment (DXE), where Boot Services are available. If the code is loaded as a DXE driver or a Shell application, it must also follow the lifecycle constraints of the corresponding phase.
- Graphics: Frame buffer access through the Graphics Output Protocol (GOP) for mode setting, frame buffer querying, and image transfers.
- Input: Key detection through the wait event of the Simple Text Input protocol.
- Execution: Code is copied to a clean environment and loaded/run via the UEFI Shell.
- Build: The
.efifile is produced with the UEFI development framework’s build toolchain. - Debug channel: Serial port.
The emphasis on a “clean environment” is deliberate, because common legacy-code failures fall into two categories:
- Environment-coupling: it compiles and runs, but depends on old directories, old configs, or old dependencies;
- Logic defects: the code logic itself is wrong.
Verifying in a clean environment first quickly rules out the first category, letting subsequent investigation focus on protocol calls, resource lifecycles, and runtime logic.
To improve reproducibility, it helps to record the following environment details:
- EDK2 version: e.g.,
stable202405or a same-generation stable branch; - Build configuration:
Target=DEBUG,Arch=X64orIA32; - Firmware environment: OVMF, a QEMU platform, or a specific dev board’s firmware version;
- Serial parameters: commonly
115200 8N1; - Log collection: serial terminal, serial-to-file utility, or VM serial redirection;
- Acceptance criteria: whether it enters the main loop, whether graphics output appears, whether keys respond, and whether it exits cleanly.
The Two Rounds
| Round | Goal | Acceptance criteria |
|---|---|---|
| Round 1 | Fix key defects blocking execution | Program starts normally, enters the main loop, keys respond, screen updates continuously |
| Round 2 | Improve performance and robustness | Stable frame rate, resources released correctly, clear feedback on error paths, portability across devices |
Round 1: From “Finished” to “Runs”
Review First, Then Modify
After handing the legacy code to the model, the first instruction was not “fix it,” but:
Review this code and list the likely problems; don’t modify anything yet.
The reason: if you ask the model to fix code directly, it often rewrites it according to its own understanding, which can throw away the sound parts of the original and loses the window to observe the model’s diagnostic ability. Only by making it read and judge first can you see how deeply it understands the code structure, interface constraints, and potential failures.
The model analyzed module by module — entry point, main loop, game logic, rendering, input — and produced a severity-ranked problem list. It helps to organize the review output into a table for point-by-point verification:
| # | Problem | Severity | Evidence | Verification |
|---|---|---|---|---|
| 1 | Mode info pointer becomes invalid after mode switch | Blocking | Serial log shows crash after mode setting | Confirmed |
| 2 | Incorrect use of the GOP protocol GUID | Blocking | Graphics init returns EFI_NOT_FOUND |
Confirmed |
| 3 | Repeated key triggering | High | Movement too fast on long press | Confirmed |
| 4 | Unstable frame rate | Medium | Large variance in frame intervals | Confirmed |
| 5 | Handle array not freed | Low | Code review | No leak warning after fix |
It’s worth stressing: the model’s judgments are only hypotheses and must be confirmed or refuted by actual runtime results. A trackable fix list is far better suited to firmware debugging than a one-off “large rewrite.”
Fault 1: Exits on Startup — Root Cause Is a Wild Pointer
Symptom
- The program loads successfully and the serial log prints
Starting Game Loop. - Just as the main loop is about to begin, the program exits directly.
- There’s no standard error-handling flow before exit and no recoverable exception message.
Localization
I had the model add finer logging on the critical path: print status before entering the main loop and before/after each protocol call. The serial output showed the program behaving abnormally on the GOP call chain: the mode-set call returned success, but the program crashed when subsequently accessing the mode info.
Root cause
When QueryMode queries mode information, it returns a block of firmware-allocated memory through the Info output parameter; the Mode Information struct within describes details such as the mode’s resolution. But when SetMode sets a mode, it changes the device’s working state, and the mode info pointer previously obtained through QueryMode may become invalid as a result.
If the code keeps using the old pointer after SetMode, you get a classic wild-pointer or dangling-pointer problem. This kind of bug may “look fine” during single-step debugging, because memory isn’t necessarily reused immediately after a mode switch; but once allocation behavior changes, it immediately manifests as a crash or random failure.
Fix
- After
SetModesucceeds, re-query the current mode info; - Don’t keep using the pre-switch pointer;
- If you need to re-read the frame buffer, re-read both
Gop->Mode->FrameBufferBaseandGop->Mode->FrameBufferSize; - The mode info memory returned by
QueryModemust be freed after use.
#include <Uefi.h>#include <Library/UefiBootServicesTableLib.h>#include <Library/DebugLib.h>#include <Library/MemoryAllocationLib.h>#include <Protocol/GraphicsOutput.h>EFI_STATUSReloadCurrentModeInfo (IN EFI_GRAPHICS_OUTPUT_PROTOCOL *Gop,IN UINT32 TargetMode){EFI_STATUS Status;EFI_GRAPHICS_OUTPUT_MODE_INFORMATION *ModeInfo;UINTN SizeOfInfo;ModeInfo = NULL;SizeOfInfo = 0;Status = Gop->SetMode (Gop, TargetMode);if (EFI_ERROR (Status)) {DEBUG ((EFI_D_ERROR, "SetMode(%u) failed: %r\n", TargetMode, Status));return Status;}//// SetMode may invalidate the previous ModeInfo pointer, so it must be re-queried.//Status = Gop->QueryMode (Gop, Gop->Mode->Mode, &SizeOfInfo, &ModeInfo);if (EFI_ERROR (Status) || ModeInfo == NULL) {DEBUG ((EFI_D_ERROR, "QueryMode after SetMode failed: %r\n", Status));if (ModeInfo != NULL) {FreePool (ModeInfo);}return EFI_UNSUPPORTED;}DEBUG ((EFI_D_INFO,"Current mode: %u x %u\n",ModeInfo->HorizontalResolution,ModeInfo->VerticalResolution));//// The ModeInfo returned by QueryMode must be freed after use.//FreePool (ModeInfo);ModeInfo = NULL;return EFI_SUCCESS;}
After the fix and re-run, the program no longer crashes on startup.
Generalizable lessons
- In UEFI, interfaces of the “query first, set, then use” kind often have non-obvious lifecycle constraints that must be confirmed one by one.
- After setting the memory attributes table (
SetVirtualAddressMap), the semantics of some pointers change. - Pointer lifetime is the number-one source of firmware debugging problems. Whenever you get a pointer from a protocol interface, ask first: when does it become invalid?
- The model’s diagnostic value isn’t in “guessing” but in tracing, by call order, “who might become invalid at what moment” — provided the logs are fine-grained enough and a human supplies accurate context.
Fault 2: Blank Screen — Root Cause Is Improper Protocol Location
Symptom
The program no longer crashes, but the screen never shows any graphics — a solid black screen.
Localization
From the serial log, the program had reached the graphics-init stage and got a failure status there, so the subsequent rendering flow was skipped. Further inspection of the protocol-location logic revealed improper use of the GOP protocol GUID.
Root cause
In UEFI, protocols are identified by GUID and obtained through boot services such as LocateProtocol, HandleProtocol, and OpenProtocol. GOP has a corresponding protocol definition and GUID constant in the framework headers, and normally you just use that constant directly. Common mistakes include:
- A symbol not declared due to header-version or platform differences;
- Hand-writing or copying a GUID from old code to get around a compile error;
- Using the wrong graphics-related GUID, such as the UGA Draw Protocol GUID that coexists with GOP;
- Locating on the wrong handle.
These issues often show up as “compiles but can’t find the protocol at runtime” — the program is running, but graphics don’t come out.
Fix
- Uniformly use the GOP GUID constant defined in the framework headers; don’t hand-write or copy it;
- Do a global protocol locate first, then fall back to scanning the handle array on failure;
- Log every failure branch so the problem is “visible” on the serial port;
- Free the handle array promptly after use.
#include <Uefi.h>#include <Library/UefiBootServicesTableLib.h>#include <Library/DebugLib.h>#include <Library/MemoryAllocationLib.h>#include <Protocol/GraphicsOutput.h>EFI_STATUSInitGraphics (OUT EFI_GRAPHICS_OUTPUT_PROTOCOL **Gop){EFI_STATUS Status;UINTN NoHandles;UINTN HandleIndex;EFI_HANDLE *HandleBuffer;NoHandles = 0;HandleBuffer = NULL;//// Option 1: global locate, works when GOP is available system-wide.//Status = gBS->LocateProtocol (&gEfiGraphicsOutputProtocolGuid,NULL,(VOID **)Gop);if (!EFI_ERROR (Status) && *Gop != NULL) {return EFI_SUCCESS;}DEBUG ((EFI_D_WARN,"LocateProtocol(GOP) failed: %r, fallback to handle scan\n",Status));//// Option 2: iterate over all handles and find one that supports GOP.//Status = gBS->LocateHandleBuffer (ByProtocol,&gEfiGraphicsOutputProtocolGuid,NULL,&NoHandles,&HandleBuffer);if (EFI_ERROR (Status) || HandleBuffer == NULL || NoHandles == 0) {DEBUG ((EFI_D_ERROR,"No GOP handle found: %r (NoHandles=%lu)\n",Status,(UINT64)NoHandles));return EFI_NOT_FOUND;}*Gop = NULL;for (HandleIndex = 0; HandleIndex < NoHandles; HandleIndex++) {Status = gBS->HandleProtocol (HandleBuffer[HandleIndex],&gEfiGraphicsOutputProtocolGuid,(VOID **)Gop);if (!EFI_ERROR (Status) && *Gop != NULL) {DEBUG ((EFI_D_INFO,"GOP found on handle %lu\n",(UINT64)(UINTN)HandleBuffer[HandleIndex]));break;}}FreePool (HandleBuffer);if (*Gop == NULL) {DEBUG ((EFI_D_ERROR, "GOP not available\n"));return EFI_NOT_FOUND;}return EFI_SUCCESS;}
After the fix, graphics init succeeded and the screen appeared for the first time.
Why this fault matters
Protocol-location failures are common in firmware development, and the cause is usually not a logic error but a portability issue: on different boards and different firmware versions, whether GOP exists and where its handle is mounted can all differ. The model’s fix approach — “if global locate fails, scan handles” — matches the general practice and shows it has a proper grasp of this class of problem.
So firmware code can’t be validated on just “one machine that works.” At minimum, prepare two kinds of devices: one with working graphics, and one without graphics or with a different firmware version. If conditions allow, add a virtualized firmware environment as a standard regression path.
Round 2: From “Runs” to “Runs Stably”
After Round 1, the program’s basic functionality worked: it played Breakout, it displayed, it responded. But continued testing surfaced a batch of new problems. These are all issues “that only become visible after it runs,” showing that Round 1’s pass is a necessary but not sufficient condition.
Performance: Dropped Frames and Frame-Rate Variance
- Symptom: The program runs, but the screen occasionally stutters, with the frame rate rising and falling.
- Cause: The main loop uses fixed delays to control pacing; rendering clears the whole screen and redraws everything; input polling has no time-slice management.
- Fix:
- Compute frame intervals with high-precision timing and advance logic by time slices;
- Adopt dirty-region updates, redrawing only what changed;
- Split game logic, rendering, and input into separate time slices.
//// Bad example: using gBS->Stall(16000) for a fixed-beat wait.// Stall blocks the current execution flow and occupies the processor,// easily getting in the way of rendering and input.//while (1) {UpdateGame ();RenderAll ();gBS->Stall (16000);}
//// Good example: time-slice scheduling.//UINT64 LastTick;UINT64 Now;UINT64 FrameTime;LastTick = GetCurrentTick ();while (!gExit) {Now = GetCurrentTick ();FrameTime = Now - LastTick;LastTick = Now;PollInput (); // Input: once per frame, no long delayUpdateGame (FrameTime); // Logic: advance by timeRenderDirtyRegions (); // Render: refresh dirty regions onlyWaitNextFrame (FrameTime); // Wait: use an event or short delay, no busy wait}
After the fix, the frame rate was stable and input response showed no noticeable latency.
Robustness: Sticky Keys and Long-Press Auto-Repeat
- Symptom: Long-pressing a direction key moves too fast to control precisely; short taps are occasionally missed.
- Cause: Key handling only detects “press” without debounce or repeat throttling; the polling interval is out of sync with the logical frame rate.
- Fix:
- Maintain a key-state table recording press duration and repeat-trigger time;
- Set an initial delay and a repeat interval;
- Complete polling within a fixed time slice.
Here’s the state-machine pseudocode:
typedef struct {UINT32 LastRawKey;UINT64 PressedTicks;UINT64 LastRepeatTick;BOOLEAN RepeatEnabled;} KEY_STATE;KEY_STATE KeyState;VOIDProcessKey (IN UINT32 RawKey,IN UINT64 Now){UINT64 InitialDelay = 300; // msUINT64 RepeatDelay = 80; // msif (RawKey == 0) {KeyState.LastRawKey = 0;KeyState.PressedTicks = 0;KeyState.LastRepeatTick = Now;return;}if (RawKey != KeyState.LastRawKey) {KeyState.LastRawKey = RawKey;KeyState.PressedTicks = 0;KeyState.LastRepeatTick = Now;TriggerKeyOnce (RawKey);return;}KeyState.PressedTicks += TickInterval;if (KeyState.PressedTicks >= InitialDelay &&Now - KeyState.LastRepeatTick >= RepeatDelay) {TriggerKeyRepeat (RawKey);KeyState.LastRepeatTick = Now;}}
Robustness: Resource Release and Abnormal Exit
- Symptom: After a normal exit, the serial log reports a memory-leak warning.
- Cause: Allocated memory — the handle array, the mode info returned by
QueryMode, custom game state or render buffers, etc. — was not freed. - Fix: Enumerate every allocation point and add release logic on the corresponding exit path. Error paths must not handle only the “successful exit” case.
A general principle here: every resource that outlives the current function must have its allocation and release explicitly documented. The release logic on error paths is exactly what models most often miss when generating code. Note in particular that StartImage itself doesn’t necessarily produce memory the caller must free; what really needs checking are the handle array, the info returned by QueryMode, buffers allocated by AllocatePool, and any objects the protocol interface explicitly says the caller must free.
Portability: Resolution and Device Differences
- Symptom: The aspect ratio is wrong on some machines; it won’t run on lower-resolution machines.
- Cause: The code hard-codes a resolution, e.g., 1024×600, and doesn’t fall back for modes GOP doesn’t support.
- Fix:
- Dynamically obtain resolution via
MaxMode,Mode->Mode, andModeInfo->HorizontalResolution/VerticalResolution; - If the target mode is unavailable, degrade step by step;
- Check for out-of-bounds coordinates before drawing, and clip the excess;
- After
SetModesucceeds, re-read the current mode’sMode->Info; don’t keep using the old mode info.
- Dynamically obtain resolution via
EFI_STATUSSelectModeSafely (IN EFI_GRAPHICS_OUTPUT_PROTOCOL *Gop,IN UINT32 PreferredMode,OUT UINT32 *Width,OUT UINT32 *Height){EFI_STATUS Status;UINT32 Candidate;if (PreferredMode >= Gop->Mode->MaxMode) {if (Gop->Mode->MaxMode == 0) {Candidate = 0;} else {Candidate = Gop->Mode->MaxMode - 1;}} else {Candidate = PreferredMode;}//// Degrade step by step when the target mode is unavailable, ultimately falling back to mode 0.//for (;;) {Status = Gop->SetMode (Gop, Candidate);if (!EFI_ERROR (Status)) {break;}DEBUG ((EFI_D_WARN,"SetMode(%u) failed: %r, try lower mode\n",Candidate,Status));if (Candidate == 0) {return Status;}Candidate--;}//// After SetMode succeeds, the current mode info should be taken from Mode->Info.//if (Gop->Mode->Info == NULL) {return EFI_UNSUPPORTED;}*Width = Gop->Mode->Info->HorizontalResolution;*Height = Gop->Mode->Info->VerticalResolution;return EFI_SUCCESS;}
If the code really does call QueryMode and store its returned ModeInfo, you must call FreePool after use. Don’t treat the pointer returned by QueryMode as current mode info for the long term.
Checklist After Round 2
After Round 2, you can use the following checklist for final acceptance:
| Item | Pass criterion |
|---|---|
| Build | No errors, no warnings, or all warnings evaluated |
| Startup | Complete serial logs, mode set successfully |
| Display | Correct resolution, no out-of-bounds, no screen corruption |
| Input | Short-press and long-press behavior as expected |
| Performance | Stable frame rate, no stutter |
| Resources | All exit paths release, no leak warnings |
| Compatibility | Runs on at least two kinds of devices |
The value of this checklist isn’t in filling in the table, but in turning the vague “it runs” into verifiable items. As long as the criteria are clear, both AI and humans can iterate around it.
Distilling the Methodology: Four Lessons in Human-AI Collaboration
Looking back at the two rounds, what really made the difference wasn’t how strong the model was, but whether the collaboration approach was sound.
Standards First: Translate “It Runs” into Verifiable Items
An instruction like “fix this” carries almost no information for the model. Effective instructions should include:
- Target platform and execution method;
- Existing error messages and serial logs;
- Expected behavior;
- Acceptance criteria;
- Scope that must not be modified;
- Rollback conditions.
For example:
Fix the code under the following constraints; do not rewrite the whole project.Platform: UEFI Shell, EDK2 stable202405, Arch X64, OVMF.Symptom: after loading, the program prints "Starting Game Loop" on serial, then crashes.Log: SetMode returns EFI_SUCCESS, then it crashes while reading ModeInfo.Acceptance: enter the main loop, no anomalies on serial, direction keys move, ESC exits.Do not modify: don't switch protocols, don't remove serial logging.Rollback condition: if two consecutive edits cause startup to fail, restore the last buildable version and explain why.
This kind of prompt is far more effective than “just fix it.”
Small-Step Iteration: Change One Variable at a Time
- Having the model rewrite the entire project in one go looks efficient but actually makes it hard to tell which step broke things;
- Proceed at a “problem — fix — verify” rhythm, changing one file or one function per step;
- Combined with version control, rollback cost is very low.
In this test, the startup crash and the protocol-location problem were located and fixed separately, so the effect of each change could be verified independently.
Observability First: Make the System “Able to Speak” Before Letting the Model “Read Logs”
The biggest difference between firmware debugging and desktop development is the feedback channel. Recommendations for log design:
- Record the return value and status of each call on the critical path;
- Grade the output, distinguishing ERROR, WARN, and INFO to avoid excessive noise;
- Output to the serial port and collect it with an external tool, making it easy to observe during long runs;
- Prefer English text and digits in logs to avoid encoding issues;
- Run builds in a containerized sandbox, using serial logs and monitoring for regression verification.
If conditions allow, unify serial-log collection into a logging service, searchable by time and event, then feed it back to the model as context. That way, “modify — compile — run — feedback” forms a closed loop, with humans only responsible for designing tasks and judging results.
Human Backstop: Safety-Critical and Hardware-Intensive Parts Must Be Reviewed by Humans
Models are good at pattern recognition and structured reasoning, but not at bearing consequences. The following should be checked line by line by humans:
- Boot chain and startup configuration;
- Memory attributes and permission settings;
- Interrupt handling and concurrency logic;
- Code that manipulates hardware registers;
- Secure boot, cryptographic authentication, and firmware update logic.
Any practice of “letting AI-generated code go straight into a high-risk environment” needs a human gate.
Common Pitfalls and Risk Notes
- Pitfall 1: Compilation passing means it runs. Compilation only shows that syntax and types are basically correct; interface calling conventions, resource lifecycles, and device differences can still go wrong.
- Pitfall 2: Treating “it runs” as “it’s finished.” Performance, robustness, and portability are independent acceptance dimensions and need dedicated time in the design.
- Pitfall 3: Trusting the model’s “confident output.” The model’s problem list is only a set of hypotheses and must be verified by runtime results.
- Pitfall 4: Ignoring the cost of debugging facilities. Logs should be graded, and release builds should turn off redundant output, otherwise they hurt performance and readability.
- Risk note: Safety-critical code must be human-owned. Especially for parts involving booting, memory permissions, and cryptographic authentication, the model cannot be the final responsible party.
Conclusion
This test of “letting AI fix the leftovers from AI” was more interesting in the process than in the result. The two key changes in Round 1 were both small: one was re-querying the current mode info after SetMode and freeing it correctly; the other was fixing the GOP protocol location. But each points to a high-frequency class of firmware debugging problems: memory lifecycle and protocol interface conventions. The Round 2 performance and robustness work also shows that AI is very efficient at “checking items one by one against a list.”
For developers, the more valuable conclusions are:
- Model output quality depends heavily on input context quality — code, logs, environment, and acceptance criteria;
- Humans must fill the “define standards” and “judge results” roles in the workflow, not act as line-by-line proofreaders;
- Only when verification is automated — build, serial logs, regression tests — does human-AI collaboration efficiency truly improve.
AI won’t replace firmware developers, but firmware developers who use AI will indeed be much faster. The prerequisite: your verification system has to keep up with your generation speed.
