Debugging Firmware with LLMs: A Two-Phase Path from Unrunnable Code to a Reliable Build
When an LLM inherits firmware that looks complete but will not run, treat the work as two phases: first make it observable and bootable, then harden lifecycle, errors, rendering, and tests. This article walks through code review, crash and blank-screen failures, and engineering practices for collaborating with models on low-level code.
1. The real problem: inheriting a project that looks complete but will not run
Discussions of large language models in firmware often split into two stories: a small game that compiles in hours, or hours of work with nothing that boots. Those anecdotes travel well but are weak technical evidence. Goals, environments, starting code, observability, and acceptance criteria all differ.
A more reusable question is how to take an existing, seemingly structured firmware project that is not yet stable and drive it to a state that is runnable, debuggable, and regressable.
A typical case: the previous generation produced multiple files with a split among entry, main loop, rendering, input, and state. After a move to a new firmware environment, the program fails to start or exits quickly. Do not aim for a one-shot rewrite. Split the work:
- Round one: make it basically run. Unblock boot, protocol discovery, graphics output, input, and the main loop.
- Round two: make it reliable. Add error handling, lifecycle management, resolution handling, performance work, and maintainability.
Firmware has many conditions that never appear in static code. Large refactors in round one mix original faults with new ones and multiply debug cost.
2. Why firmware is harder for models than application code
Shared traits: a weak runtime, many external dependencies, sensitive state, and poor observability.
- No full OS underneath. Memory management, a standard library, exceptions, and logging may be incomplete. Code cannot assume a high-level language runtime.
- Hardware and protocol state are tightly coupled. Handles, mode info, and buffer pointers are valid only in certain states; after a switch, old pointers may be invalid.
- Platforms differ. Protocol IDs, pixel formats, and memory layout for the same feature can change across firmware.
- Feedback is long. Apps have consoles; firmware often has serial logs, the screen, error codes, or LEDs.
- Error paths are easy to skip. Code that compiles may never check failed protocol lookup, mode set, or empty buffers.
Models are good at inferring intent and producing plausible modules. Firmware success depends on call order, error codes, pointer lifetimes, and safe access to registers and buffers. Without logs and clear acceptance criteria, the model only patches text and can loop.
3. Round one: observability first, then the smallest fix
3.1 Review before you let the model edit
On unfamiliar code, review first. Constrain the task to “review only, no edits” and ask for a verifiable issue list. A useful prompt:
Act as a firmware code reviewer. Do not modify code. List issues by severity. For each, give trigger, likely symptoms, code evidence, a minimal fix, and how to verify. Mark unconfirmed items as “to verify.” Do not invent runtime results.
Review dimensions:
- Complete call chain from entry to the main loop
- Return-value checks on protocol locate, mode query, mode set, and framebuffer get
- Whether mode info is reused after a state change
- Hard-coded resolution, stride, or pixel format
- Implicit global state shared across modules
- Blocking, dropped, or repeated input
- Clear logs on error paths
- Build config vs. the target environment
- Uninitialized memory, out-of-bounds writes, dangling pointers, integer overflow
Map each claim to symptoms and logs. Prefer reproducible items, then static confirmation; defer pure speculation.
3.2 Symptom: crash shortly after start
The program may print from the main loop, then exit after a brief init message. Do not rewrite game logic first. Add staged logs:
- Enter entry
- Protocol locate result
- Mode query result
- Mode set result
- Framebuffer get result
- First frame drawn
- Main-loop iteration count
Log stage name, status, and key parameters. Faults often sit after graphics protocol acquire and before the first draw. A common bug: query mode info, keep the pointer, set mode, then keep using the old pointer. Some implementations bind mode info to current mode; after the switch the pointer is invalid.
The lesson is not “this function always invalidates pointers,” but: pointers and handles must not be assumed valid across protocol state changes. Re-acquire the protocol and mode info, then validate width, height, stride, pixel format, and framebuffer address.
/* Pseudocode: lifetime rules, not a specific platform API */gfx = locate_protocol(GFX_PROTOCOL_ID);if (!gfx) {log_error("gfx protocol missing");return ERR_NO_GFX;}mode_info = query_mode(gfx, desired_mode);if (!mode_info) {log_error("query mode failed");return ERR_QUERY_MODE;}status = set_mode(gfx, desired_mode);if (is_error(status)) {log_error("set mode failed: %d", status);return ERR_SET_MODE;}/* Wrong: keep using mode_info from before set_mode *//* Right: re-acquire and validate after the state change */gfx = locate_protocol(GFX_PROTOCOL_ID);if (!gfx) {log_error("gfx protocol missing after set_mode");return ERR_NO_GFX;}mode_info = query_mode(gfx, desired_mode);if (!mode_info || !mode_info->frame_buffer) {log_error("invalid framebuffer info");return ERR_INVALID_FB;}if (mode_info->stride < mode_info->width) {log_error("invalid stride: %d, width: %d",mode_info->stride, mode_info->width);return ERR_INVALID_STRIDE;}draw_first_frame(mode_info);
The point is three rules: check return values, re-acquire after state change, validate bounds before use.
3.3 Symptom: it runs but the screen stays blank
The loop runs, but nothing appears. Causes include a wrong protocol GUID, the wrong instance after a successful query, an invalid framebuffer address, or a pixel-format mismatch.
Generated code often copies protocol IDs from another platform. Several similar protocols may exist; a mismatched ID yields “not found” or the wrong instance. It still compiles; the bug is runtime-only.
- Log the full status on locate failure, not only “init failed”
- Keep protocol IDs in one config header or HAL; avoid magic numbers
- Align headers with the target build
- Explicitly check resolution, stride, and pixel format
- Fill a solid color or draw a rectangle before game logic
Do not silence graphics failures into a black screen:
status = init_graphics(&gfx, &mode_info);if (is_error(status)) {log_error("graphics init failed, stage=%d", status);return status;}if (!is_supported_pixel_format(mode_info)) {log_error("unsupported pixel format: %d", mode_info->pixel_format);return ERR_PIXEL_FORMAT;}clear_screen(mode_info, COLOR_BLACK);draw_test_rect(mode_info, 10, 10, 100, 60, COLOR_WHITE);
3.4 Round-one acceptance
Do not require full features. Require:
- Boot on the target firmware
- Protocol discovery and mode set
- Clear screen and basic drawing
- At least one input path that updates state
- Run for a while without crash
- Stable logs and error codes at each critical stage
- Shutdown and error paths that do not leave bad resource state
Only then start round two. Early work on animation and “feel” buries base faults.
4. Round two: from “it runs” to “it is reliable”
4.1 Lifecycle
Many faults are lifetime bugs, not algorithm bugs. Define:
- When protocol handles are acquired and re-acquired
- Whether mode info may be cached across switches
- Who owns the framebuffer and whether modules may keep it
- Whether drawing needs double buffering
- Whether exit or re-init must restore display mode
Hold external resources briefly; do not bury critical pointers in deep modules. A HAL can wrap protocol calls so game logic uses a drawing API instead of the framebuffer.
4.2 Errors and logs
Logs are scarce. Check every external call and map failures to stable error codes. Include:
- Stage name
- Return status
- Parameters such as resolution, stride, pixel format
- Recoverable vs. fatal
Avoid per-frame spam and identical messages for every error. Debuggers need where, why, and what to try next.
4.3 Rendering, input, performance
Rendering:
- Compute addresses from current mode width and stride
- Do not assume a fixed bytes-per-pixel
- Clip before draw to avoid out-of-bounds writes
- Avoid per-frame allocation
- If there is no double buffer, use dirty rects to reduce flicker
Input: an explicit state machine for press, hold, and release; debounce or rate-limit repeats. The game loop can use a fixed timestep or a capped delta so a slow frame does not jump state.
4.4 Maintainability and regression
Three layers:
- HAL: protocol locate, display mode, input, logging
- Game logic: state, collision, scoring, draw commands
- Host tests: null graphics and simulated input, no real firmware
Most logic can regress on a host; firmware only validates the HAL and the final look. After each change: build, boot logs, minimal graphics, input smoke, and critical-path regression beat “run it again by feel.”
5. How to work with the model
Value in firmware: understanding unfamiliar code, hypothesizing faults, emitting small patches. It does not replace runtime proof.
- One hypothesis per change. Keep diffs small; compare logs before and after.
- Demand an evidence chain. Code, expected symptoms, and verification—not conclusions alone.
- Fix reproducible bugs first. Be cautious of speculative refactors.
- Humans own acceptance. Compile is not run; one run is not boundary-safe. Verify on hardware and regress.
- Keep rollback points. Clear diffs so new faults are locatable.
- Engineer the prompt. Environment, logs, acceptance, forbidden changes, and editable scope beat “please fix this.”
6. Conclusion
The reusable story is not “an LLM wrote a game in hours.” It is a process: review, add observability, apply minimal patches for boot and protocol lifetime; get it running, then harden errors, input, rendering, and structure.
Constraints remain: protocols have state, pointers and buffers have lifetimes, platforms differ, errors must be visible. Treat the model as a fast, high-memory collaborator with no runtime sense, and constrain it with logs, tests, and human acceptance so generated firmware becomes runnable, maintainable, and shippable.
