TOR Magic header support

HW-Image-Coreq=Yes
SBE-Image-Coreq=No (SBE image is back compatible)

This commit adds an 12-byte header to all TOR ring sections:
- for improved self-containment of TOR ring sections incl
  stand-alone ring sections like .overrides which, currently,
  has no meaningful size info associated with it in the PNOR,
- to support a more data-driven implementation of TOR API,
- to eliminate the current usage of XIP_MAGIC ids to inform the
  TOR APIs which ring section they are dealing with, and
- to improve debugging binary ring sections.

The TOR header expands on the current TorNumDdLevels field in the
HW ring section and is added to all other ring sections as well,
e.g. for the SBE and OVRD ring sections.  Most importantly, the
TOR header adds the TOR magic number which is unique for each
possible TOR ring section. Also, of quite practical importance,
a size field has been added so that the size of a true standalone
section like .overrides can be extracted (since its size in PNOR
is not indicative of its size).

Further, to support the use of ddLevel and chipType in the TOR
header fields, these two data points need to be always supplied
whenever calling ring_apply. Thus, updates have been made to the
ring_apply.mk file as well as the override .pl script.  While
making these changes, we also decided to change the --type arg
to the --bOverrides arg to make the arguments being passed less
confusing in view of the Centaur commit that's coming and its
demands to make codes less data dependent, incl make and script
files which should simply inform the functional intent of the
"user". The user shouldn't presume it knows about which specific
type of ring section needs to be produced.

Further, the DD level block struct has been increased from 8B
to 12B to avoid the unnecessarily complex merging of the
ddLevel and offset into the same 4B field. It's included in
this commit since this is also going to break the lab and
because the required code changes are in the same places
where the code changes needed for the TOR header are.

Further, xip_tool has been updated to support the new TOR
header so that it can be called by supplying a standalone
ring section, such as overrides.bin. Various changes have
been made in xip_tool's dissect section to support overrides
as well.

This code uses many  of the code changes in 33778 except
changes to p9_tor.C|H are at a bare minimum focusing on the
functional changes and keeping any cleanups to a minimum changing
only some variable names associated with the functional changes
for improved readability of the code.

CMVC-Prereq: 1034144
CMVC-Prereq: 1035575
Change-Id: I29ba8905ac55dad5c10878a94fb94468e5580ea0
Reviewed-on: http://ralgit01.raleigh.ibm.com/gerrit1/35372
Tested-by: Jenkins Server <pfd-jenkins+hostboot@us.ibm.com>
Tested-by: HWSV CI <hwsv-ci+hostboot@us.ibm.com>
Reviewed-by: Jennifer A. Stofer <stofer@us.ibm.com>
Reviewed-on: http://ralgit01.raleigh.ibm.com/gerrit1/37993
Reviewed-by: Hostboot Team <hostboot@us.ibm.com>
Tested-by: FSP CI Jenkins <fsp-CI-jenkins+hostboot@us.ibm.com>
Reviewed-by: Sachin Gupta <sgupta2m@in.ibm.com>

1 files changed, 56 insertions, 41 deletions

diff --git a/src/import/chips/p9/utils/imageProcs/p9_tor.H b/src/import/chips/p9/utils/imageProcs/p9_tor.H
index d4b4250e..7d578723 100644
--- a/src/import/chips/p9/utils/imageProcs/p9_tor.H
+++ b/src/import/chips/p9/utils/imageProcs/p9_tor.H
@@ -25,7 +25,6 @@
 #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
@@ -36,7 +35,7 @@ namespace P9_TOR
 extern const char* ppeTypeName[];
 extern const char* ringVariantName[];
 
-#define  TOR_VERSION  2
+#define  TOR_VERSION  3
 
 //
 // TOR Magic values for top-level TOR image and TOR sub-images
@@ -53,7 +52,34 @@ enum TorMagicNum
     TOR_MAGIC_CEN   = (uint32_t)0x544F524E,   // "TORN"
 };
 
+//
+// Chip types to represent p9n, p9c, centaur
+//
+enum ChipType
+{
+    CT_P9N,
+    CT_P9C,
+    CT_CEN,
+    NUM_CHIP_TYPES
+};
+
 typedef uint8_t ChipType_t;
+const ChipType_t INVALID_CHIP_TYPE = 0xff;
+
+typedef struct ChipTypeList
+{
+    const char* name;
+    ChipType_t  type;
+} ChipTypeList_t;
+
+const ChipTypeList_t CHIP_TYPE_LIST[] =
+{
+    {"p9n",     CT_P9N},
+    {"p9c",     CT_P9C},
+    {"cen",     CT_CEN},
+};
+
+
 
 //
 // TOR header field (appears in top of every HW, SBE, CEN, OVRD, etc ring section)
@@ -65,26 +91,26 @@ typedef struct
     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.
+    uint32_t   size;        // A place holder for now, but will be used in a later commit.
 } TorHeader_t;
 
+#define UNDEFINED_DD_LEVEL (uint8_t)0xff
 
+//
+// Subsequent TOR fields (listed in order they appear in TOR for easier understanding)
+//
 typedef struct
 {
-    uint32_t TorNumDdLevels;
-    uint32_t reserved;
-} TorNumDdLevels_t;
-
-typedef struct
-{
-    uint32_t TorDdLevelAndOffset;
-    uint32_t TorDdBlockSize;
-} TorDdLevelBlock_t;
+    uint32_t offset;
+    uint32_t size;
+    uint8_t  ddLevel;
+    uint8_t  reserved[3];
+} TorDdBlock_t;
 
 typedef struct
 {
-    uint32_t TorPpeTypeOffset;
-    uint32_t TorPpeBlockSize;
+    uint32_t offset;
+    uint32_t size;
 } TorPpeBlock_t;
 
 typedef struct
@@ -95,6 +121,13 @@ typedef struct
 
 typedef uint16_t TorRingOffset_t;  // Ring offset value in TOR offset slot
 
+//@FIXME Discard asap
+typedef enum TorOffsetSize
+{
+    RING_OFFSET_SIZE = 2,
+    CPLT_OFFSET_SIZE = 4
+} TorOffsetSize_t;
+
 #define TOR_SUCCESS                           0
 #define TOR_RING_FOUND                        0
 #define TOR_RING_BLOCKS_FOUND                 0
@@ -117,6 +150,7 @@ typedef uint16_t TorRingOffset_t;  // Ring offset value in TOR offset slot
 #define TOR_BUFFER_TOO_SMALL                 17
 #define TOR_TOO_MANY_DD_LEVELS               18
 #define TOR_OFFSET_TOO_BIG                   19
+#define TOR_INVALID_VARIANT                  20
 
 // Different options to extract data using tor_access_ring API
 typedef enum RingBlockType
@@ -142,12 +176,6 @@ typedef enum PpeType
     NUM_PPE_TYPES = 0x03
 } PpeType_t;
 
-typedef enum TorOffsetSize
-{
-    RING_OFFSET_SIZE = 2,
-    CPLT_OFFSET_SIZE = 4
-} TorOffsetSize_t;
-
 ///
 /// ****************************************************************************
 /// Function declares.
@@ -161,9 +189,6 @@ typedef enum TorOffsetSize
 /// 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
@@ -211,8 +236,7 @@ typedef enum TorOffsetSize
 /// 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
+/// based on \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
@@ -222,33 +246,29 @@ typedef enum TorOffsetSize
 /// 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
+/// buffer based on \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,
+/// buffer based on \a 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
+/// buffer based on \a 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
+/// based on \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,
@@ -261,7 +281,6 @@ typedef enum TorOffsetSize
 ///
 /// \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
@@ -282,9 +301,6 @@ int tor_access_ring( void*           i_ringSection, // Ring address Ptr any of .
 /// 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
@@ -316,7 +332,6 @@ int tor_access_ring( void*           i_ringSection, // Ring address Ptr any of .
 ///
 /// \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,