Cranelift aarch64 panic when bitcasting into vectors: root cause and fix

This crash is triggered by a very specific lowering gap: a scalar value is bitcast into a small SIMD vector, then immediately used by a vector arithmetic instruction on AArch64/NEON. In the failing path, Cranelift ends up with an illegal or unsupported combination during legalization or instruction selection, and the backend panics instead of rewriting the IR into a form the target can encode safely.

Reproducing the panic

The issue appears with a test like this, where a 64-bit integer is reinterpreted as a smaller vector and then used in a vector add:

test compile
target aarch64

function %bitcast_neon_repro() -> i64x2 {
block0:
    v0 = iconst.i64 0x0001_0001_0001_0001
    v1 = bitcast.i16x4 little v0
    v2 = iadd v1, v1
    ; ... more operations or return path

At first glance, this looks harmless. A bitcast should preserve bits without changing data, and i16x4 addition is a standard NEON operation. The failure happens because the value begins life as a scalar integer, but later gets consumed as a vector lane structure. That transition is where the backend can lose a valid lowering strategy.

Understanding the Root Cause

Cranelift distinguishes between type-level reinterpretation and target-legal machine values. In the IR, bitcast.i16x4 little v0 means “treat these 64 bits as four 16-bit lanes.” However, on AArch64, the backend still needs a legal way to materialize that value in a NEON register or transform it into equivalent operations.

The panic usually comes from one of these backend mismatches:

• A scalar GPR-originated constant is reinterpreted as a vector, but no legalization path inserts the proper move into a SIMD register class.
• The vector type created by the bitcast is valid in IR but not in the exact form expected by the AArch64 lowering rules.
• Subsequent vector arithmetic like iadd assumes a legal vector value already exists, but the previous bitcast produced an intermediate form the backend cannot select.
• Endianness metadata such as little on the bitcast can further constrain how lanes are interpreted, exposing missing rewrites or assertions.

In short, the bug is not that vector addition is invalid. The bug is that scalar-to-vector reinterpretation through bitcast is not fully legalized for this code path on aarch64, and the backend panics instead of converting it into a canonical NEON-friendly sequence.

Step-by-Step Solution

The most reliable fix is to avoid depending on a direct scalar-to-vector bitcast in the problematic path. Rewrite the IR so the vector value is constructed in a way the AArch64 backend already knows how to lower.

1. Replace scalar bitcast with explicit vector construction

If the scalar constant is only being used to create repeated 16-bit lanes, build the vector directly:

function %bitcast_neon_fixed() -> i16x4 {
block0:
    lane = iconst.i16 1
    v = splat.i16x4 lane
    r = iadd v, v
    return r

This is the cleanest approach because it keeps the value in a vector-native form from the start.

2. If exact bit layout matters, use lane insertion instead of bitcast

When you need the literal 64-bit pattern to define lane contents, build the vector explicitly:

function %bitcast_neon_fixed_explicit() -> i16x4 {
block0:
    v0 = iconst.i16 1
    v1 = iconst.i16 1
    v2 = iconst.i16 1
    v3 = iconst.i16 1
    base = vconst.i16x4 [0, 0, 0, 0]
    a = insertlane base, v0, 0
    b = insertlane a, v1, 1
    c = insertlane b, v2, 2
    d = insertlane c, v3, 3
    r = iadd d, d
    return r

This avoids the illegal scalar-to-vector reinterpretation step entirely.

3. Canonicalize the problematic pattern in the backend or legalization pass

If you are fixing Cranelift itself rather than just working around the issue in input IR, add a legalization rule that rewrites:

bitcast.i16x4 little (iconst.i64 K)

into a legal vector constant or lane construction sequence before instruction selection.

A conceptual legalization rule looks like this:

match v = bitcast.i16x4 little x
where x : i64

if x is iconst.i64 K:
    lanes = split_64bit_constant_into_4x16_lanes(K, little_endian=true)
    replace v with vconst.i16x4 lanes
else:
    tmp = move_scalar_to_vector_register(x)
    replace v with reinterpret_vector_from_simd(tmp)

The exact implementation depends on Cranelift’s current legalization and ISLE structure, but the idea is stable: normalize the value before vector ALU ops see it.

4. Add a regression test

Once fixed, preserve the behavior with a compile test targeted at AArch64:

test compile
target aarch64

function %bitcast_neon_repro_fixed() -> i16x4 {
block0:
    lane = iconst.i16 1
    v = splat.i16x4 lane
    r = iadd v, v
    return r
}

If you are patching the compiler, keep the original failing shape too, so the backend is forced to handle it without panicking:

test compile
target aarch64

function %bitcast_neon_repro() -> i16x4 {
block0:
    raw = iconst.i64 0x0001_0001_0001_0001
    vec = bitcast.i16x4 little raw
    sum = iadd vec, vec
    return sum
}

5. Verify on the actual target path

Do not stop at a generic compile check if the bug originally occurred during backend lowering. Run the test through the AArch64 codegen path and confirm there is no panic during legalization, register allocation, or final emission.

Common Edge Cases

• Different vector widths: The same issue can show up with i8x8, i32x2, or wider types if the backend lacks a legal reinterpretation path for that exact shape.
• Non-constant scalar sources: Constants are easier to canonicalize. If the source is a runtime i64, the backend may need an explicit scalar-to-SIMD register transfer before any vector op.
• Endianness-sensitive lane order: A raw 64-bit pattern split into 16-bit lanes must preserve the intended little-endian mapping. A fix that builds the vector with reversed lanes will compile but compute the wrong result.
• Return type mismatch in tests: The sample issue snippet shows a function returning i64x2 while intermediate values are i16x4. Make sure the final IR returns a type consistent with the value produced, or add an explicit conversion path.
• Backend-specific legality: An IR pattern may compile on x86 with SSE/AVX and still fail on AArch64 because register classes and legalizations differ.
• Using bitcast after arithmetic: Reinterpreting vectors back into scalars can trigger the inverse problem if there is no legal move from SIMD registers to GPRs for the exact type combination.

FAQ

Why does bitcast panic here if it is supposed to be a no-op?

It is a no-op at the semantic level, not necessarily at the machine lowering level. The backend still must represent that value in a legal register class and instruction sequence.

Is this an AArch64 bug or a Cranelift bug?

This is a Cranelift backend/legalization bug on the AArch64 path. AArch64 NEON can handle vector arithmetic, but Cranelift must transform the IR into a legal target form first.

What is the safest workaround in user-generated CLIF?

Avoid scalar-to-vector bitcast when the result will immediately feed vector arithmetic. Prefer vconst, splat, or explicit insertlane construction so the value starts as a legal vector.

The practical takeaway is simple: if a value will be consumed by NEON vector operations, construct it as a vector rather than relying on a scalar reinterpretation. That eliminates the unsupported transition that causes the panic and gives Cranelift a legal path all the way through AArch64 code generation.