summaryrefslogtreecommitdiffstats log msg author committer range
path: root/src/import/chips/p9/utils/imageProcs/p9_tor.H
blob: d4b4250e12d0922d2903ca272e0ca592f8fa74a1 (plain)
 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447  /* IBM_PROLOG_BEGIN_TAG */ /* This is an automatically generated prolog. */ /* */ /* $Source: src/import/chips/p9/utils/imageProcs/p9_tor.H$ */ /* */ /* OpenPOWER sbe Project */ /* */ /* Contributors Listed Below - COPYRIGHT 2016,2017 */ /* [+] International Business Machines Corp. */ /* */ /* */ /* Licensed under the Apache License, Version 2.0 (the "License"); */ /* you may not use this file except in compliance with the License. */ /* You may obtain a copy of the License at */ /* */ /* http://www.apache.org/licenses/LICENSE-2.0 */ /* */ /* Unless required by applicable law or agreed to in writing, software */ /* distributed under the License is distributed on an "AS IS" BASIS, */ /* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or */ /* implied. See the License for the specific language governing */ /* permissions and limitations under the License. */ /* */ /* IBM_PROLOG_END_TAG */ #ifndef _P9_TOR_H_ #define _P9_TOR_H_ #include "p9_ring_id.h" #include "p9_ringId.H" #define MAX_TOR_RING_OFFSET (256*256-1) // Max value of 2Byte uint namespace P9_TOR { extern const char* ppeTypeName[]; extern const char* ringVariantName[]; #define TOR_VERSION 2 // // TOR Magic values for top-level TOR image and TOR sub-images // enum TorMagicNum { TOR_MAGIC = (uint32_t)0x544F52 , // "TOR" TOR_MAGIC_HW = (uint32_t)0x544F5248, // "TORH" TOR_MAGIC_SBE = (uint32_t)0x544F5242, // "TORB" TOR_MAGIC_SGPE = (uint32_t)0x544F5247, // "TORG" TOR_MAGIC_CME = (uint32_t)0x544F524D, // "TORM" TOR_MAGIC_OVRD = (uint32_t)0x544F5252, // "TORR" TOR_MAGIC_OVLY = (uint32_t)0x544F524C, // "TORL" TOR_MAGIC_CEN = (uint32_t)0x544F524E, // "TORN" }; typedef uint8_t ChipType_t; // // TOR header field (appears in top of every HW, SBE, CEN, OVRD, etc ring section) // typedef struct { uint32_t magic; uint8_t version; ChipType_t chipType; // Value from ChipType enum uint8_t ddLevel; // =0xff if MAGIC_HW, >0 all other MAGICs uint8_t numDdLevels; // >0 if MAGIC_HW, =1 all other MAGICs uint32_t size; // Size of the TOR ringSection. } TorHeader_t; typedef struct { uint32_t TorNumDdLevels; uint32_t reserved; } TorNumDdLevels_t; typedef struct { uint32_t TorDdLevelAndOffset; uint32_t TorDdBlockSize; } TorDdLevelBlock_t; typedef struct { uint32_t TorPpeTypeOffset; uint32_t TorPpeBlockSize; } TorPpeBlock_t; typedef struct { uint32_t commonOffset; uint32_t instanceOffset; } TorCpltBlock_t; typedef uint16_t TorRingOffset_t; // Ring offset value in TOR offset slot #define TOR_SUCCESS 0 #define TOR_RING_FOUND 0 #define TOR_RING_BLOCKS_FOUND 0 #define TOR_RING_NOT_FOUND 1 #define TOR_AMBIGUOUS_API_PARMS 2 #define TOR_SECTION_NOT_FOUND 3 #define TOR_DD_LEVEL_NOT_FOUND 4 #define TOR_OP_BUFFER_INVALID 5 #define TOR_OP_BUFFER_SIZE_EXCEEDED 6 #define TOR_INVALID_RING_ID 7 #define TOR_INVALID_INSTANCE_ID 8 #define TOR_INVALID_CHIPLET 9 #define TOR_INVALID_RING_BLOCK_TYPE 10 #define TOR_INVALID_MAGIC_NUMBER 11 #define TOR_IMAGE_DOES_NOT_SUPPORT_CME 12 #define TOR_IMAGE_DOES_NOT_SUPPORT_SGPE 13 #define TOR_IMAGE_DOES_NOT_SUPPORT_DD_LEVEL 14 #define TOR_IMAGE_DOES_NOT_SUPPORT_PPE_LEVEL 15 #define TOR_RING_AVAILABLE_IN_RINGSECTION 16 // Ring is already present #define TOR_BUFFER_TOO_SMALL 17 #define TOR_TOO_MANY_DD_LEVELS 18 #define TOR_OFFSET_TOO_BIG 19 // Different options to extract data using tor_access_ring API typedef enum RingBlockType { GET_SINGLE_RING = 0x00, GET_DD_LEVEL_RINGS = 0x01, GET_PPE_LEVEL_RINGS = 0x02, PUT_SINGLE_RING = 0x03 } RingBlockType_t; typedef enum RingType { COMMON = 0x00, INSTANCE = 0x01, ALLRING = 0x02 } RingType_t; typedef enum PpeType { SBE = 0x00, CME = 0x01, SGPE = 0x02, NUM_PPE_TYPES = 0x03 } PpeType_t; typedef enum TorOffsetSize { RING_OFFSET_SIZE = 2, CPLT_OFFSET_SIZE = 4 } TorOffsetSize_t; /// /// **************************************************************************** /// Function declares. /// **************************************************************************** /// /// Traverse on TOR structure and copies data in granular up to DD type, /// ppe type, ring type, RS4 ring container and ring address /// /// \param[in] i_ringSection A pointer to a Ring section binary image. /// It contains details of p9 Ring, which is used for scanning operation. /// TOR API supports two type of binary image. 1) HW image format and 2) /// SEEPROM image format binary /// /// \param[in] i_magic A uint64_t variable to indicate XIP image format /// ring section passed /// /// \param[in] i_ringId A enum to indicate unique ID for the ring /// /// \param[in] i_ddLevel A variable to indicate chip DD level. TOR API /// uses DD level to extract single ring or block of rings from hw_image /// /// \param[in] i_PpeType A enum to indicate ppe type. They are SBE, CME /// and SGPE. It is used to decode TOR structure /// /// \param[in/out] io_RingType A enum and passed by reference. Acts as input /// paramfor extracting block of rings copy under Chiplet level. Acts as /// outputparam to indicate type of single ring copied is whether common or /// instance specific ring /// /// \param[in] i_RingVariant A enum to indicate which variant type of /// requested for single ring extract. There are three major types. They are /// base, Cache contained and Risk level ring /// /// \param[in/out] io_instanceId A variable to indicate chiplet instance ID. /// It returns Chiplet instance ID while doing get single ring operation /// /// \param[in] i_RingVariant A enum to indicate type of operation performed /// by TOR API Option: /// GET_SINGLE_RING indicates to extract single ring container. /// GET_DD_LEVEL_RINGS indicates to extract specific DD level TOR and rings /// GET_PPE_LEVEL_RINGS indcates to extract specific PPE level TOR and rings /// GET_CPLT_LEVEL_RINGS indciates to extract specific chiplet ring type /// TOR and rings /// PUT_SINGLE_RING indicates to extract ring absolute memory addres for /// ringType start and ringTorSlot location /// /// \param[in/out] io_ringBlockPtr A void pointer to pointer. Returns data /// which copied during extract ring operation and returns tor absolute address /// where RingType offset slot is located while PUT_SINGLE_RING call. /// Note:- Caller's responsibility for free() to avoid memory leak /// /// \param[in/out] io_ringBlockSize A variable. Returns size of data copied /// into io_ringBlockPtr and returns absolute offset where ring RS4 starts in /// TOR during PUT_SINGLE_RING call /// /// \param[out] o_ringName A string. Returns name of ring ID in characters /// /// \param[in] - i_debug is debug statment params. Supports 0 to 3. /// /// This API traverse TOR structure of .ringSection from HW image or SBE image /// and the following n number of operation based on the call. /// /// GET_SINGLE_RING (\a i_ringVariant) - traverse on \a i_ringSection buffer /// based on the following input param \a i_magic which gives details of image /// type, \a i_ringId which gives ring info, \a i_ddLevel which gives dd spec /// (Used only for HW image/optional for other image) i_ppeType which gives ppe /// type info, \a i_ringVarint gives ring variant info and \a io_instance which /// gives chiplet instance specific while accessing instance specific ring and /// returns chiplet number while accessing common ring. On return, /// \a io_ringBlockPtr contains RS4 container \a io_RingType contains which /// ring type of ring requested and \a io_ringBlockSize contains size of the /// data copied into io_ringBlockPtr. \a o_ringName returns ring string name. /// /// GET_DD_LEVEL_RINGS (\a i_ringVariant) - traverse on \a i_ringSection /// buffer based on the following input param \a i_magic which gives details /// of image type and \a i_ddLevel which gives dd spec(Used only for HW image /// /optional for other image) On return, \a io_ringBlockPtr contains DD level /// specific ring section and \a io_ringBlockSize contains size of the data /// copied into io_ringBlockPtr. \a Other params are optional. /// This ringVariant works on HW image. /// /// GET_PPE_LEVEL_RINGS (\a i_ringVariant) - traverse on \a i_ringSection /// buffer based on the following input param \a i_magic which gives the detail /// of image type, i_ppeType which gives ppe type info and \a i_ddLevel which /// gives dd spec(Used only for HW image/optional for other image) On return, /// \a io_ringBlockPtr contains PPE type specific ring section and /// \a io_ringBlockSize contains size of the data copied into io_ringBlockPtr. /// \a Other params are optional. This ringVariant works on HW image. /// /// GET_CPLT_LEVEL_RINGS (\a i_ringVariant) - traverse on \a i_ringSection /// buffer based on the following input param \a i_magic which gives the detail /// of image type, i_ppeType which gives ppe type info, \a i_ddLevel which gives /// dd spec(Used only for HW image/optional for other image) and \a io_RingType /// which gives ring type info. On return, \a io_ringBlockPtr contains chiplet /// specific ring type ring section and \a io_ringBlockSize contains size of /// the data copied into io_ringBlockPtr. \a Other params are optional. /// /// PUT_SINGLE_RING (\a i_ringVariant) - traverse on \a i_ringSection buffer /// based on the following input param \a i_magic which gives detail of image /// type, \a i_ringId which gives ring info, \a i_ddLevel which gives dd spec /// (Used only for HW image/optional for other image), i_ppeType which gives /// ppe type info, \a i_ringVarint gives ring variant info and \a io_instance /// which gives chiplet instance specific while accessing instance specific /// ring and returns chiplet number while accessing common ring. On return, /// \a io_ringBlockPtr contains absolute memory address of ring type of /// requested ring and \a io_ringBlockSize contains of absolute memory addres /// of ringTor slot copied into io_ringBlockPtr \a o_ringName returns ring /// string name /// /// \retval 0 Success /// /// \retval non-0 See \ref TOR API RETURN errors int tor_access_ring( void* i_ringSection, // Ring address Ptr any of .rings, .overrides and .overlays. uint64_t i_magic, // Image Magic Number RingID i_ringId, // Unique ring ID uint16_t i_ddLevel, // DD level info PpeType_t i_PpeType, // PPE type : SBE, CME, etc RingType_t& io_RingType, // 0: Common 1: Instance RingVariant_t i_RingVariant, // Base, Cache etc uint8_t& io_instanceId, // chiplet instance ID RingBlockType_t i_RingBlockType, // 0: single ring, 1: ring block void** io_ringBlockPtr, // Addr of ring buffer uint32_t& io_ringBlockSize, // size of ring data char* o_ringName, // Ring name uint32_t i_dbgl = 0 ); // Debug option /// Traverse on TOR structure and copies RS4 ring container data for ring /// variant /// /// \param[in] i_ringSection A pointer to a Ring section binary image. /// It contain details of p9 Ring which is used for scanning operation. /// TOR API supports HW image format only /// /// \param[in] i_magic A uint64_t variable to indicate XIP image format /// ring section passed /// /// \param[in] i_ringId A enum to indicate unique ID for the ring /// /// \param[in] i_ddLevel A variable to indicate chip DD level. TOR API /// uses DD level to extract single ring or block of rings on hw_image. /// /// \param[in] i_PpeType A enum to indicate ppe type. /// They are SBE, CME and SGPE. It is used to decode TOR structure /// /// \param[in] i_RingVariant A enum to indicate which variant type of /// requested for get single ring operation There are three major types. /// They are base, Cache contained and Risk level ring /// /// \param[in] io_instanceId A variable to indicate chiplet instance ID /// /// \param[in/out] io_ringBlockPtr A void point to pointer. Returns data /// which copied during extract ring operation /// Note- Caller's responsibility for free() to avoid memory leak /// /// \param[in/out] io_ringBlockSize A variable. Returns size of data copied /// into io_ringBlockPtr /// /// \param[in] - i_debug is debug statment params. Supports 0 to 3. /// /// This API contains wrapper on top of tor_access_ring API to support get /// single ring container from .ring section and customizes for /// get_single_ring parameter. /// /// \retval 0 Success /// /// \retval non-0 See \ref TOR API RETURN errors int tor_get_single_ring ( void* i_ringSection, uint64_t i_magic, // Image Magic Number uint16_t i_ddLevel, RingID i_ringId, PpeType_t i_PpeType, RingVariant_t i_RingVariant, uint8_t i_instanceId, void** io_ringBlockPtr, uint32_t& io_ringBlockSize, uint32_t i_dbgl = 0 ); // Debug option /// Traverse on TOR structure and copies data in block level up to DD type, /// ppe type and ring type /// /// \param[in] i_ringSection A pointer to a Ring section binary image. /// It contains details of p9 Ring which is used for scanning operation. /// API supports HW image format only /// /// \param[in] i_ddLevel A variable to indicate chip DD level. TOR API /// uses DD level to extract single ring or block of rings on hw_image /// /// \param[in] i_PpeType A enum to indicate ppe type passed. /// they are SBE, CME and SGPE. It is used to decode TOR structure /// TOR API uses Ppe type to extract single ring or block of rings /// on either hw_image or SBE image /// /// \param[in] i_RingType A enum and passed by reference. Acts as /// input param for extracting block of rings copy under Chiplet level /// /// \param[in] i_RingVariant A enum to indicate which variant type of /// requested for single ring extract. There are three major types. /// They are base, Cache contained and Risk level ring /// /// \param[in] i_instanceId A variable to indicate chiplet instance ID /// /// \param[in/out] io_ringBlockPtr A void point to pointer. Returns data /// which copied block of rings. Note: Caller's responsibility for free() /// to avoid memory leak // /// \param[in/out] io_ringBlockSize A variable. Returns size of data /// copied into io_ringBlockPtr /// /// \param[in] - i_debug is debug statment params. Supports 0 to 3. /// /// This API contains wrapper on top of tor_access_ring API and supports /// to copy block of rings in DD level, ppe level and ringType level. /// /// \retval 0 Success /// /// \retval non-0 See \ref TOR API RETURN errors int tor_get_block_of_rings ( void* i_ringSection, uint16_t i_ddLevel, PpeType_t i_PpeType, RingType_t i_RingType, RingVariant_t i_RingVariant, uint8_t i_instanceId, void** io_ringBlockPtr, uint32_t& io_ringBlockSize, uint32_t i_dbgl = 0 ); /// Traverse on TOR structure and copies absolute memory address of Ringtype /// offset addres and TOR offset slot address /// /// \param[in] i_ringSection A pointer to a Ring section binary image. /// It contains details of p9 Ring which is used for scanning operation. /// TOR API supports SEEPROM image format. /// /// \param[in/out] io_ringSectionSize In: Exact size of i_ringSection. /// Out: Updated size of i_ringSection. /// Note: Caller manages this buffer and must make sure the RS4 ring fits /// before making this call /// /// \param[in] i_ringBuffer A pointer to a ring work buffer, which is used /// for scanning operation purpose /// /// \param[in] i_ringBufferSize A constant value to indicate size of /// ringBuffer data passed in /// /// \param[in] i_ringId A enum to indicate unique ID for the ring /// /// \param[in] i_PpeType A enum to indicate ppe type. They are SBE, /// CME and SGPE. It is used to decode TOR structure /// /// \param[in] i_RingType A enum to indicate ring type of ring whether /// common or instance specific ring /// /// \param[in] i_RingVariant A enum and used as input param to indicate /// which variant type of requested for single ring extract /// /// \param[in] i_instanceId A variable to indicate chiplet instance ID /// /// \param[in] i_rs4_container A void pointer. Contains RS4 compressed ring /// data which eventually attached into void image pointer i_ringSection /// /// \param[in] - i_debug is debug statment params. Supports 0 to 3. /// /// This API contains wrapper on tor_access_ring to get \a io_ringBlockPtr /// contains absolute memory address of ring type start address of the ring /// \a io_ringBlockSize contains absolute memory address of ringTorslot. Then /// appends new rs4 ring container at the end of ring section and updates new /// ring offset address on ring offset location. the slot must be empty. If there /// is non-zero content in the slot, the API will fail catastrophically. Do not /// "insert" or "replace" rings at ring section. /// /// \retval 0 Success /// /// \retval non-0 See \ref TOR API RETURN errors int tor_append_ring( void* i_ringSection, uint32_t& io_ringSectionSize, void* i_ringBuffer, const uint32_t i_ringBufferSize, RingID i_ringId, PpeType_t i_ppeType, RingType_t i_RingType, RingVariant_t i_RingVariant, uint8_t i_instanceId, void* i_rs4Container, uint32_t i_dbgl = 0 ); /// Inform caller of TOR version /// /// \param[in] - none /// /// \retval - TOR version uint8_t tor_version( void); }; #endif //_P9_TOR_H_