Zane Shelley | 871adec | 2019-07-30 11:01:39 -0500 | [diff] [blame] | 1 | #pragma once |
Zane Shelley | fd3f9cc | 2019-07-29 15:02:24 -0500 | [diff] [blame] | 2 | |
| 3 | // Module Description ************************************************** |
| 4 | // |
| 5 | // Description: This module contains the declarations for the |
| 6 | // Processor Runtime Diagnostics Scan Communication |
| 7 | // Register class. |
| 8 | // |
| 9 | // Notes: Unless stated otherwise, assume that each function |
| 10 | // specification has no side-effects, no dependencies, and |
| 11 | // constant time complexity. |
| 12 | // |
| 13 | // End Module Description ********************************************** |
| 14 | |
| 15 | |
| 16 | //---------------------------------------------------------------------- |
| 17 | // Includes |
| 18 | //---------------------------------------------------------------------- |
| 19 | |
| 20 | #include <iipbits.h> |
| 21 | #include <iipconst.h> |
| 22 | #include <iipsdbug.h> |
| 23 | #include <prdfMain.H> |
| 24 | #include <prdfTrace.H> |
| 25 | |
Zane Shelley | 871adec | 2019-07-30 11:01:39 -0500 | [diff] [blame] | 26 | namespace libhei |
Zane Shelley | fd3f9cc | 2019-07-29 15:02:24 -0500 | [diff] [blame] | 27 | { |
| 28 | |
| 29 | /*--------------------------------------------------------------------*/ |
| 30 | /* Forward References */ |
| 31 | /*--------------------------------------------------------------------*/ |
| 32 | |
| 33 | /*--------------------------------------------------------------------*/ |
| 34 | /* User Types */ |
| 35 | /*--------------------------------------------------------------------*/ |
| 36 | |
| 37 | /*--------------------------------------------------------------------*/ |
| 38 | /* Constants */ |
| 39 | /*--------------------------------------------------------------------*/ |
| 40 | |
| 41 | /*--------------------------------------------------------------------*/ |
| 42 | /* Macros */ |
| 43 | /*--------------------------------------------------------------------*/ |
| 44 | |
| 45 | /*--------------------------------------------------------------------*/ |
| 46 | /* Global Variables */ |
| 47 | /*--------------------------------------------------------------------*/ |
| 48 | |
| 49 | /*--------------------------------------------------------------------*/ |
| 50 | /* Function Prototypes */ |
| 51 | /*--------------------------------------------------------------------*/ |
| 52 | |
| 53 | // Class Specification ************************************************* |
| 54 | // |
| 55 | // Name: SCAN_COMM_REGISTER_CLASS |
| 56 | // |
| 57 | // Title: Scan Communication Register |
| 58 | // |
| 59 | // Purpose: SCAN_COMM_REGISTER_CLASS provides the representation |
| 60 | // and access to a physical register. |
| 61 | // |
| 62 | // Usage: This is an abstract base class. |
| 63 | // |
| 64 | // Side-effects: Memory is allocated. |
| 65 | // |
| 66 | // Dependencies: None. |
| 67 | // |
| 68 | // Notes: The Scan Communication Register is a model of an actual |
| 69 | // physical register. The bits in the register are represented by the |
| 70 | // bit_string data member which is modified dynamically as operations |
| 71 | // are preformed. It acts as a temporarily cached value of the |
| 72 | // register. When a read is performed, the bit values are updated in |
| 73 | // the bit string. When a write is performed, the current value of the |
| 74 | // bits are used as the value to write. The current value of this |
| 75 | // cached bit string can be accessed or modified by other objects via |
| 76 | // the public interface. The physical address and bit length of the |
| 77 | // hardware register are set during initialization and used on all |
| 78 | // acceses. |
| 79 | // |
| 80 | // The basic Read() and Write() functions are virtual. The |
| 81 | // actual implemenations are dependent on the actual hardware |
| 82 | // and the software Hardware Manual Ops Scan Control Routines. |
| 83 | // These function specifications describe a common behaviour |
| 84 | // that every derived class must follow. Additional, |
| 85 | // information may also be specified. |
| 86 | // |
| 87 | // A Read() function is also provided that has a Bit String |
| 88 | // mask parameter. This function calls the virtual Read() |
| 89 | // and then applies the mask so that the internal Bit String |
| 90 | // contains the hardware register contents with certain bits |
| 91 | // ignored (masked off). |
| 92 | // |
| 93 | // Cardinality: 0 |
| 94 | // |
| 95 | // Space Complexity: Linear |
| 96 | // K + Mn where K and M are constants and n is the |
| 97 | // number of bits in the register. |
| 98 | // |
| 99 | // End Class Specification ********************************************* |
| 100 | /** |
| 101 | SCAN_COMM_REGISTER_CLASS |
| 102 | @author Doug Gilbert |
| 103 | @V5R2 |
| 104 | */ |
| 105 | class SCAN_COMM_REGISTER_CLASS |
| 106 | { |
| 107 | public: // enums, structs, typedefs |
| 108 | |
| 109 | /** The register access level */ |
| 110 | enum AccessLevel |
| 111 | { |
| 112 | ACCESS_NONE = 0x0, ///< No access |
| 113 | ACCESS_RO = 0x1, ///< Read-only access |
| 114 | ACCESS_WO = 0x2, ///< Write-only access |
| 115 | ACCESS_RW = 0x3, ///< Read/Write access |
| 116 | }; |
| 117 | |
| 118 | public: // functions |
| 119 | |
| 120 | /** |
| 121 | Destructor |
| 122 | */ |
| 123 | virtual ~SCAN_COMM_REGISTER_CLASS(void); |
| 124 | |
| 125 | /** |
| 126 | Read hardware register (virtual) |
| 127 | <ul> |
| 128 | <br><b>Parameters: </b> None |
| 129 | <br><b>Returns: </b> [SUCCESS | MOPs return code] |
| 130 | <br><b>Requirements:</b> None. |
| 131 | <br><b>Promises: </b> Internal bit string represents the value of the |
| 132 | hardware register (if rc == SUCCESS) |
| 133 | <br><b>Sideaffects: </b> Value guaranteed to be read from hardware. |
| 134 | <br><b>Exceptions: </b> None. |
| 135 | <br><b>Notes: </b> Default is to call Read(). If a child class cannot |
| 136 | guarantee hardware access every time Read() is |
| 137 | called then the function ForceRead() should be |
| 138 | overridden. |
| 139 | </ul><br> |
| 140 | */ |
| 141 | virtual uint32_t ForceRead(void) const { return Read(); } |
| 142 | |
| 143 | /** |
| 144 | Read hardware register (pure virtual) |
| 145 | <ul> |
| 146 | <br><b>Parameters: </b> None |
| 147 | <br><b>Returns: </b> [SUCCESS | MOPs return code] |
| 148 | <br><b>Requirements:</b> None. |
| 149 | <br><b>Promises: </b> Internal bit string represents the value of the |
| 150 | hardware register (if rc == SUCCESS) |
| 151 | <br><b>Sideaffects: </b> The bit string value may or may not be retrieved |
| 152 | from hardware; a buffered copy may be used. |
| 153 | <br><b>Exceptions: </b> None. |
| 154 | </ul><br> |
| 155 | */ |
| 156 | virtual uint32_t Read(void) const = 0; |
| 157 | |
| 158 | /** |
| 159 | Read hardware register and apply a mask |
| 160 | <ul> |
| 161 | <br><b>Parameters: </b> Mask to apply |
| 162 | <br><b>Returns: </b> [SUCCESS | MOPs return code] |
| 163 | <br><b>Requirements:</b> None. |
| 164 | <br><b>Promises: </b> Internal bit string represents the value of the |
| 165 | hardware register with the bits turned off as |
| 166 | specified by the mask. |
| 167 | <br><b>Sideaffects: </b> The bit string value may or may not be retrieved |
| 168 | from hardware. a buffered copy may be used. |
| 169 | <br><b>Exceptions: </b> None. |
| 170 | <br><b>Notes: </b> if bits read from hardware = '00110100' |
| 171 | and mask = '01110000' |
| 172 | then internal bit sting = '00000100' |
| 173 | |
| 174 | if mask.Length() < GetBitString()->Length() |
| 175 | then mask is right extended with 0's |
| 176 | if mask.Length() > GetBitString()->Length() |
| 177 | then extra mask bits are ignored. |
| 178 | </ul><br> |
| 179 | */ |
| 180 | uint32_t Read(BitString & mask); |
| 181 | |
| 182 | /** |
| 183 | Write hardware register (pure virtual) |
| 184 | <ul> |
| 185 | <br><b>Parameters: </b> None |
| 186 | <br><b>Returns: </b> [SUCCESS | MOPs return code] |
| 187 | <br><b>Requirements:</b> None. |
| 188 | <br><b>Promises: </b> Internal bit string value written to hardware |
| 189 | <br><b>Exceptions: </b> None. |
| 190 | <br><b>Notes: </b> If internal bitstring was never read/set/modified then |
| 191 | zeros are written to corresponding hardware register. |
| 192 | </ul><br> |
| 193 | */ |
| 194 | virtual uint32_t Write(void) = 0; |
| 195 | |
| 196 | /** |
| 197 | Access a copy of the scan comm address |
| 198 | <ul> |
| 199 | <br><b>Parameters: </b> None |
| 200 | <br><b>Returns: </b> Returns scom address |
| 201 | <br><b>Requirements:</b> None. |
| 202 | <br><b>Promises: </b> None. |
| 203 | <br><b>Exceptions: </b> None. |
| 204 | </ul><br> |
| 205 | */ |
| 206 | virtual uint64_t GetAddress(void) const {return 0 ;} |
| 207 | |
| 208 | /** |
| 209 | Access a copy of the short id for signatures. |
| 210 | <ul> |
| 211 | <br><b>Parameters: </b> None |
| 212 | <br><b>Returns: </b> ID. |
| 213 | <br><b>Requirements:</b> None. |
| 214 | <br><b>Promises: </b> None. |
| 215 | <br><b>Exceptions: </b> None. |
| 216 | </ul><br> |
| 217 | */ |
| 218 | virtual uint16_t GetId(void) const = 0; |
| 219 | |
| 220 | /** |
| 221 | Set the short id for signatures. |
| 222 | <ul> |
| 223 | <br><b>Parameters: </b> ID. |
| 224 | <br><b>Returns: </b> None. |
| 225 | <br><b>Requirements:</b> None. |
| 226 | <br><b>Promises: </b> None. |
| 227 | <br><b>Exceptions: </b> For virtual registers, this is not required to have |
| 228 | any effect. |
| 229 | </ul><br> |
| 230 | */ |
| 231 | virtual void SetId(uint16_t) = 0; |
| 232 | |
| 233 | |
| 234 | /** |
| 235 | Access the bit length of the register |
| 236 | <ul> |
| 237 | <br><b>Parameters: </b> None |
| 238 | <br><b>Returns: </b> bit length of the register |
| 239 | <br><b>Requirements:</b> None. |
| 240 | <br><b>Promises: </b> None. |
| 241 | <br><b>Exceptions: </b> None. |
| 242 | </ul><br> |
| 243 | */ |
| 244 | virtual uint32_t GetBitLength(void) const { return DEFAULT_BIT_LENGTH ;} |
| 245 | |
| 246 | /** |
| 247 | Access the internal bit string (pure virtual) |
| 248 | <ul> |
| 249 | <br><b>Parameters: </b> None |
| 250 | <br><b>Returns: </b> ptr to the internal bit string (const) |
| 251 | <br><b>Requirements:</b> None. |
| 252 | <br><b>Promises: </b> None. |
| 253 | <br><b>Exceptions: </b> None. |
| 254 | <br><b>Notes: </b> If the internal bit string was never read/modified then |
| 255 | all bits are zero |
| 256 | </ul><br> |
| 257 | */ |
| 258 | virtual |
| 259 | const BitString * GetBitString(ATTENTION_TYPE |
| 260 | i_type = INVALID_ATTENTION_TYPE |
| 261 | ) const = 0; |
| 262 | |
| 263 | /** |
| 264 | Modify the internal bit string (pure virtual) |
| 265 | <ul> |
| 266 | <br><b>Parameters: </b> a bit string |
| 267 | <br><b>Returns: </b> Nothing |
| 268 | <br><b>Requirements:</b> None. |
| 269 | <br><b>Promises: </b> Internal bit string == *bs for first len bits where |
| 270 | len is the smaller of the two lengths. |
| 271 | Memory may be (re)allocated |
| 272 | <br><b>Exceptions: </b> None. |
| 273 | <br><b>Notes: </b> The hardware register value is not modified until |
| 274 | Write() is called |
| 275 | </ul><br> |
| 276 | */ |
| 277 | virtual void SetBitString(const BitString * bs) = 0; |
| 278 | |
| 279 | /** |
| 280 | SetBit |
| 281 | <ul> |
| 282 | <br><b>Parameters: </b> Position of bit to set (= 1) |
| 283 | <br><b>Returns: </b> None. |
| 284 | <br><b>Requirements:</b> bit position < GetBitString()->Length() |
| 285 | <br><b>Promises: </b> GetBitString()->isBitSet(bit_position) == true |
| 286 | <br><b>Exceptions: </b> None. |
| 287 | <br><b> Notes: </b> Register value is not reflected in hardware until |
| 288 | Write() is called |
| 289 | </ul><br> |
| 290 | */ |
| 291 | void SetBit(uint32_t bit_position); |
| 292 | |
| 293 | /** |
| 294 | ClearBit (reset bit) |
| 295 | <ul> |
| 296 | <br><b>Parameters: </b> Position of bit to clear (= 0) |
| 297 | <br><b>Returns: </b> None. |
| 298 | <br><b>Requirements:</b> bit position < GetBitString()->Length() |
| 299 | <br><b>Promises: </b> GetBitString()->isBitSet(bit_position) == false |
| 300 | <br><b>Exceptions: </b> None. |
| 301 | <br><b> Notes: </b> Register value is not reflected in hardware until |
| 302 | Write() is called |
| 303 | </ul><br> |
| 304 | */ |
| 305 | void ClearBit(uint32_t bit_position); |
| 306 | |
| 307 | /** |
| 308 | * @brief Will query if a bit is set. |
| 309 | * @param i_bitPos The bit position to query. |
| 310 | * @pre The bit position must be less than GetBitString()->Length() |
| 311 | * @return TRUE if the bit is set, FALSE otherwise. |
| 312 | */ |
| 313 | bool IsBitSet( uint32_t i_bitPos ) |
| 314 | { return GetBitString()->isBitSet(i_bitPos); } |
| 315 | |
| 316 | /** @brief Flushes all bits to 0. */ |
| 317 | void clearAllBits(); |
| 318 | |
| 319 | /** @brief Flushes all bits to 1. */ |
| 320 | void setAllBits(); |
| 321 | |
| 322 | /** |
| 323 | * @brief Returns target value from the BitString (right justified). |
| 324 | * @param i_pos Starting position in the bit string. |
| 325 | * @param i_len Length of target value. |
| 326 | * @pre i_pos + i_len must be less than or equal 64 bits. |
| 327 | * @return The target value (right justified). |
| 328 | */ |
| 329 | uint64_t GetBitFieldJustified( uint32_t i_pos, uint32_t i_len ) const; |
| 330 | |
| 331 | /** |
| 332 | * @brief Set a field within the BitString with a value (right justified). |
| 333 | * @param i_pos Starting position in the bit string. |
| 334 | * @param i_len Length of target value. |
| 335 | * @param i_value Value to add to BitString. |
| 336 | * @pre i_pos + i_len must be less than or equal 64 bits. |
| 337 | */ |
| 338 | void SetBitFieldJustified( uint32_t i_pos, uint32_t i_len, |
| 339 | uint64_t i_value ); |
| 340 | |
| 341 | /** |
| 342 | Query if bit string is all zeros |
| 343 | <ul> |
| 344 | <br><b>Parameters: </b> None. |
| 345 | <br><b>Returns: </b> [true | false] |
| 346 | <br><b>Requirements:</b> None. |
| 347 | <br><b>Promises: </b> None. |
| 348 | <br><b>Exceptions: </b> None. |
| 349 | </ul><br> |
| 350 | */ |
| 351 | bool BitStringIsZero() |
| 352 | { return GetBitString()->isZero(); } |
| 353 | |
| 354 | /** |
| 355 | *@brief Returns TYPE_NA as type of Target associated with register.Actual |
| 356 | * implementation is expected in derived class |
| 357 | *@return TYPE_NA |
| 358 | */ |
| 359 | virtual TARGETING::TYPE getChipType(void)const { return TARGETING::TYPE_NA; } |
| 360 | |
| 361 | /** @return The register access level (see enum AccessLevel). */ |
| 362 | virtual AccessLevel getAccessLevel() const { return ACCESS_RW; } |
| 363 | |
| 364 | /** @brief Sets the register access level (see enum AccessLevel). */ |
| 365 | virtual void setAccessLevel( AccessLevel i_op ) {} |
| 366 | |
| 367 | protected: |
| 368 | |
| 369 | /** |
| 370 | Get modifiable reference to internal bit string (don't even thing about making this public!!!) |
| 371 | <ul> |
| 372 | <br><b>Parameters: </b> None. |
| 373 | <br><b>Returns </b> Reference to the internal bit string |
| 374 | <br><b>Requirments </b> None. |
| 375 | <br><b>Promises </b> None. |
| 376 | </ul><br> |
| 377 | */ |
| 378 | virtual BitString & AccessBitString(void) = 0; |
| 379 | private: // Data |
| 380 | static const int DEFAULT_BIT_LENGTH = 64; |
| 381 | |
| 382 | // Enum Specification ////////////////////////////////////////////// |
| 383 | // |
| 384 | // Purpose: These enumerated constants specify implementation data. |
| 385 | // |
| 386 | // End Enum Specification ////////////////////////////////////////// |
| 387 | |
| 388 | enum |
| 389 | { |
| 390 | ODD_PARITY_SET_BIT_POSITION = 16 |
| 391 | }; |
| 392 | |
| 393 | // Data Specification ////////////////////////////////////////////// |
| 394 | // |
| 395 | // Purpose: These data members specify the physical properties of |
| 396 | // register. |
| 397 | // |
| 398 | // End Data Specification ////////////////////////////////////////// |
| 399 | |
| 400 | |
| 401 | }; |
| 402 | |
Zane Shelley | 871adec | 2019-07-30 11:01:39 -0500 | [diff] [blame] | 403 | } // end namespace libhei |
Zane Shelley | fd3f9cc | 2019-07-29 15:02:24 -0500 | [diff] [blame] | 404 | |