Add DWARF variant part support for polymorphic variables in CUDA debug info

[jiel-nv]

Overview

This PR implements proper DWARF debug information generation for polymorphic variables in Numba CUDA kernels using DW_TAG_variant_part (discriminated unions). This enables debuggers like cuda-gdb to correctly inspect polymorphic variables that can hold different types throughout their lifetime.

Key Changes

1. Enhanced Polymorphic Variable Lowering (lowering.py)

• With CUDA_DEBUG_POLY enabled:
  • Allocates storage for discriminant + data
  • Stores discriminant at offset 0 and data at offset sizeof(fetype)
  • Retrieves data pointer with proper offset calculation
  • Memory layout:
    [discriminant: 8 bits][padding][data: varies by type]

2. DWARF Variant Part Metadata Generation (debuginfo.py)

• Generate proper debug info metadata for variant types:
  • Creates DW_TAG_variant_part with discriminator field
  • Emits variant members with extraData field containing discriminant values
  • Wraps variant part in a structure type with proper size calculations
  • Each variant member includes correct offset (equals element's width in bits)
    The final DWARF structure: after this change would look like the following e.g.,

  variant_wrapper_struct (DW_TAG_structure_type)
  ├── discriminator (DW_TAG_member, 8 bits)
  └── variant_part (DW_TAG_variant_part)
      ├── _bool (DW_TAG_member, extraData: 0, offset: 8)
      ├── _float64 (DW_TAG_member, extraData: 1, offset: 64)
      ├── _int32 (DW_TAG_member, extraData: 2, offset: 32)
      └── _int64 (DW_TAG_member, extraData: 3, offset: 64)
  

• Added llvmlite version-dependent logic for extraData emission:
  • Typed constant (i8 N) for newer llvmlite versions (> 0.45)
  • Metadata node reference for older versions (<= 0.45), requires an in progress nvvm patch
  • Controlled by CUDA_DEBUG_POLY_USE_TYPED_CONST config flag
• Added CTK version threshold check:
  • Feature enabled: When CTK > 13.1
  • Feature disabled: When CTK <= 13.1

3. Test Coverage (test_debuginfo.py)

• Added a new test test_poly_variant_part() to verify DWARF output:
  • Conditionally turns on, opt-in via CUDA_DEBUG_POLY configuration flag
  • Validates complete hierarchical structure: DILocalVariable → wrapper struct → elements list → discriminator + variant_part → variant members
  • Dynamically adapts FileCheck patterns based on CUDA_DEBUG_POLY_USE_TYPED_CONST
  • Verifies all variant members (_bool, _float64, _int32, _int64) with correct offsets

4. Backward Compatibility

• Without CUDA_DEBUG_POLY: Falls back to existing behavior, i.e. user mentally choose runtime type from a union like types wrapper in a debugging session.
• Older test (test_union_poly_types) preserved and conditionally skipped

This change implements issue#520.

Summary by CodeRabbit

• New Features

  • Added support for polymorphic debug information for CUDA union types, enabling enhanced debugging capabilities with structured variant metadata.
  • Introduced new configuration flags to control polymorphic debug behavior and data representation modes.

• Tests

  • Added test coverage for polymorphic variant-part debugging information under various configuration scenarios.

[copy-pr-bot]

Auto-sync is disabled for ready for review pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[jiel-nv]

/ok to test 387f756

[jiel-nv]

/ok to test 98e1283

[coderabbitai]

Walkthrough

This PR introduces polymorphic debug information support for CUDA debugging. It adds version detection for llvmlite support, enhanced debug metadata generation for UnionModel payloads using DWARF5 variant_part structures, and corresponding storage/retrieval logic for polymorphic variables with discriminant handling in the lowering layer.

Changes

Cohort / File(s)	Summary
Polymorphic debug capability detection numba_cuda/numba/cuda/debuginfo.py	Added _get_llvmlite_version() and _check_polymorphic_debug_info_support() to detect support based on CUDA/CTK and llvmlite versions. Introduced module-level config flags DEBUG_POLY_SUPPORTED and DEBUG_POLY_USE_TYPED_CONST.
Debug metadata generation for polymorphic unions numba_cuda/numba/cuda/debuginfo.py	Enhanced CUDADIBuilder._var_type to handle UnionModel payloads by accumulating member metadata dictionaries and generating DIDerivedType entries. When CUDA_DEBUG_POLY is enabled, constructs wrapper struct with discriminator and variant_part; otherwise preserves legacy union-based path.
Polymorphic variable storage/retrieval numba_cuda/numba/cuda/lowering.py	Extended CUDALower.storevar, _alloca_var, and getvar to handle polymorphic variables when CUDA_DEBUG_POLY is active: allocates two-slot aggregates, writes discriminants, and performs offset-based reads/writes using i8\* bitcasts and GEP. Falls back to original paths for non-polymorphic variables.
Test coverage for polymorphic debug info numba_cuda/numba/cuda/tests/cudapy/test_debuginfo.py	Added conditional skip guards for existing union tests based on CUDA_DEBUG_POLY state. Introduced test_poly_variant_part to validate DWARF5 variant_part debug info with dynamic FileCheck patterns based on typed constant vs node reference configuration.

Sequence Diagram

sequenceDiagram
    participant Config as Configuration
    participant DebugInfo as DebugInfo Builder
    participant Lowering as CUDA Lowering
    participant Runtime as Runtime Execution

    Config->>DebugInfo: Initialize CUDA_DEBUG_POLY flag
    Note over DebugInfo: _check_polymorphic_debug_info_support()<br/>detects llvmlite version & capabilities
    
    alt CUDA_DEBUG_POLY enabled
        Lowering->>Lowering: _alloca_var: allocate 2-slot aggregate<br/>(discriminant + data)
        Lowering->>Runtime: storevar: write discriminant at offset 0
        Lowering->>Runtime: storevar: write data at offset sizeof(fetype)
        Runtime->>Lowering: getvar: read from offset sizeof(fetype)
        DebugInfo->>DebugInfo: _var_type: generate variant_part<br/>wrapper struct metadata
    else CUDA_DEBUG_POLY disabled
        Lowering->>Lowering: _alloca_var: allocate single slot
        Lowering->>Runtime: storevar: standard path
        Runtime->>Lowering: getvar: simple bitcast
        DebugInfo->>DebugInfo: _var_type: emit legacy union<br/>(DICompositeType)
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

The changes introduce new detection logic, multiple conditional paths in core debug metadata generation and variable storage/retrieval, and span three interconnected files with varying logic density. The polymorphic variant handling in _var_type and the offset-based reads/writes in lowering require careful verification, though the conditional structure preserves backward compatibility for non-polymorphic paths.

Poem

🐰 Hop into the debug realm so deep,
Where variants and types their secrets keep!
With discriminants marking each polymorphic way,
Your CUDA code's mysteries shine bright today! ✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 57.14% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The PR title "Add DWARF Variant Part Support for Polymorphic Variables in CUDA Debug Info" directly captures the main objective of the changeset. The title explicitly identifies the primary feature being introduced (DWARF Variant Part Support), the target use case (Polymorphic Variables), and the context (CUDA Debug Info). The changes across debuginfo.py, lowering.py, and tests all focus on implementing this exact functionality, and the title accurately reflects this scope. The title is concise, specific, and avoids vague terminology, making it clear to developers scanning the history that this PR adds debug info support for polymorphic variables.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[jiel-nv]

/ok to test a7f5393

[gmarkall]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (5)

numba_cuda/numba/cuda/tests/cudapy/test_debuginfo.py (1)

467-506: Tighten FileCheck and clean up unused noqa markers

• Patterns look correct and adapt to typed-const vs node-ref. LGTM.
• Static analysis flags unused “# noqa: F841” on Lines 483–485. Remove them; these assignments are already intentionally unused in a test context.

Apply this minimal cleanup:

-            foo = 3.14  # noqa: F841
-            foo = True  # noqa: F841
-            foo = np.int32(42)  # noqa: F841
+            foo = 3.14
+            foo = True
+            foo = np.int32(42)

numba_cuda/numba/cuda/lowering.py (2)

1863-1867: Alloc size choice matches test expectations; consider documenting alignment rationale

Doubling max element size to house [discriminant + data] matches the 128‑bit wrapper check. A brief comment on why data lives at offset sizeof(fetype) (not a fixed base) would help future maintainers reason about padding/alignment and the DWARF offsets.

---

1920-1939: Offset read mirrors store; ensure index type width is intentional

Using i32 indices in GEP on i8* works, but LLVM permits any integer width. If targeting 64‑bit consistently, consider IntType(64) to avoid future assertions in newer llvmlite.

-                    [llvm_ir.Constant(llvm_ir.IntType(32), sizeof_bytes)],
+                    [llvm_ir.Constant(llvm_ir.IntType(64), sizeof_bytes)],

numba_cuda/numba/cuda/debuginfo.py (2)

61-70: Config mutation at import time

Setting config defaults here is convenient but surprising. Consider centralizing config defaults in a single module (or guard behind explicit env/config read) to avoid hidden side‑effects on import.

---

679-794: DWARF variant_part emission looks consistent; add two clarifying comments

• Offsets: you set each variant member’s offset to its own width (bits). This aligns with the storage scheme (data at sizeof(fetype)). Add a short comment to tie the metadata to the layout decision.
• Discriminator: mark as artificial and 8 bits — good. Consider clarifying that wrapper size = 2*maxwidth to reserve [discriminant+padding]+[max variant] as implemented in lowering.

Add comments near metadata_dict["offset"] and wrapper_struct_size explaining the memory/layout rationale.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2567b28 and a7f5393.

📒 Files selected for processing (3)

• numba_cuda/numba/cuda/debuginfo.py (3 hunks)
• numba_cuda/numba/cuda/lowering.py (3 hunks)
• numba_cuda/numba/cuda/tests/cudapy/test_debuginfo.py (3 hunks)

🧰 Additional context used

🪛 Ruff (0.14.1)

numba_cuda/numba/cuda/debuginfo.py

27-27: Consider moving this statement to an else block

(TRY300)

---

28-28: Do not catch blind exception: Exception

(BLE001)

---

54-54: Consider moving this statement to an else block

(TRY300)

---

56-56: Do not catch blind exception: Exception

(BLE001)

numba_cuda/numba/cuda/tests/cudapy/test_debuginfo.py

483-483: Unused noqa directive (unused: F841)

Remove unused noqa directive

(RUF100)

---

484-484: Unused noqa directive (unused: F841)

Remove unused noqa directive

(RUF100)

---

485-485: Unused noqa directive (unused: F841)

Remove unused noqa directive

(RUF100)

🔇 Additional comments (3)

numba_cuda/numba/cuda/tests/cudapy/test_debuginfo.py (2)

10-10: Import of config is appropriate

Needed for gating on CUDA_DEBUG_POLY. No issues.

---

407-409: Good guard for legacy-union test

Skipping union-format test when variant_part is active avoids false failures.

numba_cuda/numba/cuda/lowering.py (1)

1692-1735: Polymorphic store bypasses parent decref—low risk today, but verify NRT remains disabled

The early return at line 1735 does skip the parent's decref(fetype, old) call (line 1580 in Lower.storevar). This is harmless today because NRT defaults to disabled—decref becomes a no-op—but if CUDA_ENABLE_NRT is ever toggled, old values would leak.

NRT is disabled by default in CUDA targets via the enable_nrt property, which returns getattr(config, "CUDA_ENABLE_NRT", False), and both incref and decref guard with if not self.context.enable_nrt: return. The bypass is therefore safe under current defaults.

To defensively prevent future issues, consider guarding the early return with a check to ensure it only bypasses when NRT is disabled, and add a comment explaining why parent logic must run if NRT is ever enabled.

[jiel-nv]

/ok to test 9927acb

[jiel-nv]

/ok to test f64dddc

[jiel-nv]

/ok to test 2388791

[jiel-nv]

/ok to test d1f1dc3

[jiel-nv]

/ok to test c8dc398

[jiel-nv]

/ok to test 9932955

[jiel-nv]

@gmarkall Could you please take another look at this PR?

[gmarkall]

A couple of small nits on the diff. I'm going to merge main, fix these up and then run CI, because I think this will then be good to merge.

[gmarkall]

This import can be at the top level - llvmlite will always be available in a working Numba-CUDA installation.

[gmarkall]

With the import at the top level an ImportError should not be expected here. If the version splits into less than two parts (e.g. a single integer for some reason), we could also get an IndexError:

Suggested change

	except (ImportError, AttributeError, ValueError):
	except (IndexError, AttributeError, ValueError):

[gmarkall]

/ok to test

[gmarkall]

(Set to auto merge)