proposal: runtime: support general dynamic thread local storage model

[amusman]

Proposal Details

Proposal: Support General Dynamic TLS Model

Summary

This proposal aims to add support for the general dynamic (GD) Thread Local Storage (TLS) model to the Go runtime, to resolve issue 54805. The current implementation only supports the initial exec (IE) and local exec (LE) TLS models, which restricts interoperability with certain C libraries (particularly Musl) and prevents loading Go shared libraries without LD_PRELOAD.

A more detailed design document is available at: Proposal: Go general dynamic TLS

There is a prototype implementation for Arm64 Linux in review 644975.

Problem

The Go runtime uses Thread Local Storage to preserve goroutine state (g) when interacting with C code, but lacks support for the general dynamic TLS model. This limitation:

1. Hinders interoperability with C libraries that have strict TLS allocation schemes (e.g., Musl)
2. Restricts loading of Go shared libraries without using LD_PRELOAD

Proposed Changes

Assembler and Linker Changes

• Add a new flag -tls=[IE,LE,GD] to the assembler to explicitly select the TLS model
• Default to -tls=IE for shared mode, while cmd/go specifies -tls=GD explicitly when needed
• Add target-specific relocations in the linker depending on target architecture

Runtime Changes

• Update references to thread-local variables in runtime assembly code

Command Changes

• Modify cmd/go to automatically enable the general dynamic TLS model when required, based on the combination of GOOS/GOARCH and buildmode
• Pass -D=TLS_GD and -tls=GD option to assembler to enable the GD model

Initial Implementation Focus

• Arm64 architecture on Linux systems
• buildmode=c-shared and buildmode=c-archive

Please refer to the full design document for more detailed information on the implementation approach and technical considerations.

[ianlancetaylor]

CC @cherrymui @golang/compiler

[gabyhelp]

Related Issues

• proposal: cmd/link: add support for TLS variables to the toolchain #11270 (closed)

Related Code Changes

• cmd/asm,cmd/link,cmd/go: Add dynamic TLS model for ARM64
• runtime: always set up TLS storage for darwin/arm64

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[gopherbot]

Change https://go.dev/cl/644615 mentions this issue: design: add 71953-go-dynamic-tls.md

[tudor-timcu]

Hello! Is there a plan to support this for x86_64? I hit this problem recently on Alpine Linux and was wondering if there's a fix in sight in the near future? Thank you!

[amusman]

Hello,
While there isn't a concrete timeline for x86_64 support yet, the proposed design will accommodate it. Specifically, we can pass the same -D=TLS_GD flag and -tls=GD option on x86_64, and then implement the architecture-specific parts under these conditional flags. The initial implementation focuses on Arm64 and allows to extend support to new architectures incrementally.