bitunion.hh revision 4680
1/* 2 * Copyright (c) 2003-2005 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 <inttypes.h> 35#include "base/bitfield.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). 48namespace 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 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 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 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 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 operator Type () const 197 { 198 return Base::__data; 199 } 200 201 Type 202 operator=(const Type & _data) 203 { 204 Base::__data = _data; 205 return _data; 206 } 207 208 bool 209 operator<(const Base & base) const 210 { 211 return Base::__data < base.__data; 212 } 213 214 bool 215 operator==(const Base & base) const 216 { 217 return Base::__data == base.__data; 218 } 219 }; 220} 221 222//This macro is a backend for other macros that specialize it slightly. 223//First, it creates/extends a namespace "BitfieldUnderlyingClasses" and 224//sticks the class which has the actual union in it, which 225//BitfieldOperators above inherits from. Putting these classes in a special 226//namespace ensures that there will be no collisions with other names as long 227//as the BitUnion names themselves are all distinct and nothing else uses 228//the BitfieldUnderlyingClasses namespace, which is unlikely. The class itself 229//creates a typedef of the "type" parameter called __DataType. This allows 230//the type to propagate outside of the macro itself in a controlled way. 231//Finally, the base storage is defined which BitfieldOperators will refer to 232//in the operators it defines. This macro is intended to be followed by 233//bitfield definitions which will end up inside it's union. As explained 234//above, these is overlayed the __data member in its entirety by each of the 235//bitfields which are defined in the union, creating shared storage with no 236//overhead. 237#define __BitUnion(type, name) \ 238 namespace BitfieldUnderlyingClasses \ 239 { \ 240 class name; \ 241 } \ 242 class BitfieldUnderlyingClasses::name : \ 243 public BitfieldBackend::BitfieldTypes<type> \ 244 { \ 245 public: \ 246 typedef type __DataType; \ 247 union { \ 248 type __data;\ 249 250//This closes off the class and union started by the above macro. It is 251//followed by a typedef which makes "name" refer to a BitfieldOperator 252//class inheriting from the class and union just defined, which completes 253//building up the type for the user. 254#define EndBitUnion(name) \ 255 }; \ 256 }; \ 257 typedef BitfieldBackend::BitUnionOperators< \ 258 BitfieldUnderlyingClasses::name::__DataType, \ 259 BitfieldUnderlyingClasses::name> name; 260 261//This sets up a bitfield which has other bitfields nested inside of it. The 262//__data member functions like the "underlying storage" of the top level 263//BitUnion. Like everything else, it overlays with the top level storage, so 264//making it a regular bitfield type makes the entire thing function as a 265//regular bitfield when referred to by itself. 266#define __SubBitUnion(fieldType, first, last, name) \ 267 class : public BitfieldBackend::BitfieldTypes<__DataType> \ 268 { \ 269 public: \ 270 union { \ 271 fieldType<first, last> __data; 272 273//This closes off the union created above and gives it a name. Unlike the top 274//level BitUnion, we're interested in creating an object instead of a type. 275//The operators are defined in the macro itself instead of a class for 276//technical reasons. If someone determines a way to move them to one, please 277//do so. 278#define EndSubBitUnion(name) \ 279 }; \ 280 inline operator const __DataType () \ 281 { return __data; } \ 282 \ 283 inline const __DataType operator = (const __DataType & _data) \ 284 { __data = _data; } \ 285 } name; 286 287//Regular bitfields 288//These define macros for read/write regular bitfield based subbitfields. 289#define SubBitUnion(name, first, last) \ 290 __SubBitUnion(Bitfield, first, last, name) 291 292//Regular bitfields 293//These define macros for read/write regular bitfield based subbitfields. 294#define SignedSubBitUnion(name, first, last) \ 295 __SubBitUnion(SignedBitfield, first, last, name) 296 297//Use this to define an arbitrary type overlayed with bitfields. 298#define BitUnion(type, name) __BitUnion(type, name) 299 300//Use this to define conveniently sized values overlayed with bitfields. 301#define BitUnion64(name) __BitUnion(uint64_t, name) 302#define BitUnion32(name) __BitUnion(uint32_t, name) 303#define BitUnion16(name) __BitUnion(uint16_t, name) 304#define BitUnion8(name) __BitUnion(uint8_t, name) 305 306#endif // __BASE_BITUNION_HH__ 307