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:

    1. Ask the AI tool to read through the code and produce a risk list.
    2. Manually confirm the findings.
    3. Fix high-risk issues.
    4. Add serial logs.
    5. 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_STATUS checked?
    • Does LocateProtocol use the correct protocol GUID?
    • Is memory returned by QueryMode released with FreePool after 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:

    1. Print(L"[STEP] LocateProtocol enter\r\n");
    2. Status = gBS->LocateProtocol(
    3. &gEfiGraphicsOutputProtocolGuid,
    4. NULL,
    5. (VOID **)&Gop
    6. );
    7. 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.

    1. EFI_STATUS Status;
    2. EFI_GRAPHICS_OUTPUT_PROTOCOL *Gop = NULL;
    3. UINTN ModeNumber = 2;
    4. UINTN SizeOfInfo = 0;
    5. EFI_GRAPHICS_OUTPUT_MODE_INFORMATION *Info = NULL;
    6. UINT32 Width = 0;
    7. UINT32 Height = 0;
    8. UINTN FrameBufferBase = 0;
    9. UINTN FrameBufferSize = 0;
    10. Print(L"[STEP] Locate GOP\r\n");
    11. Status = gBS->LocateProtocol(
    12. &gEfiGraphicsOutputProtocolGuid,
    13. NULL,
    14. (VOID **)&Gop
    15. );
    16. if (EFI_ERROR(Status)) {
    17. Print(L"[ERROR] LocateProtocol failed: %r\r\n", Status);
    18. return Status;
    19. }
    20. Print(L"[STEP] QueryMode ModeNumber=%d\r\n", ModeNumber);
    21. Status = Gop->QueryMode(
    22. Gop,
    23. ModeNumber,
    24. &SizeOfInfo,
    25. &Info
    26. );
    27. if (EFI_ERROR(Status)) {
    28. Print(L"[ERROR] QueryMode failed: %r\r\n", Status);
    29. return Status;
    30. }
    31. Width = Info->HorizontalResolution;
    32. Height = Info->VerticalResolution;
    33. Print(
    34. L"[INFO] Mode=%d, Width=%d, Height=%d\r\n",
    35. ModeNumber,
    36. Width,
    37. Height
    38. );
    39. gBS->FreePool(Info);
    40. Info = NULL;
    41. Print(L"[STEP] SetMode ModeNumber=%d\r\n", ModeNumber);
    42. Status = Gop->SetMode(Gop, ModeNumber);
    43. if (EFI_ERROR(Status)) {
    44. Print(L"[ERROR] SetMode failed: %r\r\n", Status);
    45. return Status;
    46. }
    47. FrameBufferBase = Gop->Mode->FrameBufferBase;
    48. FrameBufferSize = Gop->Mode->FrameBufferSize;
    49. Print(
    50. L"[INFO] FrameBufferBase=0x%lx, FrameBufferSize=0x%lx\r\n",
    51. FrameBufferBase,
    52. FrameBufferSize
    53. );
    54. if (FrameBufferSize == 0) {
    55. Print(L"[ERROR] FrameBufferSize is zero\r\n");
    56. return EFI_DEVICE_ERROR;
    57. }

    There are three key points in this code:

    1. Call LocateProtocol first to obtain GOP.
    2. If QueryMode fails, return immediately instead of continuing to use a null pointer.
    3. After SetMode succeeds, read framebuffer information from gop->Mode, not from an old Info pointer.

    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:

    1. [BOOT] Enter UEFI app
    2. [APP] QueryMode ok
    3. [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:

    1. Status = gop->QueryMode(gop, ModeNumber, &SizeOfInfo, &info);
    2. Status = gop->SetMode(gop, ModeNumber);
    3. width = info->HorizontalResolution;
    4. height = info->VerticalResolution;

    The fix diff is as follows:

    1. - Status = gop->QueryMode(gop, ModeNumber, &SizeOfInfo, &info);
    2. - Status = gop->SetMode(gop, ModeNumber);
    3. - width = info->HorizontalResolution;
    4. - height = info->VerticalResolution;
    5. + Status = gop->QueryMode(gop, ModeNumber, &SizeOfInfo, &info);
    6. + if (EFI_ERROR(Status)) {
    7. + Print(L"[ERROR] QueryMode failed: %r\r\n", Status);
    8. + return Status;
    9. + }
    10. +
    11. + width = info->HorizontalResolution;
    12. + height = info->VerticalResolution;
    13. +
    14. + gBS->FreePool(info);
    15. + info = NULL;
    16. +
    17. + Status = gop->SetMode(gop, ModeNumber);
    18. + if (EFI_ERROR(Status)) {
    19. + Print(L"[ERROR] SetMode failed: %r\r\n", Status);
    20. + return Status;
    21. + }
    22. +
    23. + FrameBufferBase = gop->Mode->FrameBufferBase;
    24. + FrameBufferSize = gop->Mode->FrameBufferSize;

    After applying the fix and running again, the serial output should look similar to the following:

    1. [STEP] Locate GOP
    2. [STEP] LocateProtocol Status=EFI_SUCCESS
    3. [STEP] QueryMode ModeNumber=2
    4. [INFO] Mode=2, Width=1024, Height=768
    5. [STEP] SetMode ModeNumber=2
    6. [STEP] SetMode Status=EFI_SUCCESS
    7. [INFO] FrameBufferBase=0x..., FrameBufferSize=0x...
    8. [SHOW] rectangle start

    During the next review, focus on three things:

    1. Whether the Info memory returned by QueryMode has been released.
    2. Whether framebuffer information is obtained only from gop->Mode after SetMode.
    3. 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.