[API Proposal]: AVX512 BMM Intrinsics

[alexcovington]

Background and motivation

New AVX512 BMM (Bit Matrix Multiply and Bit Reversal) instructions have been published, and I would like to add support for these instructions as .NET intrinsics.

API Proposal

namespace System.Runtime.Intrinsics.X86
{
    public abstract class Avx512Bmm : Avx512F
    {
        public static new bool IsSupported { get; }

        public static Vector128<byte> ReverseBits(Vector128<byte> x);
        public static Vector256<byte> ReverseBits(Vector256<byte> x);
        public static Vector512<byte> ReverseBits(Vector512<byte> x);

        public static Vector256<ushort> BitMultiplyMatrix16x16WithOrReduction(Vector256<ushort> x, Vector256<ushort> y, Vector256<ushort> z);
        public static Vector512<ushort> BitMultiplyMatrix16x16WithOrReduction(Vector512<ushort> x, Vector512<ushort> y, Vector512<ushort> z);
        public static Vector256<ushort> BitMultiplyMatrix16x16WithXorReduction(Vector256<ushort> x, Vector256<ushort> y, Vector256<ushort> z);
        public static Vector512<ushort> BitMultiplyMatrix16x16WithXorReduction(Vector512<ushort> x, Vector512<ushort> y, Vector512<ushort> z);
    }
}

API Usage

Usage would be consistent with other AVX512 intrinsics:

Vector256<ushort> x = Vector256.Create((ushort)0x1);
Vector256<ushort> y = Vector256.Create((ushort)0x1);
Vector256<ushort> z = Vector256.Create((ushort)0x1011);
Vector256<ushort> result = Avx512Bmm.BitMatrix16x16x16MultiplyAddWithOrReduction(x, y, z);
// result = <0x1011, 0x1011, 0x1011, 0x1011, 0x1011, 0x1011, 0x1011, 0x1011,
//           0x1011, 0x1011, 0x1011, 0x1011, 0x1011, 0x1011, 0x1011, 0x1011>

Vector128<byte> x = Vector128.Create((byte)0xAA);
Vector128<byte> y = Avx512Bmm.ReverseBits(x);
// y = <0x55, 0x55, 0x55, 0x55, 0x55, 0x55, 0x55, 0x55,
//      0x55, 0x55, 0x55, 0x55, 0x55, 0x55, 0x55, 0x55>

Alternative Designs

BitMatrix16x16x16MultiplyAddWithOrReduction is a lengthy name, and I'm open to other suggestions.

Risks

N/A

[dotnet-policy-service]

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

[tannergooding]

BitMatrix16x16x16MultiplyAddWithOrReduction is a lengthy name, and I'm open to other suggestions.

I'm not sure we need the full 16x16x16 name as these are logically operating on 16x16 matrices and so simply 16x16 is likely sufficient.

The naive matrix multiply loop is:

for (int i = 0; i < 16; i++)
{
    for (int j = 0; j < 16; j++)
    {
        for (int k = 0; k < 16; k++)
        {
            C[i][j] += A[i][k] * B[k][j];
        }
    }
}

For bitwise, we then have the following:

0 * 0 = 0     -same as-    0 & 0 = 0
0 * 1 = 0     -same as-    0 & 1 = 0
1 * 0 = 0     -same as-    1 & 0 = 0
1 * 1 = 0     -same as-    1 & 1 = 1

We then have:

0 + 0 = 0     -same as-    0 - 0 = 0     -same as-    0 ^ 0 = 0
0 + 1 = 1     -same as-    0 - 1 = 1     -same as-    0 ^ 1 = 1
1 + 0 = 1     -same as-    1 - 0 = 1     -same as-    1 ^ 0 = 1
1 + 1 = 0     -same as-    1 - 1 = 0     -same as-    1 ^ 1 = 0

So BitMultiplyAddWithXorReduction is really effectively just "Bitwise multiply and add a 16x16 matrix`.

The WithOrReduction is then effectively the same, but we have 1 | 1 = 1 instead, so it effectively ends up as Bitwise mutliply and saturating add a 16x16 matrix

Given that, some general ideas are:

// Could lean into the actual operation its doing, ignoring the fact its optimized using bitwise-or/xor
BitMultiplyAddMatrix16x16
BitMultiplySaturateAddMatrix16x16

// Could spell it out, putting Matrix16x16 in the middle
BitMultiplyAddMatrix16x16WithOrReduction
BitMultiplyAddMatrix16x16WithXorReduction

// The MultiplyAdd might not be relevant, since that's just "standard" for matrix multiply and we could just say Multiply
BitMultiplyMatrix16x16WithOrReduction
BitMultiplyMatrix16x16WithXorReduction

Other ideas might be relevant too, just throwing some out there

[alexcovington]

BitMultiplyMatrix16x16WithOrReduction and BitMultiplyMatrix16x16WithXorReduction I think are probably better than the current names and still communicate the semantics of the instructions.

[bartonjs]

• BitMultiply...(x, y, z) to (left, right, addend) (assuming that's the correct order, fix it if not)
• ReverseBits(x) => ReverseBits(values)

namespace System.Runtime.Intrinsics.X86
{
    public abstract class Avx512Bmm : Avx512F
    {
        public static new bool IsSupported { get; }

        public static Vector128<byte> ReverseBits(Vector128<byte> values);
        public static Vector256<byte> ReverseBits(Vector256<byte> values);
        public static Vector512<byte> ReverseBits(Vector512<byte> values);

        public static Vector256<ushort> BitMultiplyMatrix16x16WithOrReduction(Vector256<ushort> left, Vector256<ushort> right, Vector256<ushort> addend);
        public static Vector512<ushort> BitMultiplyMatrix16x16WithOrReduction(Vector512<ushort> left, Vector512<ushort> right, Vector512<ushort> addend);
        public static Vector256<ushort> BitMultiplyMatrix16x16WithXorReduction(Vector256<ushort> left, Vector256<ushort> right, Vector256<ushort> addend);
        public static Vector512<ushort> BitMultiplyMatrix16x16WithXorReduction(Vector512<ushort> left, Vector512<ushort> right, Vector512<ushort> addend);
    }
}