Address space support in LLDB has been a long-desired feature. This RFC revives an earlier discussion from @JDevlieghere and @jasonmolenda from 2020.
link: [RFC] Segmented Address Space Support in LLDB
TL;DR
Several targets debugged through LLDB have more than one address space: the same numeric address means different memory depending on which space you name. LLDB today assumes a memory location is a single addr_t (uint64_t), so it cannot represent or read these locations.
This RFC proposes address-space support built around three ideas:
-
The target reports its address spaces dynamically at runtime over gdb-remote (jAddressSpacesInfo). And no object/symbol format has to encode them.
-
A value type, AddressSpec (an address plus an optional address-space name/id), carries “where” through the code that needs it, and an AddressSpec with no space behaves exactly like today’s addr_t, i.e. single-address-space targets and all existing APIs are unaffected.
-
Rollout is incremental : new overloads that fall back to the plain path in the default space and error when a space is requested but unsupported.
A working end-to-end implementation exists downstream (memory reads, CLI, DWARF expression evaluation, variable display, TLS, unwinding, and a GPU plugin); this RFC describes that design and proposes to upstream it in phases, starting with runtime memory reads.
Full implementation is available in @clayborg 's clayborg/llvm-server-plugins branch.
Motivation and use cases
Address spaces are needed by a range of targets:
- GPUs / accelerators (the immediate driver for Meta). A GPU exposes distinct memories (eg: generic, global, local, private (per-lane / per-wave), region etc.) where the same numeric address refers to different storage, and several are thread/wave-specific. AMD’s DWARF address spaces are a concrete example (see User Guide for AMDGPU Backend — LLVM 23.0.0git documentation).
From the original RFC
-
Harvard architectures: separate instruction/data memories reusing addresses, e.g. Motorola DSP56300 p:/x:/y: where p:100, x:100, y:100 are three different locations.
-
Low-level / JTAG debugging : viewing memory as “virtual via TLB”, “virtual == physical via core”, “physical via SoC, uncached”.
-
WebAssembly : no fixed number of address spaces — every module gets its own — and the DWARF does not say which space a location is in; the dynamic loader decides.
-
Embedded targets: that encode address-space info in ELF.
Background: how LLDB represents addresses today
LLDB has three kinds of uint64_t address (as clarified by Greg Clayborg on the other RFC):
-
file address: This is meaningful only to its Module; carried as lldb_private::Address (section + offset) and it resolves to a load address if the section is mapped (needs a Target).
-
load address : This is unique in a process that has no segments; the transient addr_t used for user input and inferior memory read/write.
-
host address: a pointer into LLDB’s own process (expression results).
The load-address assumption is that “it is unique in a process with no segments”, which breaks for the targets above.
Open Questions from 2020 RFC
- Bigger scope of the Refactor: give Address a segment discriminator, introduce ProcessAddress (uint64_t + discriminator) to replace addr_t throughout, do the substitution with a clang tool as one large NFC patch, then add behavior, then SB overloads. Greg and Pavel argued that it is not entirely NFC.
- Where does address-space info come from? No Agreement on this one, options are DWARF, ELF, or dynamically retrieved from the target etc.
Design
Key Design Principles
- Target is the source of truth for the set of live address spaces (
jAddressSpacesInfogdb packet): The running target inherently knows its own memory layout, so it’s the authority. - DWARF supplies static locations spaces via the standard LLVM extension
DW_OP_LLVM_form_aspace_address, so variable reads land in the right space. - Additive and incremental with small blast radius. Existing addr_t/Address APIs untouched i.e. default space behaves as today and unsupported spaces error rather than silently read the wrong memory.
Address space discovery (jAddressSpacesInfo)
The client asks the target which address spaces exist by sending a jAddressSpacesInfo packet, and each one is described by an AddressSpaceInfo:
struct AddressSpaceInfo {
std::string name; // e.g. "generic", "local"
uint64_t value; // numeric id used on the wire / in DWARF
};
send: jAddressSpacesInfo
reply: \[{"name":"global","value":1},{"name":"local","value":2}\]
jAddressSpacesInfo returns the list as JSON; the client caches it on the Process. Empty list implies single default address space (the common case), everything behaves as today. Advertised via qSupported (address-spaces+); if not advertised, the client never sends address-space packets.
value is the numeric address space id used both on the wire and in DWARF.
Specifying an address location (AddressSpec)
This is meant to be generic and expressive for every scenario. It is constructed differently depending on what is known, and an empty space means the default space:
class AddressSpec {
lldb::addr_t m_addr;
std::optional<std::string> m_space_name; // set if addressed by name, or
std::optional<uint64_t> m_space_id; // set if addressed by id, else default
public:
AddressSpec(lldb::addr_t addr) : m_addr(addr) {} // default space
AddressSpec(lldb::addr_t addr, uint64_t space_id) // by id
: m_addr(addr), m_space_id(space_id) {}
AddressSpec(lldb::addr_t addr, llvm::StringRef space_name) // by name
: m_addr(addr), m_space_name(space_name.str()) {}
lldb::addr_t GetValue() const { return m_addr; }
bool IsInDefaultAddressSpace() const {
return !m_space_name && !m_space_id;
}
/// Resolve to the target's AddressSpaceInfo (by id or name), or an error.
llvm::Expected<AddressSpaceInfo> GetAddressSpaceInfo(Process &) const;
};
introducing a new packet for mem read (qMemRead )
send: qMemRead:addr:1000;space:2;length:4;
reply: <hex bytes> # e.g. 11223344
E<xx> # error
(empty) # unsupported
Reading memory
Process gets an AddressSpec overload; the default space falls back to the existing path, and unsupported spaces error:
size_t Process::ReadMemory(const AddressSpec &, void \*buf, size_t, Status &);
// default space -> resolve to plain addr_t -> ReadMemory(addr_t)
// otherwise -> GetAddressSpaceInfo -> DoReadMemory(AddressSpec, info)
virtual size_t Process::DoReadMemory(const AddressSpec &, const AddressSpaceInfo &, void \*buf, size_t, Status &);
// base: "address space memory reading is not supported"; ProcessGDBRemote overrides.
On the wire (ProcessGDBRemote):
qMemRead:addr:<hex>;space:<hex id>;length:<hex>;
Note: we started with reads first.
Expression evaluation and variables (DWARF)
When debug info places a variable in an address space (via the standard LLVM DWARF extension DW_OP_LLVM_form_aspace_address), LLDB reads that variable and its members from the correct space automatically.
Command line
memory read gains a --space <name> option.
Public API
class SBAddressSpec {
SBAddressSpec(lldb::addr_t load_addr); // default
SBAddressSpec(lldb::addr_t addr, const char \*name); // by name
};
SBProcess gets a new API, and existing ReadMemory(addr_t, ...) is not touched
size_t SBProcess::ReadMemoryFromSpec(SBAddressSpec, void \*buf, size_t, SBError &);
Unwinding
RegisterContext / RegisterContextUnwind consult the address space when reading during unwind, so stacks in non-default spaces unwind correctly.
References
- [RFC] Segmented Address Space Support in LLDB (2020)
- Reference implementation: @clayborg already has a full working implementation for AMD GPU case in his private branch
clayborg/llvm-server-plugins; initial upstream PR: [lldb] Add generic address space support by satyajanga · Pull Request #206370 · llvm/llvm-project · GitHub