Fixing a UEFI Graphics Crash: Using GOP Mode Information Correctly

    This article describes how an LLM helped fix a UEFI graphics program that crashed after a GOP mode switch. It covers the three kinds of data the GOP protocol provides, why cached mode information becomes stale, how to check LocateProtocol results, and a checklist for similar bugs.

    1. Conclusion

    In this test, the LLM first fixed the compile errors through static review. The program then exited right after printing “Starting Game Loop” on screen. The serial log showed that the failure happened after the graphics mode switch. The rendering module kept using mode information from before the switch. The fix has two parts. After switching modes, read the current state again from the GOP protocol instance. After calling LocateProtocol, check both the returned status and the output pointer.

    This article is based on a single test. Exact field paths and behavior should be confirmed against the header files of the target EDK2 version.

    2. Risk Warning

    Low-level firmware debugging can leave a device unable to boot. Some firmware write operations can also corrupt data. Run the code in this article first on a virtual machine or a test platform that you can recover. Back up the firmware image before you modify it.

    3. Using GOP Mode Information Correctly

    The GOP protocol provides three kinds of data. Each comes from a different source, so handle each one separately.

    First, the EFI_GRAPHICS_OUTPUT_MODE_INFORMATION structure returned by QueryMode. It describes the parameters of one display mode, including the horizontal resolution, vertical resolution, pixel format, and pixels per scan line. The firmware allocates this structure, so the caller must release it with FreePool after use. It describes the mode only. It does not contain the frame buffer address.

    Second, the description of the current mode, Gop->Mode->Info. The firmware maintains this structure. Its HorizontalResolution and VerticalResolution fields hold the current resolution. The caller must not call FreePool on it.

    Third, the frame buffer, Gop->Mode->FrameBufferBase and Gop->Mode->FrameBufferSize. After SetMode succeeds, these two fields reflect the frame buffer base address and size of the new mode. The rendering module should read them directly.

    The original test code had a problem. The rendering module saved the resolution and frame buffer information from before the mode switch, and it did not fetch them again afterward. With the mode unchanged, this approach may work for a while. After a mode switch, it becomes likely to fail.

    The corrected sequence is as follows:

    1. Call LocateProtocol to get the Gop pointer. Check the returned status and whether the pointer is NULL.
    2. Call QueryMode to query the target mode. Call FreePool on the returned Info as soon as you finish using it.
    3. Call SetMode to switch to the target mode.
    4. Read FrameBufferBase and FrameBufferSize from Gop->Mode. Read HorizontalResolution and VerticalResolution from Gop->Mode->Info. Then update the parameters that the rendering module uses.

    4. LocateProtocol and GUID Checks

    The return type of gBS->LocateProtocol is EFI_STATUS. When the lookup succeeds, the protocol pointer is returned through the third parameter. When the lookup fails, the return value is usually EFI_NOT_FOUND, and the output pointer must not be used. The code should therefore check both the status and the pointer:

    1. Status = gBS->LocateProtocol(&gEfiGraphicsOutputProtocolGuid, NULL, (VOID **)&Gop);
    2. if (EFI_ERROR(Status) || Gop == NULL) {
    3. // Report the error message and stop initialization
    4. }

    GUID errors often appear when code mixes GUIDs from different protocols. After you change a GUID, check the name against the EDK2 header files. The GUID for the Graphics Output Protocol is named gEfiGraphicsOutputProtocolGuid. Its declaration is in the GraphicsOutput.h header in MdePkg.

    5. Debugging with AI Assistance

    Static review can catch syntax errors and obvious call problems. It is much less likely to catch state changes that happen after a mode switch. When you ask a model to debug this kind of issue, provide the following information together:

    • The serial log, including the last output line before the crash.
    • The status codes returned by LocateProtocol, QueryMode, and SetMode.
    • The resolution in Gop->Mode->Info before and after the switch, and the frame buffer base and size in Gop->Mode.
    • The EDK2 version, the compiler version, the target platform, and the path to the protocol header files, along with where fields such as Gop->Mode->Info are declared in those headers.

    Also ask the model to label each change with the specification entry or header location it relies on. A developer should check those references by hand. Verify the model’s conclusions on the target platform. Do not rely on code inspection alone.

    6. Common Errors Checklist

    • Keeping a QueryMode Info pointer for later use. Symptom: reads go wrong or the program crashes after the mode switch. Fix: read the current values from Gop->Mode->Info, and call FreePool on the QueryMode Info as soon as you finish with it. Verification: print Gop->Mode->Info->HorizontalResolution, Gop->Mode->Info->VerticalResolution, and Gop->Mode->FrameBufferBase before and after the switch.
    • Using the QueryMode Info to access the frame buffer. This structure does not contain a frame buffer address. Symptom: the picture is misaligned, or memory is written out of bounds. Fix: use Gop->Mode->FrameBufferBase and Gop->Mode->FrameBufferSize. Verification: compare the frame buffer address and size in the serial output with the values in Gop->Mode.
    • Ignoring the return value of LocateProtocol. Symptom: a NULL pointer is dereferenced. Fix: check both the EFI_STATUS and the pointer. Verification: temporarily use an incorrect GUID, and confirm that the program prints an error message instead of crashing.
    • Mixing GUIDs from different protocols. Symptom: the protocol cannot be found, or the wrong protocol instance is returned. Fix: check each GUID against the header files. Verification: use the same method as the previous item.

    7. Conclusion

    In this test, the LLM used the runtime log to locate the problem, and it proposed a fix that can be verified. This conclusion comes from one test. Firmware implementations may behave differently, so confirm field paths against the header files of the target EDK2 version. The final check is always the log and the run results on the target platform.