Debugging UEFI Graphics Applications with AI: From Startup Crashes to Stable Rendering
Developing UEFI graphics applications on bare metal removes the runtimes, exception handling, and debuggers we rely on at the application layer, so failures often show up as silent crashes or blank screens rather than clean error messages. This article walks through a practical workflow for debugging a UEFI graphics application with the help of an AI coding assistant, moving a program from "compiles but won't run" to one that renders stably. It covers having the AI review the code first, fixing a startup crash caused by stale framebuffer pointers after SetMode, resolving a blank screen caused by an incorrect GOP protocol GUID or unchecked return status, and using serial logs to turn silent failures into observable progress. It also presents a reusable debugging methodology, a post-fix verification checklist, and a realistic view of what AI can and cannot do in low-level firmware development.
Why UEFI Graphics Applications Are So Hard to Debug
When we develop at the application layer, we can usually rely on the operating system, runtimes, exception handling, memory protection, and mature debuggers. But in a low-level firmware environment like UEFI/BIOS, most of these conditions don’t exist: the program runs directly on bare metal with no OS underneath; the screen, serial port, memory, and graphics output protocol all have to be driven by the developer; and a single null-pointer dereference or illegal memory access often won’t gracefully throw an exception—instead it crashes directly, silently exits, or on real hardware simply “prints a few lines of log and then disappears.”
That is why using an AI coding assistant to develop UEFI graphics applications both tests the AI’s ability to understand an unfamiliar codebase and exposes the particular difficulty of low-level debugging. To make the problems more reproducible, it is best to verify them in a clearly defined environment—such as an OVMF/QEMU virtual machine or a real development board—and record the UEFI firmware version, how the debug serial port is connected, the serial baud rate, the serial-log capture tool, and so on. That way, when the problem shifts from “the code looks wrong” to “the program crashes on startup,” “black screen after SetMode,” or “what do I do when the GOP protocol can’t be found,” troubleshooting has a stable basis to stand on.
Task Setup: From Not Running to Stable Rendering
In practice, you often run into a situation where the code structure is complete and the modules are clean, there are no obvious syntax problems, but the program simply can’t complete its intended task the moment it runs. In this case, rather than starting over, it’s better to let an AI coding assistant take over the review first. The task can be split into two rounds:
- Round 1: Get the program from “compiles but won’t run” to “basically runnable”.
- Round 2: On the runnable foundation, refine the UI, performance, and compatibility.
This article focuses on reconstructing the typical problems from Round 1: startup crashes, a blank screen, protocol-location failures, and serial debugging methods.
Step One: Have the AI Do a Code Review First
Before running anything, the first prompt should be as clear and actionable as possible. Below is a reusable review prompt template, suitable for UEFI graphics modules, firmware applications, or hardware abstraction layer code:
Please review the following UEFI module code, with the goal of finding issues that could cause runtime failure.Please check according to these five categories:1. Entry function: whether the EFI_IMAGE_ENTRY_POINT return path is complete, whether the initialization order is reasonable, and whether there is any early return that fails to clean up resources;2. Mode switching: whether Mode, Info, FrameBufferBase, and FrameBufferSize are re-fetched before and after SetMode, and whether framebuffer information from before the switch is cached;3. Protocol location: whether LocateProtocol checks the EFI_STATUS return value, whether it checks for a null protocol pointer, and whether the GUID used comes from the correct header file;4. Memory lifetime: whether the pointer source is clear, whether it is reset by a lower-level call, and whether old pointers continue to be used after switching modes, reinitializing, or unloading a protocol;5. Error returns: whether critical calls check status, whether logs are output on failure, and whether execution continues with an invalid handle.
The value of this kind of review is not that the AI gets everything right in one pass, but that it turns debugging from “blind trial and error” into “verifying with a hypothesis.” The list of suspected issues the AI produces can serve as a starting point for setting up serial-log checkpoints, breakpoints, and manual review.
Problem 1: Program Crashes on Startup—The Pointer Lifetime Trap
On the first run, the program prints the startup log and then exits immediately. This phenomenon is very common in low-level development and usually points to a memory-access or resource-lifetime problem.
By adding finer-grained logs to the serial port, the crash point can be narrowed down to right after the graphics output protocol call. Further review reveals that after calling QueryMode to get display mode information, the code obtains an info pointer; it then calls SetMode to switch the display mode; but after the switch it still uses the old framebuffer address to draw.
The key here isn’t simply judging “whether the pointer was freed”—it’s recognizing that: SetMode may change the framebuffer base address, size, or pixel format, and framebuffer information cached before the switch is no longer reliable. At the application layer, this kind of problem might be caught by memory protection and reported as an error; but in a bare-metal UEFI environment, it often shows up directly as a silent crash or a black screen.
The fixed code should re-fetch the current mode information after SetMode, and validate the QueryMode return status and the size_of_info size. If the current mode information is already maintained by GOP, you can also read it directly from gop->Mode->Info.
// Pseudocode: framebuffer information must be re-fetched after switching modesEFI_STATUS Status;UINTN FrameBufferBase = 0;UINTN FrameBufferSize = 0;EFI_GRAPHICS_OUTPUT_MODE_INFORMATION *CurrentInfo = NULL;Status = Gop->SetMode(Gop, TargetMode);if (EFI_ERROR(Status)) {Print(L"SetMode failed: %r\n", Status);return Status;}// Current mode info can be read directly from the GOP mode structureCurrentInfo = Gop->Mode->Info;if (CurrentInfo == NULL) {Print(L"GOP Mode->Info is NULL after SetMode\n");return EFI_DEVICE_ERROR;}FrameBufferBase = Gop->Mode->FrameBufferBase;FrameBufferSize = Gop->Mode->FrameBufferSize;// If the code prefers to re-query mode info, it must validate the return status and sizeEFI_GRAPHICS_OUTPUT_MODE_INFORMATION *QueriedInfo = NULL;UINTN SizeOfInfo = 0;Status = Gop->QueryMode(Gop, Gop->Mode->Mode, &SizeOfInfo, &QueriedInfo);if (EFI_ERROR(Status) || QueriedInfo == NULL ||SizeOfInfo < sizeof(EFI_GRAPHICS_OUTPUT_MODE_INFORMATION)) {Print(L"QueryMode failed or invalid info, Status=%r, Size=%d\n",Status, SizeOfInfo);return EFI_INVALID_PARAMETER;}// Subsequent rendering should use the latest address, size, and pixel format
This fix can be abstracted into a general rule: any resource that has been reset by a lower-level call must have its referencing pointers and cached values re-fetched and validated.
Problem 2: It Runs but the Screen Is Blank—GOP Protocol GUID and Return-Status Issues
After the crash is fixed, the program no longer crashes, but there’s still nothing on the screen. Combining the symptoms with the code, the AI points to the acquisition of the graphics output protocol (GOP).
In firmware, to use a certain capability, you usually need to locate the protocol instance by GUID through LocateProtocol. The common problem here isn’t simply “there are multiple similar definitions,” but rather: different projects or header files may reference the wrong GUID constant, so you need to verify against the EDK2/platform definitions. For example, some code may mistakenly use another protocol’s GUID, an old macro definition, a custom wrapper header, or fail to confirm the header’s source, causing the located protocol’s semantics to not match expectations.
Once the GUID is wrong, two results are possible:
LocateProtocolreturns “not found,” and the program can’t get the protocol pointer;- it gets the pointer, but subsequent calls behave abnormally, ultimately showing up as “runs but no output.”
So the fix must include GUID verification, with the following suggested steps:
- Confirm the header source: the graphics output protocol GUID should come from the corresponding UEFI spec header file, such as the relevant EDK2 protocol header;
- Confirm the symbol definition: check for same-named macros, duplicate definitions, wrong references, or locally defined GUIDs;
- Confirm the protocol interface version: make sure you’re using a GOP version supported by the platform;
- Confirm the
LocateProtocolreturn code: don’t just check whether the pointer is non-null—also check theEFI_STATUS; - Confirm the status of subsequent calls:
QueryMode,SetMode,Blt,Draw, and other calls all need error handling.
Example code:
EFI_STATUS Status;EFI_GRAPHICS_OUTPUT_PROTOCOL *Gop = NULL;Status = gBS->LocateProtocol(&gEfiGraphicsOutputProtocolGuid,NULL,(VOID **)&Gop);if (EFI_ERROR(Status) || Gop == NULL) {Print(L"LocateProtocol GOP failed: %r\n", Status);return Status;}// Continue by checking GOP capabilities and the current modeif (Gop->Mode == NULL || Gop->Mode->Info == NULL) {Print(L"GOP Mode or Mode->Info is invalid\n");return EFI_DEVICE_ERROR;}
In a low-level environment, any “locate/acquire” call must explicitly check its return status. Otherwise, once you get a null pointer or an invalid handle, all subsequent operations will fail in a chain reaction—and often there’s no exception mechanism to catch it for you.
Serial Log Template: Turning Silent Failures into Observable Progress
In UEFI debugging, serial logs are the most reliable and most fundamental tool. It’s recommended to print logs at four key points: protocol location, SetMode, QueryMode, and the drawing loop.
Print(L"[GOP] LocateProtocol start\n");Status = gBS->LocateProtocol(&gEfiGraphicsOutputProtocolGuid, NULL, (VOID **)&Gop);Print(L"[GOP] LocateProtocol done, Status=%r, Gop=%p\n", Status, Gop);if (EFI_ERROR(Status) || Gop == NULL) {return Status;}Print(L"[GOP] SetMode start, target=%d, current=%d\n",TargetMode, Gop->Mode->Mode);Status = Gop->SetMode(Gop, TargetMode);Print(L"[GOP] SetMode done, Status=%r\n", Status);if (EFI_ERROR(Status)) {return Status;}UINTN SizeOfInfo = 0;EFI_GRAPHICS_OUTPUT_MODE_INFORMATION *Info = NULL;Status = Gop->QueryMode(Gop, Gop->Mode->Mode, &SizeOfInfo, &Info);Print(L"[GOP] QueryMode done, Status=%r, Size=%d, Info=%p\n",Status, SizeOfInfo, Info);if (EFI_ERROR(Status) || Info == NULL || SizeOfInfo == 0) {return EFI_DEVICE_ERROR;}Print(L"[RENDER] framebuffer base=0x%x, size=0x%x, res=%dx%d\n",Gop->Mode->FrameBufferBase,Gop->Mode->FrameBufferSize,Gop->Mode->Info->HorizontalResolution,Gop->Mode->Info->VerticalResolution);
The logs don’t need to be complete from the start, but they must cover three kinds of information: “where execution got to,” “whether the call succeeded or failed,” and “what was returned on failure.” That way, even if the serial port is your only observation window, you can progressively narrow a black screen, a crash, or a hang down to a specific stage.
A Debugging Methodology Drawn from Practice
Abstracting the above process gives a reusable low-level AI-collaboration debugging workflow:
- Review first, run second: have the AI produce a structured list of suspected issues first, turning blind trial and error into verifying with a hypothesis;
- Make good use of serial logs: place checkpoints at key points to turn silent failures into observable progress;
- Focus on lifetime: most low-level crashes stem from pointer or resource-lifetime errors, so focus on whether things are re-fetched after being reset;
- Enforce status checks: check the return values and null pointers of
LocateProtocol,QueryMode,SetMode, and other calls one by one; - Iterate in rounds: in the first round, just aim to run; in the second, talk about running well—avoid premature optimization that masks real defects.
This methodology isn’t limited to graphics applications. As long as you’re developing in a firmware environment without full runtime support, it can be reused.
A Verification Checklist After AI Fixes
An AI-provided fix can’t just stop at “looks reasonable”—it must be verified. It’s worth forming a fixed checklist:
- Static review: have the AI review the changed spots again to confirm no new null pointers, wrong returns, or uninitialized variables were introduced;
- Serial reproduction: observe whether the program advances past the original crash point and whether any new
EFI_ERRORappears; - Rendering regression: confirm whether the screen displays stably, and whether there’s any black screen, garbled display, flicker, or resolution anomaly;
- Performance and compatibility observation: check frame rate, CPU usage, and memory access range, and if necessary verify on different OVMF versions or real hardware platforms;
- Version confirmation: record the firmware version, the UEFI spec, and the GOP implementation source, so as not to misjudge a platform difference as a code error.
For firmware development, capabilities like firmware CI compilation, serial-log capture, and firmware version verification are closer to the real workflow than simple “cloud builds.” They can help a team automatically compile after committing code, automatically collect serial output, and record firmware version changes—thereby improving the efficiency of problem localization.
How to View AI’s Role in Low-Level Development
This practice both demonstrated the value of an AI coding assistant and exposed its boundaries.
What it can do:
- Quickly read through an unfamiliar modular codebase and produce a list of issues;
- Recognize typical error patterns fairly well, such as wild pointers, GUID misuse, and missing status checks;
- After a human describes the symptoms, connect them to underlying mechanisms and help pinpoint the root cause.
Where it tends to fall short:
- Without real hardware and runtime feedback, it may provide fixes that look reasonable but can’t be verified;
- For problems that heavily depend on a specific platform or specific firmware implementation, human oversight is still needed;
- It can’t replace the developer’s experience-based judgment about serial output, memory layout, and protocol semantics.
So a more pragmatic positioning is: treat the AI as a tireless first reader and troubleshooting assistant, while the human provides the runtime environment, verification results, and final decisions.
Summary: Common Problems and How to Handle Them
Low-level firmware development is hard precisely because it strips away the runtime protections we take for granted at the application layer and puts every memory detail and protocol constraint out in the open. This article addresses common problems such as “how to troubleshoot a UEFI graphics app that crashes on startup,” “what to do when the GOP protocol can’t be found,” and “how to handle a black screen after SetMode,” and gives a practical approach:
- For a startup crash, first check protocol calls, mode switching, and the framebuffer pointer’s lifetime;
- For a black screen, first confirm the GUID source, the protocol-location return value, and the current mode information;
- For a silent failure, first add serial logs, then progressively narrow down the fault range;
- For an AI fix, don’t trust the result directly—verify it with static review, serial reproduction, and regression testing.
Once you’ve mastered this method of “review → serial observation → lifetime review → status validation → round-by-round iteration,” and combine it with engineering capabilities like firmware CI compilation, serial-log capture, and firmware version verification, even complex firmware-level graphics application development can be steadily advanced to a runnable, maintainable state.
