AI-Assisted UEFI Graphics Development: Practice and Debugging

    This article explains how to build and debug UEFI graphics programs with AI assistance, covering GOP usage, staged development, static review limits, mode-switch pitfalls, protocol lookup, serial logging, and runtime verification.

    Background: Why Graphics in Firmware

    After UEFI firmware starts and before an OS loads, programs can use only firmware services. Graphics output is one of them. The Graphics Output Protocol (GOP) exposes display-mode queries, mode switches, and framebuffer access. There is no full runtime: memory allocation, protocol lookup, and error handling are the developer’s responsibility.

    The environment is unforgiving. A dangling pointer or a wrong GUID rarely produces a clear error; the typical results are a black screen, a hang, or an immediate exit.

    Split the Work: Run First, Then Refine

    Splitting the work into two phases reduces risk.

    Phase one: get it running. Initialize, enter the main loop, and put pixels on screen. Ignore performance and style; prove the happy path.

    Phase two: refine. Clean module interfaces, tighten drawing, and add error handling.

    Each step should produce an observable result. Do not start refinement until phase one succeeds.

    Code Review: Limits of Static Checks

    Generative tools can scan existing code and flag unused variables, missing return checks, and unclear loop exits. Static review mainly covers syntax and common patterns. Protocol call order and memory lifetime are less reliable to judge from inspection alone.

    Review checklist:

    • Every protocol call’s return status is checked.
    • Pointers obtained from protocols or services remain valid for the entire use window.
    • After state changes (for example, a mode switch), dependent information is re-read.
    • Resources (memory, events, handles) have matching release paths.
    • Input polling and exit conditions in the main loop are reachable.

    Treat review findings as hypotheses. Confirm them with build and run.

    Issue 1: Cached Data Invalid After Mode Switch

    Switching graphics mode changes resolution, scanline width, and framebuffer address. Reusing mode info or pointers captured before the switch can access invalid data.

    Re-read current mode info after SetMode; do not reuse pre-switch pointers.

    1. Status = Gop->SetMode(Gop, ModeNumber);
    2. if (EFI_ERROR(Status)) {
    3. return Status;
    4. }
    5. // Re-read after mode switch; do not reuse pre-switch pointers
    6. FrameBase = Gop->Mode->FrameBufferBase;
    7. HorizMax = Gop->Mode->Info->HorizontalResolution;
    8. VertMax = Gop->Mode->Info->VerticalResolution;
    9. PixPerLine = Gop->Mode->Info->PixelsPerScanLine;

    Symptoms are often unstable: one frame draws, then the program exits in the main loop. Confirm whether pointer origin and use straddle a state change.

    Issue 2: Protocol Lookup Failure

    Firmware protocols are located by GUID. A wrong GUID fails lookup or returns the wrong handle. Use the GOP GUID constant from the specification or firmware development kit; do not type the numeric value by hand.

    Always check the locate status:

    1. EFI_GRAPHICS_OUTPUT_PROTOCOL *Gop = NULL;
    2. Status = gBS->LocateProtocol(
    3. &gEfiGraphicsOutputProtocolGuid,
    4. NULL,
    5. (VOID **)&Gop
    6. );
    7. if (EFI_ERROR(Status)) {
    8. // Log the error code; abort or degrade
    9. return Status;
    10. }

    Ignoring the status makes later NULL-pointer use much harder to diagnose.

    Debugging: Segmented Logs to Narrow Scope

    Firmware often lacks a debugger; serial output is the usual tool. Logs should:

    1. Sit before and after key steps so you get a comparable timeline.
    2. Print status codes, not only “success” or “failure” text.

    Log one line each for locate protocol, query mode, set mode, and enter main loop, with return values. Where the log stops is the next failing step. Narrowing this way is faster than reading the whole codebase.

    Verification: Runtime Is the Source of Truth

    Review notes often claim “it should run after this change.” Before you accept that, do three things:

    • Rebuild with no new warnings or errors.
    • Boot on the target or in a VM.
    • Confirm serial logs complete every stage as expected.

    Only then treat the fix as valid. One success is not stability. Repeat boots and try more than one resolution.

    Practical Advice

    1. Treat generated code as a draft to verify, not drop-in product.
    2. Review protocol calls, memory management, and state transitions first.
    3. Put status codes in logs, not only success/failure text.
    4. Change one thing per fix so you can roll back.
    5. Keep a reproducible test recipe: boot parameters and target environment.

    Summary

    Firmware graphics work is less about drawing algorithms than about call order, pointer lifetime, and error returns. Automation can speed a first draft; verification still belongs to the developer.