AI Coding Tools for UEFI Graphics Applications: Practical GOP Development Guide
This guide explains how AI coding tools can help developers build UEFI graphics applications around the Graphics Output Protocol (GOP). It covers prerequisites, a two-stage development workflow, static code review checklists, common troubleshooting for LocateProtocol, QueryMode, SetMode, GUIDs, framebuffers, and serial logs, plus a human-in-the-loop debugging example. The focus is on spec-driven, log-driven, and runtime-driven development.
1. Prerequisites and Scope: What AI Can Help With and What It Cannot Replace
If you are searching for topics such as “how AI coding tools can help develop UEFI graphics applications,” “common mistakes during UEFI graphics development,” or “important precautions before starting UEFI firmware graphics work,” this article is aimed at developers who already have some exposure to C, basic UEFI concepts, EDK2, or firmware debugging.
This article does not promise a one-time success, and it does not discuss any specific commercial tool. Instead, it focuses on the Graphics Output Protocol (GOP) and presents a practical workflow for developing UEFI graphics applications.
UEFI graphics applications run before the operating system is loaded. They usually do not have a complete graphics framework, a mature desktop environment, or high-level UI abstractions. Developers must work directly with firmware-provided protocols, mode information, framebuffer addresses, and serial debug output.
AI coding tools can help developers read code, generate checklists, produce serial logs, compare fix options, and identify suspicious patterns. However, they cannot replace the developer’s judgment about the UEFI specification, firmware implementation differences, or hardware behavior.
Typical prerequisites include:
- Basic C programming skills, including an understanding of pointers, structures, and memory management.
- The ability to compile and run a UEFI application or EDK2 module.
- A target platform that supports UEFI GOP and allows serial output observation.
- Acceptance of normal trial-and-error costs, such as rebooting, debugging failures, and rolling back code versions.
If the target environment has no serial output, cannot compile UEFI programs, or uses fully closed-source firmware that does not support a graphics output protocol, the methods in this article may need to be adjusted.
Different UEFI implementations, firmware versions, EDK2 versions, and toolchains can all affect the result. For this reason, the principles of “follow the specification,” “trust the logs,” and “validate with actual runtime behavior” are more important than advice from any single tool.
2. Two-Stage Development Workflow: Get It Running First, Then Refine
Low-level graphics programs rarely work correctly on the first attempt if the developer tries to implement complex interaction or visual effects immediately. It is usually better to split development into two stages.
| Stage | Goal | Acceptance Criteria | Main Risks | How AI Tools Can Help |
|---|---|---|---|---|
| Round 1: Get it running | Locate GOP, query mode, set mode, obtain framebuffer, output logs | Serial logs show success, and the screen shows basic graphics or a clear-screen effect | Wrong GUID, protocol not located, unsupported mode, pointer misuse | Generate checklists, review status codes, add serial logs |
| Round 2: Refine | Improve drawing, input response, frame rate, and code structure | Program runs stably in a loop, drawing range is correct, and resource release is reasonable | Framebuffer out-of-bounds access, memory leaks, logic errors after mode switching | Suggest refactoring, boundary checks, and log comparisons |
In the first round, do not try to implement all features. The only goal is to prove that the protocol can be opened, the mode can be set, the framebuffer can be accessed, and serial output works.
In the second round, you can gradually add rectangles, text, input handling, or simple animation. This separation reduces debugging difficulty and makes AI-generated suggestions easier to verify.
3. GOP Code Review and Debugging Steps: Review First, Then Run
When you receive existing UEFI graphics code, it is usually not advisable to compile and run it immediately. A safer order is:
- Ask the AI tool to read through the code and produce a risk list.
- Manually confirm the findings.
- Fix high-risk issues.
- Add serial logs.
- Run the program.
A practical static review checklist is shown below:
- Are all protocol pointers checked for NULL before use?
- Are all calls returning
EFI_STATUSchecked? - Does
LocateProtocoluse the correct protocol GUID? - Is memory returned by
QueryModereleased withFreePoolafter use? - Are old mode information pointers still being reused after
SetMode? - Does the framebuffer address come from the current
gop->Mode->FrameBufferBase? - Does the framebuffer size come from
gop->Mode->FrameBufferSize? - During drawing, are width, height, pixel format, and buffer boundaries checked?
- Are input and output protocols handled with the same status-checking approach?
- Do serial logs cover key steps such as locating, querying, setting, and reading the framebuffer?
Serial logs are one of the most effective tools for debugging UEFI graphics. You can print return values, mode numbers, framebuffer addresses, and framebuffer sizes before and after key calls.
For example:
Print(L"[STEP] LocateProtocol enter\r\n");Status = gBS->LocateProtocol(&gEfiGraphicsOutputProtocolGuid,NULL,(VOID **)&Gop);Print(L"[STEP] LocateProtocol Status=%r\r\n", Status);
A more complete example is shown below. It only demonstrates the key flow. In actual use, it should be integrated into your UEFI application entry point or module logic.
EFI_STATUS Status;EFI_GRAPHICS_OUTPUT_PROTOCOL *Gop = NULL;UINTN ModeNumber = 2;UINTN SizeOfInfo = 0;EFI_GRAPHICS_OUTPUT_MODE_INFORMATION *Info = NULL;UINT32 Width = 0;UINT32 Height = 0;UINTN FrameBufferBase = 0;UINTN FrameBufferSize = 0;Print(L"[STEP] Locate GOP\r\n");Status = gBS->LocateProtocol(&gEfiGraphicsOutputProtocolGuid,NULL,(VOID **)&Gop);if (EFI_ERROR(Status)) {Print(L"[ERROR] LocateProtocol failed: %r\r\n", Status);return Status;}Print(L"[STEP] QueryMode ModeNumber=%d\r\n", ModeNumber);Status = Gop->QueryMode(Gop,ModeNumber,&SizeOfInfo,&Info);if (EFI_ERROR(Status)) {Print(L"[ERROR] QueryMode failed: %r\r\n", Status);return Status;}Width = Info->HorizontalResolution;Height = Info->VerticalResolution;Print(L"[INFO] Mode=%d, Width=%d, Height=%d\r\n",ModeNumber,Width,Height);gBS->FreePool(Info);Info = NULL;Print(L"[STEP] SetMode ModeNumber=%d\r\n", ModeNumber);Status = Gop->SetMode(Gop, ModeNumber);if (EFI_ERROR(Status)) {Print(L"[ERROR] SetMode failed: %r\r\n", Status);return Status;}FrameBufferBase = Gop->Mode->FrameBufferBase;FrameBufferSize = Gop->Mode->FrameBufferSize;Print(L"[INFO] FrameBufferBase=0x%lx, FrameBufferSize=0x%lx\r\n",FrameBufferBase,FrameBufferSize);if (FrameBufferSize == 0) {Print(L"[ERROR] FrameBufferSize is zero\r\n");return EFI_DEVICE_ERROR;}
There are three key points in this code:
- Call
LocateProtocolfirst to obtain GOP. - If
QueryModefails, return immediately instead of continuing to use a null pointer. - After
SetModesucceeds, read framebuffer information fromgop->Mode, not from an oldInfopointer.
You should also pay attention to firmware differences. Some firmware implementations may not support the current ModeNumber. If QueryMode or SetMode returns EFI_UNSUPPORTED, the mode may not exist or may not be supported.
In that case, do not blindly retry the same mode number. Instead, check Gop->Mode->MaxMode, iterate through supported display modes, and use serial logs to confirm the available resolution and pixel format.
4. Troubleshooting Checklist for QueryMode, SetMode, and GUID Issues
In UEFI graphics development, many errors are not compile-time errors. They are runtime failures that happen silently.
The following checklist organizes common symptoms, priority checks, and recommended actions.
| Symptom | Priority Check | Recommended Action |
|---|---|---|
| The program exits immediately after printing logs | Is an old Info pointer returned by QueryMode still being used after SetMode? |
Stop reusing the old pointer. Read framebuffer information from gop->Mode instead. |
LocateProtocol fails |
Is EFI_GRAPHICS_OUTPUT_PROTOCOL_GUID being used? |
Verify the GUID, check whether the firmware supports GOP, and print the status code. |
QueryMode fails |
Is ModeNumber supported by the firmware? |
Iterate through available modes. Do not hardcode an incompatible mode. |
SetMode fails |
Is mode switching failing, the resolution unsupported, or the state abnormal? | Print the %r status code and retry with a known supported mode. |
| The program runs but the screen is black | Are the framebuffer address, resolution, and pixel format correct? | Verify gop->Mode, print Base and Size, and avoid out-of-bounds access. |
| The program does not crash but the feature does not work | Are status codes unchecked, or is the framebuffer offset wrong? | Add serial logs and narrow down the failure step by step. |
Memory leak after QueryMode |
Is Info not released? |
Call gBS->FreePool(Info) after use. |
For protocol identification, avoid vague descriptions. First verify EFI_GRAPHICS_OUTPUT_PROTOCOL_GUID and confirm that LocateProtocol returns EFI_SUCCESS and that the Gop pointer is valid.
After that, continue checking the protocol handle, current Mode, pixel format, resolution, and serial logs. If the logs do not show a clear status code, you should not immediately guess that the hardware or graphics driver is faulty.
5. Human-in-the-Loop Example: From Reset Logs to a Fix Diff
Suppose you receive a code sample. After running it, the serial output is:
[BOOT] Enter UEFI app[APP] QueryMode ok[APP] SetMode ok
Then the system resets.
After review, the AI tool finds that the code still accesses Info->HorizontalResolution after SetMode, and that the memory returned by QueryMode is not released.
The initial code may look like this:
Status = gop->QueryMode(gop, ModeNumber, &SizeOfInfo, &info);Status = gop->SetMode(gop, ModeNumber);width = info->HorizontalResolution;height = info->VerticalResolution;
The fix diff is as follows:
- Status = gop->QueryMode(gop, ModeNumber, &SizeOfInfo, &info);- Status = gop->SetMode(gop, ModeNumber);- width = info->HorizontalResolution;- height = info->VerticalResolution;+ Status = gop->QueryMode(gop, ModeNumber, &SizeOfInfo, &info);+ if (EFI_ERROR(Status)) {+ Print(L"[ERROR] QueryMode failed: %r\r\n", Status);+ return Status;+ }++ width = info->HorizontalResolution;+ height = info->VerticalResolution;++ gBS->FreePool(info);+ info = NULL;++ Status = gop->SetMode(gop, ModeNumber);+ if (EFI_ERROR(Status)) {+ Print(L"[ERROR] SetMode failed: %r\r\n", Status);+ return Status;+ }++ FrameBufferBase = gop->Mode->FrameBufferBase;+ FrameBufferSize = gop->Mode->FrameBufferSize;
After applying the fix and running again, the serial output should look similar to the following:
[STEP] Locate GOP[STEP] LocateProtocol Status=EFI_SUCCESS[STEP] QueryMode ModeNumber=2[INFO] Mode=2, Width=1024, Height=768[STEP] SetMode ModeNumber=2[STEP] SetMode Status=EFI_SUCCESS[INFO] FrameBufferBase=0x..., FrameBufferSize=0x...[SHOW] rectangle start
During the next review, focus on three things:
- Whether the
Infomemory returned byQueryModehas been released. - Whether framebuffer information is obtained only from
gop->ModeafterSetMode. - Whether drawing functions check boundaries to avoid writing outside the firmware buffer.
This example shows that the most valuable role of AI tools is not necessarily generating complex code in one shot. It is helping developers turn hidden risks into visible checklist items and log points.
6. Best Practices and Conclusion
The core difficulty of firmware-level graphics development is not syntax. It is timing, state, and boundaries.
QueryMode, SetMode, framebuffer addresses, mode information, and protocol handles can all be affected by firmware implementation and runtime environment.
Therefore, any AI-generated code should be manually reviewed, especially code involving pointers, status codes, and mode switching.
It is recommended to keep the following habits:
- Review before running.
- Check logs before guessing.
- Verify step by step before extending features.
- Check return values for all protocol calls.
- Release memory allocated by firmware in a timely manner.
- Base all drawing operations on the current framebuffer information from
gop->Mode.
With these habits, even if a problem occurs, you can quickly locate the exact step where it happened.
AI coding tools can significantly reduce repetitive work in low-level development, but they cannot replace the developer’s judgment about specifications. Real confidence comes from serial logs, status codes, repeatable verification steps, and a solid understanding of differences between UEFI implementations.
