[RFC] Add __int256/__uint256 builtin types to Clang

Hi,

I’m Xavier Roche, a search engineer at Algolia. I’m not a compiler specialist, just a user of LLVM/Clang who needs 256-bit integers in production and built a proof-of-concept to explore whether a builtin type is feasible. The first question is whether this should exist at all, and if so, who should lead the effort. This RFC is a request for guidance as much as a proposal.

This PoC and this RFC were developed with AI assistance (Claude Code). I made all design decisions and reviewed the PR, but I’m not an LLVM expert. Some design choices, particularly around ABI, are probably wrong. If something in this document is off, please point it out. I’d rather be corrected early than build on flawed assumptions.

The first question: should this exist?

Before getting into technical details, there’s a higher-level go/no-go decision:

  1. Is __int256 as a builtin type worth the breadth of changes? It touches Clang, LLVM backends, compiler-rt, libc++, LLDB, libc, and Flang. Are the performance and C++ integration benefits over _BitInt(256) sufficient to justify this scope?
  2. Is it reasonable to pursue this based on an AI-aided PoC by a non-specialist? I’m a search engineer, not a compiler developer. The PoC demonstrates feasibility, but the ABI and design questions flagged below show the limits of what I can do alone. Initial feedback from @topperc, @lenary, @RKSimon, @davemgreen, and @smithp35 confirmed this: several technical claims in the original PR description turned out to be wrong, and the AI-assisted communication style was flagged as a problem. I’ve tried to address these, but they show why expert involvement is essential.
  3. Who should lead this effort? I’m happy to continue driving it, but I’m also open to stepping back. If experienced LLVM contributors would rather own the design and ABI decisions, I’d welcome that. I can help with mechanical parts (boilerplate, testing, compiler-rt builtins) while experts handle the architecture. Options: I lead with mentoring, someone else leads and I assist, or the PoC serves as a reference for a future effort.

If the answer to (1) is “no” or “not now”, that’s fine. The PoC and pre-patches stand on their own as a reference. But if there’s interest, I’d like guidance on how to proceed.

What and why

I’d like to add __int256 / __uint256 as builtin types in Clang, mirroring __int128. The primary motivation is C++ ecosystem integration that _BitInt(256) cannot provide without changes to the C++ standard: std::is_integral, std::numeric_limits, std::hash, natural overload resolution, and container support. A builtin type provides these out of the box, just as __int128 does today. There is no near-term prospect of _BitInt gaining these traits through standardization.

A secondary motivation is the performance opportunity from register-based ABI on targets where the platform ABI allows it. _BitInt(256) uses sret/byval on all targets. A builtin type can potentially use register passing, eliminating stack copy overhead at function boundaries. This advantage is target-dependent and unresolved: the PoC currently uses indirect passing on x86-64 (matching _BitInt(256) and the SysV ABI), while AArch64 uses direct register passing (pending AAPCS review). RISC-V and s390x use indirect passing.

The comparison between a builtin type and _BitInt(256):

Feature __uint256_t unsigned _BitInt(256)
a == b, a < b, a ^ b same IR operations same IR operations
__builtin_clzg(a) same IR operations same IR operations
a / b (division) compiler-rt libcall ~289 x86 insns inline expansion (1)
std::is_integral true false
std::numeric_limits specialized unspecialized
std::hash / containers works needs user specialization
Overload resolution natural integer rank no implicit conversions
printf format possible (extension) explicitly excluded by spec

(1) Without the MaxDivRemBitWidthSupported change. On AArch64, MaxDivRem=256 routes both types through a compiler-rt libcall (also benefiting existing _BitInt(256) code). On x86-64, MaxDivRem stays at 128 due to an ABI incompatibility between frontend indirect passing and backend libcall conventions, so division expands inline (~289 instructions).

Both types produce the same i256 operations in LLVM IR. Machine code differs due to calling convention: function signatures use different passing mechanisms (direct register vs. sret/byval) depending on the target and type. Within a single translation unit where the compiler can inline, both types produce equivalent code.

Use cases include SHA-256 digest operations, DHT routing (Kademlia), block deduplication (ZFS), and blockchain arithmetic. Database analytics is another area: ClickHouse moved from a software bigint library to _BitInt(256) for 4.7x mul / 20x div speedup, demonstrating the value of compiler-native 256-bit support. A builtin type would provide the same codegen benefits plus C++ integration (overload resolution, type traits, containers) without workarounds.

Prior art

  • __int128 in Clang/GCC: The direct precedent. Shipping for over a decade with register-based ABI on 64-bit targets.
  • GCC OImode: GCC’s machine description defines OImode (OctaInteger, 256-bit) but does not expose it as a usable type. __attribute__((__mode__(__OI__))) produces error: unable to emulate 'OI'. A 2012 patch series proposed __int256 for GCC but was never completed.
  • No compiler currently provides __int256 as a builtin type.

Proof of concept

The implementation is available as draft PR #182733 (17 commits, ~291 files). It covers Clang (type system, AST, sema, codegen, mangling), LLVM backends (X86, AArch64, data layout), compiler-rt (39 builtins + UBSan), libc++, LLDB, libc, and Flang. CI passes: check-clang (50,910 tests, 0 failures), check-clang-cir (527 tests, 0 failures), check-llvm (72,482 tests, 0 failures), check-flang (4,237 tests, 0 failures), check-lld (3,173 tests, 0 failures). Compiler-rt builtins pass on 9 architectures via QEMU:

Target Endian Result
x86-64 LE 39/39 pass
AArch64 LE 39/39 pass
RISC-V 64 LE 39/39 pass
PPC64le LE 37/39 pass (2 tf link failures, IBM double-double)
PPC64 BE 37/39 pass (2 tf link failures, IBM double-double)
s390x BE 39/39 pass
MIPS64el LE 39/39 pass
LoongArch64 LE 39/39 pass
SPARC64 BE 39/39 pass

32-bit targets (ARM32, i686): __int256 correctly rejected at sema level.

libc++ integration tested via cross-built static libc++ on 12 architectures (8 x 64-bit, 4 x 32-bit). Each target runs 8 tests: type_traits, numeric_limits, bit_ops, byteswap, charconv (to_chars, from_chars), format, hash.

Target Pointer Result Notes
x86-64 64 8/8 pass
AArch64 64 8/8 pass
RISC-V 64 64 8/8 pass
PPC64le 64 8/8 pass
PPC64 64 8/8 pass big-endian
s390x 64 8/8 pass big-endian
MIPS64el 64 8/8 pass
LoongArch64 64 8/8 pass
SPARC64 64 8/8 pass big-endian
ARM32 32 8/8 pass _LIBCPP_HAS_INT256=0, all skip gracefully
i686 32 8/8 pass _LIBCPP_HAS_INT256=0, all skip gracefully
MIPSel 32 8/8 pass _LIBCPP_HAS_INT256=0, all skip gracefully
PPC32 32 8/8 pass _LIBCPP_HAS_INT256=0, all skip gracefully

The 32-bit targets validate that the conditional compilation (#ifdef _LIBCPP_HAS_INT256) does not break libc++ on platforms where __int256 is unavailable.

Baseline codegen test pre-patches (independent of this work): #183586 (X86), #183587 (AArch64), #183588 (RISCV).

Most of the implementation is systematic, following the __int128 pattern in each file. The compiler-rt builtins are the largest new-code component.

Known design gaps

I’ve tried to follow __int128’s design throughout, but __int128 fits neatly within existing ABI specifications (2 eightbytes on x86-64 SysV, 16 bytes on AArch64 AAPCS). __int256 does not. The ABI story is the weakest part of this proposal, and I’m aware several choices may be wrong. Other areas likely have gaps I haven’t identified yet.

1. x86-64 SysV: now using strict MEMORY-class passing

__int256 is 4 eightbytes, exceeding the SysV 2-eightbyte limit. classify() correctly returns MEMORY. The PoC initially inherited the upstream non-aggregate bypass in getIndirectResult(), which converted scalar builtins (excluding _BitInt) to ABIArgInfo::getDirect(), producing i256 in IR. The backend split this into 4 x i64 and distributed across registers. This deviated from the SysV ABI and caused a va_arg correctness bug (returning garbage values).

The PoC now adds a size check: scalar types >128 bits use indirect passing (sret for returns, byval for arguments), matching _BitInt(256) behavior and the SysV ABI specification. va_arg works correctly with this approach. This eliminates any x86-64 performance advantage over _BitInt(256), but is ABI-conformant. Is this the right trade-off, or should register passing be reconsidered with explicit x86-64 psABI coordination?

2. AArch64 AAPCS: >16-byte type in registers

On AArch64, __int256 currently passes arguments and return values in x0-x3 (4 GPRs). An identity function compiles to a single ret. However, the AAPCS requires indirect passing for composite types >16 bytes, and the current 16-byte rule exists for good reason: the AAPCS does not allow a type to be half in registers and half on the stack, so a 32-byte type would consume half the argument registers (only 1-2 __int256 values could be passed directly).

__int256 is a builtin scalar that would rarely appear in general-purpose code, but this still needs formal ABI coordination, not a unilateral Clang decision. If we agree this feature is worth pursuing, an issue should be opened at ARM-software/abi-aa to discuss with ABI maintainers and the GCC team. Someone with ABI expertise would be better suited to lead that conversation than me.

3. Other 64-bit targets: ABI behavior needs review

hasInt256Type() defaults to pointerWidth >= 64, meaning __int256 is enabled on all 64-bit targets: PPC64, s390x, MIPS N64, SPARC64, LoongArch64, BPF, VE, WebAssembly64, etc. Compiler-rt builtins have been tested via QEMU on PPC64le, PPC64 (big-endian), s390x, MIPS64el, LoongArch64, and SPARC64 (all pass, including all three big-endian targets), but ABI conformance has not been audited on any of these.

The actual calling conventions vary widely by target with no explicit frontend decision: PPC64le passes and returns __int256 in GPRs (r3-r6 / r7-r10) with an identity function compiling to a bare blr; RISC-V 64 and s390x use fully indirect passing (sret + pointer arguments); other targets fall through to backend-default behavior. On PPC64le, this may actually be ELFv2-conformant (scalar values up to 8 quadwords pass in registers), but this needs verification. Should __int256 be initially restricted to x86-64 and AArch64, with other targets added after ABI review?

Unlike __int128, which is available on some 32-bit targets (e.g. ARM32 with 4 x 32-bit GPRs), __int256 is restricted to 64-bit targets. On a 32-bit target, a single __int256 value would require 8 GPRs, which is impractical on register-constrained architectures (ARM32 has 14 usable GPRs). The compiler-rt builtins are portable and work on 32-bit, but the type is rejected at the sema level. This could be revisited for specific 32-bit targets if there’s demand, but it is not part of this proposal.

4. Alignment

__int256 does not add i256:256 to any target data layout string. Instead, i256 inherits 16-byte alignment from the existing i128:128 entry. This matches how __int256 is actually used: arithmetic is performed on 4 x 64-bit values in GPRs, and memory operations are decomposed into 64-bit (or 128-bit SSE/NEON) loads and stores. No hardware instruction on any current target loads or stores a 256-bit scalar integer as a single operation – that capability exists only for vector types (__m256i on x86 with AVX).

This avoids a massive data layout blast radius: adding i256:256 to all 64-bit targets would change every data layout string, breaking thousands of existing tests that embed these strings (LTO bitcode modules, CodeGen CHECK lines, etc.). If per-target 32-byte alignment is desired in the future (e.g., for AVX-aligned spills), it can be added as a focused, mechanical follow-up.

6. MaxDivRemBitWidthSupported raised to 256 (AArch64 only)

This is raised on AArch64 only. On x86-64 it stays at 128 because the backend generates libcalls using a split-scalar convention (4 x i64 in registers) that is incompatible with the frontend’s indirect passing convention (sret/byval) for __int256. On AArch64, the Direct ABI (4 GPRs) matches the backend’s convention, so the libcall optimization works correctly there. On x86-64 and RISC-V, i256 division expands at the IR level via ExpandLargeDivRem (~289 x86 instructions). This is a performance optimization, not a correctness fix: the ExpandIRInsts pass (added in 2022) already handles wide division correctly, just with much larger code. On AArch64, this also improves _BitInt(N) for 128 < N <= 256 as a side effect. Should this be a separate PR?

7. Naming and encoding choices

Some choices follow established conventions and are “lower-risk”:

  • compiler-rt prefix: oi (octa-integer) following the si/di/ti convention, consistent with GCC’s existing OImode
  • __SIZEOF_INT256__ macro: follows __SIZEOF_INT128__ pattern

Others are arbitrary placeholders that would need external coordination before the ABI is locked, especially if GCC also implements __int256:

  • Itanium mangling: u7__int256 / u8__uint256 (vendor-extended). This should be coordinated with the Itanium ABI maintainers before shipping.
  • Microsoft mangling: $$_L / $$_M. Arbitrary, could conflict with future MSVC choices. Needs coordination if Microsoft ever supports the type.
  • Objective-C @encode: w/W. Arbitrary next pair after t/T (i128).

These can all be finalized during code review, but the Itanium and Microsoft manglings in particular should not be locked in without coordination.

8. libc++ is_integral = true

__int256 satisfies std::is_integral (like __int128), while _BitInt(256) does not (per C++ standard). This matches __int128 behavior but may surprise users who expect is_integral to cover only standard types.

9. CUDA accepts __int256 on all device targets

CUDA inherits the host type system, so __int256 is accepted in CUDA mode even though GPU hardware has no 256-bit integer support. SYCL correctly rejects it on SPIR targets. Should CUDA be more restrictive?

Alternatives considered

  1. Improving _BitInt(256) ABI. Making _BitInt(256) use register passing for common widths would address the performance gap. This is a separate, complementary effort that would benefit all _BitInt users. However, it does not address std::is_integral, std::numeric_limits, std::hash, or natural overload resolution, which require changes to the C++ standard. __int256 fills the C++ ecosystem gap that _BitInt structurally cannot.

  2. Library-only uint256 class. A class with operator overloads can provide syntactic convenience, but cannot match builtin codegen (the compiler cannot optimize through opaque function calls the same way), cannot provide std::is_integral<uint256> == true, and cannot participate in the language’s implicit conversion and overload resolution rules.

  3. Compiler intrinsics without a new type (e.g., __builtin_add256). This would provide fast operations without a type system change, but sacrifices type safety, template integration, and the ability to use standard containers and algorithms directly.

What this RFC is NOT

  • Not a proposal to standardize 256-bit integers in C/C++
  • Not a final patch series, just a basis for community feedback
  • Not claiming _BitInt(256) should be replaced or deprecated

Open questions (if we proceed)

Some of these can be decided within LLVM during code review. Others require external coordination and would gate the ABI before it can be locked in.

Internal decisions (can be resolved during LLVM review):

  1. ABI per target. The PoC currently uses indirect passing (sret/byval) on x86-64, matching _BitInt(256) and the SysV ABI. AArch64 uses direct register passing (4 GPRs), which is fast but of uncertain AAPCS conformance. PPC64le also uses direct register passing. RISC-V and s390x use indirect. Should all targets start with indirect passing (safe, ABI-conformant, no performance advantage) and move to register passing only after formal ABI coordination per target?
  2. ABI stability. The ABI is not proposed as stable in this initial implementation. __int256 should ship with an explicit “ABI may change” warning until formal ABI coordination is complete per target. This avoids creating legacy constraints from a first-draft ABI.
  3. Target scope: All 64-bit targets, or x86-64 + AArch64 initially?
  4. Is the _BitInt ABI the right thing to fix instead? Improving _BitInt(256) ABI for common widths is a separate, complementary effort. It would not address is_integral, numeric_limits, std::hash, or natural overload resolution, which require changes to the C++ standard. __int256 fills the C++ ecosystem gap that _BitInt structurally cannot.
  5. Alignment: The implementation uses inherited 16-byte alignment (from i128:128) with no data layout string changes. Should any target use 32-byte alignment? If so, that can be a follow-up PR.
  6. RISC-V tail call with indirect arguments: During cross-architecture testing, we observed that RISC-V tail-calls functions whose arguments are passed indirectly (via a pointer to caller-allocated stack space). X86 explicitly rejects this case in isEligibleForTailCallOptimization (X86ISelLoweringCall.cpp). The existing RISC-V test tail-calls.ll has a comment “Do not tail call optimize if parameters need to be passed indirectly” but the test CHECK lines showed it IS being tail-called. This affects any type requiring indirect passing on RISC-V (fp128 on RV32, i256 on RV64, etc.) and is not specific to __int256. We have a proposed fix; if confirmed, it should land independently.

External coordination needed (before locking the ABI):

  1. AArch64 AAPCS: Formal discussion at ARM-software/abi-aa to decide register vs. indirect passing, ideally led by someone with ABI expertise.
  2. Itanium mangling: Coordinate u7__int256 / u8__uint256 with Itanium ABI maintainers.
  3. Microsoft mangling: Coordinate $$_L / $$_M with Microsoft if they have interest in the type.
  4. GCC alignment: If GCC implements __int256 (building on their existing OImode), ABI choices should be consistent across compilers.
Motivating examples (SHA-256 digests, Kademlia DHT routing, ZFS dedup)

Motivating examples

256-bit integers come up wherever SHA-256 hashes are treated as values rather than opaque byte arrays. Today, C and C++ code represents these as uint8_t[32] with memcmp for comparison, byte-by-byte loops for XOR, and manual bit extraction for prefix length. With __uint256_t, each of these is a single expression.

SHA-256 digest operations

SHA-256 is used in TLS, Git (SHA-256 object format), ZFS (block checksums), IPFS (content addressing), and Nix (store paths). Common operations on 256-bit digests include equality comparison, ordering (for sorted indices), XOR distance (for DHTs), and leading-zero counting (for proof-of-work).

#include <stdint.h>
#include <stdbool.h>
#include <string.h>

// --- Today: SHA-256 digest as a byte array ---

typedef uint8_t sha256_t[32];

bool sha256_equal(const sha256_t a, const sha256_t b) {
    return memcmp(a, b, 32) == 0;
}

bool sha256_less(const sha256_t a, const sha256_t b) {
    // Must compare big-endian, byte by byte
    for (int i = 0; i < 32; i++) {
        if (a[i] != b[i])
            return a[i] < b[i];
    }
    return false;
}

void sha256_xor(sha256_t out, const sha256_t a, const sha256_t b) {
    for (int i = 0; i < 32; i++)
        out[i] = a[i] ^ b[i];
}

int sha256_leading_zeros(const sha256_t h) {
    int count = 0;
    for (int i = 0; i < 32; i++) {
        if (h[i] == 0) { count += 8; continue; }
        for (int bit = 7; bit >= 0; bit--) {
            if (h[i] & (1 << bit)) return count;
            count++;
        }
    }
    return 256;
}

// --- With __uint256_t (native integer storage convention) ---

bool sha256_equal(__uint256_t a, __uint256_t b) { return a == b; }
__uint256_t sha256_xor(__uint256_t a, __uint256_t b) { return a ^ b; }

// Ordering and CLZ require native integer byte order -- see note below
bool sha256_less(__uint256_t a, __uint256_t b)  { return a < b; }
int sha256_leading_zeros(__uint256_t h)  { return __builtin_clzg(h); }

Endianness caveat: Equality (==) and XOR (^) are byte-order-neutral and work correctly after a raw memcpy from any byte sequence. However, ordering (<) and leading-zero counting (__builtin_clzg) depend on byte significance. SHA-256 digests are big-endian byte sequences (h[0] is the most significant byte), but on little-endian targets (x86-64, AArch64), memcpy into __uint256_t reverses the byte significance: h[0] becomes the integer’s least significant byte. This means a < b gives the opposite ordering from the byte-array version, and __builtin_clzg counts from the wrong end. For ordering and CLZ with big-endian input data, a byteswap at the load boundary is needed (e.g., std::byteswap in C++23, which this implementation supports for __uint256_t). Alternatively, if both producer and consumer use native integer storage consistently (not raw big-endian bytes), ordering and CLZ work correctly without byteswap.

On x86-64, the __uint256_t versions compile to branchless straight-line code: equal (9 insns, 29 bytes), less (6 insns, 20 bytes), xor (10 insns, 37 bytes), leading_zeros (18 insns, 62 bytes). The byte-array equivalents use loops and conditional branches: equal (11 insns, 43 bytes; memcmp is SSE-optimized), less (25 insns, 89 bytes; byte-by-byte loop), xor (36 insns, 120 bytes), leading_zeros (61 insns, 165 bytes). AArch64 shows similar ratios.

Kademlia DHT routing (IPFS, BitTorrent)

Kademlia is the distributed hash table protocol used by IPFS, BitTorrent, and Ethereum’s node discovery. Nodes are identified by 256-bit IDs (typically SHA-256 of the public key), and the core operation is XOR distance: the “distance” between two node IDs is their bitwise XOR, interpreted as an unsigned integer.

typedef __uint256_t node_id;

// XOR distance between two nodes
static inline __uint256_t distance(node_id a, node_id b) {
    return a ^ b;
}

// Which k-bucket does a peer belong to?
// = index of the highest differing bit (0-255)
static inline int bucket_index(node_id self, node_id peer) {
    __uint256_t dist = self ^ peer;
    if (dist == 0) return -1;  // same node
    return 255 - __builtin_clzg(dist);
}

// Is node A closer than node B to the target?
static inline bool is_closer(node_id a, node_id b, node_id target) {
    return (a ^ target) < (b ^ target);
}

Without a native 256-bit type, libp2p (the IPFS networking stack) implements this with byte arrays and manual loops. The byte-array is_closer compiles to 88 instructions / 323 bytes on x86-64 (49 insns / 196 bytes on AArch64), with conditional branches and SSE operations. With __uint256_t, it compiles to 20 branchless instructions / 66 bytes on x86-64 (16 insns / 64 bytes on AArch64).

ZFS block deduplication

ZFS uses SHA-256 checksums for block-level deduplication. The dedup table (DDT) maps checksums to block references. Lookups require comparing and sorting 256-bit keys:

struct ddt_entry {
    __uint256_t checksum;   // SHA-256 of block content
    uint64_t    block_ref;  // physical block address
    uint32_t    ref_count;  // number of references
};

// Binary search in a sorted DDT -- native comparison operators
bool ddt_lookup(const struct ddt_entry *table, size_t n,
                __uint256_t target, uint64_t *block_out) {
    size_t lo = 0, hi = n;
    while (lo < hi) {
        size_t mid = lo + (hi - lo) / 2;
        if (table[mid].checksum < target)
            lo = mid + 1;
        else
            hi = mid;
    }
    if (lo < n && table[lo].checksum == target) {
        *block_out = table[lo].block_ref;
        return true;
    }
    return false;
}

Today, OpenZFS represents checksums as uint64_t[4] and implements custom comparison functions. A native type enables standard qsort, C++ std::sort, std::lower_bound, and std::unordered_map (with trivial hash) to work directly on checksum values.

Micro-benchmark: ABI impact on arithmetic operations (x86-64)

Micro-benchmark

Single-machine micro-benchmark comparing __uint256_t, _BitInt(256), and manual uint128_t[2] on x86-64 (AMD Ryzen, -O2 -march=native). This measures ABI overhead, not algorithmic advantage. Not a performance claim – results are anecdotal and CPU-dependent.

On x86-64, __uint256_t and _BitInt(256) now use the same calling convention (sret/byval), so most operations produce identical codegen. The “manual” column uses a struct of two __uint128_t with inline helper functions.

Operation __uint256_t _BitInt(256) manual native/man bitint/man
add 2.18 ns 5.45 ns 5.33 ns 2.4x 1.0x
sub 5.34 ns 5.56 ns 5.24 ns 1.0x 0.9x
mul 7.23 ns 7.17 ns 6.92 ns 1.0x 1.0x
udiv 17.03 ns 16.92 ns 293.94 ns 17.3x 17.4x
umod 20.49 ns 19.85 ns 310.34 ns 15.1x 15.6x
xor 4.46 ns 4.50 ns 5.60 ns 1.3x 1.2x
and 4.44 ns 4.49 ns 5.60 ns 1.3x 1.2x
or 4.46 ns 4.49 ns 5.60 ns 1.3x 1.2x
shl 6.90 ns 6.63 ns 3.27 ns 0.5x 0.5x
lshr 6.95 ns 6.76 ns 5.66 ns 0.8x 0.8x
popcount 5.03 ns 5.12 ns 4.86 ns 1.0x 0.9x
clz 5.45 ns 5.45 ns 4.96 ns 0.9x 0.9x
lt 4.67 ns 4.63 ns 4.48 ns 1.0x 1.0x

Observations:

  • Division/modulo: Both builtin types are 15-17x faster than manual (which uses a naive loop). This is the ExpandLargeDivRem IR pass, not a library call on x86-64.
  • Bitwise ops: ~1.2-1.3x faster than manual due to avoiding struct overhead.
  • Shifts: Manual is faster (0.5x for shl) because the compiler can inline a simple two-word shift, while the builtin goes through ExpandThroughStack legalization.
  • __uint256_t vs _BitInt(256): Nearly identical on x86-64, as expected given the same ABI. The add outlier (2.18 ns vs 5.45 ns) is a measurement artifact: both produce identical assembly (verified with -S), and 2.18 ns for add being faster than 4.46 ns for xor is physically implausible. Likely a cache/ordering effect from the benchmark running native first with warm caches from input generation.
  • The motivation for __int256 is C++ ecosystem integration (is_integral, numeric_limits, hash, overload resolution), not raw performance over _BitInt(256).

AI disclosure

This implementation was developed with AI assistance (Claude Code) under human direction. ~43 hours of active pairing across 24 sessions, ~360 human prompts. Only ~30% was writing code; the rest was testing, review, git hygiene, and communication. All commits carry Assisted-by: Claude (Anthropic) trailers per the LLVM AI Tool Policy.

I (Xavier Roche) made all design decisions, reviewed all source code, and ran all testing. Machine-generated content (such as .ll CHECK lines from update_llc_test_checks.py) was validated through test runs rather than line-by-line review.

Links

Gcc is most likely not going to add __int256. Currently gcc is also not going to add __int128 for ilp32 targets either. The only route for gcc will be via BitInt. It seems better to push wg21 for BitInt support rather than add another integer extension. As I have seen the need for 1024 bit integers in the near future.

Also there could be variants of the abi for local functions for medium BitInt types. This does not even need to be exposed to the user. Llvm could optimize to change the abi for local functions such that the medium types are passed via registers. Each backend and middle end will change but nothing else.

2 Likes

My personal stance is that this is already covered by _BitInt and we should not add dedicated sizes for every interesting integer bit width. There are efforts in WG21 to standardize _BitInt which has some amount of committee traction, so I think efforts should be put towards that instead.

4 Likes

Thank you both for the quick feedback!

I get the position: _BitInt is the standardized path, and adding fixed-width builtin types for every interesting width doesn’t scale much (and I guess we would need even more than 1024 for some cryptographic cases). If the consensus is that this isn’t the right direction for Clang, let’s bury the RFC.

Before closing the book on this, I’d like to flag two concerns about the _BitInt path that I haven’t seen addressed:

  • std::is_integral<_BitInt(N)> is false by design in the C++ standard (WG21 excluded it from the integral type traits I believe), which also mean you don’t get the free meal (std::numeric_limits, std::hash, container key types, or overload resolution with other integer types)
  • the other concern is the moving pace of WG21; this is probably a multi-year effort with uncertain outcome

In any case, the exercise produced a few concrete upstream contributions that might be worth considering:

Thanks again for the feedback!

I think the main flaw in your thinking here is that we can’t consider `_BitInt` to be an extended integer type. libc++ already claims `is_integral_v<_BitInt(N)>`. We’ve simply had nobody doing the actual work to make all the changes required to implement the features that have to be provided by extended integer types. If you want to do that I’m sure we’re happy to take patches. You should probably write a short RFC which lists all the areas that would have to be updated, but I don’t see anybody being against this.

2 Likes

I think the C ABIs for any __int256 types (and __int128 too) should be identical to the corresponding _BitInt types, since Rust intentionally only has one fixed-width integer type for each signedness-width pair, so Rust would only have a single u256 type and a singlei256 type, so for ABI compatibility with C I think __int256 and _BitInt(256) need to have identical ABIs.

1 Like

Thanks a lot philnik for the feedback - I have posted ( _BitInt(N) support in libc++: investigations, possile improvements: looking for guidance ) a new topic find a couple of findings and possible improvements. If this can help, I’d be happy to contribute; otherwise this can be the beginning of possible follow-ups!

The PR draft for 256-bit integer is now closed; the much better approach seems to be focusing on _BitInt.

2 Likes