From e907fc9e01ce8fe1e557a3889956e959ef3796f0 Mon Sep 17 00:00:00 2001 From: agra Date: Wed, 3 Jun 2026 14:28:28 +0300 Subject: [PATCH] docs(debugger): describe Frame global build as LLVMConstNamedStruct over getFrameStructType (A9.2) The compiled backend builds each trace Frame global as an LLVM named-struct constant over the cached getFrameStructType() layout (file, line, col, func, line_text) via LLVMConstNamedStruct -- a type-safe LLVM struct, not the sx Frame TypeId / normal struct-emission path. Also correct the file field to the source basename (full paths live in DWARF). --- docs/debugger.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/debugger.md b/docs/debugger.md index c1487d9..0d2968d 100644 --- a/docs/debugger.md +++ b/docs/debugger.md @@ -124,14 +124,19 @@ global — would make the global visible to the interpreter (forcing comptime onto the pointer-deref path) and fatten the lowerer; **do not do this.** -`Frame` is defined **once** in sx (`trace.sx`/std); the reflection builder -(`src/backend/llvm/reflection.zig`) builds the interned global off that -`TypeId` through the normal struct-emission path, -never a bespoke byte layout (which would risk the "8-bytes-assumed" -clobber class of bug). `file`/`func` strings are interned into a shared -pool so a path shared by N push sites is stored once — the table stays -tiny. File paths are normalized to a stable relative form so trace output -is machine-independent and snapshot-testable. +`Frame` is defined **once** in sx (`trace.sx`/std), and its runtime layout — +`{ string file, i32 line, i32 col, string func, string line_text }` — is +mirrored by the cached LLVM named-struct type `getFrameStructType()` +(`src/ir/emit_llvm.zig`). The reflection builder +(`src/backend/llvm/reflection.zig`) assembles each push site's global as an +LLVM **named-struct constant** over that cached type via +`LLVMConstNamedStruct` — a type-safe LLVM struct, not hand-packed bytes +(which would risk the "8-bytes-assumed" clobber class of bug). It does +**not** derive the layout from the sx `Frame` `TypeId`, nor route through +the normal struct-emission path. `file`/`func`/`line_text` strings are +interned into a shared pool so a path shared by N push sites is stored once +— the table stays tiny. The `file` field is the source basename (full paths +live in DWARF), so trace output is machine-independent and snapshot-testable. ### Push and clear sites