DWARF Processing

nvlink contains a complete DWARF-2/3 debug information processing subsystem at address range 0x1D10000--0x1D20570. This subsystem parses, validates, and re-emits standard DWARF sections carried in CUDA device ELF objects, handling abbreviation tables, compilation units, type information, location expressions, and line number programs. The implementation supports both 32-bit and 64-bit address sizes and recognizes seven vendor-specific attribute extensions from four vendors: NVIDIA (DW_AT_NV_general_flags), MIPS/GCC (DW_AT_MIPS_linkage_name), GNU (DW_AT_GNU_pubnames), and PGI (DW_AT_PGI_lbase/soffset/lstride). Of these, DW_AT_MIPS_linkage_name and the PGI triplet have unique processing logic; the others are recognized for display but passed through opaquely. All DWARF encoding uses LEB128/ULEB128 variable-length integers, decoded through a shared codec subsystem with SSE-accelerated variants at 0x1D00000--0x1D0FFF0.

This page documents the core parsing functions. For the NVIDIA-specific extensions and Mercury debug section variants, see NVIDIA Debug Extensions. For line-table merging during the link phase, see Line Table Merging.

Key Facts

Standard DWARF Sections

nvlink processes the following standard DWARF sections from input ELF objects. The section type classifier at sub_12D4370 assigns numeric IDs used internally to dispatch processing:

Additional sections processed by the ELF emitter (sub_1CED0E0 at 0x1CED0E0) but not given classifier IDs include .debug_frame, .debug_ranges, .debug_aranges, .debug_pubnames, .debug_pubtypes, and .debug_macinfo. These are carried through as opaque blobs during linking and re-emitted in the output under the Mercury namespace prefix .nv.merc.:

Top-Level Entry Point: sub_1D166F0

The top-level DWARF processing entry point allocates a 95,968-byte (0x176E0) context structure and dispatches to the section-level parser.

Signature

int64_t dwarf_process_sections(
    void*    section_data,     // a1: raw section bytes
    size_t   section_size,     // a2: byte count
    char*    section_name,     // a3: e.g. ".debug_info"
    uint64_t flags             // a4: processing flags
);
// Returns byte count processed, or -64 on allocation failure.

Context Structure Layout

The function allocates a context via malloc(0x176E0) and initializes it before calling sub_1D15E00 (the section-level dispatcher). Key offsets within this context:

The magic value 38110068 stored at offset +224 acts as a state sentinel: it is set at the start of each compilation unit's processing and cleared to zero when parsing is complete.

Abbreviation Table Parser: sub_1D17C90

The abbreviation table parser (sub_1D17C90 at 0x1D17C90, 18,519 bytes, 675 decompiled lines) reads .debug_abbrev section data and builds an in-memory lookup table. Each abbreviation entry maps an abbreviation number to a DW_TAG code, a has-children flag, and a list of (attribute, form) pairs.

Signature

int dwarf_parse_abbrev_table(
    dwarf_context* ctx,         // a1: context with abbrev table storage
    uint64_t       section_base, // a2: start of .debug_abbrev data
    int            section_size, // a3: byte count
    int            verbose       // a4: 1 = print parsed entries to stdout
);

Abbreviation Table Storage

The parser stores entries in a contiguous buffer at ctx+128. Initial allocation is 2048 bytes. When the buffer is full (entry count reaches capacity >> 5), the parser doubles the capacity, allocates a new buffer via sub_1D16C20, copies existing entries with memcpy, frees the old buffer, and swaps in the new one.

Each abbreviation entry is a 32-byte record:

Offset   Size   Field
------   ----   -----
+0       4      DW_TAG code (from first ULEB128 of attr/form pair loop)
+4       4      DW_FORM code (companion to the attribute)
+8       1      has_children flag (1 = DW_CHILDREN_yes)
+12      4      Number of attribute/form pairs for this abbreviation
+16      4      Byte offset within the .debug_abbrev section
+24      8      Pointer to heap-allocated (attr, form) pair array

The pair array at +24 stores each attribute/form pair as an 8-byte record: 4 bytes for DW_AT_* code, 4 bytes for DW_FORM_* code. The maximum number of pairs per abbreviation is 256; exceeding this triggers a fatal error:

unexpectedly too many dwarf attributes for any DW_TAG entry!

Parse Loop

The parser is a while(1) loop that reads ULEB128-encoded abbreviation numbers from the byte stream. For each non-zero abbreviation number:

1. Read the DW_TAG code (ULEB128) via sub_1D1FAD0.
2. Read the has-children byte (single byte after the tag).
3. Read attribute/form pairs in a loop until both attribute and form are zero (the null terminator).
4. Allocate heap storage for the pair array, copy from a 256-entry stack buffer (v151, 2048 bytes on stack).
5. Store the completed entry into the abbreviation table at the current index.
6. Increment the abbreviation index at ctx+152.

When verbose (a4) is non-zero, the parser prints each entry to stdout:

Contents of the .debug_abbrev section:

  Number  TAG
   1      0x11 DW_TAG_compile_unit      [has children]
   DW_AT_producer(0x25)          DW_FORM_strp(0xe)
   DW_AT_language(0x13)          DW_FORM_data1(0xb)
   ...

The DW_TAG code-to-name lookup uses the string table at off_245F080, which contains 67 entries (indices 0 through 0x42). Tag codes beyond this range produce <unknown>.

DW_FORM Name Lookup: sub_1D16C60

A simple switch-based lookup (sub_1D16C60 at 0x1D16C60, 80 lines) that maps DWARF form codes to their string names. The complete mapping:

This covers all forms defined in DWARF-2 and DWARF-3. Form code 2 (DW_FORM_block2 gap in the standard) is not handled -- the standard reserves but does not assign it. Unknown form codes produce a diagnostic to stderr:

Unknown FORM value %d

DW_AT Attribute Name Lookup: sub_1D16DF0

The attribute name lookup (sub_1D16DF0 at 0x1D16DF0, 330 lines) is a deeply nested if/else tree (not a switch) that maps DWARF attribute codes to string names. It covers the full DWARF-2/3 standard attribute set plus several vendor extensions.

Standard Attributes (Codes 1--90)

DWARF-3 Attributes (Codes 79--91)

Vendor Extensions

Unknown attribute codes produce a diagnostic to stderr:

Unknown Attribute value %d

The if/else tree structure in sub_1D16DF0 (not a compiler-generated switch table) suggests this was hand-written or came from a legacy code generator. The vendor attribute codes fall in the DWARF user-defined ranges: 0x2000--0x2FFF for vendor-specific use (MIPS, GNU, NVIDIA), and 0x3A00--0x3FFF for the upper user range (PGI, sentinel).

DW_AT_MIPS_linkage_name (0x2007) -- Linkage Name Priority

DW_AT_MIPS_linkage_name is the most extensively handled vendor attribute in the DWARF subsystem. Originally defined by SGI for the MIPS ABI, it was adopted by GCC and Clang as the de facto standard for encoding the mangled (C++ linkage) name of a symbol before DWARF-4 introduced DW_AT_linkage_name (code 0x76). The CUDA toolchain emits it in device ELF objects for mangled kernel names.

nvlink gives DW_AT_MIPS_linkage_name priority over DW_AT_name when extracting the canonical name of a DIE. This affects three functions:

DIE tree walker (sub_1D1BE80): When processing DW_TAG_subprogram (tag 46), the walker has a special check at the attribute dispatch level. If the current attribute is DW_AT_name (3) and the previous attribute stored in the DIE context (offset +48) was DW_AT_MIPS_linkage_name (8199), the walker skips the DW_AT_name extraction entirely -- the linkage name already captured is the canonical identifier. Conversely, if the attribute is DW_AT_MIPS_linkage_name, the walker proceeds directly to the name extraction path. The pseudocode for the relevant check:

// Inside DIE tree walker, attribute dispatch for DW_TAG_subprogram (46):
if (current_attr == DW_AT_name) {
    if (die_ctx->prev_attr == DW_AT_MIPS_linkage_name)
        goto skip;   // linkage name already captured, ignore DW_AT_name
}
if (current_attr == DW_AT_MIPS_linkage_name) {
    goto extract_name;  // treat as the canonical name
}

Pubnames emitter (sub_1D19900) and pubtypes emitter (sub_1D193E0): Both use an identical priority pattern when building the .debug_pubnames / .debug_pubtypes name index. For each abbreviation entry's attribute list, they check:

if (attr == DW_AT_MIPS_linkage_name ||
    (attr == DW_AT_name && prev_captured_name != DW_AT_MIPS_linkage_name))
{
    // Extract name string from the stream, allocate arena copy
    prev_captured_name = attr;
}

This means: if a DIE has both DW_AT_name and DW_AT_MIPS_linkage_name, the mangled linkage name always wins. The DW_AT_name is only used as a fallback when no linkage name is present. After capturing via DW_AT_MIPS_linkage_name, encountering DW_AT_name has no effect on the stored name. This guarantees that pubnames/pubtypes entries use the mangled C++ name when available, which matches what host-side linkers and debuggers expect.

DW_AT_GNU_pubnames (0x2134) -- GCC .debug_gnu_pubnames

DW_AT_GNU_pubnames is a boolean attribute added to DW_TAG_compile_unit DIEs by GCC when the .debug_gnu_pubnames section is present. This is the GCC extension for accelerated name lookup (later standardized as .debug_names in DWARF-5). nvlink recognizes the attribute name for display in verbose mode but does not perform any special processing on its value -- the attribute is decoded generically through the form value reader like any other boolean or constant. The .debug_pubnames section itself is carried through as an opaque blob in the Mercury output (.nv.merc.debug_pubnames).

DW_AT_NV_general_flags (0x2703) -- NVIDIA GPU Function Properties

DW_AT_NV_general_flags at code 9987 (0x2703) is NVIDIA's sole custom DWARF attribute in the vendor extension range. It is used by the CUDA toolchain (cicc/ptxas) to annotate DW_TAG_subprogram DIEs with GPU-specific function properties in device ELF .debug_info sections.

Despite being the only NVIDIA-proprietary attribute, DW_AT_NV_general_flags has no special handling in the nvlink DWARF subsystem beyond the name lookup in sub_1D16DF0. The attribute value is:

• Decoded generically by the form value reader (sub_1D1B540) according to whatever DW_FORM_* is specified in the abbreviation table (typically DW_FORM_data4 for a 32-bit flags word or DW_FORM_data2)
• Not examined, filtered, or modified by the DIE tree walker (sub_1D1BE80)
• Not referenced by the pubnames or pubtypes emitters
• Passed through opaquely to the Mercury output

The exact bit layout of the flags value was not determined from decompilation of nvlink alone -- the flags are produced by cicc and consumed by cuda-gdb and other NVIDIA debug tools. The attribute code 0x2703 falls in the 0x2000--0x3FFF user-defined range (specifically in the 0x2700--0x27FF sub-range that appears to be reserved for NVIDIA).

PGI Extensions (0x3A00--0x3A02) -- Fortran Array Descriptors

The three PGI attributes reflect nvlink's lineage from the PGI (Portland Group / NVIDIA HPC SDK) compiler toolchain. They encode Fortran array descriptor components:

These are typically encoded as DW_FORM_block1 values containing DWARF location expressions (DW_OP_* sequences). The form value reader (sub_1D1B540) explicitly includes all three PGI codes in its location-expression decode check:

// In sub_1D1B540, DW_FORM_block1 handler:
if (attr == DW_AT_location       ||   // 2
    attr == DW_AT_data_location   ||   // 81
    (attr - 14848) <= 2u          ||   // DW_AT_PGI_lbase/soffset/lstride
    attr == DW_AT_stride_size)         // 46
{
    // Invoke DW_OP expression decoder (sub_1D1A920) on block contents
}

This means the PGI array descriptor attributes are treated as first-class location expressions by the DWARF subsystem -- their block values are decoded through the full DW_OP_* interpreter (sub_1D1A920), producing human-readable location descriptions in verbose mode. This is the same treatment given to standard location attributes like DW_AT_location and DW_AT_data_location.

DW_OP Expression Decoder: sub_1D1A920

The DW_OP expression decoder (sub_1D1A920 at 0x1D1A920, 15,580 bytes, 616 lines) parses DWARF location expressions and prints them into a string buffer. It handles the full set of DWARF-2/3 expression opcodes needed for GPU debug information.

Signature

uint64_t dwarf_decode_dw_op(
    uint32_t*   addr_size_ctx,   // a1: points to CU address size
    char**      section_name,    // a2: section name pointer (for debug_frame detection)
    int         expr_length,     // a3: byte count of expression data
    string_buf* output,          // a4: output string buffer
    int64_t     reserved1,       // a5
    int64_t     reserved2,       // a6
    void*       expr_data,       // a7: expression byte stream
    uint64_t    expr_capacity    // a8: bounds-checking limit
);

Supported Opcodes

The DW_OP_addr handler dispatches on the CU address size: 4-byte addresses use format "DW_OP_addr: 0x%x", while 8-byte addresses use "DW_OP_addr: 0x%llx".

For DW_OP_bregx (opcode 0x92), the decoder has a special code path for .debug_frame sections. When the section name matches "debug_frame" (compared against the suffix of ".nv.merc.debug_frame"), it decodes the register number through sub_1D17460 which maps register numbers to NVIDIA-specific register names with a 24-bit mask (& 0xFFFFFF). Otherwise it uses the generic ULEB128 decoder.

Multiple DW_OP operations within a single expression are separated by "; " in the output string.

Form Value Reader: sub_1D1B540

The form value reader (sub_1D1B540 at 0x1D1B540, 9,243 bytes, 353 lines) reads and formats a single DWARF attribute value based on its DW_FORM code. This is the central dispatch for all attribute value decoding.

Signature

int64_t dwarf_read_form_value(
    dwarf_context* ctx,       // a1: parsing context (offset +52 = addr size, +56 = section name)
    void*          allocator, // a2: memory allocator context
    uint16_t       form,      // a3: DW_FORM_* code
    string_buf*    output,    // a4: output buffer for formatted value
    int64_t        reserved1, // a5
    int64_t        reserved2, // a6
    void*          data,      // a7: raw byte stream
    uint64_t       data_size, // a8: remaining bytes
    int64_t        slice_ctx  // a9: slice/validation context
);
// Returns number of bytes consumed from the data stream.

Form Dispatch Table

For block forms (DW_FORM_block1, DW_FORM_block4, DW_FORM_block), after printing the hex dump the reader also invokes the DW_OP expression decoder (sub_1D1A920) to produce a human-readable interpretation. The decoded expression is appended in parentheses: (%s).

The DW_FORM_block1 reader has an additional dispatch based on the attribute code: for location-related attributes (DW_AT_location = 2, DW_AT_data_member_location = 56, DW_AT_stride_size = 46, DW_AT_address_class = 51, and PGI attributes 14848--14850), it invokes sub_1D1A920 with the block contents. For DW_AT_data_member_location specifically, it passes the data through a different slice path to handle the member offset encoding.

Encountering DW_FORM_indirect triggers a fatal error with exit(1) and the message:

Warning: we should not get here! - DW_FORM_indirect

Any unrecognized form code triggers:

Error in get_form_value default

Compilation Unit Parser: sub_1D1D2F0

The .debug_info section parser (sub_1D1D2F0 at 0x1D1D2F0, 9,191 bytes, 397 lines) iterates over compilation units (CUs) and dispatches to the DIE tree walker. This is called through a thin wrapper sub_1D1DAE0 which normalizes the parameter order.

Signature

int dwarf_parse_debug_info(
    dwarf_context*  ctx,           // a1: DWARF context
    uint64_t        section_size,  // a2: total .debug_info size
    int64_t         string_table,  // a3: .debug_str base address
    const char*     section_name,  // a4: ".debug_info" or ".nv_debug_info_ptx"
    void*           allocator,     // a5: memory allocator
    uint8_t         alloc_flags,   // a6
    void*           data,          // a7: raw .debug_info bytes
    uint64_t        data_size,     // a8: byte count
    uint8_t         data_valid,    // a9: computed from a7 != NULL && a8 != 0
    uint8_t         verbose        // a10: 1 = print compilation unit headers
);

Compilation Unit Header

Each compilation unit starts with an 11-byte header (DWARF-2/3 32-bit format):

Offset   Size   Field
------   ----   -----
+0       4      unit_length: total bytes after this field (excludes the 4-byte length itself)
+4       2      version: DWARF version (2 or 3)
+6       4      debug_abbrev_offset: byte offset into .debug_abbrev for this CU's table
+10      1      address_size: pointer size (4 or 8)

The parser reads these fields and stores them in the context:

ctx->cu_total_length    = unit_length;       // +192
ctx->cu_header_size     = 11;                // +196 (constant for DWARF-2/3)
ctx->cu_content_length  = unit_length;       // +200
ctx->cu_version         = version;           // +204
ctx->cu_address_size    = address_size;      // +208
ctx->cu_abbrev_offset   = abbrev_offset;     // +212

When verbose mode is active (a10 != 0), the parser prints:

 Compilation Unit @ offset 0x%zx:
  Length:           %d
  Version:          %d
  Abbrev Offset:    %d
  Pointer Size:     %d

Abbreviation Table Matching

After reading the CU header, the parser scans the abbreviation table (stored at ctx+128) to find the first entry whose byte offset matches the CU's debug_abbrev_offset. This establishes the base index for abbreviation lookups within this CU:

for (int i = 1; i <= ctx->abbrev_count; i++) {
    abbrev_entry* entry = &ctx->abbrev_table[i];
    if (entry->section_offset == abbrev_offset) {
        ctx->matched_abbrev_base = i - 1;  // +216
        break;
    }
}

DIE Tree Dispatch

After CU header parsing, the function reads the first ULEB128 from the CU content (the root DIE's abbreviation number) and allocates a 48-byte record for the CU's data pointers, then dispatches to sub_1D1BE80 (the DIE tree walker) if the section name matches either ".debug_info" or ".nv_debug_info_ptx".

After processing one CU, the parser advances data by unit_length - 7 bytes and loops to process the next CU, continuing until all data is consumed.

DIE Tree Walker: sub_1D1BE80

The DIE tree walker (sub_1D1BE80 at 0x1D1BE80, 27,583 bytes, 1,059 lines) recursively processes all Debug Information Entries within a compilation unit. For each DIE it:

1. Reads the abbreviation number (ULEB128).
2. Looks up the abbreviation entry to determine the DW_TAG, has-children flag, and attribute list.
3. For each attribute, calls the form value reader (sub_1D1B540) to consume and format the value.
4. If the DIE has children, recurses to process child DIEs.
5. A zero abbreviation number signals the end of a sibling chain (returns to parent scope).

In verbose mode, each DIE is printed as:

 <%d><%x>:  Abbrev Number: %d   (0x%02x %s)

where the fields are nesting depth, byte offset from CU start, abbreviation number, DW_TAG code, and DW_TAG name.

The walker recognizes DW_TAG values 5 (DW_TAG_formal_parameter) and 52 (DW_TAG_variable) as special cases for tracking function parameter and variable debug information through a separate codepath.

LEB128 Codec Subsystem

The LEB128 codec at 0x1D00000--0x1D0FFF0 provides variable-length integer encoding/decoding used throughout the DWARF subsystem. It has four implementation tiers:

Inline Decoders Used by DWARF

The DWARF parser calls two specific ULEB128/SLEB128 decoders for individual values:

• sub_1D229C0 -- ULEB128 decoder. Returns the decoded unsigned value and stores the byte count consumed into an output parameter. Used for abbreviation numbers, form lengths, unsigned data.
• sub_1D22B50 -- SLEB128 (signed LEB128) decoder. Returns the decoded signed value. Used for DW_FORM_sdata and DW_OP_fbreg/DW_OP_breg* offsets.
• sub_1D1FAD0 -- Another ULEB128 decoder variant used in the abbreviation parser. Returns the decoded value and stores consumed byte count via a pthread_mutexattr_t* parameter (reused struct for alignment).

SSE Acceleration

The SSE-accelerated encoders and decoders process 16 bytes at a time using SSE2 SIMD instructions (_mm_load_si128, _mm_shuffle_epi8, _mm_and_si128, _mm_or_si128, _mm_srli_epi64). They extract continuation bits in parallel across 16 LEB128 bytes, determine group boundaries, and decode/encode all values in a single pass. These are used for bulk operations on large DWARF sections, not for individual value decoding.

The signed SSE decoder (sub_1D10120, 69,928 bytes -- the largest function in the LEB128 subsystem) additionally handles sign extension for negative values, which requires detecting the sign bit position within each variable-length group.

Helper Functions

Pubnames and Pubtypes Emitters

Two functions emit the .debug_pubnames and .debug_pubtypes lookup sections:

• sub_1D18EA0 (0x1D18EA0, 5,152 bytes) -- .debug_pubnames emitter. Walks the abbreviation table, and for each DIE with a DW_AT_name attribute, emits an entry mapping the name to the DIE offset within .debug_info.

• sub_1D193E0 (0x1D193E0, 6,101 bytes) -- .debug_pubtypes emitter. Similar structure but emits entries for type DIEs (those with DW_TAG_base_type, DW_TAG_typedef, etc.).

Both follow the DWARF-2/3 pubnames/pubtypes section format: a header with CU offset and CU size, followed by (offset, name) pairs terminated by a zero offset.

Bounds Checking

The DWARF parser performs pervasive bounds checking through a consistent pattern. Each data access is guarded by three assertions on the context's data triple (pointer, capacity, valid_flag):

1. Null check: if (!pointer) fatal(ASSERT_NOT_NULL);
2. Valid flag: if (!valid_flag) fatal(ASSERT_VALID);
3. Bounds check: if (required_offset > capacity) fatal(ASSERT_BOUNDS);

These correspond to the three error codes referenced as dword_2A5F0D0 (null pointer), dword_2A5F0B0 (invalid state), and dword_2A5F0A0 (out of bounds). The assertions are implemented as calls to sub_467460 which is the global diagnostic/assertion handler. This pattern appears on virtually every byte read throughout the DWARF subsystem, giving strong protection against malformed input but contributing significantly to code size.

Cross-References

Internal (nvlink wiki):

• NVIDIA Debug Extensions -- Six proprietary debug sections (.nv_debug_*) processed alongside standard DWARF sections
• Line Table Merging -- DWARF line program merging during linking, including NVIDIA extended opcodes
• Mercury Debug Sections -- Mercury-format debug sections with .nv.merc.* prefix and the Mercury section dispatcher
• Debug Options -- CLI flags controlling debug section emission (-g, --no-debug, debug section output matrix)
• Mercury ELF Sections -- The 11 standard DWARF mirrors under .nv.merc.* namespace
• Error Reporting -- sub_467460 diagnostic handler used by DWARF bounds-check assertions
• Section Merging -- How debug sections are classified and routed during merge_elf

Sibling wikis:

The debug information lifecycle spans three toolchain components. For the upstream generation stages:

• ptxas: Debug Info -- DWARF line table generation (PTX-level and SASS-level), .nv_debug_info_reg_sass/.nv_debug_info_reg_type emission, Mercury debug section classifiers, and the --device-debug/--lineinfo flag semantics within ptxas
• cicc: Debug Info Pipeline -- Four-stage debug metadata lifecycle from CUDA source through the LLVM optimizer to PTX .loc/.file directives. Covers the three compilation modes (-g, -generate-line-info, neither), the five stripping passes, and the NVVM container DebugInfo enum (NONE/LINE_INFO/DWARF)

nvlink's DWARF processing subsystem consumes the output of both upstream stages: cicc produces PTX with @@DWARF directives and .loc/.file metadata, ptxas compiles this to SASS and emits the standard and NVIDIA-proprietary debug sections, and nvlink merges and re-emits these sections during linking.

Confidence Assessment