NVVMPassOptions

NVVMPassOptions is NVIDIA's proprietary per-pass configuration system -- a 4,512-byte flat struct containing 221 option slots that controls every aspect of the NVVM optimization pipeline. It has no upstream LLVM equivalent. Where LLVM uses scattered cl::opt<T> globals that each pass reads independently, NVIDIA consolidates all pass configuration into a single contiguous struct that is allocated once and threaded through the entire pipeline assembler as a parameter. This design allows the pipeline to make pass-enable decisions through simple byte reads at known offsets rather than hash-table lookups, and it ensures that the complete configuration state can be copied between Phase I and Phase II of the two-phase compilation model.

The struct is populated by a single 125KB function (sub_12D6300) that reads from a PassOptionRegistry hash table and flattens the results into 221 typed slots. The pipeline assembler (sub_12E54A0) and its sub-pipeline builders (sub_12DE330, sub_12DE8F0) then read individual slots by offset to decide which passes to insert and how to configure them.

Struct Layout

The struct is heap-allocated as a single 4,512-byte block. The first 16 bytes contain header fields, followed by 221 option slots packed contiguously, and a 32-byte zero trailer:

Offset  Size   Field
──────  ────   ─────
0       4      int opt_level (copied from registry+112)
4       4      (padding)
8       8      qword ptr to PassOptionRegistry
16      ~4464  221 option slots (variable-size, packed)
4480    32     zero trailer (4 qwords, sentinel)

Slot offsets are deterministic -- they depend on the type sequence hard-coded into sub_12D6300. String slots consume 24 bytes, boolean and integer slots consume 16 bytes, and the unique string-pointer slot at index 181 consumes 28 bytes. The initializer writes each slot at a compile-time-constant offset; there is no dynamic layout calculation.

Slot Types

Type A: String Option (24 bytes) -- sub_12D6090

114 slots. Stores a string value (pass name or parametric value) along with flags, optimization level, and pass ID.

struct StringOption {       // 24 bytes, written by sub_12D6090
    char*    value;         // +0:  pointer to string data
    int32_t  option_index;  // +8:  1-based slot index
    int32_t  flags;         // +12: from PassDef byte 40
    int32_t  opt_level;     // +16: from header opt_level
    int32_t  pass_id;       // +20: resolved via sub_1691920
};

Type B: Boolean Compact (16 bytes) -- sub_12D6100

83 slots. The most common boolean representation. The helper encapsulates the lookup-parse-resolve sequence.

struct BoolCompactOption {  // 16 bytes, written by sub_12D6100
    uint8_t  value;         // +0:  0 or 1
    uint8_t  pad[3];        // +1:  padding
    int32_t  option_index;  // +4:  1-based slot index
    int32_t  flags;         // +8:  from PassDef byte 40
    int32_t  pass_id;       // +12: resolved via sub_1691920
};

Type C: Boolean Inline (16 bytes) -- direct write

17 slots. Identical layout to Type B, but written directly by sub_12D6300 rather than through the sub_12D6100 helper. These correspond to option pairs where the boolean resolution requires checking PassDef+36 (has_overrides byte) and resolving via sub_1691920 inline. The 17 inline boolean slots are: 7, 11, 13, 49, 53, 55, 59, 61, 95, 103, 119, 127, 151, 159, 169, 177, 211.

struct BoolInlineOption {   // 16 bytes, same layout as Type B
    uint8_t  value;         // +0:  0 or 1
    uint8_t  pad[3];        // +1
    int32_t  option_index;  // +4:  high 32 bits of sub_12D6240 return
    int32_t  opt_level;     // +8:  from header
    int32_t  pass_id;       // +12: resolved inline
};

Type D: Integer (16 bytes) -- direct write via sub_16D2BB0

6 slots. The integer value is parsed from the registry string by sub_16D2BB0 (string-to-int64). Layout is identical to boolean compact but the first 4 bytes store a full int32_t rather than a single byte.

struct IntegerOption {      // 16 bytes
    int32_t  value;         // +0:  parsed integer
    int32_t  option_index;  // +4:  1-based slot index
    int32_t  opt_level;     // +8
    int32_t  pass_id;       // +12
};

Type E: String Pointer (28 bytes) -- slot 181 only

Unique. Stores a raw char* plus length rather than a managed string. Likely a file path or regex pattern that requires direct C-string access.

struct StringPtrOption {    // 28 bytes, slot 181 only
    char*    data;          // +0:  raw char pointer
    uint64_t length;        // +8:  string length
    int32_t  option_index;  // +16: 1-based slot index
    int32_t  opt_level;     // +20
    int32_t  pass_id;       // +24
};

Pair Organization Pattern

The 221 slots follow a predominantly paired layout. Slots 1--6 are six standalone STRING options (likely the global compilation parameters: ftz, prec-div, prec-sqrt, fmad, opt-level, sm-arch). Starting at slot 7, slots are organized in (EVEN, ODD) pairs:

• Even slot N: STRING option -- the pass's parameter value or name
• Odd slot N+1: BOOLEAN or INTEGER option -- the enable/disable toggle

Each "pass knob" thus gets a string parameter slot and a boolean gate. The pipeline assembler reads the boolean to decide whether to insert the pass, and passes the string value as the pass's configuration parameter.

Exceptions to the pair pattern:

Helper Functions

sub_12D6170 -- PassOptionRegistry::lookupOption

Looks up an option by its 1-based slot index in the hash table at registry+120. Returns a pointer to an OptionNode or 0 if the option was not set from the command line:

// Signature: int64 sub_12D6170(void* registry, int option_index)
// Returns: OptionNode* or 0
//
// OptionNode layout:
//   +40   int16   flags
//   +48   char**  value_array_ptr (array of string values)
//   +56   int     value_count

The hash table uses open addressing. The lookup computes hash(option_index) and probes linearly. When an option is not present in the registry (meaning the user did not supply a CLI override), the caller falls back to the hard-coded default in sub_12D6300.

sub_12D6240 -- PassOptionRegistry::getBoolOption

Resolves a boolean option with a default value. This is the critical function for all 100 boolean slots -- it performs a three-step resolution:

sub_12D6240(registry, option_index, default_string):
    1. Call sub_12D6170(registry, option_index)
    2. If found AND has value:
         lowercase the string via sub_16D2060
         result = (first_char == '1' || first_char == 't')  // "1" or "true"
    3. If not found OR no value:
         result = (default_string[0] == '1')  // "0" -> false, "1" -> true
    Return: packed(bool_value:8, flags:32) in low 40 bits

The packing convention is significant: the boolean value occupies the low 8 bits and the flags occupy bits 8--39. Callers unpack with (result & 0xFF) for the boolean and (result >> 8) for the flags.

sub_1691920 -- PassDefTable::getPassDef

Resolves a 1-based pass index to its PassDef entry in a table with 64-byte stride:

// sub_1691920(table_ptr, pass_index):
//   return table_ptr[0] + (pass_index - 1) * 64
//
// PassDef layout (64 bytes):
//   +32   int     pass_id
//   +36   byte    has_overrides
//   +40   int16   override_index

The pass_id field is written into every option slot and later used by the pipeline assembler to map configuration back to the pass factory that should receive it.

sub_16D2BB0 -- parseInt

Parses a string to a 64-bit integer. Used for the 6 integer-typed option slots (9, 197, 203, 205, 207, 215).

Default Values

Most boolean slots default to 0 (disabled). 14 slots default to 1 (enabled) -- these represent passes that run by default and must be explicitly disabled:

Confidence note: Pass associations marked [MEDIUM] are inferred from pipeline guard cross-references (a4[offset]). Associations marked [LOW] are based solely on offset proximity or default-value patterns.

Integer slot defaults:

CLI Flag Routing

The path from a user-visible flag to an NVVMPassOptions slot traverses four stages:

nvcc -Xcicc -opt "-do-licm=0"          ← user invocation
    │
    ▼
sub_9624D0 (flag catalog, 75KB)        ← parses -opt flags into opt_argv vector
    │   pushes "-do-licm=0" into v327 (opt vector)
    ▼
PassOptionRegistry (hash table)         ← opt-phase parser populates registry
    │   key = slot_index, value = "0"
    ▼
sub_12D6300 (125KB initializer)         ← flattens registry into 4512-byte struct
    │   sub_12D6240(registry, LICM_SLOT, "1") → returns 0 (overridden)
    │   writes opts[2880] = 0
    ▼
sub_12E54A0 / sub_12DE8F0              ← pipeline assembler reads opts[2880]
    if (opts[2880]) AddPass(LICM);     ← skipped because opts[2880] == 0

The -opt flag prefix is critical: it routes the argument to the optimizer phase vector rather than to the linker, LTO, or codegen phases. The flag catalog (sub_9624D0) recognizes several shorthand patterns:

Pipeline Consumer: How Passes Read NVVMPassOptions

The pipeline assembler and its sub-pipeline builders receive the NVVMPassOptions struct as parameter a4 (in sub_12E54A0) or opts (in sub_12DE330/sub_12DE8F0). They read individual boolean slots by dereferencing a byte at a known offset and branching:

// Pattern 1: simple disable guard
if (!*(uint8_t*)(opts + 1760))           // opts[1760] = MemorySpaceOpt disable
    AddPass(PM, sub_1C8E680(0), 1, 0);  // insert MemorySpaceOpt

// Pattern 2: enable guard (inverted logic)
if (*(uint8_t*)(opts + 2880))            // opts[2880] = LICM enabled (default=1)
    AddPass(PM, sub_195E880(0), 1, 0);  // insert LICM

// Pattern 3: combined guard with opt-level gating
if (*(uint8_t*)(opts + 3200) &&          // opts[3200] = opt-level sufficient
    !*(uint8_t*)(opts + 880))            // opts[880] = NVVMReflect not disabled
    AddPass(PM, sub_1857160(), 1, 0);   // insert NVVMReflect

// Pattern 4: integer parameter read
v12 = *(int32_t*)(opts + 200);           // opts[200] = opt threshold (default=1)
// used to configure codegen dispatch in sub_12DFE00

The key insight is that the pipeline assembler never performs string comparison or hash-table lookup at pass-insertion time -- it reads pre-resolved values from the flat struct. This makes the ~150 pass-insertion decisions in sub_12E54A0 essentially free in terms of runtime cost.

Offset-to-Pass Mapping

The following table maps struct offsets (as seen in pipeline assembler guards opts[OFFSET]) to the passes they control. Offsets are byte offsets from the struct base. "Guard sense" indicates whether the pass runs when the byte is 0 (!opts[X] -- most common, where the option is a disable flag) or when it is nonzero (opts[X] -- the option is an enable flag).

Known Option Names

Option names are stored in the PassOptionRegistry hash table, not in sub_12D6300 itself. The following names are extracted from binary string references in global constructors and pass factories:

Boolean Toggles (do-X / no-X)

Dump/Debug Toggles

Parametric Knobs

Differences from Upstream LLVM

Upstream LLVM has nothing resembling this system. The closest analogue is the cl::opt<T> flag mechanism, but that scatters configuration across hundreds of global variables that each pass reads independently. The differences are architectural:

The thread-safety property is crucial for the two-phase concurrent compilation model. When Phase II runs per-function compilation in parallel threads, each thread receives a copy of the NVVMPassOptions struct. If NVIDIA used upstream cl::opt globals for pass configuration, they would need global locks or TLS for every option read during pass execution -- an unacceptable overhead for a GPU compiler that may process hundreds of kernels in a single translation unit.

Interaction with Two-Phase Compilation

The NVVMPassOptions struct is allocated and populated before Phase I begins, in the orchestrator sub_12E7E70:

// sub_12E7E70, line ~128
void* opts = malloc(4512);              // allocate NVVMPassOptions
sub_12D6300(opts, registry);            // populate from CLI-parsed registry
// ... pass opts to sub_12E54A0 for Phase I ...
// ... pass same opts to sub_12E54A0 for Phase II ...

Both phases receive the same opts pointer. Individual passes within the pipeline assembler check qword_4FBB3B0 (the TLS phase counter) to skip themselves in the wrong phase -- but the NVVMPassOptions struct itself does not change between phases. This means a pass cannot be enabled in Phase I but disabled in Phase II through NVVMPassOptions alone; phase selection is handled by the separate TLS mechanism.

The second caller, sub_12F4060 (TargetMachine creation in the standalone path), performs an identical allocation and initialization sequence, confirming that every compilation path goes through the same NVVMPassOptions infrastructure.

Function Map

Cross-References

• LLVM Optimizer -- pipeline assembler that consumes NVVMPassOptions
• Configuration Knobs -- all three knob systems (cl::opt, NVVMPassOptions, codegen)
• CLI Flags -- flag catalog and routing to opt phase vector
• Optimization Levels -- O-level encoding and fast-compile modes
• Concurrent Compilation -- Phase I/II threading model
• Entry Point & CLI -- wizard mode and -opt flag dispatching
• OptiX IR -- forces do-ip-msp=0 and do-licm=0