/** * @file include/ActivMiddleware/Misc/BitFields.h * * @brief Header file for bit field helper classes. */ #if (!defined ACTIV_MISC_BIT_FIELDS_H) #define ACTIV_MISC_BIT_FIELDS_H #include "ActivMiddleware/ActivMiddleware.h" #include ACTIV_BOOST_INCLUDE(static_assert.hpp) #include ACTIV_BOOST_INCLUDE(mpl/back_inserter.hpp) #include ACTIV_BOOST_INCLUDE(mpl/bitor.hpp) #include ACTIV_BOOST_INCLUDE(mpl/copy_if.hpp) #include ACTIV_BOOST_INCLUDE(mpl/fold.hpp) #include ACTIV_BOOST_INCLUDE(mpl/integral_c.hpp) #include ACTIV_BOOST_INCLUDE(mpl/not.hpp) #include ACTIV_BOOST_INCLUDE(mpl/transform.hpp) #include ACTIV_BOOST_INCLUDE(mpl/vector/vector40.hpp) #include ACTIV_BOOST_INCLUDE(type_traits/is_void.hpp) #if (defined ACTIV_BOOST_NO_CXX11_VARIADIC_TEMPLATES) #include ACTIV_BOOST_INCLUDE(preprocessor/arithmetic/inc.hpp) #include ACTIV_BOOST_INCLUDE(preprocessor/repetition/repeat_from_to.hpp) #endif #include //! Activ namespace. namespace Activ { //! For bitmaps where bit 0 means right-most (least significant) bit. class LsbOrigin { }; // --------------------------------------------------------------------------------------------------------------------------------- //! For bitmaps where bit 0 means left-most (most significant) bit. class MsbOrigin { }; // --------------------------------------------------------------------------------------------------------------------------------- // --------------------------------------------------------------------------------------------------------------------------------- namespace BitmapDetail { //! Helper to determine the base offset for a Bitmap. template class BaseOffset { // Nothing. Use specializations. }; // --------------------------------------------------------------------------------------------------------------------------------- //! Helper to determine the base offset for a LsbOrigin Bitmap. Always 0. template class BaseOffset { public: static const size_t value = 0; }; // --------------------------------------------------------------------------------------------------------------------------------- //! Helper to determine the base offset for a MsbOrigin Bitmap. template class BaseOffset { public: // There may be unused bits if N is not the same as the size of the integral type. static const size_t value = (sizeof(typename BitTraits::IntegralType) * CHAR_BIT) - N; }; // --------------------------------------------------------------------------------------------------------------------------------- // --------------------------------------------------------------------------------------------------------------------------------- #if (defined ACTIV_BOOST_NO_CXX11_VARIADIC_TEMPLATES) /** * @brief Boost::mpl::integral_c constant for a BitFieldConstant shifted to its position in a Bitmap. * * T is a BitFieldConstant. */ template class BitFieldConstantShifted { public: typedef typename Boost::mpl::integral_c::type type; }; #endif // (defined ACTIV_BOOST_NO_CXX11_VARIADIC_TEMPLATES) } // namespace BitmapDetail // --------------------------------------------------------------------------------------------------------------------------------- // --------------------------------------------------------------------------------------------------------------------------------- /** * @brief Bitmap helper class. * * For example: * * struct MyBitmap : public Bitmap<8, LsbOrigin> * { * typedef BitField Length; * typedef BitField MessageType; * typedef TerminalBitField UserData; * }; * * Note where N is not the same as the size of a built-in integral type, using MsbOrigin means there will be unused * bits in the least-significant places. * * For example, Bitmap<24, MsbOrigin>::Type == uint32_t. The least significant 8 bits of this type will be unused. The * "first bit" is bit 31, not bit 23, of the Type. * * @param N size of the bitmap, in bits. * @param ORIGIN whether to count bit 0 as left- or right-most bit, using MsbOrigin or LsbOrigin class respectively. */ template class Bitmap { public: typedef Bitmap ThisType; typedef Bitmap BitmapType; ///< We require access to this type from either Bitmap or BitField templates. static const size_t numberOfBits = N; typedef ORIGIN Origin; typedef typename BitTraits::IntegralType Type; ///< Smallest integral type that will hold all the bitmap's bits. static const size_t baseOffset = BitmapDetail::BaseOffset::value; ///< Offset to first bit. }; // --------------------------------------------------------------------------------------------------------------------------------- // --------------------------------------------------------------------------------------------------------------------------------- /** * @brief Bitmap helper class, where the bitmap is to be defined in terms of an existing BitField. * * BITFIELD should be a BitField type. * * An example usage would be where a bitmap has a "Flags" BitField with, for example, 3 bits in it: * * struct MyBitmap : public Bitmap<8, LsbOrigin> * { * typedef BitField MessageType; * typedef BitField Flags; * typedef TerminalBitField NotInteresting; * }; * * Now we can define a separate bitmap for the Flags bits (there may be multiple definitions of Flags, if the flags definitions * depend on the MessageType bits): * * struct FlagsBitmap1 : public NestedBitmap * { * typedef BitField IsStale; * typedef BitField IsSequenceNumberPresent; * typedef BitField IsDelete; * }; * * Access is simply something like: * * if (0 != FlagsBitmap1::IsStale::GetUnshifted(myBitmap)) { } */ template class NestedBitmap { public: typedef NestedBitmap ThisType; typedef NestedBitmap BitmapType; ///< We require access to this type from either NestedBitmap or BitField templates. static const size_t numberOfBits = BITFIELD::length; ///< Can only contain as many bits as the "containing" BitField. typedef typename BITFIELD::BitmapType::Origin Origin; ///< Ordering is the same as the containing BitField's parent Bitmap. typedef typename BITFIELD::BitmapType::Type Type; ///< The integral type that fits the containing BitField's Bitmap. static const size_t baseOffset = BITFIELD::offset; ///< Offset for the first bit this bitmap will contain. }; // --------------------------------------------------------------------------------------------------------------------------------- // --------------------------------------------------------------------------------------------------------------------------------- /** * @brief BitField helper class. * * Generally this class won't be used directly. The derived BitField would be used instead, unless you need to define * a particular bit explicitly, rather than in relation to a previous bitfield. * * @tparam BITMAP bitmap class. * @tparam OFFSET_VALUE 0 based offset of the bitfield within the bitmap. * @tparam LENGTH_VALUE length of the bitfield in bits. */ template class BitFieldHelperBase { public: typedef BitFieldHelperBase ThisType; typedef BITMAP BitmapType; ///< We require access to the Bitmap type from either Bitmap or BitField templates. typedef typename BITMAP::Type Type; ///< Smallest integral type that will hold all the bitmap's bits. typedef typename BitTraits::IntegralType FieldType; ///< Smallest integral type that will hold all this field's bits. //! Value wrapper for passing to Bitmap::Create(). class Value { public: typedef BitFieldHelperBase BitFieldType; /** * @brief Constructor. * * value the (unshifted) value for this BitField. There are no run-time checks this value does not exceed the * maximum allowed for the BitField, other than a debug-only assert. */ Value(const typename BitFieldType::Type value) : m_value(value) { // Using the Less template due to GCC warnings. assert((0 == value) || (Less()(value - 1))); } const typename BitFieldType::Type m_value; }; /** * @brief Get the unshifted value of a bitfield. * * E.g. * MyBitmap::Type bitmap = 0; * MyBitmap::MessageType::Set(bitmap, 0x0f); * MyBitmap::MessageType::GetUnshifted(bitmap) == 0x3c * * @param bitmap the bitmap from which to retrieve the field. * * @return The bitmap with all other fields masked away. */ static Type GetUnshifted(const Type bitmap) { return (bitmap & mask); } /** * @brief Get the right-shifted value of a bitfield. * * E.g. * MyBitmap::Type bitmap = 0; * MyBitmap::MessageType::Set(bitmap, 0x0f); * MyBitmap::MessageType::GetShifted(bitmap) == 0x0f * * @param bitmap the bitmap from which to retrieve the field. * * @return The bitmap with all other fields masked away and shifted to the right. */ static FieldType GetShifted(const Type bitmap) { return static_cast((bitmap & mask) >> offset); } /** * @brief Set the value of a bitfield. * * @param bitmap the bitmap in which to set the bitfield. * @param value the value of the field to set. */ static void Set(Type &bitmap, const FieldType value) { // Using the Less template due to GCC warnings. assert((0 == value) || (Less()(value - 1))); bitmap &= ~mask; bitmap |= (static_cast(value) << offset); } static const size_t offset = OFFSET_VALUE; static const size_t length = LENGTH_VALUE; static const Type maxValue = BitTraits::maxValue; static const Type mask = maxValue << offset; ACTIV_BOOST_STATIC_ASSERT(0 != LENGTH_VALUE); }; // --------------------------------------------------------------------------------------------------------------------------------- // --------------------------------------------------------------------------------------------------------------------------------- /** * @brief BitField helper class. * * Generally this class won't be used directly. The derived BitField would be used instead, unless you need to define * a particular bit explicitly, rather than in relation to a previous bitfield. * * @tparam BITMAP bitmap class. * @tparam OFFSET_VALUE 0 based offset of the bitfield within the bitmap. * @tparam LENGTH_VALUE length of the bitfield in bits. */ template class BitFieldHelper : public BitFieldHelperBase { }; // --------------------------------------------------------------------------------------------------------------------------------- /** * @brief BitField helper class. * * Specialization for single bit fields to add an IsSet() function. * * Generally this class won't be used directly. The derived BitField would be used instead, unless you need to define * a particular bit explicitly, rather than in relation to a previous bitfield. * * @tparam BITMAP bitmap class. * @tparam OFFSET_VALUE 0 based offset of the bitfield within the bitmap. * @tparam LENGTH_VALUE length of the bitfield in bits. */ template class BitFieldHelper : public BitFieldHelperBase { private: typedef BitFieldHelperBase Base; public: typedef typename Base::Type Type; /** * @brief Get the boolean value of a single bit bitfield. * * @param bitmap the bitmap from which to retrieve the field. * * @return The boolean value of the single bit. */ static bool IsSet(const Type bitmap) { return (0 != Base::GetUnshifted(bitmap)); } }; // --------------------------------------------------------------------------------------------------------------------------------- // --------------------------------------------------------------------------------------------------------------------------------- /** * @brief Helper template to define a compile-time constant for a BitField value. * * @param BITFIELD the BitField template. * @param VALUE the constant value for the BitField. */ template class BitFieldConstant { public: typedef BITFIELD BitFieldType; ///! Hook back to the BitField type. ACTIV_BOOST_STATIC_ASSERT(VALUE <= BitFieldType::maxValue); static const typename BitFieldType::Type value = static_cast(VALUE); }; // --------------------------------------------------------------------------------------------------------------------------------- // --------------------------------------------------------------------------------------------------------------------------------- #if (defined ACTIV_BOOST_NO_CXX11_VARIADIC_TEMPLATES) /** * @brief Helper template to create a compile-time constant for a set of Bitmap fields. * * Usage: *
 *	ACTIV_BOOST_STATIC_ASSERT(BitmapConstant<
 *		BitFieldConstant,
 *		BitFieldConstant
 *	>::value == 30);
 *	
* * BitFields which aren't specified will have the value 0. * * The maximum length of a Bitmap is 8 bytes, so this template supports 64 BitFieldConstant parameters. */ template class BitmapConstant { private: // The first type cannot be void. ACTIV_BOOST_STATIC_ASSERT(!Boost::is_void::value); // Create lists of the provided types. vector has a max template arity of 50, so two lists. typedef Boost::mpl::vector32 TypeList1; typedef Boost::mpl::vector32 TypeList2; // Create lists of types that aren't void. typedef typename Boost::mpl::copy_if< TypeList1, Boost::mpl::not_ >, Boost::mpl::back_inserter > >::type NoVoidTypeList1; typedef typename Boost::mpl::copy_if< TypeList2, Boost::mpl::not_ >, Boost::mpl::back_inserter > >::type NoVoidTypeList2; // Create shifted mpl constants for each type. typedef typename Boost::mpl::transform< NoVoidTypeList1, BitmapDetail::BitFieldConstantShifted >::type ShiftedTypeList1; typedef typename Boost::mpl::transform< NoVoidTypeList2, BitmapDetail::BitFieldConstantShifted >::type ShiftedTypeList2; // Finally bitwise or each shifted constant, starting with initial state of 0. typedef typename Boost::mpl::fold< ShiftedTypeList1, Boost::mpl::integral_c, Boost::mpl::bitor_ >::type State1; typedef typename Boost::mpl::fold< ShiftedTypeList2, State1, Boost::mpl::bitor_ >::type State2; public: //! Compile-time constant for a set of BitField values. static const typename T1::BitFieldType::Type value = State2::type::value; }; // --------------------------------------------------------------------------------------------------------------------------------- // --------------------------------------------------------------------------------------------------------------------------------- #define ACTIV_MISC_BIT_FIELDS_BITMAP_VALUE_TEMPLATE_PARAM(z, n, data) , typename T##n #define ACTIV_MISC_BIT_FIELDS_BITMAP_VALUE_FUNCTION_PARAM(z, n, data) , T##n t##n #define ACTIV_MISC_BIT_FIELDS_BITMAP_VALUE_OR_FIELD(z, n, data) | (t##n.m_value << T##n::BitFieldType::offset) #define ACTIV_MISC_BIT_FIELDS_BITMAP_VALUE(z, n, data) \ template \ typename T1::BitFieldType::Type operator()(T1 t1 \ ACTIV_BOOST_PP_REPEAT_FROM_TO(2, ACTIV_BOOST_PP_INC(n), ACTIV_MISC_BIT_FIELDS_BITMAP_VALUE_FUNCTION_PARAM, )) const \ { \ return (t1.m_value << T1::BitFieldType::offset) \ ACTIV_BOOST_PP_REPEAT_FROM_TO(2, ACTIV_BOOST_PP_INC(n), ACTIV_MISC_BIT_FIELDS_BITMAP_VALUE_OR_FIELD, ); \ } // --------------------------------------------------------------------------------------------------------------------------------- /** * @brief Helper class to create run-time Bitmap values. * * assert(BitmapValue()(MyBitmap::Length::Value(1), MyBitmap::MessageType::Value(12)) == 49); * * If the BitField values are compile-time constants then the BitmapConstant template is preferred, since it is compile-time only. * * Note an arity of up to 32 BitField::Value parameters is supported. Compilation time is excessive with higher values. */ class BitmapValue { public: ACTIV_BOOST_PP_REPEAT_FROM_TO(1, ACTIV_BOOST_PP_INC(32), ACTIV_MISC_BIT_FIELDS_BITMAP_VALUE, ) }; // --------------------------------------------------------------------------------------------------------------------------------- #undef ACTIV_MISC_BIT_FIELDS_BITMAP_VALUE #undef ACTIV_MISC_BIT_FIELDS_BITMAP_VALUE_OR_FIELD #undef ACTIV_MISC_BIT_FIELDS_BITMAP_VALUE_FUNCTION_PARAM #undef ACTIV_MISC_BIT_FIELDS_BITMAP_VALUE_TEMPLATE_PARAM // --------------------------------------------------------------------------------------------------------------------------------- // --------------------------------------------------------------------------------------------------------------------------------- #else /** * @brief Helper class to create run-time Bitmap values. * * assert(BitmapValue()(MyBitmap::Length::Value(1), MyBitmap::MessageType::Value(12)) == 49); * * If the BitField values are compile-time constants then the BitmapConstant template is preferred, since it is compile-time only. */ class BitmapValue { public: template typename T1::BitFieldType::Type operator()(T1 t1) const { return (t1.m_value << T1::BitFieldType::offset); } template typename T1::BitFieldType::Type operator()(T1 t1, Tn... tn) const { return operator()(t1) | operator()(tn...); } }; // --------------------------------------------------------------------------------------------------------------------------------- // --------------------------------------------------------------------------------------------------------------------------------- /** * @brief Helper template to create a compile-time constant for a set of Bitmap fields. * * Usage: *
 *	ACTIV_BOOST_STATIC_ASSERT(BitmapConstant<
 *		BitFieldConstant,
 *		BitFieldConstant
 *	>::value == 30);
 *	
* * BitFields which aren't specified will have the value 0. */ template class BitmapConstant { public: //! Compile-time constant for a set of BitField values. static const typename T1::BitFieldType::Type value = BitmapConstant::value | BitmapConstant::value; }; template class BitmapConstant { public: static const typename T1::BitFieldType::Type value = (T1::value << T1::BitFieldType::offset); }; #endif // --------------------------------------------------------------------------------------------------------------------------------- // --------------------------------------------------------------------------------------------------------------------------------- namespace BitmapDetail { template class BitmapFieldOffset { // Nothing. Use specializations. }; // --------------------------------------------------------------------------------------------------------------------------------- template class BitmapFieldOffset, LENGTH_VALUE, LsbOrigin> { public: // Initial field. static const size_t value = 0; }; // --------------------------------------------------------------------------------------------------------------------------------- template class BitmapFieldOffset { public: static const size_t value = PREVIOUS_FIELD::offset + PREVIOUS_FIELD::length; ACTIV_BOOST_STATIC_ASSERT((value + LENGTH_VALUE) <= (PREVIOUS_FIELD::BitmapType::numberOfBits + PREVIOUS_FIELD::BitmapType::baseOffset)); }; // --------------------------------------------------------------------------------------------------------------------------------- template class BitmapFieldOffset, LENGTH_VALUE, LsbOrigin> { public: // Can't be longer than the containing BitField. ACTIV_BOOST_STATIC_ASSERT(LENGTH_VALUE <= BITFIELD::length); static const size_t value = BITFIELD::offset; }; // --------------------------------------------------------------------------------------------------------------------------------- template class BitmapFieldOffset, LENGTH_VALUE, MsbOrigin> { public: // Initial field. typedef Bitmap BitmapType; ACTIV_BOOST_STATIC_ASSERT(LENGTH_VALUE <= BitmapType::numberOfBits); static const size_t value = (sizeof(typename BitmapType::Type) * CHAR_BIT) - LENGTH_VALUE; }; // --------------------------------------------------------------------------------------------------------------------------------- template class BitmapFieldOffset { public: ACTIV_BOOST_STATIC_ASSERT(PREVIOUS_FIELD::offset >= LENGTH_VALUE); static const size_t value = PREVIOUS_FIELD::offset - LENGTH_VALUE; // For bitmaps that don't start at a 0 offset. ACTIV_BOOST_STATIC_ASSERT(value >= PREVIOUS_FIELD::BitmapType::baseOffset); }; // --------------------------------------------------------------------------------------------------------------------------------- template class BitmapFieldOffset, LENGTH_VALUE, MsbOrigin> { public: // Can't be longer than the containing BitField. ACTIV_BOOST_STATIC_ASSERT(LENGTH_VALUE <= BITFIELD::length); static const size_t value = BITFIELD::offset + BITFIELD::length - LENGTH_VALUE; }; // --------------------------------------------------------------------------------------------------------------------------------- // --------------------------------------------------------------------------------------------------------------------------------- template class TerminalBitmapFieldLength { // Nothing. Use specializations. }; // --------------------------------------------------------------------------------------------------------------------------------- template class TerminalBitmapFieldLength, LsbOrigin> { public: // Initial field is terminal field; length is whole bitmap. static const size_t value = N; }; // --------------------------------------------------------------------------------------------------------------------------------- template class TerminalBitmapFieldLength, LsbOrigin> { public: // Initial field is terminal field for a NestedBitmap; length is whole bitmap. static const size_t value = BITFIELD::length; }; // --------------------------------------------------------------------------------------------------------------------------------- template class TerminalBitmapFieldLength { public: static const size_t value = (PREVIOUS_FIELD::BitmapType::numberOfBits + PREVIOUS_FIELD::BitmapType::baseOffset) - (PREVIOUS_FIELD::offset + PREVIOUS_FIELD::length); ACTIV_BOOST_STATIC_ASSERT((PREVIOUS_FIELD::BitmapType::numberOfBits + PREVIOUS_FIELD::BitmapType::baseOffset) > (PREVIOUS_FIELD::offset + PREVIOUS_FIELD::length)); }; // --------------------------------------------------------------------------------------------------------------------------------- template class TerminalBitmapFieldLength, MsbOrigin> { public: // Initial field is terminal field for a Bitmap; length is whole bitmap. static const size_t value = N; }; // --------------------------------------------------------------------------------------------------------------------------------- template class TerminalBitmapFieldLength, MsbOrigin> { public: // Initial field is terminal field for a NestedBitmap; length is whole bitmap. static const size_t value = BITFIELD::length; }; // --------------------------------------------------------------------------------------------------------------------------------- template class TerminalBitmapFieldLength { public: // Terminal field has preceding fields; length is remainder. ACTIV_BOOST_STATIC_ASSERT(PREVIOUS_FIELD::offset > PREVIOUS_FIELD::BitmapType::baseOffset); static const size_t value = PREVIOUS_FIELD::offset - PREVIOUS_FIELD::BitmapType::baseOffset; }; } // namespace BitmapDetail // --------------------------------------------------------------------------------------------------------------------------------- // --------------------------------------------------------------------------------------------------------------------------------- /** * @brief BitField class. * * @param PREVIOUS_FIELD previous field type, or Bitmap type for the initial field. * @param LENGTH_VALUE length of the bitfield in bits. */ template class BitField : public BitFieldHelper< typename PREVIOUS_FIELD::BitmapType, BitmapDetail::BitmapFieldOffset::value, LENGTH_VALUE> { }; // --------------------------------------------------------------------------------------------------------------------------------- // --------------------------------------------------------------------------------------------------------------------------------- /** * @brief TerminalBitField class. * * Use the remaining bits in a bitmap for a field (up to the number of bits N provided to the Bitmap class, * not the integral size of the underlying type). * * @param PREVIOUS_FIELD previous field type, or Bitmap type for the initial field. */ template class TerminalBitField : public BitFieldHelper< typename PREVIOUS_FIELD::BitmapType, BitmapDetail::BitmapFieldOffset::value, typename PREVIOUS_FIELD::BitmapType::Origin>::value, BitmapDetail::TerminalBitmapFieldLength::value> { }; } // namespace Activ #endif // (!defined ACTIV_MISC_BIT_FIELDS_H)