bitfield.hh revision 4425:e94d396daad9
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: Steve Reinhardt 29 * Nathan Binkert 30 */ 31 32#ifndef __BASE_BITFIELD_HH__ 33#define __BASE_BITFIELD_HH__ 34 35#include <inttypes.h> 36 37/** 38 * Generate a 64-bit mask of 'nbits' 1s, right justified. 39 */ 40inline uint64_t 41mask(int nbits) 42{ 43 return (nbits == 64) ? (uint64_t)-1LL : (1ULL << nbits) - 1; 44} 45 46 47 48/** 49 * Extract the bitfield from position 'first' to 'last' (inclusive) 50 * from 'val' and right justify it. MSB is numbered 63, LSB is 0. 51 */ 52template <class T> 53inline 54T 55bits(T val, int first, int last) 56{ 57 int nbits = first - last + 1; 58 return (val >> last) & mask(nbits); 59} 60 61/** 62 * Mask off the given bits in place like bits() but without shifting. 63 * msb = 63, lsb = 0 64 */ 65template <class T> 66inline 67T 68mbits(T val, int first, int last) 69{ 70 return val & (mask(first+1) & ~mask(last)); 71} 72 73inline uint64_t 74mask(int first, int last) 75{ 76 return mbits((uint64_t)-1LL, first, last); 77} 78 79/** 80 * Sign-extend an N-bit value to 64 bits. 81 */ 82template <int N> 83inline 84int64_t 85sext(uint64_t val) 86{ 87 int sign_bit = bits(val, N-1, N-1); 88 return sign_bit ? (val | ~mask(N)) : val; 89} 90 91/** 92 * Return val with bits first to last set to bit_val 93 */ 94template <class T, class B> 95inline 96T 97insertBits(T val, int first, int last, B bit_val) 98{ 99 T t_bit_val = bit_val; 100 T bmask = mask(first - last + 1) << last; 101 return ((t_bit_val << last) & bmask) | (val & ~bmask); 102} 103 104/** 105 * A convenience function to replace bits first to last of val with bit_val 106 * in place. 107 */ 108template <class T, class B> 109inline 110void 111replaceBits(T& val, int first, int last, B bit_val) 112{ 113 val = insertBits(val, first, last, bit_val); 114} 115 116/** 117 * Returns the bit position of the MSB that is set in the input 118 */ 119inline 120int 121findMsbSet(uint64_t val) { 122 int msb = 0; 123 if (!val) 124 return 0; 125 if (bits(val, 63,32)) { msb += 32; val >>= 32; } 126 if (bits(val, 31,16)) { msb += 16; val >>= 16; } 127 if (bits(val, 15,8)) { msb += 8; val >>= 8; } 128 if (bits(val, 7,4)) { msb += 4; val >>= 4; } 129 if (bits(val, 3,2)) { msb += 2; val >>= 2; } 130 if (bits(val, 1,1)) { msb += 1; } 131 return msb; 132} 133 134// The following implements the BitUnion system of defining bitfields 135//on top of an underlying class. This is done through the pervasive use of 136//both named and unnamed unions which all contain the same actual storage. 137//Since they're unioned with each other, all of these storage locations 138//overlap. This allows all of the bitfields to manipulate the same data 139//without having to have access to each other. More details are provided with the 140//individual components. 141 142//This namespace is for classes which implement the backend of the BitUnion 143//stuff. Don't use any of these directly, except for the Bitfield classes in 144//the *BitfieldTypes class(es). 145namespace BitfieldBackend 146{ 147 //A base class for all bitfields. It instantiates the actual storage, 148 //and provides getBits and setBits functions for manipulating it. The 149 //Data template parameter is type of the underlying storage. 150 template<class Data> 151 class BitfieldBase 152 { 153 protected: 154 Data __data; 155 156 //This function returns a range of bits from the underlying storage. 157 //It relies on the "bits" function above. It's the user's 158 //responsibility to make sure that there is a properly overloaded 159 //version of this function for whatever type they want to overlay. 160 inline uint64_t 161 getBits(int first, int last) const 162 { 163 return bits(__data, first, last); 164 } 165 166 //Similar to the above, but for settings bits with replaceBits. 167 inline void 168 setBits(int first, int last, uint64_t val) 169 { 170 replaceBits(__data, first, last, val); 171 } 172 }; 173 174 //This class contains all the "regular" bitfield classes. It is inherited 175 //by all BitUnions which give them access to those types. 176 template<class Type> 177 class RegularBitfieldTypes 178 { 179 protected: 180 //This class implements ordinary bitfields, that is a span of bits 181 //who's msb is "first", and who's lsb is "last". 182 template<int first, int last=first> 183 class Bitfield : public BitfieldBase<Type> 184 { 185 public: 186 operator uint64_t () const 187 { 188 return this->getBits(first, last); 189 } 190 191 uint64_t 192 operator=(const uint64_t _data) 193 { 194 this->setBits(first, last, _data); 195 return _data; 196 } 197 }; 198 199 //A class which specializes the above so that it can only be read 200 //from. This is accomplished explicitly making sure the assignment 201 //operator is blocked. The conversion operator is carried through 202 //inheritance. This will unfortunately need to be copied into each 203 //bitfield type due to limitations with how templates work 204 template<int first, int last=first> 205 class BitfieldRO : public Bitfield<first, last> 206 { 207 private: 208 uint64_t 209 operator=(const uint64_t _data); 210 }; 211 212 //Similar to the above, but only allows writing. 213 template<int first, int last=first> 214 class BitfieldWO : public Bitfield<first, last> 215 { 216 private: 217 operator uint64_t () const; 218 219 public: 220 using Bitfield<first, last>::operator=; 221 }; 222 }; 223 224 //This class contains all the "regular" bitfield classes. It is inherited 225 //by all BitUnions which give them access to those types. 226 template<class Type> 227 class SignedBitfieldTypes 228 { 229 protected: 230 //This class implements ordinary bitfields, that is a span of bits 231 //who's msb is "first", and who's lsb is "last". 232 template<int first, int last=first> 233 class SignedBitfield : public BitfieldBase<Type> 234 { 235 public: 236 operator int64_t () const 237 { 238 return sext<first - last + 1>(this->getBits(first, last)); 239 } 240 241 int64_t 242 operator=(const int64_t _data) 243 { 244 this->setBits(first, last, _data); 245 return _data; 246 } 247 }; 248 249 //A class which specializes the above so that it can only be read 250 //from. This is accomplished explicitly making sure the assignment 251 //operator is blocked. The conversion operator is carried through 252 //inheritance. This will unfortunately need to be copied into each 253 //bitfield type due to limitations with how templates work 254 template<int first, int last=first> 255 class SignedBitfieldRO : public SignedBitfield<first, last> 256 { 257 private: 258 int64_t 259 operator=(const int64_t _data); 260 }; 261 262 //Similar to the above, but only allows writing. 263 template<int first, int last=first> 264 class SignedBitfieldWO : public SignedBitfield<first, last> 265 { 266 private: 267 operator int64_t () const; 268 269 public: 270 int64_t operator=(const int64_t _data) 271 { 272 *((SignedBitfield<first, last> *)this) = _data; 273 return _data; 274 } 275 }; 276 }; 277 278 template<class Type> 279 class BitfieldTypes : public RegularBitfieldTypes<Type>, 280 public SignedBitfieldTypes<Type> 281 {}; 282 283 //When a BitUnion is set up, an underlying class is created which holds 284 //the actual union. This class then inherits from it, and provids the 285 //implementations for various operators. Setting things up this way 286 //prevents having to redefine these functions in every different BitUnion 287 //type. More operators could be implemented in the future, as the need 288 //arises. 289 template <class Type, class Base> 290 class BitUnionOperators : public Base 291 { 292 public: 293 operator Type () const 294 { 295 return Base::__data; 296 } 297 298 Type 299 operator=(const Type & _data) 300 { 301 Base::__data = _data; 302 return _data; 303 } 304 305 bool 306 operator<(const Base & base) const 307 { 308 return Base::__data < base.__data; 309 } 310 311 bool 312 operator==(const Base & base) const 313 { 314 return Base::__data == base.__data; 315 } 316 }; 317} 318 319//This macro is a backend for other macros that specialize it slightly. 320//First, it creates/extends a namespace "BitfieldUnderlyingClasses" and 321//sticks the class which has the actual union in it, which 322//BitfieldOperators above inherits from. Putting these classes in a special 323//namespace ensures that there will be no collisions with other names as long 324//as the BitUnion names themselves are all distinct and nothing else uses 325//the BitfieldUnderlyingClasses namespace, which is unlikely. The class itself 326//creates a typedef of the "type" parameter called __DataType. This allows 327//the type to propagate outside of the macro itself in a controlled way. 328//Finally, the base storage is defined which BitfieldOperators will refer to 329//in the operators it defines. This macro is intended to be followed by 330//bitfield definitions which will end up inside it's union. As explained 331//above, these is overlayed the __data member in its entirety by each of the 332//bitfields which are defined in the union, creating shared storage with no 333//overhead. 334#define __BitUnion(type, name) \ 335 namespace BitfieldUnderlyingClasses \ 336 { \ 337 class name; \ 338 } \ 339 class BitfieldUnderlyingClasses::name : \ 340 public BitfieldBackend::BitfieldTypes<type> \ 341 { \ 342 public: \ 343 typedef type __DataType; \ 344 union { \ 345 type __data;\ 346 347//This closes off the class and union started by the above macro. It is 348//followed by a typedef which makes "name" refer to a BitfieldOperator 349//class inheriting from the class and union just defined, which completes 350//building up the type for the user. 351#define EndBitUnion(name) \ 352 }; \ 353 }; \ 354 typedef BitfieldBackend::BitUnionOperators< \ 355 BitfieldUnderlyingClasses::name::__DataType, \ 356 BitfieldUnderlyingClasses::name> name; 357 358//This sets up a bitfield which has other bitfields nested inside of it. The 359//__data member functions like the "underlying storage" of the top level 360//BitUnion. Like everything else, it overlays with the top level storage, so 361//making it a regular bitfield type makes the entire thing function as a 362//regular bitfield when referred to by itself. 363#define __SubBitUnion(fieldType, first, last, name) \ 364 class : public BitfieldBackend::BitfieldTypes<__DataType> \ 365 { \ 366 public: \ 367 union { \ 368 fieldType<first, last> __data; 369 370//This closes off the union created above and gives it a name. Unlike the top 371//level BitUnion, we're interested in creating an object instead of a type. 372//The operators are defined in the macro itself instead of a class for 373//technical reasons. If someone determines a way to move them to one, please 374//do so. 375#define EndSubBitUnion(name) \ 376 }; \ 377 inline operator const __DataType () \ 378 { return __data; } \ 379 \ 380 inline const __DataType operator = (const __DataType & _data) \ 381 { __data = _data; } \ 382 } name; 383 384//Regular bitfields 385//These define macros for read/write regular bitfield based subbitfields. 386#define SubBitUnion(name, first, last) \ 387 __SubBitUnion(Bitfield, first, last, name) 388 389//Regular bitfields 390//These define macros for read/write regular bitfield based subbitfields. 391#define SignedSubBitUnion(name, first, last) \ 392 __SubBitUnion(SignedBitfield, first, last, name) 393 394//Use this to define an arbitrary type overlayed with bitfields. 395#define BitUnion(type, name) __BitUnion(type, name) 396 397//Use this to define conveniently sized values overlayed with bitfields. 398#define BitUnion64(name) __BitUnion(uint64_t, name) 399#define BitUnion32(name) __BitUnion(uint32_t, name) 400#define BitUnion16(name) __BitUnion(uint16_t, name) 401#define BitUnion8(name) __BitUnion(uint8_t, name) 402 403#endif // __BASE_BITFIELD_HH__ 404