Using Large Language Models for UEFI Graphics Development and Debugging: A Practical Guide

    This article explains how large language models (LLMs) can assist with developing and debugging UEFI graphics programs, a particularly challenging area of low-level firmware development. It covers a practical collaboration workflow that moves from virtualization to real hardware in iterative rounds, prioritizing code review before execution. It addresses common failure modes—black screens, screen corruption, crashes, failed protocol location, and missing serial output—and shows how to distinguish wild pointers from dangling pointers, verify Graphics Output Protocol (GOP) handling, and rely on serial logs as the primary debugging signal. Readers will find concrete code examples, structured prompt templates, a troubleshooting reference table, and guidance on which parts still require human review, so LLMs are used as collaborators rather than automatic code generators.

    1. Background: Why UEFI Graphics Programs Are Hard, and Why LLMs Can Help

    Developing graphics programs in a firmware environment like UEFI is one of the more difficult tasks in low-level development. UEFI runs before the operating system loads, so there is no mature graphics library, window system, or input/output abstraction, and none of the runtime support common in traditional application development. Screen output typically depends on the UEFI Graphics Output Protocol (GOP), and developers must handle mode querying, mode setting, framebuffer drawing, input reading, and exit logic themselves.

    As a result, these programs share a few characteristics:

    • Constrained runtime environment: without an OS-provided graphics stack, many capabilities must call firmware protocols directly.
    • Limited debugging options: there is no conventional user-mode debugger, so debugging usually relies on serial logs, virtual machine screenshots, and step-by-step bisection.
    • Obvious consequences of errors: mishandling a pointer, mode, or protocol handle can directly cause a black screen, screen corruption, a crash, or a hang.

    In this kind of task, a large language model can play an assisting role—for example, helping to organize code structure, flagging common risks, generating checklists, explaining UEFI protocol call flows, and narrowing down problems based on serial logs. It is worth emphasizing that this article does not evaluate any specific product, nor does it treat the LLM as a “generate it and it’s ready to ship” tool. Instead, it treats the LLM as a collaboration aid. The reliability of firmware graphics programs ultimately depends on real-environment verification, manual review, and a complete testing process.

    2. Overall Collaboration Workflow: Virtual Machine First, Real Hardware Later, Iterated Acceptance

    The thing low-level graphics development fears most is “generating a huge pile of code at once and then having no idea where to start.” A safer approach is to split the task into multiple stages, each with clear goals and acceptance criteria.

    2.1 Prerequisites

    Before involving a large language model in development or review, it is worth preparing the following conditions:

    • Clarify the EDK2 or target firmware SDK version to avoid the model generating code that does not match the actual APIs.
    • Prepare a QEMU plus OVMF virtual machine environment as the first-round verification platform; if real-hardware verification is required, first choose a recoverable test machine.
    • Confirm that serial output is available—for example, being able to see boot information through SerialLib, DebugLib, or platform logs.
    • Keep a rollback path: when USB boot, firmware image modification, or flashing is involved, first assess data safety, boot-failure risk, and the recovery plan.
    • Keep a minimal diff for each change, so it is easier to identify which change introduced a problem.

    2.2 Per-Round Goals and Acceptance Checklist

    The first round should only solve the “does it run” problem, without pursuing visuals or feel. Acceptance items can include:

    • The program compiles successfully.
    • Boot information can be output to serial or virtual machine logs.
    • The graphics output protocol is located successfully.
    • The display mode is set successfully, and the return status is correctly checked.
    • The screen can be cleared and can output basic text or color blocks.

    The second round then handles interaction and logic, for example:

    • Key reading does not block the main flow.
    • The exit condition is clear, and the main loop can exit normally.
    • Coordinate updates, boundary checks, and collision detection do not go out of bounds.
    • The rendered content shows no obvious corruption, ghosting, or framebuffer errors.
    • Resource allocation and release are paired, with no obvious signs of double release or leaks.

    The value of this per-round strategy is that the problem domain in each round is small. Whether you are debugging it yourself or having the LLM review it, the more focused the goal, the easier the output is to verify.

    2.3 Prompt Templates for the LLM

    To make the model’s output more controllable, you can use structured prompts. For example:

    1. You are reviewing a UEFI graphics program module.
    2. Context: below is the entry function and GOP initialization code.
    3. Goal: in this round, only check the risks of graphics output protocol location and the SetMode call.
    4. Constraints: do not introduce new dependencies, do not change function signatures, only point out issues and give minimal fix suggestions.
    5. Output format:
    6. 1. Issue list: organized by risk level;
    7. 2. Fix suggestions: provide a minimal-change diff;
    8. 3. Verification method: explain how to confirm the fix through serial logs or virtual machine behavior.

    This kind of prompt emphasizes “context, goal, constraints, and output format,” which effectively reduces the model’s tendency to speak in generalities.

    3. Code Review First: Find Risks Before Running

    When you get code of unknown origin—especially UEFI code generated by a large language model—your first reaction should not be to run it directly, but to do a static review first. You can break the code into modules and have the model output a risk list for each module.

    Common review modules include:

    • Entry and initialization flow: whether the protocol location result is checked, whether error returns are handled.
    • Main loop: whether the exit condition is complete, whether there are infinite loops or state machine omissions.
    • Game logic: whether coordinates go out of bounds, whether input states can be consumed repeatedly.
    • Rendering module: whether the framebuffer base address, dimensions, and pixel format are correct, whether pointer lifetimes are clear.
    • Input handling: whether key reading blocks, whether there are array out-of-bounds issues.
    • Memory and resource management: whether the information returned by QueryMode is released, whether it is released twice, whether it continues to be accessed after release.

    In this practice, the benefit of static review depends on whether the modules are split clearly, rather than on a universal conclusion that can be drawn independently of the specific task. A verifiable small case is as follows.

    Original code snippet:

    1. Status = gop->QueryMode(gop, mode, &InfoSize, &Info);
    2. gop->SetMode(gop, mode);

    Issues found during review:

    • The Status returned by QueryMode is not checked.
    • Whether Info is NULL is not checked.
    • When the mode number is out of bounds, QueryMode may return EFI_UNSUPPORTED; continuing to access Info at this point is risky.
    • It does not note that Info is a copy held by the caller and must be freed after use.

    Key logic after the fix:

    1. Status = gop->QueryMode(gop, mode, &InfoSize, &Info);
    2. if (EFI_ERROR(Status) || Info == NULL) {
    3. // Log the error and return safely
    4. return;
    5. }
    6. Status = gop->SetMode(gop, mode);
    7. if (EFI_ERROR(Status)) {
    8. FreePool(Info);
    9. Info = NULL;
    10. // Log the error and return safely
    11. return;
    12. }
    13. FreePool(Info);
    14. Info = NULL;

    This case shows that the model can help detect common issues such as “unchecked status, unreleased resources, and null-pointer risk” before the code runs. But whether a fix is ultimately applied still needs to be confirmed through serial logs and virtual machine behavior.

    4. How to Diagnose Crashes? Distinguish Wild Pointers from Dangling Pointers, Then Check Lifetimes

    A program that starts, prints initial logs, and then suddenly exits is a fairly common failure symptom in UEFI graphics programs. When diagnosing, first distinguish two concepts:

    • Wild pointer: a pointer that is uninitialized or points to an indeterminate address.
    • Dangling pointer: a pointer that was once valid, but after the object has been freed or its lifetime has ended, the pointer is still being used.

    In the graphics output protocol, a high-risk pattern is calling QueryMode to get mode information and then either not checking the status, not freeing the memory, or continuing to reference it after freeing.

    Risk example:

    1. // Risk example: return value not checked, and reference continued after release
    2. EFI_STATUS Status;
    3. UINTN InfoSize = 0;
    4. EFI_GRAPHICS_OUTPUT_MODE_INFORMATION *Info = NULL;
    5. Status = gop->QueryMode(gop, mode, &InfoSize, &Info);
    6. // Risk: Status and Info are not checked. When the mode number is out of bounds, it may return EFI_UNSUPPORTED and Info may be empty.
    7. gop->SetMode(gop, mode);
    8. // Risk: the return value of SetMode is not checked; if Info is accessed directly afterward, an empty pointer or outdated mode information may be used.
    9. FreePool(Info);
    10. Info = NULL;
    11. // If the resolution is later read through the old Info, this may form a dangling pointer.
    12. // If the same memory block is freed again on an error path, it may cause a double release.

    One point needs special clarification here: according to the EDK2 reference implementation, the ModeInfo returned by QueryMode is a copy held by the caller and must be freed with FreePool after use. SetMode is mainly responsible for switching the display mode, so the problem should not simply be attributed to “SetMode causing the buffer returned by QueryMode to become invalid.” The truly common risks include:

    • Not checking the Status of QueryMode.
    • Not checking whether Info is NULL.
    • Mode number out of bounds, causing the query to fail.
    • Not checking the return value of SetMode.
    • Continuing to access Info after it is freed, forming a dangling pointer.
    • Releasing the same memory twice on an error path.
    • gop itself being empty, or protocol location failing.

    A safer approach is: check errors first, pair resource release, and read state from the current mode object after switching modes.

    Recommended pattern:

    1. if (gop == NULL) {
    2. // Log the protocol location failure
    3. return;
    4. }
    5. Status = gop->QueryMode(gop, mode, &InfoSize, &Info);
    6. if (EFI_ERROR(Status) || Info == NULL) {
    7. // Log the query failure, for example an out-of-bounds mode number
    8. return;
    9. }
    10. Status = gop->SetMode(gop, mode);
    11. if (EFI_ERROR(Status)) {
    12. FreePool(Info);
    13. Info = NULL;
    14. // Log the mode-set failure
    15. return;
    16. }
    17. FreePool(Info);
    18. Info = NULL;
    19. // After switching is complete, prefer reading information from the current mode
    20. UINTN CurrentMode = gop->Mode->Mode;
    21. UINT32 Width = gop->Mode->Info->HorizontalResolution;
    22. UINT32 Height = gop->Mode->Info->VerticalResolution;
    23. EFI_PHYSICAL_ADDRESS FrameBuffer = gop->Mode->FrameBufferBase;
    24. UINTN FrameBufferSize = gop->Mode->FrameBufferSize;

    If the business only needs current-mode information, you can also use gop->Mode->Info, gop->Mode->FrameBufferBase, and gop->Mode->FrameBufferSize directly after SetMode succeeds, without relying on the local Info from before the switch.

    In addition, a crash in the main loop should not be attributed solely to pointers. You should also check:

    • Whether the stack space is exhausted, especially with recursion, large local arrays, or calls made in an interrupt context.
    • Whether timer events or key events are registered repeatedly.
    • Whether global state is being modified by multiple modules at the same time.
    • Whether resources are being released twice across multiple paths.
    • Whether an interface of a protocol that failed to initialize is being called.

    5. UI Won’t Show: Why Does LocateProtocol Fail?

    If the program does not crash but the graphical interface does not appear, you should first check whether protocol location succeeded. UEFI identifies and locates protocols via GUIDs, so if the graphics output protocol GUID is incorrect, or the corresponding driver has not loaded, LocateProtocol may fail.

    Example:

    1. EFI_GRAPHICS_OUTPUT_PROTOCOL *gop = NULL;
    2. EFI_STATUS Status;
    3. Status = gBS->LocateProtocol(
    4. &gEfiGraphicsOutputProtocolGuid,
    5. NULL,
    6. (VOID **)&gop
    7. );
    8. if (EFI_ERROR(Status) || gop == NULL) {
    9. // May fail here when the GUID does not match, the driver is not loaded, or the platform has not connected the controller
    10. return;
    11. }

    The troubleshooting approach can be:

    1. Print the Status returned by LocateProtocol.
    2. Determine whether gop is empty.
    3. Check whether the graphics output protocol is available on the current platform.
    4. Check whether the controller needs to be connected or the relevant driver loaded first.
    5. Distinguish “protocol location failure” from “mode-setting failure.”

    In a virtual machine environment, you can confirm from logs which step the program reached; in a real-hardware environment, you should be especially cautious and avoid making the device unbootable through repeated flashing or firmware modification.

    6. Serial Logs Are the Primary Basis for Firmware Debugging

    In a UEFI environment without a graphical debugger, observability is critical. Whether you are debugging manually or having a large language model analyze the code, serial logs should be one of the main sources of evidence.

    Concrete practices include:

    • Output key information to the serial port through SerialLib, DebugLib, or platform logging facilities, commonly COM1.
    • In QEMU, you can use -serial stdio to observe serial output, or redirect the logs to a file.
    • Print marked logs at key points, for example:
      • Program entry
      • Protocol location complete
      • Mode query complete
      • Mode set complete
      • Framebuffer acquisition complete
      • Entering the main loop
      • Exiting the main loop
    • Increase log density at suspicious spots, and use bisection to narrow the scope.
    • For error states, print the Status and whether key pointers are empty, but avoid uncontrolled printing that blocks the serial port.

    The more complete the logs, the more the large language model has to reason from. If you just hand a piece of code to the model and tell it to “guess where the error is,” it is usually inefficient. A better approach is to submit the symptoms, the logs, and the relevant code snippets together, so the model can give a troubleshooting path centered on the specific problem.

    7. Quick Reference Table: Common Symptoms and Troubleshooting Order

    Symptom Check First Common Causes Next Step
    Program starts but screen is black SetMode return value, whether gop is non-empty Protocol location failure, mode-setting failure Print Status, confirm whether the display mode was set successfully
    Screen shows corruption or ghosting Framebuffer base address, dimensions, pixel format Wrong framebuffer pointer, drawing range out of bounds Verify gop->Mode->FrameBufferBase and FrameBufferSize
    UI displays but keys are unresponsive Input protocol or key-state reading Input reading blocks, key state not updated Add key-reading logs, check the main loop state machine
    Crashes after running for a while The most recent change, the last log position Dangling pointer, resource leak, stack exhaustion Bisect the problem, add boundary printing and memory-release checks
    No logs at all on serial Serial initialization, COM port, QEMU arguments Logging not initialized, wrong serial redirection First output a fixed string to confirm the log channel works
    LocateProtocol fails Protocol GUID, platform driver status Wrong GUID, driver not loaded Print Status, check the platform firmware environment

    8. Treat LLMs as Collaborators, Not Replacements

    In UEFI graphics program development, a large language model can help developers build code structure faster, produce issue lists, explain protocol semantics, and narrow the scope based on logs. But the high-risk parts still must be manually reviewed by the developer.

    Key things to review manually include:

    • Pointer lifetime: whether it is initialized, whether it is used after being freed, whether it is freed twice.
    • Whether resource allocation and release are paired: whether the ModeInfo allocated by QueryMode is freed with FreePool.
    • Protocol call ordering: whether the protocol is located before its interface is called, whether the mode is set before reading the current framebuffer.
    • Global state: whether the main loop, input state, and render state have races or overwrites.
    • Platform differences: different firmware implementations, virtual machine environments, and real-hardware environments may behave differently.
    • Security impact: when USB boot, firmware flashing, or boot-entry modification is involved, the recovery plan must be assessed first.

    Manual gatekeeping is not a process burden but a safety boundary that cannot be omitted in firmware development. Especially in areas like memory, protocol handles, and display modes—the parts that “look right but crash when run”—any automated suggestion must be verified in a real environment.

    9. FAQ

    9.1 What to do if the program starts but the screen is black or corrupted?

    First check whether SetMode returned success, then check whether gop is non-empty. If the mode was set successfully, read gop->Mode->Info to confirm the resolution and pixel format, and verify gop->Mode->FrameBufferBase and gop->Mode->FrameBufferSize. A black screen commonly results from not correctly obtaining the framebuffer, while corruption commonly results from errors in drawing coordinates, width/height calculations, or pixel-format handling.

    9.2 How to locate a crash after entering the main loop?

    First see where the last serial log stops, then check the pointers and resources near that location. Focus on whether the Info returned by QueryMode was not checked, not freed, or used after being freed; also check the SetMode return value, stack space, timer events, key-array out-of-bounds access, and double release.

    9.3 How to diagnose missing serial logs?

    First confirm whether the log channel is initialized. Common checks include: whether the serial base address is correct, whether the COM port matches, whether QEMU uses -serial stdio or redirects to a file, whether debug-level log output is enabled, and whether a fixed string is output at the very start of the entry point. If even the fixed string does not appear, first troubleshoot the log channel itself.

    9.4 Can AI-generated UEFI code be used directly in production firmware?

    It is not recommended. Code generated by a large language model can serve as a draft or a review aid, but production firmware must go through manual review, code review, static checks, virtual machine testing, real-hardware testing, regression testing, and a security assessment. Code that involves the boot flow, memory management, protocol calls, and firmware flashing carries higher risk and cannot rely solely on model output.

    10. Conclusion

    Large language models are changing the way low-level development is done, but constrained environments like UEFI are precisely a real-world test of their reliability. Problems such as black screens, screen corruption, crashes, protocol location failures, and missing serial logs will not automatically disappear just because AI is introduced. In fact, they demand a rigorous methodology: proceed in iterative rounds, review code first, drive debugging with serial logs, verify on a virtual machine before real hardware, and rely on manual review as the final safeguard.

    By mastering this collaboration method, developers can put large language models where they genuinely fit—for example, generating checklists, explaining protocol semantics, flagging common risks, and narrowing the problem scope based on logs—while keeping architecture decisions, memory lifetimes, protocol ordering, and safety boundaries firmly in their own hands. That is how you can deliver code that runs, is maintainable, and is verifiable more steadily and more quickly in complex firmware environments.