From 9871a892f8c19489f32f3b4eaadc4eeedff84f2d Mon Sep 17 00:00:00 2001 From: Guillaume Chatelet Date: Mon, 29 Jun 2020 12:48:44 +0000 Subject: [PATCH] [ADT] Add Bitfield utilities Context: -------- There are places in LLVM where we need to pack typed fields into opaque values. For instance, the `XXXInst` classes in `llvm/include/llvm/IR/Instructions.h` that extract informations from `Value::SubclassData` via `getSubclassDataFromInstruction()`. The bit twiddling is done manually: this impairs readability and prevent consistent handling of out of range values (e.g. https://github.com/llvm/llvm-project/blob/435b458ad0a4630e6126246a6865748104ccad06/llvm/include/llvm/IR/Instructions.h#L564) More importantly, the bit pattern is scattered throughout the implementation making it hard to pack additionnal fields or check for overlapping bits. Design decisions: ----------------- The Bitfield structs are to be declared together so it is clear which bits are used or not. The code is designed with simplicity in mind, hence a few limitations: - Storage is limited to a single integer, - Enum values have to be `unsigned`, - Storage type has to be `unsigned`, - There are no automatic detection of overlapping fields (packed bitfield declaration should help though), - The interface is C like so `storage` needs to be passed in everytime (code is simpler and lifetime considerations more obvious) RFC: http://lists.llvm.org/pipermail/llvm-dev/2020-June/142196.html Differential Revision: https://reviews.llvm.org/D81580 --- include/llvm/ADT/Bitfields.h | 282 ++++++++++++++++++++++++++++++++ unittests/ADT/BitFieldsTest.cpp | 244 +++++++++++++++++++++++++++ unittests/ADT/CMakeLists.txt | 1 + 3 files changed, 527 insertions(+) create mode 100644 include/llvm/ADT/Bitfields.h create mode 100644 unittests/ADT/BitFieldsTest.cpp diff --git a/include/llvm/ADT/Bitfields.h b/include/llvm/ADT/Bitfields.h new file mode 100644 index 00000000000..e15ecea4a19 --- /dev/null +++ b/include/llvm/ADT/Bitfields.h @@ -0,0 +1,282 @@ +//===-- llvm/ADT/Bitfield.h - Get and Set bits in an integer ---*- C++ -*--===// +// +// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. +// See https://llvm.org/LICENSE.txt for license information. +// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception +// +//===----------------------------------------------------------------------===// +/// +/// \file +/// This file implements methods to test, set and extract typed bits from packed +/// unsigned integers. +/// +/// Why not C++ bitfields? +/// ---------------------- +/// C++ bitfields do not offer control over the bit layout nor consistent +/// behavior when it comes to out of range values. +/// For instance, the layout is implementation defined and adjacent bits may be +/// packed together but are not required to. This is problematic when storage is +/// sparse and data must be stored in a particular integer type. +/// +/// The methods provided in this file ensures precise control over the +/// layout/storage as well as protection against out of range values. +/// +/// Usage example +/// ------------- +/// \code{.cpp} +/// uint8_t Storage = 0; +/// +/// // Store and retrieve a single bit as bool. +/// using Bool = Bitfield::Element; +/// Bitfield::set(Storage, true); +/// EXPECT_EQ(Storage, 0b00000001); +/// // ^ +/// EXPECT_EQ(Bitfield::get(Storage), true); +/// +/// // Store and retrieve a 2 bit typed enum. +/// // Note: enum underlying type must be unsigned. +/// enum class SuitEnum : uint8_t { CLUBS, DIAMONDS, HEARTS, SPADES }; +/// // Note: enum maximum value needs to be passed in as last parameter. +/// using Suit = Bitfield::Element; +/// Bitfield::set(Storage, SuitEnum::HEARTS); +/// EXPECT_EQ(Storage, 0b00000101); +/// // ^^ +/// EXPECT_EQ(Bitfield::get(Storage), SuitEnum::HEARTS); +/// +/// // Store and retrieve a 5 bit value as unsigned. +/// using Value = Bitfield::Element; +/// Bitfield::set(Storage, 10); +/// EXPECT_EQ(Storage, 0b01010101); +/// // ^^^^^ +/// EXPECT_EQ(Bitfield::get(Storage), 10U); +/// +/// // Interpret the same 5 bit value as signed. +/// using SignedValue = Bitfield::Element; +/// Bitfield::set(Storage, -2); +/// EXPECT_EQ(Storage, 0b11110101); +/// // ^^^^^ +/// EXPECT_EQ(Bitfield::get(Storage), -2); +/// +/// // Ability to efficiently test if a field is non zero. +/// EXPECT_TRUE(Bitfield::test(Storage)); +/// +/// // Alter Storage changes value. +/// Storage = 0; +/// EXPECT_EQ(Bitfield::get(Storage), false); +/// EXPECT_EQ(Bitfield::get(Storage), SuitEnum::CLUBS); +/// EXPECT_EQ(Bitfield::get(Storage), 0U); +/// EXPECT_EQ(Bitfield::get(Storage), 0); +/// +/// Storage = 255; +/// EXPECT_EQ(Bitfield::get(Storage), true); +/// EXPECT_EQ(Bitfield::get(Storage), SuitEnum::SPADES); +/// EXPECT_EQ(Bitfield::get(Storage), 31U); +/// EXPECT_EQ(Bitfield::get(Storage), -1); +/// \endcode +/// +//===----------------------------------------------------------------------===// + +#ifndef LLVM_ADT_BITFIELDS_H +#define LLVM_ADT_BITFIELDS_H + +#include +#include // CHAR_BIT +#include // size_t +#include // uintXX_t +#include // numeric_limits +#include + +namespace llvm { + +namespace bitfields_details { + +/// A struct defining useful bit patterns for n-bits integer types. +template struct BitPatterns { + /// Bit patterns are forged using the equivalent `Unsigned` type because of + /// undefined operations over signed types (e.g. Bitwise shift operators). + /// Moreover same size casting from unsigned to signed is well defined but not + /// the other way around. + using Unsigned = typename std::make_unsigned::type; + static_assert(sizeof(Unsigned) == sizeof(T), "Types must have same size"); + + static constexpr unsigned TypeBits = sizeof(Unsigned) * CHAR_BIT; + static_assert(TypeBits >= Bits, "n-bit must fit in T"); + + /// e.g. with TypeBits == 8 and Bits == 6. + static constexpr Unsigned AllZeros = Unsigned(0); // 00000000 + static constexpr Unsigned AllOnes = ~Unsigned(0); // 11111111 + static constexpr Unsigned Umin = AllZeros; // 00000000 + static constexpr Unsigned Umax = AllOnes >> (TypeBits - Bits); // 00111111 + static constexpr Unsigned SignBitMask = Unsigned(1) << (Bits - 1); // 00100000 + static constexpr Unsigned Smax = Umax >> 1U; // 00011111 + static constexpr Unsigned Smin = ~Smax; // 11100000 + static constexpr Unsigned SignExtend = Smin << 1U; // 11000000 +}; + +/// `Compressor` is used to manipulate the bits of a (possibly signed) integer +/// type so it can be packed and unpacked into a `bits` sized integer, +/// `Compressor` is specialized on signed-ness so no runtime cost is incurred. +/// The `pack` method also checks that the passed in `UserValue` is valid. +template ::value> +struct Compressor { + static_assert(std::is_unsigned::value, "T is unsigned"); + using BP = BitPatterns; + + static T pack(T UserValue, T UserMaxValue) { + assert(UserValue <= UserMaxValue && "value is too big"); + assert(UserValue <= BP::Umax && "value is too big"); + return UserValue; + } + + static T unpack(T StorageValue) { return StorageValue; } +}; + +template struct Compressor { + static_assert(std::is_signed::value, "T is signed"); + using BP = BitPatterns; + + static T pack(T UserValue, T UserMaxValue) { + assert(UserValue <= UserMaxValue && "value is too big"); + assert(UserValue <= T(BP::Smax) && "value is too big"); + assert(UserValue >= T(BP::Smin) && "value is too small"); + if (UserValue < 0) + UserValue &= ~BP::SignExtend; + return UserValue; + } + + static T unpack(T StorageValue) { + if (StorageValue >= T(BP::SignBitMask)) + StorageValue |= BP::SignExtend; + return StorageValue; + } +}; + +/// Impl is where Bifield description and Storage are put together to interact +/// with values. +template struct Impl { + static_assert(std::is_unsigned::value, + "Storage must be unsigned"); + using IntegerType = typename Bitfield::IntegerType; + using C = Compressor; + using BP = BitPatterns; + + static constexpr size_t StorageBits = sizeof(StorageType) * CHAR_BIT; + static_assert(Bitfield::FirstBit <= StorageBits, "Data must fit in mask"); + static_assert(Bitfield::LastBit <= StorageBits, "Data must fit in mask"); + static constexpr StorageType Mask = BP::Umax << Bitfield::Shift; + + /// Checks `UserValue` is within bounds and packs it between `FirstBit` and + /// `LastBit` of `Packed` leaving the rest unchanged. + static void update(StorageType &Packed, IntegerType UserValue) { + const StorageType StorageValue = C::pack(UserValue, Bitfield::UserMaxValue); + Packed &= ~Mask; + Packed |= StorageValue << Bitfield::Shift; + } + + /// Interprets bits between `FirstBit` and `LastBit` of `Packed` as + /// an`IntegerType`. + static IntegerType extract(StorageType Packed) { + const StorageType StorageValue = (Packed & Mask) >> Bitfield::Shift; + return C::unpack(StorageValue); + } + + /// Interprets bits between `FirstBit` and `LastBit` of `Packed` as + /// an`IntegerType`. + static StorageType test(StorageType Packed) { return Packed & Mask; } +}; + +/// `Bitfield` deals with the following type: +/// - unsigned enums +/// - signed and unsigned integer +/// - `bool` +/// Internally though we only manipulate integer with well defined and +/// consistent semantic, this excludes typed enums and `bool` that are replaced +/// with their unsigned counterparts. The correct type is restored in the public +/// API. +template ::value> +struct ResolveUnderlyingType { + using type = typename std::underlying_type::type; +}; +template struct ResolveUnderlyingType { + using type = T; +}; +template <> struct ResolveUnderlyingType { + /// In case sizeof(bool) != 1, replace `void` by an additionnal + /// std::conditional. + using type = std::conditional::type; +}; + +} // namespace bitfields_details + +/// Holds functions to get, set or test bitfields. +struct Bitfield { + /// Describes an element of a Bitfield. This type is then used with the + /// Bitfield static member functions. + /// \param T, the type of the field once in unpacked form, + /// \param Offset, the position of the first bit, + /// \param Size, the size of the field, + /// \param MaxValue, For enums the maximum enum allowed. + template ::value + ? T(0) // coupled with static_assert below + : std::numeric_limits::max()> + struct Element { + using Type = T; + using IntegerType = + typename bitfields_details::ResolveUnderlyingType::type; + static constexpr unsigned Shift = Offset; + static constexpr unsigned Bits = Size; + static constexpr unsigned FirstBit = Offset; + static constexpr unsigned LastBit = Shift + Bits; + + private: + template friend struct bitfields_details::Impl; + + static_assert(Bits > 0, "Bits must be non zero"); + static constexpr size_t TypeBits = sizeof(IntegerType) * CHAR_BIT; + static_assert(Bits <= TypeBits, "Bits may not be greater than T size"); + static_assert(!std::is_enum::value || MaxValue != T(0), + "Enum Bitfields must provide a MaxValue"); + static_assert(!std::is_enum::value || + std::is_unsigned::value, + "Enum must be unsigned"); + static_assert(std::is_integral::value && + std::numeric_limits::is_integer, + "IntegerType must be an integer type"); + + static constexpr IntegerType UserMaxValue = + static_cast(MaxValue); + }; + + /// Unpacks the field from the `Packed` value. + template + static typename Bitfield::Type get(StorageType Packed) { + using I = bitfields_details::Impl; + return static_cast(I::extract(Packed)); + } + + /// Return a non-zero value if the field is non-zero. + /// It is more efficient than `getField`. + template + static StorageType test(StorageType Packed) { + using I = bitfields_details::Impl; + return I::test(Packed); + } + + /// Sets the typed value in the provided `Packed` value. + /// The method will asserts if the provided value is too big to fit in. + template + static void set(StorageType &Packed, typename Bitfield::Type Value) { + using I = bitfields_details::Impl; + I::update(Packed, static_cast(Value)); + } + + /// Returns whether the two bitfields share common bits. + template static constexpr bool isOverlapping() { + return A::LastBit > B::FirstBit && B::LastBit > A::FirstBit; + } +}; + +} // namespace llvm + +#endif // LLVM_ADT_BITFIELDS_H diff --git a/unittests/ADT/BitFieldsTest.cpp b/unittests/ADT/BitFieldsTest.cpp new file mode 100644 index 00000000000..759c1839499 --- /dev/null +++ b/unittests/ADT/BitFieldsTest.cpp @@ -0,0 +1,244 @@ +//===- llvm/unittests/ADT/BitFieldsTest.cpp - BitFields unit tests --------===// +// +// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. +// See https://llvm.org/LICENSE.txt for license information. +// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception +// +//===----------------------------------------------------------------------===// + +#include "llvm/ADT/Bitfields.h" +#include "gtest/gtest.h" + +using namespace llvm; + +namespace { + +TEST(BitfieldsTest, Example) { + uint8_t Storage = 0; + + // Store and retrieve a single bit as bool. + using Bool = Bitfield::Element; + Bitfield::set(Storage, true); + EXPECT_EQ(Storage, 0b00000001); + // ^ + EXPECT_EQ(Bitfield::get(Storage), true); + + // Store and retrieve a 2 bit typed enum. + // Note: enum underlying type must be unsigned. + enum class SuitEnum : uint8_t { CLUBS, DIAMONDS, HEARTS, SPADES }; + // Note: enum maximum value needs to be passed in as last parameter. + using Suit = Bitfield::Element; + Bitfield::set(Storage, SuitEnum::HEARTS); + EXPECT_EQ(Storage, 0b00000101); + // ^^ + EXPECT_EQ(Bitfield::get(Storage), SuitEnum::HEARTS); + + // Store and retrieve a 5 bit value as unsigned. + using Value = Bitfield::Element; + Bitfield::set(Storage, 10); + EXPECT_EQ(Storage, 0b01010101); + // ^^^^^ + EXPECT_EQ(Bitfield::get(Storage), 10U); + + // Interpret the same 5 bit value as signed. + using SignedValue = Bitfield::Element; + Bitfield::set(Storage, -2); + EXPECT_EQ(Storage, 0b11110101); + // ^^^^^ + EXPECT_EQ(Bitfield::get(Storage), -2); + + // Ability to efficiently test if a field is non zero. + EXPECT_TRUE(Bitfield::test(Storage)); + + // Alter Storage changes value. + Storage = 0; + EXPECT_EQ(Bitfield::get(Storage), false); + EXPECT_EQ(Bitfield::get(Storage), SuitEnum::CLUBS); + EXPECT_EQ(Bitfield::get(Storage), 0U); + EXPECT_EQ(Bitfield::get(Storage), 0); + + Storage = 255; + EXPECT_EQ(Bitfield::get(Storage), true); + EXPECT_EQ(Bitfield::get(Storage), SuitEnum::SPADES); + EXPECT_EQ(Bitfield::get(Storage), 31U); + EXPECT_EQ(Bitfield::get(Storage), -1); +} + +TEST(BitfieldsTest, FirstBit) { + uint8_t Storage = 0; + using FirstBit = Bitfield::Element; + // Set true + Bitfield::set(Storage, true); + EXPECT_EQ(Bitfield::get(Storage), true); + EXPECT_EQ(Storage, 0x1ULL); + // Set false + Bitfield::set(Storage, false); + EXPECT_EQ(Bitfield::get(Storage), false); + EXPECT_EQ(Storage, 0x0ULL); +} + +TEST(BitfieldsTest, SecondBit) { + uint8_t Storage = 0; + using SecondBit = Bitfield::Element; + // Set true + Bitfield::set(Storage, true); + EXPECT_EQ(Bitfield::get(Storage), true); + EXPECT_EQ(Storage, 0x2ULL); + // Set false + Bitfield::set(Storage, false); + EXPECT_EQ(Bitfield::get(Storage), false); + EXPECT_EQ(Storage, 0x0ULL); +} + +TEST(BitfieldsTest, LastBit) { + uint8_t Storage = 0; + using LastBit = Bitfield::Element; + // Set true + Bitfield::set(Storage, true); + EXPECT_EQ(Bitfield::get(Storage), true); + EXPECT_EQ(Storage, 0x80ULL); + // Set false + Bitfield::set(Storage, false); + EXPECT_EQ(Bitfield::get(Storage), false); + EXPECT_EQ(Storage, 0x0ULL); +} + +TEST(BitfieldsTest, LastBitUint64) { + uint64_t Storage = 0; + using LastBit = Bitfield::Element; + // Set true + Bitfield::set(Storage, true); + EXPECT_EQ(Bitfield::get(Storage), true); + EXPECT_EQ(Storage, 0x8000000000000000ULL); + // Set false + Bitfield::set(Storage, false); + EXPECT_EQ(Bitfield::get(Storage), false); + EXPECT_EQ(Storage, 0x0ULL); +} + +TEST(BitfieldsTest, Enum) { + enum Enum : unsigned { Zero = 0, Two = 2, LAST = Two }; + + uint8_t Storage = 0; + using OrderingField = Bitfield::Element; + EXPECT_EQ(Bitfield::get(Storage), Zero); + Bitfield::set(Storage, Two); + EXPECT_EQ(Bitfield::get(Storage), Two); + EXPECT_EQ(Storage, 0b00000100); + // value 2 in ^^ +} + +TEST(BitfieldsTest, EnumClass) { + enum class Enum : unsigned { Zero = 0, Two = 2, LAST = Two }; + + uint8_t Storage = 0; + using OrderingField = Bitfield::Element; + EXPECT_EQ(Bitfield::get(Storage), Enum::Zero); + Bitfield::set(Storage, Enum::Two); + EXPECT_EQ(Bitfield::get(Storage), Enum::Two); + EXPECT_EQ(Storage, 0b00000100); + // value 2 in ^^ +} + +TEST(BitfieldsTest, OneBitSigned) { + uint8_t Storage = 0; + using SignedField = Bitfield::Element; + EXPECT_EQ(Bitfield::get(Storage), 0); + EXPECT_EQ(Storage, 0b00000000); + // value 0 in ^ + Bitfield::set(Storage, -1); + EXPECT_EQ(Bitfield::get(Storage), -1); + EXPECT_EQ(Storage, 0b00000010); + // value 1 in ^ +} + +TEST(BitfieldsTest, TwoBitSigned) { + uint8_t Storage = 0; + using SignedField = Bitfield::Element; + EXPECT_EQ(Bitfield::get(Storage), 0); + EXPECT_EQ(Storage, 0b00000000); + // value 0 in ^^ + Bitfield::set(Storage, 1); + EXPECT_EQ(Bitfield::get(Storage), 1); + EXPECT_EQ(Storage, 0b00000010); + // value 1 in ^^ + Bitfield::set(Storage, -1); + EXPECT_EQ(Bitfield::get(Storage), -1); + EXPECT_EQ(Storage, 0b00000110); + // value -1 in ^^ + Bitfield::set(Storage, -2); + EXPECT_EQ(Bitfield::get(Storage), -2); + EXPECT_EQ(Storage, 0b00000100); + // value -2 in ^^ +} + +TEST(BitfieldsTest, isOverlapping) { + // 01234567 + // A: -------- + // B: --- + // C: --- + // D: --- + using A = Bitfield::Element; + using B = Bitfield::Element; + using C = Bitfield::Element; + using D = Bitfield::Element; + EXPECT_TRUE((Bitfield::isOverlapping())); + EXPECT_TRUE((Bitfield::isOverlapping())); + EXPECT_TRUE((Bitfield::isOverlapping())); + EXPECT_TRUE((Bitfield::isOverlapping())); + + EXPECT_TRUE((Bitfield::isOverlapping())); + EXPECT_TRUE((Bitfield::isOverlapping())); + EXPECT_FALSE((Bitfield::isOverlapping())); +} + +TEST(BitfieldsTest, FullUint64) { + uint64_t Storage = 0; + using Value = Bitfield::Element; + Bitfield::set(Storage, -1ULL); + EXPECT_EQ(Bitfield::get(Storage), -1ULL); + Bitfield::set(Storage, 0ULL); + EXPECT_EQ(Bitfield::get(Storage), 0ULL); +} + +TEST(BitfieldsTest, FullInt64) { + uint64_t Storage = 0; + using Value = Bitfield::Element; + Bitfield::set(Storage, -1); + EXPECT_EQ(Bitfield::get(Storage), -1); + Bitfield::set(Storage, 0); + EXPECT_EQ(Bitfield::get(Storage), 0); +} + +#ifdef EXPECT_DEBUG_DEATH + +TEST(BitfieldsTest, ValueTooBigBool) { + uint64_t Storage = 0; + using A = Bitfield::Element; + Bitfield::set(Storage, true); + Bitfield::set(Storage, false); + EXPECT_DEBUG_DEATH(Bitfield::set(Storage, 2), "value is too big"); +} + +TEST(BitfieldsTest, ValueTooBigInt) { + uint64_t Storage = 0; + using A = Bitfield::Element; + Bitfield::set(Storage, 3); + EXPECT_DEBUG_DEATH(Bitfield::set(Storage, 4), "value is too big"); + EXPECT_DEBUG_DEATH(Bitfield::set(Storage, -1), "value is too big"); +} + +TEST(BitfieldsTest, ValueTooBigBounded) { + uint8_t Storage = 0; + using A = Bitfield::Element; + Bitfield::set(Storage, 1); + Bitfield::set(Storage, 0); + Bitfield::set(Storage, -1); + Bitfield::set(Storage, -2); + EXPECT_DEBUG_DEATH(Bitfield::set(Storage, 2), "value is too big"); + EXPECT_DEBUG_DEATH(Bitfield::set(Storage, -3), "value is too small"); +} + +#endif + +} // namespace diff --git a/unittests/ADT/CMakeLists.txt b/unittests/ADT/CMakeLists.txt index 8879a2a0058..cff3911e339 100644 --- a/unittests/ADT/CMakeLists.txt +++ b/unittests/ADT/CMakeLists.txt @@ -8,6 +8,7 @@ add_llvm_unittest(ADTTests APIntTest.cpp APSIntTest.cpp ArrayRefTest.cpp + BitFieldsTest.cpp BitmaskEnumTest.cpp BitVectorTest.cpp BreadthFirstIteratorTest.cpp