AI-Assisted UEFI Graphics Development in Practice: Two-Phase Iteration and Debugging Essentials

    A practical walkthrough for using AI coding tools to build a graphics program in the UEFI pre-boot environment. It presents a reproducible workflow of code review, two-phase iteration, and serial-port debugging, and dissects two easy-to-hit pitfalls: stale frame buffer info pointers after setting a display mode, and an incorrect Graphics Output Protocol GUID configuration. It includes copy-ready review prompt templates, a minimal runnable EDK2 skeleton, and a troubleshooting table. The core takeaway: treat AI as an amplifier for boilerplate and initial triage, while humans stay responsible for hardware timing and memory-lifetime constraints.

    1. Why Is Graphics Development So Hard Under UEFI?

    This article walks through a hands-on practice of using AI to help build a small graphics game in a UEFI environment. It lays out a reproducible workflow of code review, two-phase iteration, and serial-port debugging, and breaks down two common pitfalls: frame buffer info pointers going stale after setting a display mode, and an incorrect Graphics Output Protocol (GOP) GUID configuration.

    Most people picture “writing a graphics program” at the operating system level: a window manager, ready-made graphics libraries, and a mature runtime. In a UEFI pre-boot environment provided by the motherboard firmware before the OS starts, almost none of these conveniences exist. UEFI runs on bare metal, with no POSIX-style system calls and no process scheduling; for files, you access the EFI System Partition through EFI_SIMPLE_FILE_SYSTEM_PROTOCOL. Every pixel you draw has to be written into the frame buffer yourself (or filled and moved in blocks via the GOP Blt operations).

    Graphics capability is usually obtained through the Graphics Output Protocol (GOP). It is a standardized interface responsible for enumerating display modes, setting resolution, and exposing the frame buffer’s physical address and size. In essence, your program does this: locate the protocol handle, set the display mode, read the frame buffer info, then write pixels into the frame buffer. It sounds simple, but once you get into low-level details like protocol location, GUID matching, and memory lifetime, a small slip can cause a black screen, a garbled screen, or a silent exit. This is also why using AI coding tools to assist this kind of development is both valuable and challenging: AI excels at generating large amounts of boilerplate and standard call sequences, but its grasp of implicit constraints like hardware timing and pointer validity still needs a human to check.

    2. How Should You Split the Two-Phase Iteration to Keep It Manageable?

    Faced with a task that is “from scratch, must both run and look good,” the most effective strategy is not to state all requirements at once, but to split them into two clearly bounded phases:

    • Phase 1 (Runnable): The goal is to get the program to compile, boot, and keep the main loop turning, even if the visuals are crude and the logic is incomplete. For the review and setup, see sections 3, 4, and 5; for serial debugging, see section 6; for a ready-to-run skeleton, see section 8.
    • Phase 2 (Refinement and Optimization): Building on a runnable base, progressively fix display errors, complete input handling, and optimize drawing. For the concrete actions, see section 7.

    The value of this split is quickly narrowing the fault-isolation scope. If you introduce the three big blocks (graphics, input, game logic) all at once, you will struggle to tell which layer a crash came from. Phasing guarantees that each round introduces only one class of variable, making it much faster to localize problems.

    Two disciplines complement the two-phase approach:

    • Small-step verification: Change only one class of problem at a time, and verify via serial port immediately after each change, avoiding the situation where multiple variables shift at once and nothing can be localized.
    • Separate review from verification: First produce a checklist, then make changes, then run and verify. “Analyzing code” and “actually running it” are two independent sources of information; mixing them together makes it easy to change one thing and hope for the best, iterating by trial and error.

    3. Phase 1 in Practice: Code Review Comes First

    3.1 Have the AI Produce a Checklist First, Don’t Let It Edit Code Directly

    Before making changes, having the AI tool do a structured review of the existing code is a high-value path. The effective approach is to guide it through module-by-module inspection: program entry, main loop, game logic, rendering module, and input handling. Have the AI produce an “issue list” rather than start editing right away. The benefit is that you first gain an awareness of global risk, then decide what to change and how.

    The review checklist is the product of “analysis,” while code changes are the starting point of “verification.” Keeping the two separate is what puts the “separate review from verification” discipline from the previous section into practice.

    The prompt for this step should be specific and can pin down four things:

    • Provide a role;
    • Provide the modules to inspect;
    • Specify the output fields;
    • Require marking anything that can’t be confirmed, along with a verification method.

    The template below can be copied and used directly.

    3.2 A Copy-Ready Review Prompt Template

    Send the following template along with the source code to the AI tool:

    1. Role: You are a firmware engineer fluent in UEFI/EDK2, familiar with the
    2. Graphics Output Protocol (GOP) and firmware memory lifetime.
    3. Task: Perform static review only. Do not change code. Output an issue list only.
    4. Modules to inspect (check each in order):
    5. 1. Program entry and initialization (efi_main, handles and system table, watchdog setup)
    6. 2. Graphics Output Protocol location (LocateProtocol Status and handle, GUID constants)
    7. 3. Display mode (whether the Info returned by QueryMode is still in use after SetMode)
    8. 4. Frame buffer writes (pixel format, PixelsPerScanLine, whether the write range is out of bounds)
    9. 5. Main loop (exit condition, whether it can hang)
    10. 6. Input handling (event reads, key mapping, exit operation)
    11. 7. Memory lifetime (whether allocation and release are paired)
    12. Output format: For each issue, output the following fields
    13. - Number:
    14. - Severity: Critical/High/Medium/Low
    15. - Location: filename:line number
    16. - Cause: which UEFI/EDK2 constraint is violated
    17. - Fix direction: one sentence describing the change
    18. Requirements:
    19. - Mark anything that cannot be confirmed as "to be verified" and give a
    20. verification method (serial print / checking return values, etc.);
    21. - Prioritize issues that will cause black screen, garbled screen, or abnormal termination.

    After the list comes back, use the “to be verified” items to determine the inspection order, then start making changes.

    4. Pitfall 1: Can You Still Use the Frame Buffer Info After Setting the Display Mode?

    The conflict between pointer lifetime and the timing of setting the display mode is a subtle problem in frame buffer development.

    Before setting the display mode, a program often first queries the info for a given mode and gets a pointer to a descriptor structure; then it calls SetMode. The flow looks smooth on the surface, but danger lurks underneath:

    • Setting the mode replaces Gop->Mode->Info with the new mode’s info;
    • The info previously returned by QueryMode may become invalid or be freed by the firmware;
    • Continuing to use it is a use-after-pointer situation.

    The typical symptoms are a black screen, a garbled screen, or abnormal termination, and whether it crashes immediately depends on the firmware implementation. Some firmware just reclaims that memory; others reuse it quickly, so the problem won’t reproduce consistently, which is exactly what makes it hard to localize.

    The root cause is that the two kinds of info have different semantics:

    • The EFI_GRAPHICS_OUTPUT_MODE_INFORMATION returned by QueryMode describes a “candidate mode”;
    • Gop->Mode->Info describes the “currently active mode.”

    At the moment the screen switches, the candidate mode info is no longer a reliable basis. The correct approach is to read the currently active frame buffer info uniformly from Gop->Mode after setting the mode, rather than caching a temporary pointer from before the mode was set:

    1. #include <Guid/GraphicsOutput.h>
    2. // 1. Locate the Graphics Output Protocol
    3. EFI_STATUS Status;
    4. EFI_GRAPHICS_OUTPUT_PROTOCOL *Gop = NULL;
    5. Status = gBS->LocateProtocol (&gEfiGraphicsOutputProtocolGuid, NULL, (VOID **)&Gop);
    6. if (EFI_ERROR (Status)) {
    7. return Status; // Returns EFI_NOT_FOUND if the protocol is absent; see section 5 for troubleshooting
    8. }
    9. // 2. Set the target display mode (desiredMode is chosen by enumerating with QueryMode; see section 8 for the full skeleton)
    10. Status = Gop->SetMode (Gop, desiredMode);
    11. if (EFI_ERROR (Status)) {
    12. return Status; // Do not continue drawing if the mode set fails
    13. }
    14. // 3. Key point: get the frame buffer info AFTER SetMode.
    15. // Do not reuse the temporary pointer returned by QueryMode before SetMode.
    16. UINTN fbBase = Gop->Mode->FrameBufferBase;
    17. UINTN fbSize = Gop->Mode->FrameBufferSize;

    In firmware programming, “data obtained from a query” is often just a snapshot at a given moment. Once the underlying state switches, you must re-read it and cannot assume it stays valid.

    Getting the base address is not enough; to put a dot on the screen you also need to know “how many pixels per row” and “how colors are laid out”:

    1. // 4. Compute the pixel offset with Mode->Info: a row occupies PixelsPerScanLine pixels,
    2. // which is not necessarily equal to HorizontalResolution. Computing by width directly
    3. // will misalign the image.
    4. UINTN PixelOffset = y * Gop->Mode->Info->PixelsPerScanLine + x;
    5. // 5. Determine pixel width and color component order from PixelFormat.
    6. // Most x86 firmware uses PixelRedGreenBlueReserved8BitPerColor (4 bytes per pixel),
    7. // with RGB at bytes 1..3 from low to high (i.e., 0x00RRGGBB);
    8. // but whether it is BGR depends on the firmware, so go by the masks in PixelInformation.
    9. UINT32 *Pixel = (UINT32 *)(fbBase + PixelOffset * 4);
    10. *Pixel = Color;

    5. When Nothing Shows Up, Is It the GUID or Something Else?

    If the program runs but nothing shows on screen, the first thing to suspect is the GUID configuration in the protocol-location step.

    The UEFI specification defines a fixed GUID for each protocol. The GUID for the Graphics Output Protocol is gEfiGraphicsOutputProtocolGuid, defined in <Guid/GraphicsOutput.h>. Its name is fixed and must not be changed arbitrarily. A single discrepancy in a hand-written constant will either cause a compile-time “undefined” error or simply fail to find the protocol: LocateProtocol won’t return the correct GOP handle, and all subsequent drawing operations will fail.

    If the problem isn’t the GUID, continue isolating “nothing shows up” in this order:

    1. Check the return value of LocateProtocol: whether the status code is success and whether the handle is non-null.
    2. Confirm the Graphics Output Protocol is installed: some firmware (especially customized or stripped-down firmware) doesn’t load a GOP driver, in which case LocateProtocol returns EFI_NOT_FOUND. You can run dh -p GraphicsOutput in the UEFI Shell to view the current handles, or run drivers to check which drivers are loaded. Without GOP, consider switching to a text-output-only approach, or confirm on the dev board whether the display path is usable.
    3. Verify the pixel format: whether colors appear with red and blue swapped depends on whether the format is RGB or BGR. RGB/RGBA-type formats are common in graphics driver frameworks; in a pure UEFI environment, go by the format the firmware reports in Mode->Info.
    4. Verify resolution and scan-line width: whether the resolution and PixelsPerScanLine given by Mode->Info match your calculation, and whether the image shows diagonal striping or an overall offset.
    5. Verify Blt calls: if you draw with Blt, check whether the operation type, source buffer, target rectangle, and color value format match.

    For identifiers like GUIDs, a one-character difference leads to a completely different result. So in AI-generated boilerplate, always verify the header file name, constant name, and spelling one by one instead of assuming they are correct.

    6. How Do You Wire Up the Serial Port and Capture Output?

    In an environment with no operating system and no graphical debugger, serial output is almost the only observability means. When the program exits “silently” at some point, the most effective approach is to insert debug info at key points and watch the serial port in real time to see which step the program reached and what the value of each variable is.

    Using EDK2 development as an example, making serial output actually visible takes at least these three steps:

    1. Build in DEBUG mode: compile with the build parameter -b DEBUG, or use stuart_build -b DEBUG. The DEBUG() macro in EDK2 is compiled out in RELEASE builds, leaving no code behind, but the code size and firmware size during the build will be larger.
    2. Choose an output channel:
      • In firmware such as OVMF, DEBUG() is emitted through the debug port; in QEMU, add -debugcon file:debug.log to capture it (some versions also require -global isa-debugcon.iobase=0x402).
      • In your application, call SerialPortLib’s SerialPortWrite directly, or use the Serial IO protocol (EFI_SERIAL_IO_PROTOCOL) for output, and capture COM1 logs with -serial file:serial.log.
    3. Insert markers at key nodes: print a marker line after protocol location, after setting the mode, and before entering the main loop. Whichever marker the serial output stops after lets you narrow the fault scope down to a few lines of code, far more efficient than guessing in front of a black screen.

    Two more points:

    • Desensitize variable values (especially device info and address-type content) before printing them, to avoid writing information that shouldn’t be exposed into logs;
    • Debug prints and logs should stay only in debug builds and not be carried into production firmware.

    7. Phase 2 in Practice: How Do Refinement and Optimization Land?

    Once the image can come up, Phase 2 shifts its focus to “correct, smooth, and exitable.” The following three actions can be applied directly.

    7.1 Do Partial Redraws Based on Input Events

    Most of a game screen is usually static, so redrawing the entire screen every frame is wasteful and also more likely to expose out-of-bounds problems. You can maintain a “dirty rectangle” list that records only the regions changed by input events or game logic, and redraw just those regions on the next frame. Clear the corresponding rectangles after drawing, and the drawing range becomes easier to control.

    7.2 Lower the Redraw Rate, Not the Color Depth

    The GOP has no refresh-rate setting interface; what you can adjust is the pace of redraws:

    • Call gBS->Stall() between frames for a brief delay;
    • Skip the frame when nothing has changed on screen.

    Color depth is determined by the pixel format and shouldn’t be changed for performance. The only “frequency” issue to watch is the watchdog: call SetWatchdogTimer(0, 0, 0, NULL) when loading the image to turn it off (see section 8), which prevents the firmware from resetting the board during development debugging because no key was pressed in time.

    7.3 Validate the Region for Out-of-Bounds Before Drawing

    The frame buffer size is fixed, and an out-of-bounds write can corrupt adjacent memory, a consequence harder to diagnose than a black screen. Before drawing, check:

    • Whether the rectangle exceeds the screen resolution;
    • Whether the offset computed with PixelsPerScanLine falls within FrameBufferSize;
    • Whether the handling of the boundary between video memory and non-video memory is consistent (on some platforms the two addresses are the same; on others there’s an offset).

    When you find an out-of-bounds condition, print the rectangle parameters via serial port to quickly locate the caller.

    After fixing each spot, recompile and confirm via serial port that there’s nothing abnormal before looking at the screen, avoiding multiple variables changing at once.

    8. Minimal Runnable Skeleton: Copy and Go

    Below is a minimal skeleton: locate the GOP, select and set an 800×600 mode, clear the screen, then enter a main loop that waits for a key. Every key node emits serial output, making it easy to reproduce the debugging flow from section 6.

    1. #include <Uefi.h>
    2. #include <Library/UefiLib.h>
    3. #include <Library/UefiBootServicesTableLib.h>
    4. #include <Library/DebugLib.h>
    5. #include <Guid/GraphicsOutput.h>
    6. EFI_STATUS
    7. EFIAPI
    8. efi_main (
    9. IN EFI_HANDLE ImageHandle,
    10. IN EFI_SYSTEM_TABLE *SystemTable
    11. )
    12. {
    13. EFI_STATUS Status;
    14. EFI_GRAPHICS_OUTPUT_PROTOCOL *Gop;
    15. EFI_GRAPHICS_OUTPUT_MODE_INFORMATION *Info;
    16. UINT32 Mode;
    17. UINTN SizeOfInfo;
    18. UINTN X, Y;
    19. // Disable the watchdog when the image loads, to prevent a firmware reset during debugging
    20. (VOID)gBS->SetWatchdogTimer (0, 0, 0, NULL);
    21. // 1. Locate the Graphics Output Protocol
    22. Status = gBS->LocateProtocol (
    23. &gEfiGraphicsOutputProtocolGuid,
    24. NULL,
    25. (VOID **)&Gop
    26. );
    27. if (EFI_ERROR (Status)) {
    28. Print (L"LocateProtocol(GOP) failed: %r\n", Status);
    29. return Status;
    30. }
    31. DEBUG ((DEBUG_INFO, "GOP located, MaxMode = %d\n", Gop->Mode->MaxMode));
    32. // 2. Select the 800x600 mode (fall back to the current mode if unavailable)
    33. for (Mode = 0; Mode < Gop->Mode->MaxMode; Mode++) {
    34. Status = Gop->QueryMode (Gop, Mode, &SizeOfInfo, &Info);
    35. if (EFI_ERROR (Status)) {
    36. continue;
    37. }
    38. if ((Info->HorizontalResolution == 800) &&
    39. (Info->VerticalResolution == 600)) {
    40. FreePool (Info);
    41. break;
    42. }
    43. FreePool (Info); // Info returned by QueryMode is freed by the caller
    44. }
    45. if (Mode == Gop->Mode->MaxMode) {
    46. Mode = Gop->Mode->Mode; // Keep the current mode
    47. }
    48. // 3. Set the mode
    49. Status = Gop->SetMode (Gop, Mode);
    50. if (EFI_ERROR (Status)) {
    51. Print (L"SetMode(%d) failed: %r\n", Mode, Status);
    52. return Status;
    53. }
    54. DEBUG ((
    55. DEBUG_INFO,
    56. "Mode %d set: %dx%d, PixelFormat = %d\n",
    57. Mode,
    58. Gop->Mode->Info->HorizontalResolution,
    59. Gop->Mode->Info->VerticalResolution,
    60. Gop->Mode->Info->PixelFormat
    61. ));
    62. // 4. Clear the whole screen to black with Blt
    63. Status = gBS->SetMem ((VOID *)(UINTN)Gop->Mode->FrameBufferBase,
    64. Gop->Mode->FrameBufferSize, 0);
    65. if (EFI_ERROR (Status)) {
    66. Print (L"Clear screen failed: %r\n", Status);
    67. return Status;
    68. }
    69. DEBUG ((DEBUG_INFO, "Enter main loop\n"));
    70. // 5. Main loop: exit on ESC
    71. while (TRUE) {
    72. EFI_INPUT_KEY Key;
    73. if (!EFI_ERROR (gBS->CheckEvent (gST->ConIn->WaitForKey, 0, NULL, NULL))) {
    74. if (!EFI_ERROR (gST->ConIn->ReadKeyStroke (gST->ConIn, &Key)) &&
    75. (Key.ScanCode == SCAN_ESC)) {
    76. break;
    77. }
    78. }
    79. (VOID)gBS->Stall (100000); // 100ms, avoid busy-spinning
    80. }
    81. return EFI_SUCCESS;
    82. }

    Starting from this skeleton, wire up the game logic and the pixel writes positioned by PixelsPerScanLine (see section 4).

    When building, declare the required library classes (UefiLib, UefiBootServicesTableLib, DebugLib, DebugPortLib, etc.) in the application’s .inf, then compile with build -p <platform.dsc> -b DEBUG. When running OVMF, add -debugcon file:debug.log, and you’ll see every key node in the log.

    9. Common Problem Troubleshooting Table

    When you hit a symptom, you can start by checking item by item against the table below:

    Symptom Common cause Verification method
    Black screen Protocol not installed, LocateProtocol returns EFI_NOT_FOUND; SetMode failed; the written color is the same as the background Print the Status of LocateProtocol and SetMode; fill a known color with Blt to confirm the display path works
    Garbled screen, diagonal striping Computing the offset by width instead of PixelsPerScanLine; red and blue order reversed Print resolution, scan-line width, and pixel format; draw a known color with Blt and compare the displayed result
    Abnormal termination Still using the Info pointer returned by QueryMode after SetMode; writing out of bounds Print the addresses of Info and Gop->Mode->Info; set the suspect pointer to an invalid value and run again to see whether the problem reproduces consistently
    No serial output Used a RELEASE build; logs not redirected to a file Confirm you’re using a DEBUG build; in QEMU confirm you added -serial or -debugcon; add a DEBUG print at the earliest node
    No input response Input events not being read; a full-frame draw takes too long and keys aren’t processed in time Check with CheckEvent before ReadKeyStroke and print the key value; split drawing into several smaller frames

    After troubleshooting, you can go back and fold the newly added checks from this round into the section 3.2 prompt template, so the next review round covers these points too.

    10. Conclusion: What to Keep in Mind When Doing AI-Assisted UEFI Graphics Development?

    Developing graphics programs in a UEFI pre-boot environment is a direct test of a developer’s low-level skills. It involves a series of precise aspects: protocol location, GUID configuration, frame buffer operations, and memory lifetime management.

    With AI coding tools, the two-phase iteration of “runnable, then optimizable,” structured code review, and serial-driven precise debugging can reduce hand-writing and rework of boilerplate. But it’s important to stay clear-eyed:

    • AI can speed up the production of boilerplate and the initial localization of problems;
    • What truly decides success or failure is still the developer’s understanding of hardware behavior and the memory model.

    Concretely, treat AI as an “amplifier” rather than a replacement: let it generate standard call sequences, boilerplate, and review checklists, while the human takes responsibility for checking implicit constraints like hardware timing and memory lifetime.

    The value of human-AI collaboration lies in combining AI’s “speed” with the human’s “precision” to conquer those tedious, easy-to-stumble-on low-level tasks together.