feat(embed): add baremetal defer support

[luoliwoshang]

Summary

Add defer support for baremetal/embedded environments (ESP32, ARM7TDMI, etc.).

Key Changes:

• Add baremetal-specific defer implementation using global variables (single-threaded)
• Use setjmp/longjmp for baremetal targets instead of sigsetjmp/siglongjmp
• Add returns_twice attribute to setjmp/sigsetjmp for correct LLVM optimization
• Refactor target detection: use -target flag directly instead of Baremetal boolean
• Define platform-specific jmp_buf sizes for all embedded architectures (ESP32, ESP32-C3, ARM7TDMI, etc.)
• Comprehensive defer testing (DeferAlways, DeferInCond, DeferInLoop)
• Fix map closure and interface closure handling

Architecture

Target Detection Refactoring

Replaced boolean-based target detection with direct -target flag storage:

// Before (main branch)
type Target struct {
    GOOS   string
    GOARCH string
    GOARM  string
}

// After (this PR)
type Target struct {
    GOOS   string
    GOARCH string
    GOARM  string
    Target string  // "esp32", "arm7tdmi", "wasi", etc.
}

Logic in Sigsetjmp/Siglongjmp:

• Target != "" or GOARCH == "wasm" → use setjmp/longjmp
• Otherwise → use sigsetjmp/siglongjmp (platform-specific via build-tags)

Baremetal Defer Implementation

File Structure:

• defer_tls_baremetal.go: Uses global variable for single-threaded baremetal
• z_defer_baremetal.go: No-op FreeDeferNode (let GC collect), use longjmp in Rethrow
• Build tags: //go:build baremetal to separate from pthread-based implementation

JMP_BUF Size Definitions

Added platform-specific jmp_buf sizes for all embedded targets:

Architecture	Size (bytes)	File
ESP32 (Xtensa)	68	jmpbuf_xtensa_baremetal.go
ESP32-C3 (RISC-V32)	52	jmpbuf_riscv32_baremetal.go
RISC-V64	52	jmpbuf_riscv64_baremetal.go
ARM7TDMI	40	jmpbuf_arm_baremetal.go
Cortex-M	40	jmpbuf_cortexm_baremetal.go
AVR	24	jmpbuf_avr_baremetal.go
macOS/Linux	196/200	jmpbuf_other.go

Returns Twice Attribute

Added LLVM returns_twice attribute to setjmp and sigsetjmp function calls:

• Prevents LLVM from placing variables in caller-saved registers across setjmp/longjmp
• Required for correct defer handling (DeferFrame pointer must remain valid)
• Follows LLVM best practices and Clang implementation

Verification on ESP32

❯ llgo run -target esp32 .
Generating firmware image: defer.elf -> defer.bin (format: esp32)
esptool v5.1.0
Connected to ESP32 on /dev/cu.usbserial-110:
Chip type:          ESP32-D0WD-V3 (revision v3.1)
Features:           Wi-Fi, BT, Dual Core + LP Core, 240MHz

Wrote 49504 bytes (30423 compressed) at 0x00001000 in 3.3 seconds (120.7 kbit/s)
Hash of data verified.

Hard resetting via RTS pin...
Connected to /dev/cu.usbserial-110. Press Ctrl-C to exit.

defer in loop 2
defer in loop 1
defer in loop 0
defer in if
defer 2
defer 1

All three defer modes work correctly:

• DeferAlways: defer 1, defer 2 (LIFO order ✅)
• DeferInCond: defer in if (conditional defer ✅)
• DeferInLoop: defer in loop 2/1/0 (LIFO order per iteration ✅)

Related PRs

• ssa: fix jmp_buf size for cross-compilation #1487 - Fix jmp_buf size for cross-compilation (use rtType("SigjmpBuf") instead of cgo)
• fix(ssa): add returns_twice attribute to sigsetjmp #1499 - Add returns_twice attribute to sigsetjmp for OS platforms

Test plan

• Test basic defer on ESP32 (DeferAlways)
• Test conditional defer (DeferInCond)
• Test defer in loops (DeferInLoop)
• Verify LIFO execution order
• Add CI tests for embedded target compilation
• Verify jmp_buf sizes for all architectures
• Test map closure and interface closure fixes

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello @luoliwoshang, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request lays the groundwork for adding basic defer statement support to baremetal and embedded environments, such as ESP32. It adapts the runtime's defer mechanism to function without traditional thread-local storage by introducing a global variable for defer chain management and integrating with tinygogc for automatic cleanup of defer nodes. This is an initial work-in-progress, currently focusing on core defer functionality without support for panic/recover.

Highlights

• Baremetal Defer TLS Implementation: Introduced defer_tls_baremetal.go which utilizes a global variable (globalDeferHead) to manage the defer chain in single-threaded baremetal environments, serving as an alternative to pthread TLS.
• Baremetal Defer Node Cleanup: Added z_defer_baremetal.go containing a no-op FreeDeferNode function, indicating that defer nodes are expected to be garbage collected by tinygogc once they become unreachable in baremetal contexts.
• Refined Build Tags: Updated build tags across several files to ensure proper separation of baremetal-specific implementations from standard and nogc builds, guaranteeing the correct code is compiled for each target environment.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces basic defer support for baremetal environments by providing alternative implementations for thread-local storage and defer node memory management, controlled by build tags. For single-threaded baremetal targets, it replaces pthread-based TLS with a simple global variable. For memory management, it adds a no-op FreeDeferNode for baremetal builds with tinygogc, letting the GC handle cleanup.

My review identified a critical issue in the build constraints for z_defer_nogc.go. The current change would lead to a build failure for the nogc && baremetal configuration because no implementation of FreeDeferNode would be compiled. I have provided a suggestion to correct the build tag to cover all nogc scenarios as intended. The rest of the changes appear correct and well-structured for the intended purpose.

[gemini-code-assist]

The build constraint nogc && !baremetal leaves the nogc && baremetal build combination without an implementation for FreeDeferNode, which will likely result in a linker error. The nogc build tag should apply to both baremetal and non-baremetal environments, as both require manual memory management when no garbage collector is present. Changing the constraint to just nogc will resolve this by ensuring this c.Free-based implementation is used for all nogc builds.

Suggested change

	//go:build nogc && !baremetal
	//go:build nogc

[xgopilot]

Critical: Missing build tag coverage for baremetal && nogc

The current build tag matrix has a gap:

• !nogc && !baremetal → z_defer_gc.go
• nogc && !baremetal → z_defer_nogc.go
• baremetal && !nogc → z_defer_baremetal.go ✓
• baremetal && nogc → NO FILE ❌

When building with both baremetal and nogc tags (valid for embedded systems without GC), FreeDeferNode will be undefined, causing compilation failure.

Recommendation: Change the build tag to //go:build baremetal (remove && !nogc) to cover both baremetal scenarios. The no-op approach is appropriate for all baremetal cases since manual memory management is expected in these environments.

[xgopilot]

High: Race condition risk in ISR context

The global variable globalDeferHead is not protected against concurrent access. While documented as "single-threaded," baremetal systems commonly use Interrupt Service Routines (ISRs) that can preempt execution.

If an ISR calls Go code using defer, this can cause:

• Defer chain corruption (linked list broken)
• Lost defer statements
• Use-after-free bugs

Evidence from codebase:

• _demo/embed/export/main.go:10 mentions "hardware interrupt handlers"
• ISR functions call Go code (c.Printf)

Recommendations:

1. Disable interrupts during defer chain operations, or
2. Document that defer MUST NOT be used in ISR context, or
3. Use separate defer chains for ISR vs normal execution

Reference: CWE-362 (Improper Synchronization)

[xgopilot]

Performance: Memory leak risk in defer-heavy loops

The no-op FreeDeferNode causes memory accumulation until GC runs. In constrained baremetal environments (ESP32 has ~520KB RAM):

Impact analysis:

• Each defer iteration allocates ~64-96 bytes
• 1000 iterations = ~96KB held until GC
• GC uses stop-the-world mark-and-sweep with linear heap scanning
• Allocation performance degrades as heap fills

Comparison: Other build configurations (z_defer_gc.go, z_defer_nogc.go) explicitly free defer nodes immediately.

Recommendation: Consider implementing a simple defer node pool/freelist to:

• Eliminate GC pressure from defer nodes
• Provide O(1) allocation/deallocation
• Match performance of other builds

Reference: CWE-400 (Uncontrolled Resource Consumption)

[xgopilot]

Documentation: Add thread-safety warning

Consider making the concurrency constraints more explicit:

Suggested change

	// globalDeferHead stores the current defer chain head.
	// In baremetal single-threaded environment, a global variable
	// replaces pthread TLS.
	// globalDeferHead stores the current defer chain head.
	// In baremetal single-threaded environment, a global variable
	// replaces pthread TLS.
	//
	// WARNING: This implementation is NOT thread-safe and NOT ISR-safe.
	// Only use in single-threaded baremetal environments. Do NOT call
	// any Go code using defer from interrupt service routines (ISRs).

This makes the safety constraints clearer for future maintainers.

[xgopilot]

Code Review Summary

This PR adds clean baremetal defer support with good separation of concerns. However, there are critical issues that must be addressed:

Critical:

• Missing baremetal && nogc build tag coverage - will cause compilation failure
• Race condition risk with ISRs accessing global globalDeferHead

High Priority:

• Memory leak potential in defer-heavy loops (no-op FreeDeferNode accumulates until GC)
• Missing thread-safety documentation

Positive aspects:

• Clean API consistency across implementations
• Appropriate use of global variable for single-threaded performance (5-10x faster than TLS)
• Good build tag separation

Please address the critical build tag gap and ISR safety issues before merging.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.93%. Comparing base (3e5807d) to head (1658295).

Files with missing lines	Patch %	Lines
ssa/eh.go	0.00%	0 Missing and 2 partials ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1464   +/-   ##
=======================================
  Coverage   90.93%   90.93%           
=======================================
  Files          44       44           
  Lines       11528    11528           
=======================================
  Hits        10483    10483           
  Misses        883      883           
  Partials      162      162           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[luoliwoshang]

target defer build fail cause by libc's log
logs_52070496149.zip