Capsule Mercury Format

Capsule Mercury (capmerc) is the default binary output format for SM100+ targets in nvlink v13.0.88. It replaces the traditional cubin (CUDA binary) format with a two-layer ELF structure: the outer ELF is a standard CUDA device ELF with e_machine = 190 (EM_CUDA), but it carries an inner set of .nv.merc.* sections that encode Mercury-native instruction streams, Mercury-specific relocations, debug information, and ISA metadata. The CUDA driver reconstitutes finalized SASS from these Mercury sections at load time (or the linker can do it ahead of time via --self-check), enabling the driver to apply architecture-specific fixups and optimizations that were impossible with the flat SASS cubin model.

The name "Capsule Mercury" comes from the encapsulation metaphor: Mercury-format data is encapsulated inside a CUDA ELF container. The "capmerc" abbreviation appears consistently in CLI flags, output filenames, and internal string references.

Key Facts

Binary Kind Selection

The --binary-kind flag is registered in sub_4AC380 with the help text:

Specify the type of target ELF binary kind. Default on sm100+ is capmerc

Three values are accepted: mercury, capmerc, and sass. The capmerc value is the default when byte_2A5F222 is set (architecture > sm_99). The mercury value produces a legacy Mercury ELF without the capsule wrapping. The sass value produces a traditional flat SASS cubin identical to pre-Blackwell output.

Internally, option parsing in sub_427AE0 sets byte_2A5F222 = 1 and byte_2A5F225 = 1 for any architecture with SM > 99. These globals gate every Mercury-specific code path in the linker. When byte_2A5F225 is set, the output path in main() serializes to memory (via sub_45C950) rather than directly to file (via sub_45C920), because the FNLZR post-link transform requires a complete in-memory ELF image.

Related CLI Options

Capmerc vs Traditional Cubin

A traditional cubin (SASS kind) is a fully resolved ELF: every .text.* section contains final machine code with all relocations applied, all instruction encodings fixed, and all control-flow addresses resolved. The driver loads it and maps it directly to GPU memory.

A capmerc binary defers the final instruction encoding step. Instead of storing finalized SASS, each function's .text.* section is accompanied by a set of .nv.merc.* sections that carry:

1. Mercury intermediate code -- instruction streams in Mercury's scheduling-friendly representation, where instructions carry symbolic operand references and control-flow metadata rather than fully resolved bit-level encodings.

2. Mercury relocations -- R_MERCURY_* relocation types (see R_MERCURY Relocations) that the driver's finalizer resolves at load time. These are distinct from R_CUDA_* relocations and use a dedicated relocation table (.nv.merc.rela).

3. Mercury debug sections -- DWARF-like debug data under the .nv.merc.* namespace, including line tables, abbreviation tables, and register-level debug info.

4. Mercury ISA metadata -- EIATTR_MERCURY_ISA_VERSION and EIATTR_MERCURY_FINALIZER_OPTIONS attributes that tell the driver which Mercury ISA version the code targets and what finalizer options were used at compile time.

5. Compatibility attributes -- EICOMPAT_ATTR_MERCURY_ISA_MAJOR_MINOR_VERSION, EICOMPAT_ATTR_MERCURY_ISA_PATCH_VERSION, and EICOMPAT_ATTR_CAN_FASTPATH_FINALIZE for driver-side version matching.

The deferred encoding enables the driver to:

• Apply architecture-variant-specific instruction scheduling (sm_100 vs sm_100a vs sm_100f).
• Insert or remove NOPs based on final instruction addresses (control-flow-dependent padding).
• Apply warp-level optimizations that require knowledge of the final binary layout.
• Support forward compatibility via the "f" architecture variants (sm_100f, sm_103f, etc.).

Structural Comparison

Mercury Sections (.nv.merc.*)

The inner Mercury payload is distributed across multiple ELF sections with the .nv.merc prefix. These sections are created by the compiler backend (ptxas/cicc) and preserved through linking by nvlink's merge phase. During merge (sub_45E7D0), Mercury sections are identified and either copied or skipped depending on the linking mode -- the string "skip mercury section %i" appears when a Mercury section is not relevant to the current merge pass.

All .nv.merc.* sections carry the SHF_NV_MERC flag: bit 28 of sh_flags (0x10000000). This NVIDIA extension flag serves two purposes: (1) fast O(1) rejection of non-merc sections during classification, and (2) namespace separation during section index remapping (sub_1C99BB0). The finalizer uses this flag to identify which sections require relocation patching during off-target finalization.

Section Catalog

The Mercury code sections use a naming convention of .nv.merc. followed by a function-relative suffix. The section .nv.merc without further qualification is the prefix used during section lookup in the finalization pipeline (sub_4748F0 references .nv.merc. at four distinct call sites).

Section Name Construction

Mercury section names are constructed by two helper functions:

• sub_1CEC4C0 -- generic name constructor. Prepends ".nv.merc" to the original section name: sprintf(buf, "%s%s", ".nv.merc", original_name). Allocates strlen(name) + 9 bytes (8 for prefix + NUL).

• sub_1CEC660 -- constant bank name constructor. Maps .nv.constant* sections to Mercury equivalents with bank-type suffixes. Extracts the bank character from offset 12 of the section name, computes the bank type as char + 0x70000034 (SHT_LOPROC+52), then matches against six known bank types:

The composite name is built by sub_1CEC570: e.g., ".nv.merc" + ".nv.constant" + ".user" + bank_name.

Relocation section names are constructed in sub_1CF72E0 as: sprintf(buf, "%s%s%s", ".nv.merc", ".rela", name+8) -- the +8 strips the ".nv.merc" prefix so that ".nv.merc.debug_info" becomes ".nv.merc.rela.debug_info".

Section Classifier -- sub_1CED0E0

The 9,262-byte classifier at 0x1CED0E0 identifies .nv.merc.* sections using a two-stage guard-then-waterfall algorithm identical to the ptxas classifier at sub_1C98C60 (see ptxas: Capsule Mercury & Finalization for the full algorithm description).

Stage 1: sh_type range check with bitmask 0x5D05. The section's sh_type is tested against two processor-specific ranges:

Bitmask 0x5D05 = binary 0101_1101_0000_0101 selects: SHT_LOPROC+6 (bit 0), +8 (bit 2), +14 (bit 8), +16 (bit 10), +17 (bit 11), +18 (bit 12), +20 (bit 14).

Stage 2: Name-based disambiguation. When SHF_NV_MERC (0x10000000) is set in sh_flags, the classifier performs sequential strcmp() against 15+ section names, returning 1 on first match. The check order is: .nv.merc.debug_abbrev, .nv.merc.debug_aranges, .nv.merc.debug_frame, .nv.merc.debug_info, .nv.merc.debug_loc, .nv.merc.debug_macinfo, .nv.merc.debug_pubnames, .nv.merc.debug_pubtypes, .nv.merc.debug_ranges, .nv.merc.debug_str, .nv.merc.nv_debug_info_reg_type, and more.

A companion classifier sub_1CED7C0 (6,757 bytes) performs the same algorithm for non-merc debug sections (.debug_*), using the same 0x5D05 bitmask.

sh_type Map for Mercury Sections

The .nv.merc.* debug sections reuse the same sh_type values as their non-merc counterparts. The SHF_NV_MERC flag (0x10000000) in sh_flags is the distinguishing marker.

Capsule Descriptor Layout

The per-function .nv.capmerc<funcname> section contains a 328-byte capsule descriptor. For the full byte-level layout including all 7 field groups (Identity, SASS Data, Relocation Infrastructure, Function Metadata, Code Generation Parameters, Constant Bank Info, KNOBS Embedding), marker stream TLV format, and sub-byte relocation design, see ptxas: Capsule Mercury & Finalization which documents the descriptor format at the compiler-output level. nvlink reads and preserves these descriptors through the linking pipeline without modification.

Production Pipeline

The capmerc output pipeline in main() follows a distinct path from traditional cubin serialization.

Step 1: ELF Construction and Finalization

The standard linking pipeline runs identically for both sass and capmerc output: input parsing, merge (sub_45E7D0), shared memory layout (sub_439830), relocation application (sub_469D60), and ELF finalization (sub_445000). The finalization phase handles the 0xFF00 ELF type with special-case logic for virtual-to-physical section index remapping and Mercury-specific symbol binding rules (see Finalization Phase).

Step 2: Serialize to Memory (sub_45C950)

Instead of writing directly to a file, the Mercury path:

1. Computes total ELF size via sub_45C980.
2. Allocates a contiguous memory buffer from the arena.
3. Calls sub_45C950 which uses the mode-4 (memcpy) polymorphic writer to serialize the complete ELF into the buffer.

This produces an "in-memory-ELF-image" -- the string used as the FNLZR input identifier.

Step 3: FNLZR Post-Link Transform (sub_4275C0 -> sub_4748F0)

The FNLZR (Finalizer) operates on the serialized ELF byte buffer. sub_4275C0 is a 3,989-byte dispatch function that:

1. Builds a 160-byte configuration struct from global flags:

   • byte_2A5F222 (Mercury mode)
   • byte_2A5F225 (capmerc mode, controls config word at offset +24: value 4 or 5)
   • byte_2A5F310 (shared flag)
   • byte_2A5F210 (secondary flag)
   • byte_2A5F224, byte_2A5F223 (additional binary properties)
   • byte_2A5F2A9 (mode selector)

2. Logs to stderr when verbose: "FNLZR: Input ELF: %s", "FNLZR: Post-Link Mode", "FNLZR: Flags [ %u | %u ]", "FNLZR: Starting %s", "FNLZR: Ending %s".

3. Calls sub_4748F0 (48,730 bytes, 1,830 lines), the top-level link-and-finalize engine with 25 parameters. This function:

   • Parses the binary-kind specification to determine mercury, capmerc, or sass output.
   • Processes finalization options: "cap-merc", "self-check", "out-sass", "fastpath-off", "opportunistic-finalization-lvl".
   • Calls sub_471700 (78,516 bytes), the main finalization orchestrator that compiles Mercury intermediate code to final SASS instruction encodings.
   • Manages Hash Relocation sections (.nvHRKE, .nvHRKI, .nvHRCE, .nvHRCI, .nvHRDE, .nvHRDI) for incremental linking support.

Two FNLZR modes exist:

FNLZR Configuration Struct (160 bytes)

sub_4275C0 builds a 160-byte configuration struct (v28[0..19], with bytes 8-159 zeroed via memset(&v28[1], 0, 0x98)) before calling sub_4748F0:

The mode_selector at +24 controls finalization behavior: 4 = standard finalization, 5 = shared-mode finalization (when byte_2A5F310 is active). The FNLZR logs the two flag bytes as "FNLZR: Flags [ %u | %u ]" where the first value is the mercury_mode flag and the second is the capmerc_mode flag.

The post-link mode is the one that produces the final capmerc binary. Pre-link mode runs earlier in the pipeline on individual cubin inputs that need Mercury-level transformation before merging.

Step 4: Write Finalized Binary

After FNLZR returns, main() writes the transformed buffer to the output file via fwrite().

Mercury Section Emission Order

During ELF output serialization (sub_1CEE030), Mercury sections are emitted in five passes:

1. Data sections -- .nv.merc.* memory-space clones (constant banks, shared, local, global). Written with sh_type = 0x7000000C (SHT_LOPROC+12) and sh_flags = 0x10000000 (SHF_NV_MERC). Section headers are copied via SSE-optimized _mm_loadu_si128 operations.

2. Debug sections -- .nv.merc.debug_* and .nv.merc.nv_debug_*. Written with sh_type = 0x7000000D (SHT_LOPROC+13) and sh_flags = 0x10000000. Output offset is aligned to each section's sh_addralign value.

3. Relocation sections -- .nv.merc.rela*. Written with sh_type = 0x70000064 (SHT_LOPROC+100) in Mercury mode or 1 (SHT_PROGBITS) in some variants. sh_flags = 0x42.

4. Remaining sections -- any additional Mercury sections from the 280-entry section list.

5. Extended section index -- .nv.merc.symtab_shndx (sh_type = 18, SHT_SYMTAB_SHNDX). Created only when section indices exceed 0xFF00. When a symbol references a section with index > 0xFF00, the symbol table entry stores 0xFFFF and the actual index is recorded in this extended section index table.

Output Filename

The output filename is selected in main() based on architecture and binary-kind flags:

Fastpath Optimization

The finalizer supports a fastpath for "off-target" finalization, logged as:

[Finalizer] fastpath optimization applied for off-target %u -> %u finalization

This occurs when the driver's target architecture differs from the compilation architecture but belongs to the same decade family (e.g., sm_100 -> sm_103, since 100/10 == 103/10). The fastpath avoids a full re-finalization by applying only the delta between the two ISA variants. The --fastpath-off flag disables this optimization.

Opportunistic Finalization

The --opportunistic-finalization-lvl option controls when off-target finalization is attempted:

The option parser (sub_4AC380) rejects values greater than 4, not greater than 3 -- the range check is > 4. The attribute EICOMPAT_ATTR_ENABLE_OPPORTUNISTIC_FINALIZATION is emitted into the ELF to communicate this level to the driver.

Architecture Compatibility

The finalization compatibility checking functions (sub_4709E0, sub_470DA0) determine whether a capmerc binary can be finalized for a target architecture. The checks use:

1. Internal architecture remapping: 104 -> 120, 130 -> 107, 101 -> 110 (mapping internal variant codes to canonical family representatives).

2. Decade-family matching: Two architectures are in the same family if arch1/10 == arch2/10. For example, sm_100 and sm_103 are both in the "10x" decade.

3. Capability bitmask matching: Each architecture has a capability bitmask:

   • sm_100 (code 'd'/100) = bit 0 (value 1)
   • sm_103 (code 'g'/103) = bit 3 (value 8)
   • sm_110 (code 'n'/110) = bit 1 (value 2)
   • sm_121 (code 'y'/121) = bit 6 (value 64)

4. Version bounds: Finalization version > 0x101 returns error code 25 (version too high). The finalization class (byte at offset +3 of the arch info struct) has values 0-4, dispatched through dword_1D40660[].

5. Environment override: The CAN_FINALIZE_DEBUG environment variable enables debug logging of compatibility decisions.

Architecture Compatibility Return Codes

sub_4709E0 returns a numeric error code indicating the compatibility result:

The finalization class at offset +3 of the arch info struct controls the rules. Class 0 is the most restrictive (no cross-arch if special flag set, no sm_110 involvement). Class 4 is the most permissive (allows cross-family including sm_110 and sm_121). Classes 1-3 require the source SM to be less than the target SM. The special flag at offset +4 further restricts class 1 (returns error 26 if set) and relaxes classes 2-3 (returns error 26 for classes 0-1 if special flag is set).

Self-Check Mechanism

The --self-check flag triggers a validation pass where the linker reconstitutes SASS from the capmerc binary and compares it against expected output. Three sections are validated independently:

A more detailed failure message references the internal Jira page:

Failure of '%s' section in self-check for capsule mercury.
See the Jira confluence page 'MERCSW-125' for more information
that includes some debugging steps.

The --out-sass option works only through self-check mode. Its help text states:

Generate output of capmerc based reconstituted sass only through -self-check

The reconstitution itself is performed by sub_5207A0 (18,673 bytes, 784 lines), an instruction opcode dispatch table that routes opcode case IDs (1..49+) to the encoding handler sub_A49120 with opcode dispatch IDs (827..875+). This function is part of the reconstitution pipeline that decodes Mercury intermediate sections and re-encodes them as flat SASS instruction bytes using the instruction encoding engine at sub_4C7D10.

Mercury Uplift

The error string "Invalid elf provided for mercury uplift." reveals a conversion mechanism called "mercury uplift" -- the process of converting a traditional SASS cubin into a capmerc binary. When an input cubin is detected as SASS-only (fatbin member type is default cubin rather than 16), the linker can "uplift" it by wrapping the SASS content in Mercury sections. This operation validates that the input ELF is structurally sound before attempting the conversion.

The MercGenerateSassUCode string at 0x2443D02 names the internal pass that generates Mercury microcode from SASS input, forming the core of the uplift pipeline.

FNLZR Internals

The FNLZR finalization orchestrator (sub_471700, 78,516 bytes) is the largest function in the finalization subsystem. It:

1. Allocates a 656-byte compilation unit descriptor with a vtable at off_1D49C58.
2. Copies a 256-byte architecture profile via SSE-accelerated _mm_loadu_si128 operations.
3. Parses key-value options from the configuration: "deviceDebug", "lineInfo", "optLevel", "IsCompute" (True/False), "IsPIC" (True/False).
4. Builds compiler flags and concatenates with existing flags at v4+48.
5. Sets up the compilation unit: arch version at v4+28, PIC flag at v4+32, debug flags at v4+36/+40, optimization level at v4+104.
6. Allocates a 648-byte section builder (offsets 448+) and initializes it via sub_4F5880.
7. Creates sections including .nv.merc., .nvFatBinSegment, __nv_relfatbin, .nv_fatbin, .note.nv.tkinfo, .symtab.
8. Uses "Final memory space" as the arena name for finalization allocations.
9. Outputs the finalized ELF with version string "Cuda compilation tools, release 13.0, V13.0.88".

JIT Finalization Path

A separate JIT finalization entry exists at sub_52E060 (47,095 bytes, called finalizer_jit_entry). This handles the CUDA driver's JIT compilation path with its own logging:

FNLZR: JIT Path
FNLZR: preLink Mode
FNLZR: postLink Mode
FNLZR: Flags [ %u | %u ]
FNLZR: Starting JIT
FNLZR: Ending JIT

The JIT path uses setjmp for error handling across its multiple compilation phases. It shares the underlying finalization orchestrator (sub_471700) with the ahead-of-time path but wraps it in a JIT-specific framework that handles on-the-fly architecture selection and runtime option injection.

Error Conditions

Function Map

Global Variables

Cross-References

nvlink Internal

• R_MERCURY Relocations -- full catalog of Mercury relocation types
• Mercury ELF Sections -- detailed .nv.merc.* section layout
• FNLZR Post-Link -- FNLZR binary rewriter internals
• Mercury Overview -- high-level Mercury architecture
• Finalization Phase -- ELF finalization including 0xFF00 type handling
• Output Phase -- Mercury output path details
• Architecture Profiles -- SM100+ architecture database
• Fatbin Extraction -- fatbin member type 16 handling
• CLI Options -- --binary-kind and related flags

Sibling Wikis

• ptxas: Capsule Mercury & Finalization -- standalone ptxas capmerc format (Mercury section binary layouts, 328-byte capsule descriptor layout, sh_type map, classifier algorithm with 0x5D05 bitmask, marker stream TLV format, rela entry format, sub-byte relocation design, finalization levels)
• ptxas: Mercury Encoder Pipeline -- standalone ptxas Mercury encode/decode pipeline (phases 113--122)

Confidence Assessment