[API Proposal]: `Unsafe.BitCast` for efficient type reinterpretation

[MichalPetryka]

Background and motivation

Reinterpretation of types - especially value ones - is a common occurrence in high performance code.
Currently in C#, it is usually realized using the Unsafe.As API or with the *(TTo*)&value pattern. The JIT however has some issues with optimizing such code, due to the value being marked as address taken. Introducing a new API with a more descriptive name might be easier and cheaper than making the JIT recognize such pattern.

The name BitCast was inspired by the C++ std::bit_cast and LLVM bitcast.

Open questions:

1. Should the API have any generic constraints? Restricting it to unmanaged or struct types would make it safer to use but potentially less useful in generic contexts (for example with Enum constraint, since that by itself doesn't restrict it to such types).
2. What should the behaviour be for non matching size types? As I see it, there are two reasonable options:
   a) make the API throw in such case - that's what the C++ and LLVM bitcasts do, not really useful but could be regarded as the expected behaviour.
   b) make the API function as if a buffer of the larger size was created (and zero initialized), the value written into it and then the target type read from its beginning. This behaviour would allow the API to be utilized in the current code that reads a smaller type from the beginning of a larger one with Unsafe.As and could be used for extending stuff like Vectors.
3. Would BitCast or Bitcast be the preferred casing?

With different sizes being permitted the code would behave like this:

unsafe static TTo BitCast<TFrom, TTo>(TFrom value)
{
    if (sizeof(TFrom) >= sizeof(TTo))
        return *(TTo*)&value;
    TTo v = default;
    *(TFrom*)&v= value;
    return v;
}

With only same sizes being accepted it'd work like this:

unsafe static TTo BitCast<TFrom, TTo>(TFrom value)
{
    if (sizeof(TFrom) != sizeof(TTo))
        throw new NotSupportedException();
    return *(TTo*)&value;
}

API Proposal

namespace System.Runtime.CompilerServices;

public static class Unsafe
{
    public static TTo BitCast<TFrom, TTo>(TFrom value);
}

API Usage

runtime/src/libraries/System.Private.CoreLib/src/System/SpanHelpers.T.cs

Lines 39 to 60 in ae6a73f

	if (sizeof(T) == 1)
	{
	vector = new Vector<byte>(Unsafe.As<T, byte>(ref tmp));
	}
	else if (sizeof(T) == 2)
	{
	vector = (Vector<byte>)(new Vector<ushort>(Unsafe.As<T, ushort>(ref tmp)));
	}
	else if (sizeof(T) == 4)
	{
	// special-case float since it's already passed in a SIMD reg
	vector = (typeof(T) == typeof(float))
	? (Vector<byte>)(new Vector<float>((float)(object)tmp!))
	: (Vector<byte>)(new Vector<uint>(Unsafe.As<T, uint>(ref tmp)));
	}
	else if (sizeof(T) == 8)
	{
	// special-case double since it's already passed in a SIMD reg
	vector = (typeof(T) == typeof(double))
	? (Vector<byte>)(new Vector<double>((double)(object)tmp!))
	: (Vector<byte>)(new Vector<ulong>(Unsafe.As<T, ulong>(ref tmp)));
	}

// instead of non generic BitConverter APIs:
// Console.WriteLine(BitConverter.UInt32BitsToSingle(12345));
Console.WriteLine(Unsafe.BitCast<uint, float>(12345));
// prints 1.7299E-41

// bitcasting to a same sized type
Console.WriteLine(Unsafe.BitCast<Vector4, Vector128<float>>(new Vector4(1f, 2f, 3f, 4f)));
// prints <1, 2, 3, 4>

// bitcasting to a smaller type
Console.WriteLine(Unsafe.BitCast<Vector4, Vector2>(new Vector4(1f, 2f, 3f, 4f)));
// prints <1, 2>

// bitcasting to a bigger type
Console.WriteLine(Unsafe.BitCast<Vector2, Vector4>(new Vector2(1f, 2f)));
// prints <1, 2, 0, 0>

Alternative Designs

Using Unsafe.As for same sized or smaller types, writing to a stack allocated, zero initialized, buffer of the destination type size and reading from it.

Risks

Unsafely reinterpreting managed types if there are no generic constraints can lead to GC holes, unexpected behaviour on big endian platforms for non matching sizes can cause code to become platform specific.

Tagging subscribers to this area: @dotnet/area-system-numerics
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

Reinterpretation of types - especially value ones - is a common occurrence in high performance code.
Currently in C#, it is usually realized using the Unsafe.As API or with the *(TTo*)&value pattern. The JIT however has some issues with optimizing such code, due to the value being marked as address taken. Introducing a new API with a more descriptive name might be easier and cheaper than making the JIT recognize such pattern.

The name Bitcast was inspired by the C++ std::bit_cast and LLVM bitcast.

Open questions:

1. Should the API have any generic constraints? Restricting it to unmanaged or struct types would make it safer to use but potentially less useful in generic contexts (for example with Enum constraint, since that by itself doesn't restrict it to such types)?
2. What should the behaviour be for non matching size types? As I see it, there are two reasonable options:
   a) make the API throw in such case - that's what the C++ and LLVM bitcasts do, not really useful but could be regarded as the expected behaviour
   b) make the API function as if a buffer of the larger size was created (and zero initialized), the value written into it and then the target type read from its beginning. This behaviour would allow the API to be utilized in the current code that reads a smaller type from the beginning of a larger one with Unsafe.As and could be used for extending stuff like Vectors.

With different sizes being permitted the code would behave like this (at least for unmanaged types, ignore the inefficient implementation):

unsafe static TTo Bitcast<TFrom, TTo>(TFrom value)
{
    byte* s = stackalloc byte[Math.Max(sizeof(TFrom), sizeof(TTo))];
    new Span<byte>(s, Math.Max(sizeof(TFrom), sizeof(TTo))).Clear();
    *(TFrom*)s = value;
    return *(TTo*)s;
}

With only same sizes being accepted it'd work like this:

unsafe static TTo Bitcast<TFrom, TTo>(TFrom value)
{
    if (Unsafe.SizeOf<TFrom>() != Unsafe.SizeOf<TTo>())
        throw new NotSupportedException();
    return Unsafe.As<TFrom, TTo>(ref value);
}

API Proposal

namespace System.Runtime.CompilerServices;

public static class Unsafe
{
    public static TTo Bitcast<TFrom, TTo>(TFrom value);
}

API Usage

// instead of non generic BitConverter APIs:
// Console.WriteLine(BitConverter.UInt32BitsToSingle(12345));
Console.WriteLine(Unsafe.Bitcast<uint, float>(12345));
// prints 1.7299E-41

// bitcasting to a same sized type
Console.WriteLine(Unsafe.Bitcast<Vector4, Vector128<float>>(new Vector4(1f, 2f, 3f, 4f)));
// prints <1, 2, 3, 4>

// bitcasting to a smaller type
Console.WriteLine(Unsafe.Bitcast<Vector4, Vector2>(new Vector4(1f, 2f, 3f, 4f)));
// prints <1, 2>

// bitcasting to a bigger type
Console.WriteLine(Unsafe.Bitcast<Vector2, Vector4>(new Vector2(1f, 2f)));
// prints <1, 2, 0, 0>

Alternative Designs

Using Unsafe.As for same sized or smaller types, writing to a stack allocated, zero initialized, buffer of the destination type size and reading from it.

Risks

Unsafely reinterpreting managed types if there are no generic constraints can lead to GC holes, unexpected behaviour on big endian platforms for non matching sizes can cause code to become platform specific.

Author:	MichalPetryka
Assignees:	-
Labels:	api-suggestion, area-System.Numerics
Milestone:	-

Tagging subscribers to this area: @dotnet/area-system-runtime-compilerservices
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

Reinterpretation of types - especially value ones - is a common occurrence in high performance code.
Currently in C#, it is usually realized using the Unsafe.As API or with the *(TTo*)&value pattern. The JIT however has some issues with optimizing such code, due to the value being marked as address taken. Introducing a new API with a more descriptive name might be easier and cheaper than making the JIT recognize such pattern.

The name Bitcast was inspired by the C++ std::bit_cast and LLVM bitcast.

Open questions:

1. Should the API have any generic constraints? Restricting it to unmanaged or struct types would make it safer to use but potentially less useful in generic contexts (for example with Enum constraint, since that by itself doesn't restrict it to such types)?
2. What should the behaviour be for non matching size types? As I see it, there are two reasonable options:
   a) make the API throw in such case - that's what the C++ and LLVM bitcasts do, not really useful but could be regarded as the expected behaviour
   b) make the API function as if a buffer of the larger size was created (and zero initialized), the value written into it and then the target type read from its beginning. This behaviour would allow the API to be utilized in the current code that reads a smaller type from the beginning of a larger one with Unsafe.As and could be used for extending stuff like Vectors.

With different sizes being permitted the code would behave like this (at least for unmanaged types, ignore the inefficient implementation):

unsafe static TTo Bitcast<TFrom, TTo>(TFrom value)
{
    byte* s = stackalloc byte[Math.Max(sizeof(TFrom), sizeof(TTo))];
    new Span<byte>(s, Math.Max(sizeof(TFrom), sizeof(TTo))).Clear();
    *(TFrom*)s = value;
    return *(TTo*)s;
}

With only same sizes being accepted it'd work like this:

unsafe static TTo Bitcast<TFrom, TTo>(TFrom value)
{
    if (Unsafe.SizeOf<TFrom>() != Unsafe.SizeOf<TTo>())
        throw new NotSupportedException();
    return Unsafe.As<TFrom, TTo>(ref value);
}

API Proposal

namespace System.Runtime.CompilerServices;

public static class Unsafe
{
    public static TTo Bitcast<TFrom, TTo>(TFrom value);
}

API Usage

// instead of non generic BitConverter APIs:
// Console.WriteLine(BitConverter.UInt32BitsToSingle(12345));
Console.WriteLine(Unsafe.Bitcast<uint, float>(12345));
// prints 1.7299E-41

// bitcasting to a same sized type
Console.WriteLine(Unsafe.Bitcast<Vector4, Vector128<float>>(new Vector4(1f, 2f, 3f, 4f)));
// prints <1, 2, 3, 4>

// bitcasting to a smaller type
Console.WriteLine(Unsafe.Bitcast<Vector4, Vector2>(new Vector4(1f, 2f, 3f, 4f)));
// prints <1, 2>

// bitcasting to a bigger type
Console.WriteLine(Unsafe.Bitcast<Vector2, Vector4>(new Vector2(1f, 2f)));
// prints <1, 2, 0, 0>

Alternative Designs

Using Unsafe.As for same sized or smaller types, writing to a stack allocated, zero initialized, buffer of the destination type size and reading from it.

Risks

Unsafely reinterpreting managed types if there are no generic constraints can lead to GC holes, unexpected behaviour on big endian platforms for non matching sizes can cause code to become platform specific.

Author:	MichalPetryka
Assignees:	-
Labels:	api-suggestion, area-System.Runtime.CompilerServices, untriaged
Milestone:	-

[tannergooding]

It's worth noting that every example given is not really a "valid" scenario for this API.

For integer casts (same size or smaller), you're better off just casting.

For integer to floating-point casts, you're better off using BitConverter.SingleToInt32Bits or SingleToUInt32Bits or Int64BitsToDouble, etc...

For vector casts, you're better off doing .AsVector128(), .AsVector4(), .AsVector3(), .GetLower(), etc...

[tannergooding]

Noting that I'm not against such an API, it would be useful for other types of bitcasts such as two "Matrix4x4" definitions. It could also be used to simplify/centralize other currently intrinsic APIs to handler in the JIT.

I just wanted to explicitly call out that all the others do have existing better APIs.

The cases where you would still want this are cases like System.Numerics.Matrix4x4 where it is not promotable as 16x float but could be promotable as 4x Vector4 (for example).

However, once you start getting to larger structs, especially with pass by shadow copy, you're often going to get better codegen using ref U Unsafe.As(ref T) instead.

So the places this would be beneficial would be places where you could avoid any further calls/copies for large structs.

[tannergooding]

I do think that, as a bitcast API, it should only allow bitcasts

That is, it should throw if sizeof(T) and sizeof(U) do not match.

[jkotas]

The JIT however has some issues with optimizing such code, due to the value being marked as address taken

What would it take to fix these issues in the JIT? We have done work in the JIT to cleanup unnecessary address-taken. Is there work left to do?

[tannergooding]

I believe there are still some import and other early cases before we've removed the "address taken" that are impacted.

This can impact early constant propagation, some inlining observations, and the ability to remove of dead branches before they make it to other phases (and therefore impact the JIT throughput).

[SingleAccretion]

Concretely, we are talking about this piece of code, part of the very early IL scan:

runtime/src/coreclr/jit/fgbasic.cpp

Lines 2305 to 2320 in ae6a73f

	if (notStruct && notLastInstr && notDebugCode && impILConsumesAddr(codeAddr + sz))
	{
	// We can skip the addrtaken, as next IL instruction consumes
	// the address.
	}
	else
	{
	lvaTable[varNum].lvHasLdAddrOp = 1;
	if (!info.compIsStatic && (varNum == 0))
	{
	// Addr taken on "this" pointer is significant,
	// go ahead to mark it as permanently addr-exposed here.
	// This may be conservative, but probably not very.
	lvaSetVarAddrExposed(0 DEBUGARG(AddressExposedReason::TOO_CONSERVATIVE));
	}
	}

Before local morph determines the precise set of address-exposed locals, we have to assume lvHasLdAddrOp == true means the local can be arbitrarily mutated and its state is globally visible.

Currently impILConsumesAddr only handles ldfld, it would take some TP measuring how expensive would it be to expand to other patterns as well as non-root methods.

(Edit: there are also some limitations in this code which look like they can be just deleted and are a leftover from lvAddrTaken days)

[EgorBo]

Potential use-case (we discussed in the other issue) - it's not correct but it gives the idea of potential improvements like this:

This method is marked as AggressiveInling, but e.g. IndexOf((byte)0) will never propagate that 0 by value during inlining because IL prescan found that it is address taken. Thus, IsKnownConstant has no chance to work as desired and will always see a non-constant. Unsafe.As replaced with Unsafe.Bitcast here would resolve the issue.

[tannergooding]

@jkotas, any pushback against this API being exposed given the above?

If not, I'll mark this as api-ready-for-review.