Skip to content

Latest commit

 

History

History
254 lines (213 loc) · 14.8 KB

DEBUG.md

File metadata and controls

254 lines (213 loc) · 14.8 KB

Debug information profile

-g emits original DWARF version 4 frame records, line tables, compilation units, subprogram entries and their referenced types. The profile supports source breakpoints, stepping, type inspection, unchanged scalar parameters and backtraces across translation units. Supported scalar automatic values use initialized storage intervals. Aggregate/addressed local values, global entries and parameter writes remain open. The complete debugging acceptance campaign also requires accurate supported value locations in native debugger sessions.

The profile uses DWARF32 lengths, eight-byte target addresses, little-endian serialization, code alignment 1 and data alignment -8. It follows the June 10, 2010 DWARF 4 specification, sections 3.1, 3.3, 6.2 and 6.4. .debug_frame is a non-allocated debugger section. This is not an exception-unwinding runtime or an .eh_frame implementation.

Actual frame rules

The canonical frame address is the caller's stack pointer at the call site. At function entry it is rsp + 8; the return address is stored at CFA - 8. After push rbp, the CFA becomes rsp + 16, with the old RBP at CFA - 16. After mov rbp,rsp, the CFA becomes rbp + 16. Stack allocation and outgoing call storage do not change that stable base.

The encoder records each selected R12-R15 save after its actual store. A slot at rbp + offset is described as CFA + offset - 16. Each restore changes the register's rule to same_value after the restoring move. After leave, the CFA becomes rsp + 8 and RBP is restored. A remember/restore-state pair wraps every epilogue, so a later laid-out CFG block again has the function body's rules. Noreturn traps retain body rules throughout their range.

Each function has an FDE covering its actual text-symbol size. Its initial address has an R_X86_64_64 relocation to the function. Its CIE offset has an R_X86_64_32 relocation to the debug section. The second relocation lets the linker combine multiple translation units without leaving FDEs tied to the first unit's CIE. -S emits the same bytes and relocations with local section labels. Normal -c uses the original ELF writer.

See the encoder mapping.

Source rows and compilation units

HIR function declarations carry their scalar source location into IR. The encoder records the actual byte offset before each emitted instruction and terminator. Zero-byte lifetime markers, phi nodes and removed operations do not create rows. Rows at the same address collapse to the final source location. Each function starts a separate line sequence and ends at its exact symbol extent. The post-prologue row follows frame setup and incoming ABI register staging; parameter stores can still follow that row. It does not claim that parameter values are already available.

The line program records logical file, line and column, statement changes and the prologue boundary. Negative line deltas use signed LEB128 with defined division, avoiding an implementation-defined signed shift. Included files and #line directives use the source manager's expansion locations. Macro instructions refer to their invocation, rather than attributing executable instructions to a macro definition in a header.

.debug_info contains a DWARF4 compilation unit and a child subprogram entry for each emitted function. Entries record declaration coordinates, external visibility, relocated start address, exact byte extent, return type and a frame-base expression using DW_OP_call_frame_cfa. Section offsets relocate to .debug_abbrev and .debug_line, allowing the linker to concatenate units. The CU language is DWARF4's C99 profile identifier. This does not change the compiler's documented C17 source profile.

The CU compilation directory is the resolved physical working directory. -ffile-prefix-map maps this directory and source names; macro-only mapping does not change DWARF. Both absolute source names and compilation directories must map consistently for byte-identical relocated objects. Dependency output continues to name physical inputs. Logical names introduced by #line may require GDB source-path substitution to display physical source text.

Construction rejects incomplete function maps, invalid file/include-frame identities, unordered or out-of-function rows, absent prologue rows and repeated finalization before adding source sections. The object owns all serialized bytes and fixup names after source construction returns.

Types and parameter declarations

debug_type.c emits basic target types, const/volatile/restrict qualification, pointers, arrays, structures, unions, bitfields, enumerations and function pointer signatures. Complete records use the semantic layout's byte size, member offsets and DWARF4 data-bit offsets. Incomplete records use declaration entries; flexible arrays have an open subrange. Enum names and signed values belong to the type context, so they survive AST retirement. Named parameters carry the actual declarator token coordinates through HIR and IR.

Type references are CU-relative four-byte offsets. A queue registers types before emitting their referenced children, then patches forward references. This handles recursive records without recursive serialization. Qualified variants are keyed by their actual type record and remaining qualifiers, including separately allocated qualified copies with the same semantic tag identity. Empty function signatures use a childless abbreviation.

Function and parameter types are retained even when optimization removes their uses. Parameters assigned in the body or used through their object address have no location attribute and remain unavailable. Global variable entries, aggregate/addressed automatic values, parameter writes and retained typedef aliases remain open. The current type graph starts from emitted function signatures, rather than advertising every source typedef as a separately retained debug declaration.

Debug construction borrows the IR module, source manager and type context only while serializing. The type ownership probe destroys AST/sema before HIR lowering and HIR before machine/debug construction. It then destroys IR, types and source storage before publishing ELF from the owned bytes and fixups. Canonical CIR remains schema 6; source-only declaration coordinates and enum debug names are not serialized, and cinderir does not accept -g.

Lexical scopes and automatic declarations

IR owns local names, target types, declaration coordinates and slot IDs. Instructions and terminators retain their scope IDs through optimization and critical-edge splitting. Each declaration starts a nested suffix of its C scope. This represents the point where an inner name starts hiding an outer one, including statements before the inner declarator and loop declarations.

The encoder records begin/end offsets for every selected instruction and terminator. debug_scope.c unions nonempty operation ranges through their actual scope ancestors and merges adjacent ranges. DWARF lexical blocks use .debug_ranges, explicit function-base relocations and original section fixups. Empty scopes remain empty. Parents contain their child ranges.

Automatic declaration types and lexical identities are retained even when values are unavailable. Debug scope nesting is bounded at 1023 levels, with an explicit diagnostic when exceeded. See ADR 0017.

Supported automatic scalar values

-g -O0 preserves named local storage during scalar promotion. Parameters and unnamed temporaries retain their usual eligibility. Ordinary builds and -g -O2 keep the existing promotion profile. This is an explicit debug/code tradeoff; O0 debug text can differ from ordinary O0 text.

The supported locations are scalar local objects initialized and updated by retained direct stores, with no formed object address. The encoder records their actual allocated CFA-relative homes. A forward must-initialized analysis intersects reachable predecessors, starts function entry uninitialized and uses top initialization for loop blocks. Begin/reset/end operations clear the state. A retained store establishes availability after its final encoded instruction; undef or possibly undef phi sources do not establish a value. The result is intersected with the variable's actual lexical scope.

Location lists describe current memory, so later direct assignments update the visible value. Before initialization, after lifetime end and at a partial initialization join, the list has no applicable entry. Loop reentry clears a previous iteration's value. Promoted locals without stores have empty lists. An allocated slot alone never establishes availability.

Addressed objects, aggregates and scalar initializer-list plans currently remain unavailable. Their source declarations and types are still retained. A pointer local can have a supported location when its own object address is not formed; this does not promise that its pointee remains alive or unchanged. See ADR 0018.

Unchanged scalar parameter locations

Before optimization, IR construction marks a parameter unavailable if its slot is assigned or its address is formed. The backend records locations only for the remaining scalar parameters. This is a conservative analysis of the parameter object; it does not assume that a pointer's pointee stays unchanged. Aggregate parameter locations remain open.

Each location list begins with an explicit base-selection entry relocated to the function. Address pairs are offsets relative to that base. Register arguments use their real System V GPR/SSE register until incoming staging has completed, then a DW_OP_fbreg location in the actual private ABI save area. Stack arguments use their incoming CFA-relative address throughout. The canonical frame address is the same caller stack address before and after frame setup and leave, so the saved home remains addressable at the return instruction. Function-symbol extents bound every list.

The private incoming save slots are distinct from local objects, spills and outgoing call storage. They preserve an unchanged parameter even when its IR loads are promoted or removed. An assigned or escaped parameter cannot use that original home as its current value. No stale original value is supplied for those parameters.

Verification and use

make test-debug runs frame, source-table, type, parameter, scope and value checks. It requires LLVM's llvm-dwarfdump, llvm-objdump and llvm-mc, plus GCC and Clang reference drivers. On Linux x86-64 it also requires GDB. The test checks O0/O2 frame tables against independently decoded instruction boundaries, actual saved-register store/load bytes, all return paths, original/assembled section identity and relocation meaning. GCC/Clang execute the single-unit and two-unit fixtures. The Linux path links original objects and records GDB backtraces with the DWARF unwinder selected.

The source reader independently interprets the line program and abbreviation forms, resolves original relocation meaning, and checks every row against disassembled instruction boundaries. It verifies subprogram symbol extents, header and macro origins, backward logical line numbers, empty units, noreturn functions and prefix-map ordering. Every debug section and relocation is compared with LLVM-assembled output. Two relocated checkout trees must produce identical debug objects. On Linux, six additional GDB sessions check source breakpoints, stepping and caller chains at O0/O2.

Twelve malformed section/relocation records must fail both output writers. The object writer preserves a complete previous artifact; the assembly writer emits no bytes for the rejected records. Debug-disabled objects preserve the normal section layout and text bytes. Raw commands, object hashes, tool hashes, recordings and reports live under .agent-local/unwind/ and .agent-local/debug-lines/. A second API probe rejects forty-eight malformed source/ABI/scope maps and repeated finalization without adding sections or fixups. Type reports under .agent-local/debug-types/ check independently specified record sizes, field/bit positions, array bounds, signed enum values, recursive references, qualifier chains and callback signatures. Location-list decoding checks function bases/ranges, ABI register numbers and CFA homes against actual staging store bytes. Six corruptions must fail the independent layout assertions. GCC and Clang execute the fixture at both levels. The native path checks GDB type inspection, integer/enum/SSE and pointer values, fields reached through a record pointer, and an explicitly unavailable assigned parameter, alongside the separate lifetime probe. Explicit --execution-profile emulated runs preserve that classification; they do not count as native debugger acceptance.

On a Linux x86-64 host:

make build test-debug
build/cindercc -O0 -g tests/debug/unwind.c -o unwind-example
gdb -ex 'break unwind.c:3' -ex run -ex bt -ex next ./unwind-example

The full debug gate still requires accurate supported variable locations across its native debugger sessions. These source and frame tests do not replace that gate.

The parameter suite uses a two-unit call with seventeen scalar arguments. It exhausts six GPR and eight SSE argument registers, independently checks the three incoming CFA offsets and every actual register-save instruction, and compares original and assembled debug sections at O0/O2. On Linux it cross-links GCC/Clang objects in both directions. Two GDB sessions inspect all parameters before and after a nested call, including the stack pointer argument and its pointee. Six corruptions of locations must be rejected by the independent reader. Reports live under .agent-local/debug-parameters/.

The scope suite independently decodes range lists and resolves six declaration boundaries at O0/O2: before shadowing, double and character shadows, both returns to outer declarations, and a loop-local name. It checks range containment and every range endpoint against real disassembly, compares all debug sections with LLVM assembly, and rejects four metadata corruptions. Twelve Linux GDB sessions verify source breakpoints, exact selected types, O0 current scalar values, O2 unavailable values and caller chains. One boundary also steps through a call. Reports live under .agent-local/debug-scopes/.

The value suite checks eight initialization/join/lifetime boundaries at O0/O2 against original store bytes and actual source rows. It executes the same well-defined program through GCC, Clang and the IR interpreter. Fourteen Linux GDB sessions check before/after initialization, both complete-join paths, conservative partial joins, pointer values and loop reentry with no stale iteration value. Five false availability/home records must fail the reader. Reports live under .agent-local/debug-values/. Every debug suite retains a unique run directory and incremental raw command log.