Building UEFI Graphical Applications with AI Coding Assistants: Pitfalls and Best Practices

    This article presents a practical case study in which an AI coding assistant was used to build a graphical Snake game for the UEFI Shell. It explains UEFI-specific constraints, key implementation techniques, common pitfalls, and recommended countermeasures. The discussion also covers prompt-based iteration, observability, memory safety, localization, and how to define clear boundaries for AI-assisted firmware development.

    1. Background: Why Build a Graphical Game Inside UEFI?

    On general-purpose operating systems, writing a small game is a relatively smooth experience. Mature toolchains provide graphics libraries, font rendering, window management, and debuggers. After compiling, the program can usually be launched immediately. If something goes wrong, logs and breakpoints help developers diagnose the issue.

    The UEFI environment is different. Many of these conveniences disappear:

    • A UEFI application has no operating system underneath it; all services must be obtained through protocols provided by the firmware.
    • There is no ready-made graphics library, text box, or font-rendering service.
    • Conventional debugging tools are limited, and console output is minimal.
    • Runtime failures often appear as a black screen or a reboot, making diagnosis expensive.

    For this reason, asking an AI coding assistant to develop a firmware application is both a test of its performance in an unfamiliar technology stack and a way to reveal its practical limits.

    The goal of this project was to implement a fully playable Snake game in the UEFI Shell environment and verify it through a firmware emulation environment. The main technical characteristics were:

    • Pure firmware execution: The program runs directly in the firmware environment and does not require booting an operating system.
    • Graphical UI and Chinese text: Menus, scores, and prompts were displayed in Chinese without relying on operating-system font services.
    • Hardware framebuffer output: The program directly manipulated the graphics framebuffer through the UEFI Graphics Output Protocol, avoiding the burden of software-only pixel drawing.
    • Double buffering: Rendering was completed in a back buffer and then submitted as a whole, reducing visible tearing.
    • Progressive gameplay: Once the score reached a threshold, the game advanced to the next stage, increased in speed, and introduced obstacles.
    • Visual feedback: Particle effects appeared when food was collected.
    • Two input schemes and pause support: Both arrow keys and WASD could control the snake, and the game could be paused and resumed at any time.

    Development proceeded in three rounds: a basic version, an enhanced version, and a localized Chinese version. In total, 27 prompts were used, and the process took about three hours.

    From an efficiency perspective, the AI coding assistant was able to produce a runnable skeleton quickly in this nontraditional domain. However, the process was not smooth. Several difficult issues are the main focus of this article.

    2. Implementation Essentials: Technical Context for an AI Coding Assistant

    To help an AI coding assistant develop firmware applications correctly, developers first need to understand the fundamental differences between UEFI applications and traditional programs.

    1. Application Entry Point and Calling Conventions

    A UEFI application starts from a function with a fixed signature. The system table is passed in as a parameter, and subsequent services are obtained from it. The entry-point signature and library-dependency naming are fixed conventions in common UEFI development frameworks. They are not expanded in detail here to avoid encouraging incorrect implementations.

    Common mistakes include using the wrong return-value type or ignoring protocol status codes. The correct practice is to check the status code after every interface call before using the returned data.

    1. #include <Uefi.h>
    2. #include <Protocol/GraphicsOutput.h>
    3. #include <Protocol/SimplePointer.h>
    4. EFI_STATUS EFIAPI UefiMain(
    5. IN EFI_HANDLE ImageHandle,
    6. IN EFI_SYSTEM_TABLE *SystemTable
    7. )
    8. {
    9. EFI_STATUS Status;
    10. EFI_GRAPHICS_OUTPUT_PROTOCOL *Gop = NULL;
    11. EFI_SIMPLE_POINTER_PROTOCOL *Pointer = NULL;
    12. EFI_GRAPHICS_OUTPUT_MODE_INFORMATION *Mode = NULL;
    13. UINTN Size = 0;
    14. SystemTable->ConOut->ClearScreen(SystemTable->ConOut);
    15. /* Locate the Graphics Output Protocol. If it is unavailable, show a readable message instead of dereferencing a null pointer. */
    16. Status = gBS->LocateProtocol(&gEfiGraphicsOutputProtocolGuid, NULL, (VOID **)&Gop);
    17. if (EFI_ERROR(Status)) {
    18. SystemTable->ConOut->OutputString(
    19. SystemTable->ConOut,
    20. L"The current firmware does not provide the Graphics Output Protocol. Please run this application on firmware that supports it.\r\n");
    21. return Status;
    22. }
    23. /* Select a graphics mode and verify that the resolution meets the minimum requirement. */
    24. Status = Gop->SetMode(Gop, 0);
    25. if (!EFI_ERROR(Status)) {
    26. Mode = Gop->QueryMode(Gop, Gop->Mode->Mode, &Size);
    27. if (Mode != NULL && Mode->HorizontalResolution >= 1024
    28. && Mode->VerticalResolution >= 768) {
    29. /* Resolution requirements are met. */
    30. }
    31. FreePool(Mode);
    32. }
    33. /* Initialize resources, enter the main loop, release resources, and return here. */
    34. return EFI_SUCCESS;
    35. }

    2. Acquiring Graphics Output and Handling Pixel Formats

    The application needs to locate the Graphics Output Protocol, determine which modes the platform supports, select a suitable resolution, and calculate the address of each pixel using the framebuffer stride.

    Firmware may support multiple pixel formats, including linear RGB, BGR, and other layouts. Color components must be split according to the actual format. Otherwise, the screen may display incorrect colors, such as red and blue being swapped.

    It is also important to remember that setting a graphics mode clears the screen. All drawing code must execute after the mode has been set.

    3. Double Buffering

    A frame buffer with the same dimensions as the screen should be allocated. Each frame is first drawn into the back buffer and then submitted to the screen with one memory copy. This avoids showing a partially rendered frame while lines are being updated.

    The buffer size must be calculated using the stride and height. It should not be estimated only as width multiplied by height multiplied by bytes per pixel. Otherwise, line-offset errors can occur at wide-screen resolutions.

    1. static VOID DrawFrame(EFI_GRAPHICS_OUTPUT_PROTOCOL *Gop, UINTN W, UINTN H)
    2. {
    3. /* Pix is assumed to be a pixel buffer with the same dimensions as the screen.
    4. Color components are packed according to the firmware pixel format. */
    5. UINTN LineBytes = H > 0 ? (W * sizeof(UINT32)) : 0; /* Example: real code must align to the actual stride. */
    6. UINTN Size = LineBytes * H;
    7. if (Pix == NULL) {
    8. Pix = AllocatePool(Size);
    9. if (Pix == NULL) {
    10. return; /* If memory or video memory is insufficient, skip this frame to avoid out-of-bounds writes. */
    11. }
    12. }
    13. DrawBackground(Pix, W, H);
    14. DrawSnake(Pix, W, H);
    15. DrawFood(Pix, W, H);
    16. Gop->Blt(Gop, (EFI_GRAPHICS_OUTPUT_BLT_PIXEL *)Pix,
    17. EfiBltBufferToVideo, 0, 0, 0, 0, W, H, 0);
    18. }

    4. Keyboard and Mouse Input

    UEFI provides an event-based polling mechanism for keyboard input. Common input-related issues include:

    • Arrow keys are extended keys and may be returned in two parts: an empty character and a scan code.
    • Character case may be affected by Caps Lock and Shift, so input should be normalized consistently.
    • Menu navigation usually also needs to handle Enter and Backspace.

    Mouse control is optional. UEFI usually provides a separate pointer-device protocol. In menu-driven scenarios, it can serve as an alternative to keyboard input and may provide a better experience on touch-oriented devices.

    5. Chinese Text Display

    The Graphics Output Protocol only writes pixels to the screen. It does not recognize characters. Therefore, Chinese text must be rendered using glyph data included in the application.

    A common approach is to maintain a bitmap font table. For example, each Chinese character may use a 16×16 bitmap and occupy 32 bytes. The glyph data can be placed in a read-only data section of the program.

    Text can be stored as wide characters. Each character maps to an offset in the font table, and the drawing routine reads the bitmap row by row. An example is shown below:

    1. /* Font table: each glyph is 16x16 bits and occupies 16 * 16 / 8 = 32 bytes. */
    2. STATIC CONST UINT8 mFont16[GLYPH_COUNT][32] = { /* Generated in batches by a font-table generation script. */ };
    3. /* Draw one 16x16 glyph into the pixel buffer. */
    4. STATIC VOID DrawGlyph(EFI_GRAPHICS_OUTPUT_BLT_PIXEL *Pix, UINTN Stride,
    5. UINTN X0, UINTN Y0, CHAR16 Ch, UINT32 Fg, UINT32 Bg)
    6. {
    7. UINTN Index = GlyphIndex(Ch); /* Calculate the font-table index from the character code (illustrative). */
    8. if (Index >= GLYPH_COUNT) {
    9. Index = GlyphIndex(L'?');
    10. }
    11. for (UINTN Row = 0; Row < 16; Row++) {
    12. UINT8 Bits = mFont16[Index][Row];
    13. for (UINTN Col = 0; Col < 16; Col++) {
    14. Pix[(Y0 + Row) * Stride + (X0 + Col)] =
    15. (Bits & (1 << (7 - Col))) ? (EFI_GRAPHICS_OUTPUT_BLT_PIXEL){Fg & 0xFF, (Fg >> 8) & 0xFF, (Fg >> 16) & 0xFF, 0}
    16. : (EFI_GRAPHICS_OUTPUT_BLT_PIXEL){Bg & 0xFF, (Bg >> 8) & 0xFF, (Bg >> 16) & 0xFF, 0};
    17. }
    18. }
    19. }

    3. Pitfalls Encountered: Five Common Traps and How to Handle Them

    During this project, some issues were detected and fixed by the AI coding assistant itself. Examples included missing return-value checks, local logic errors, and reversed color formats.

    Other issues exceeded its ability to self-diagnose and required human intervention.

    Pitfall 1: Operating Outside the Working Directory

    Symptom

    The project directory had already been specified. However, the program created a firmware-development framework repository in a parent directory. During compilation, additional directories for toolchains, build artifacts, and intermediate configuration files appeared outside the expected location. The project root directory was not as clean as expected.

    Cause

    Two types of behavior can cross the intended boundary:

    • The AI coding assistant may decide that obtaining a firmware development framework and configuring the build environment requires a unified parent directory. It may therefore create files one level above the intended project directory. Similar behavior has also been observed when testing other AI coding assistants.
    • In auto-approval or permission-bypass modes, shell commands may execute with little or no confirmation. These commands may include changing the working directory to a parent directory.

    Countermeasures

    • Explicitly state in the prompt: “All file and directory creation, modification, and deletion must use the current working directory as the only boundary.”
    • Specify clear subdirectory paths for firmware frameworks, build artifacts, and other components.
    • Avoid enabling unrestricted permission-bypass modes unless necessary.
    • After each change, review the list of modified files and the shell-command history. If out-of-bounds operations are found, roll them back immediately and record the rule in a project-level convention file that the AI coding assistant reads at the start of every session.
    • From compliance and auditability perspectives, such operations should also be included in unified change management. Cloud-based code hosting and log-retention capabilities may be used when needed to record the process.

    Prompt template example

    1. Hard constraints:
    2. 1. Only create, modify, or delete files within the current working directory.
    3. 2. Put the firmware framework in .vendor/framework and build artifacts in build/.
    4. 3. Do not modify any path outside the current working directory.
    5. 4. After each change, output a list of modified files for manual review.

    Pitfall 2: The Emulation Environment Appears to Run but Actually Does Not

    Symptom

    The AI coding assistant downloaded precompiled virtualization components and a firmware image, saving the time that would otherwise be spent building them from source. However, the image was not registered in the boot entries, and the bootable media did not contain the newly compiled application. As a result, the virtual machine started directly into the firmware setup interface, and the game never ran.

    Cause

    The AI coding assistant knows that a firmware image combined with a virtualization platform can usually form an emulation environment. However, it does not always understand the default configuration differences among different firmware distributions.

    The default boot entry, default boot media, and default device order in a precompiled image may not match expectations. In a normal development environment, the assistant can often correct such issues by reading compiler errors and runtime logs. At the firmware level, if a boot entry is missing, the assistant may not be able to perceive the problem.

    Countermeasures

    • Specify the runtime environment in the prompt, including firmware architecture, whether the Shell is built in, whether the Shell enters automatically, and how the boot media is mounted.
    • Require the application setup process to configure the boot flow itself:
      • Create a boot option and set it as the next boot option.
      • Place the Shell in the default directory on bootable media.
      • Prepare a startup script that runs the application automatically. For example:
    1. # Auto-load and run the Snake game at boot (example path)
    2. fs0:\snake.efi
    • Require the program to record an expected log, including whether the Chinese title appears, whether the game starts, and whether key input produces a response.
    • Define failure behavior explicitly. If startup fails, the program should output diagnostic information, such as “No Shell found” or “Application failed to load, status code: XXXX”, rather than exiting silently.

    Pitfall 3: Weak Debug Signals and “Blind” Debugging

    Symptom

    When graphical issues occurred, no error message was visible. The AI coding assistant could not obtain runtime information and could only guess the cause based on the source code, then modify the code repeatedly.

    Cause

    The firmware environment lacks conventional debugging channels. The Graphics Output Protocol only outputs pixels and does not provide a logging mechanism.

    Countermeasures

    • Add observable points at key stages, including protocol-location results, mode-setting results, buffer-allocation results, frame rate, and input events. These logs should be written to logs and also displayed on the screen or through a serial debug port.
    • Use a strategy of “render a self-check screen first, then enter the game.” The self-check screen should display firmware version, resolution, pixel format, and memory status. This makes it easier to determine whether the issue lies in the graphics pipeline or in the game logic.
    • Require the program to keep a debug line visible in a corner of the screen, for example the current frame rate, coordinates, and status codes. This turns black-screen problems into readable problems.
    1. /* Minimal observable point: status code and key parameters */
    2. STATIC VOID Log(EFI_SYSTEM_TABLE *ST, CONST CHAR16 *Tag, EFI_STATUS S)
    3. {
    4. ST->ConOut->OutputString(ST->ConOut, Tag);
    5. ST->ConOut->OutputString(ST->ConOut, L" = 0x");
    6. ST->ConOut->OutputString(ST->ConOut, L"FFFFFFFF\r\n"); /* Example: output after formatting the status code */
    7. }

    Pitfall 4: Memory and Boundary Issues Are Not Handled Proactively

    Symptom

    After particle effects were added, screen corruption or abnormal behavior appeared at some resolutions. Investigation showed that particle-pool capacity, bounds checking, and memory-release logic had to be explicitly requested by a human before they were handled.

    Cause

    In general-purpose scenarios, AI coding assistants often rely on runtime facilities or high-level language mechanisms to manage resources. Firmware development usually uses C, manual memory allocation, and explicit lifecycle management.

    Countermeasures

    • Define memory constraints in the prompt. For example: avoid unnecessary dynamic allocation, allocate buffers once at startup where possible, and prohibit out-of-bounds access.
    • Use fixed-capacity object pools. For example, limit the maximum number of particles and reuse the oldest object when the limit is reached.
    • At the end of each frame, check coordinates, array indexes, and string lengths for possible out-of-bounds access.
    • When resource acquisition fails, use a degraded path instead of crashing. For example, if a back buffer cannot be allocated, switch to single buffering or disable particle effects.

    Pitfall 5: Localization and Encoding Traps

    Symptom

    During Chinese localization, issues appeared such as menus displaying squares, Chinese text being misaligned in the coordinate area, and wide characters being mixed with byte counts.

    Cause

    The Graphics Output Protocol does not recognize any characters. Chinese glyphs must depend on an internal bitmap font library or a custom text-rendering implementation.

    In addition, several points are easy to confuse:

    • The string length of wide characters is different from its byte count.
    • Font-table indexes must correspond exactly to the glyph table.
    • When bitmap fonts and ASCII characters are mixed, width calculation can easily produce layout errors.

    Countermeasures

    • Define the glyph strategy first. For example, use a built-in 16×16 bitmap font table, or reuse the firmware’s simple text-output service for menus and status bars while using custom drawing only in the game area.
    • State clearly in the prompt: “Chinese glyphs must be bundled with the application and must not depend on system fonts.”
    • Build a mapping table from characters to glyph data and provide a self-check item. For example, print a test string containing the required Chinese characters followed by ABC123 to verify that glyphs are complete.
    • Encapsulate text drawing into a fixed-width layout to avoid misalignment when different character types are mixed.

    4. Iteration Strategy: Three Rounds and 27 Prompts

    Development was divided into three rounds. Each round focused on one type of goal, avoiding the rework that often happens when too many requirements are submitted at once.

    • Round 1: Basic version.
      The goal was to make the core loop work: load the application, initialize graphics, draw the snake and food, handle keyboard input, and display the score. The objective was to create a minimal closed loop that could run and be observed.

    • Round 2: Enhanced version.
      This round added double buffering, level progression, obstacles, particle effects, and pause support. It also improved frame-rate handling and input processing. The focus was performance and user experience.

    • Round 3: Chinese localization version.
      This round replaced menus, scores, and prompts, improved glyph rendering and layout, and added error messages. The goal was to make the interface usable and readable.

    The average information content of each prompt was not high, but each prompt had a clear acceptance criterion. In this type of development task, prompt quality matters more than prompt quantity.

    Each prompt should include four elements:

    • Constraint: Directory and dependency boundaries.
    • Goal: What should be delivered in this round.
    • Observable point: How to prove that the result works.
    • Failure fallback: What to do first if something goes wrong.

    5. Capability Boundaries: What AI Coding Assistants Are Good at and What They Are Not

    Dimension Strengths of an AI coding assistant Points that require human involvement
    Code generation Familiar with C and protocol-call patterns; can quickly produce a usable skeleton Protocol version differences and calling-convention details need manual verification
    Environment setup Can suggest common solutions and commands Cannot self-detect when default configuration assumptions are wrong
    Permission boundaries Can follow explicit constraints May cross boundaries when constraints are missing
    Debugging Can read logs and modify code Prone to blind changes when observability signals are insufficient
    Localization Can automate copywriting, layout, and glyph indexing Missing glyphs and mixed-layout errors require manual acceptance
    Architecture trade-offs Can implement a given solution Solution selection, performance strategy, and compatibility strategy require human judgment

    6. Practical Recommendations: Use AI Where Results Can Be Verified

    Based on this experience, three reusable lessons can be drawn:

    1. Set rules before making requests.
      A project-level convention file should clearly define directory boundaries, dependency sources, build-artifact locations, code style, and verification methods. The AI coding assistant should read the same rules at the start of every session.

    2. Deliver in small steps and verify incrementally.
      Each round should solve only one type of problem. After delivery, manually check three things: whether the change list stayed within bounds, whether the runtime logs are readable, and whether the functionality matches expectations.

    3. Manage the environment as code.
      Firmware images, virtualization-platform versions, and boot configurations should be placed under version control to create a reproducible runtime environment. This avoids the familiar “it works on my machine” problem.

    An AI coding assistant can significantly shorten the prototyping cycle for firmware applications. However, it will not decide which directory level a project should be created in, nor will it automatically notice that an emulation environment cannot start properly.

    Only by defining constraints clearly, making observability solid, and setting verification into small steps can the efficiency gains of AI-assisted development be fully realized.