src/base/bitunion.hh

   1 /*
   2  * Copyright (c) 2007-2008 The Regents of The University of Michigan
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions are
   7  * met: redistributions of source code must retain the above copyright
   8  * notice, this list of conditions and the following disclaimer;
   9  * redistributions in binary form must reproduce the above copyright
  10  * notice, this list of conditions and the following disclaimer in the
  11  * documentation and/or other materials provided with the distribution;
  12  * neither the name of the copyright holders nor the names of its
  13  * contributors may be used to endorse or promote products derived from
  14  * this software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  17  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  18  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  19  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  20  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  21  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  22  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  26  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27  *
  28  * Authors: Gabe Black
  29  */
  30
  31 #ifndef __BASE_BITUNION_HH__
  32 #define __BASE_BITUNION_HH__
  33
  34 #include "base/bitfield.hh"
  35 #include "base/types.hh"
  36
  37 //      The following implements the BitUnion system of defining bitfields
  38 //on top of an underlying class. This is done through the pervasive use of
  39 //both named and unnamed unions which all contain the same actual storage.
  40 //Since they're unioned with each other, all of these storage locations
  41 //overlap. This allows all of the bitfields to manipulate the same data
  42 //without having to have access to each other. More details are provided with
  43 //the individual components.
  44
  45 //This namespace is for classes which implement the backend of the BitUnion
  46 //stuff. Don't use any of these directly, except for the Bitfield classes in
  47 //the *BitfieldTypes class(es).
  48 namespace BitfieldBackend
  49 {
  50     //A base class for all bitfields. It instantiates the actual storage,
  51     //and provides getBits and setBits functions for manipulating it. The
  52     //Data template parameter is type of the underlying storage.
  53     template<class Data>
  54     class BitfieldBase
  55     {
  56       protected:
  57         Data __data;
  58
  59         //This function returns a range of bits from the underlying storage.
  60         //It relies on the "bits" function above. It's the user's
  61         //responsibility to make sure that there is a properly overloaded
  62         //version of this function for whatever type they want to overlay.
  63         inline uint64_t
  64         getBits(int first, int last) const
  65         {
  66             return bits(__data, first, last);
  67         }
  68
  69         //Similar to the above, but for settings bits with replaceBits.
  70         inline void
  71         setBits(int first, int last, uint64_t val)
  72         {
  73             replaceBits(__data, first, last, val);
  74         }
  75     };
  76
  77     //This class contains all the "regular" bitfield classes. It is inherited
  78     //by all BitUnions which give them access to those types.
  79     template<class Type>
  80     class RegularBitfieldTypes
  81     {
  82       protected:
  83         //This class implements ordinary bitfields, that is a span of bits
  84         //who's msb is "first", and who's lsb is "last".
  85         template<int first, int last=first>
  86         class Bitfield : public BitfieldBase<Type>
  87         {
  88           public:
  89             operator const uint64_t () const
  90             {
  91                 return this->getBits(first, last);
  92             }
  93
  94             uint64_t
  95             operator=(const uint64_t _data)
  96             {
  97                 this->setBits(first, last, _data);
  98                 return _data;
  99             }
 100         };
 101
 102         //A class which specializes the above so that it can only be read
 103         //from. This is accomplished explicitly making sure the assignment
 104         //operator is blocked. The conversion operator is carried through
 105         //inheritance. This will unfortunately need to be copied into each
 106         //bitfield type due to limitations with how templates work
 107         template<int first, int last=first>
 108         class BitfieldRO : public Bitfield<first, last>
 109         {
 110           private:
 111             uint64_t
 112             operator=(const uint64_t _data);
 113         };
 114
 115         //Similar to the above, but only allows writing.
 116         template<int first, int last=first>
 117         class BitfieldWO : public Bitfield<first, last>
 118         {
 119           private:
 120             operator const uint64_t () const;
 121
 122           public:
 123             using Bitfield<first, last>::operator=;
 124         };
 125     };
 126
 127     //This class contains all the "regular" bitfield classes. It is inherited
 128     //by all BitUnions which give them access to those types.
 129     template<class Type>
 130     class SignedBitfieldTypes
 131     {
 132       protected:
 133         //This class implements ordinary bitfields, that is a span of bits
 134         //who's msb is "first", and who's lsb is "last".
 135         template<int first, int last=first>
 136         class SignedBitfield : public BitfieldBase<Type>
 137         {
 138           public:
 139             operator const int64_t () const
 140             {
 141                 return sext<first - last + 1>(this->getBits(first, last));
 142             }
 143
 144             int64_t
 145             operator=(const int64_t _data)
 146             {
 147                 this->setBits(first, last, _data);
 148                 return _data;
 149             }
 150         };
 151
 152         //A class which specializes the above so that it can only be read
 153         //from. This is accomplished explicitly making sure the assignment
 154         //operator is blocked. The conversion operator is carried through
 155         //inheritance. This will unfortunately need to be copied into each
 156         //bitfield type due to limitations with how templates work
 157         template<int first, int last=first>
 158         class SignedBitfieldRO : public SignedBitfield<first, last>
 159         {
 160           private:
 161             int64_t
 162             operator=(const int64_t _data);
 163         };
 164
 165         //Similar to the above, but only allows writing.
 166         template<int first, int last=first>
 167         class SignedBitfieldWO : public SignedBitfield<first, last>
 168         {
 169           private:
 170             operator const int64_t () const;
 171
 172           public:
 173             int64_t operator=(const int64_t _data)
 174             {
 175                 *((SignedBitfield<first, last> *)this) = _data;
 176                 return _data;
 177             }
 178         };
 179     };
 180
 181     template<class Type>
 182     class BitfieldTypes : public RegularBitfieldTypes<Type>,
 183                           public SignedBitfieldTypes<Type>
 184     {};
 185
 186     //When a BitUnion is set up, an underlying class is created which holds
 187     //the actual union. This class then inherits from it, and provids the
 188     //implementations for various operators. Setting things up this way
 189     //prevents having to redefine these functions in every different BitUnion
 190     //type. More operators could be implemented in the future, as the need
 191     //arises.
 192     template <class Type, class Base>
 193     class BitUnionOperators : public Base
 194     {
 195       public:
 196         BitUnionOperators(Type const & _data)
 197         {
 198             Base::__data = _data;
 199         }
 200
 201         BitUnionOperators() {}
 202
 203         operator const Type () const
 204         {
 205             return Base::__data;
 206         }
 207
 208         Type
 209         operator=(Type const & _data)
 210         {
 211             Base::__data = _data;
 212             return _data;
 213         }
 214
 215         bool
 216         operator<(Base const & base) const
 217         {
 218             return Base::__data < base.__data;
 219         }
 220
 221         bool
 222         operator==(Base const & base) const
 223         {
 224             return Base::__data == base.__data;
 225         }
 226     };
 227 }
 228
 229 //This macro is a backend for other macros that specialize it slightly.
 230 //First, it creates/extends a namespace "BitfieldUnderlyingClasses" and
 231 //sticks the class which has the actual union in it, which
 232 //BitfieldOperators above inherits from. Putting these classes in a special
 233 //namespace ensures that there will be no collisions with other names as long
 234 //as the BitUnion names themselves are all distinct and nothing else uses
 235 //the BitfieldUnderlyingClasses namespace, which is unlikely. The class itself
 236 //creates a typedef of the "type" parameter called __DataType. This allows
 237 //the type to propagate outside of the macro itself in a controlled way.
 238 //Finally, the base storage is defined which BitfieldOperators will refer to
 239 //in the operators it defines. This macro is intended to be followed by
 240 //bitfield definitions which will end up inside it's union. As explained
 241 //above, these is overlayed the __data member in its entirety by each of the
 242 //bitfields which are defined in the union, creating shared storage with no
 243 //overhead.
 244 #define __BitUnion(type, name) \
 245     class BitfieldUnderlyingClasses##name : \
 246         public BitfieldBackend::BitfieldTypes<type> \
 247     { \
 248       public: \
 249         typedef type __DataType; \
 250         union { \
 251             type __data;\
 252
 253 //This closes off the class and union started by the above macro. It is
 254 //followed by a typedef which makes "name" refer to a BitfieldOperator
 255 //class inheriting from the class and union just defined, which completes
 256 //building up the type for the user.
 257 #define EndBitUnion(name) \
 258         }; \
 259     }; \
 260     typedef BitfieldBackend::BitUnionOperators< \
 261         BitfieldUnderlyingClasses##name::__DataType, \
 262         BitfieldUnderlyingClasses##name> name;
 263
 264 //This sets up a bitfield which has other bitfields nested inside of it. The
 265 //__data member functions like the "underlying storage" of the top level
 266 //BitUnion. Like everything else, it overlays with the top level storage, so
 267 //making it a regular bitfield type makes the entire thing function as a
 268 //regular bitfield when referred to by itself.
 269 #define __SubBitUnion(fieldType, first, last, name) \
 270     class : public BitfieldBackend::BitfieldTypes<__DataType> \
 271     { \
 272       public: \
 273         union { \
 274             fieldType<first, last> __data;
 275
 276 //This closes off the union created above and gives it a name. Unlike the top
 277 //level BitUnion, we're interested in creating an object instead of a type.
 278 //The operators are defined in the macro itself instead of a class for
 279 //technical reasons. If someone determines a way to move them to one, please
 280 //do so.
 281 #define EndSubBitUnion(name) \
 282         }; \
 283         inline operator const __DataType () const \
 284         { return __data; } \
 285         \
 286         inline const __DataType operator = (const __DataType & _data) \
 287         { return __data = _data;} \
 288     } name;
 289
 290 //Regular bitfields
 291 //These define macros for read/write regular bitfield based subbitfields.
 292 #define SubBitUnion(name, first, last) \
 293     __SubBitUnion(Bitfield, first, last, name)
 294
 295 //Regular bitfields
 296 //These define macros for read/write regular bitfield based subbitfields.
 297 #define SignedSubBitUnion(name, first, last) \
 298     __SubBitUnion(SignedBitfield, first, last, name)
 299
 300 //Use this to define an arbitrary type overlayed with bitfields.
 301 #define BitUnion(type, name) __BitUnion(type, name)
 302
 303 //Use this to define conveniently sized values overlayed with bitfields.
 304 #define BitUnion64(name) __BitUnion(uint64_t, name)
 305 #define BitUnion32(name) __BitUnion(uint32_t, name)
 306 #define BitUnion16(name) __BitUnion(uint16_t, name)
 307 #define BitUnion8(name) __BitUnion(uint8_t, name)
 308
 309 #endif // __BASE_BITUNION_HH__