src/vendorcode/amd/agesa/f12/Proc/CPU/S3.h

   1 /* $NoKeywords:$ */
   2 /**
   3  * @file
   4  *
   5  *  ACPI S3 support definitions.
   6  *
   7  * @xrefitem bom "File Content Label" "Release Content"
   8  * @e project:      AGESA
   9  * @e sub-project:  CPU
  10  * @e \$Revision: 49927 $   @e \$Date: 2011-03-31 01:27:42 +0800 (Thu, 31 Mar 2011) $
  11  *
  12  */
  13 /*
  14 *****************************************************************************
  15 *
  16 * Copyright (c) 2011, Advanced Micro Devices, Inc.
  17  * All rights reserved.
  18  *
  19  * Redistribution and use in source and binary forms, with or without
  20  * modification, are permitted provided that the following conditions are met:
  21  *     * Redistributions of source code must retain the above copyright
  22  *       notice, this list of conditions and the following disclaimer.
  23  *     * Redistributions in binary form must reproduce the above copyright
  24  *       notice, this list of conditions and the following disclaimer in the
  25  *       documentation and/or other materials provided with the distribution.
  26  *     * Neither the name of Advanced Micro Devices, Inc. nor the names of
  27  *       its contributors may be used to endorse or promote products derived
  28  *       from this software without specific prior written permission.
  29  *
  30  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  31  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  32  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  33  * DISCLAIMED. IN NO EVENT SHALL ADVANCED MICRO DEVICES, INC. BE LIABLE FOR ANY
  34  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  35  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  36  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  37  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  38  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  39  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  40 * ***************************************************************************
  41 *
  42 */
  43
  44 #ifndef _S3_H_
  45 #define _S3_H_
  46
  47
  48 /*---------------------------------------------------------------------------------------
  49  *          M I X E D   (Definitions And Macros / Typedefs, Structures, Enums)
  50  *---------------------------------------------------------------------------------------
  51  */
  52
  53
  54 /*---------------------------------------------------------------------------------------
  55  *                 D E F I N I T I O N S     A N D     M A C R O S
  56  *---------------------------------------------------------------------------------------
  57  */
  58 #define RESTART_FROM_BEGINNING_LIST 0xFFFFFFFF
  59
  60 /*---------------------------------------------------------------------------------------
  61  *               T Y P E D E F S,   S T R U C T U R E S,    E N U M S
  62  *---------------------------------------------------------------------------------------
  63  */
  64
  65 /* Device related definitions */
  66
  67 /// Header at the beginning of a context save buffer.
  68 typedef struct {
  69   UINT16     Version;                 ///< Version of header
  70   UINT16     NumDevices;              ///< Number of devices in the list
  71   UINT16     RelativeOrMaskOffset;    ///< Size of device list + header
  72 } DEVICE_BLOCK_HEADER;
  73
  74 /// S3 device types
  75 typedef enum {
  76   DEV_TYPE_PCI_PRE_ESR,               ///< PCI device before exiting self-refresh
  77   DEV_TYPE_PCI,                       ///< PCI device after exiting self-refresh
  78   DEV_TYPE_CPCI_PRE_ESR,              ///< 'conditional' PCI device before exiting self-refresh
  79   DEV_TYPE_CPCI,                      ///< 'conditional' PCI device after exiting self-refresh
  80   DEV_TYPE_MSR_PRE_ESR,               ///< MSR device before exiting self-refresh
  81   DEV_TYPE_MSR,                       ///< MSR device after exiting self-refresh
  82   DEV_TYPE_CMSR_PRE_ESR,              ///< 'conditional' MSR device before exiting self-refresh
  83   DEV_TYPE_CMSR                       ///< 'conditional' MSR device after exiting self-refresh
  84 } S3_DEVICE_TYPES;
  85
  86 /// S3 restoration call points
  87 typedef enum {
  88   INIT_RESUME,                        ///< AMD_INIT_RESUME
  89   S3_LATE_RESTORE                     ///< AMD_S3LATE_RESTORE
  90 } CALL_POINTS;
  91
  92 /// S3 device common header
  93 typedef struct {
  94   UINT32     RegisterListID;          ///< Unique ID of this device
  95   UINT8      Type;                    ///< Appropriate S3_DEVICE_TYPES type
  96 } DEVICE_DESCRIPTOR;
  97
  98 /// S3 PCI device header
  99 typedef struct {
 100   UINT32     RegisterListID;          ///< Unique ID of this device
 101   UINT8      Type;                    ///< DEV_TYPE_PCI / DEV_TYPE_PCI_PRE_ESR
 102   UINT8      Node;                    ///< Zero-based node number
 103 } PCI_DEVICE_DESCRIPTOR;
 104
 105 /// S3 'conditional' PCI device header
 106 typedef struct {
 107   UINT32     RegisterListID;          ///< Unique ID of this device
 108   UINT8      Type;                    ///< DEV_TYPE_CPCI / DEV_TYPE_CPCI_PRE_ESR
 109   UINT8      Node;                    ///< Zero-based node number
 110   UINT8      Mask1;                   ///< Conditional mask 1
 111   UINT8      Mask2;                   ///< Conditional mask 2
 112 } CONDITIONAL_PCI_DEVICE_DESCRIPTOR;
 113
 114 /// S3 MSR device header
 115 typedef struct {
 116   UINT32     RegisterListID;          ///< Unique ID of this device
 117   UINT8      Type;                    ///< DEV_TYPE_MSR / DEV_TYPE_MSR_PRE_ESR
 118 } MSR_DEVICE_DESCRIPTOR;
 119
 120 /// S3 'conditional' MSR device header
 121 typedef struct {
 122   UINT32     RegisterListID;          ///< Unique ID of this device
 123   UINT8      Type;                    ///< DEV_TYPE_CMSR / DEV_TYPE_CMSR_PRE_ESR
 124   UINT8      Mask1;                   ///< Conditional mask 1
 125   UINT8      Mask2;                   ///< Conditional mask 2
 126 } CONDITIONAL_MSR_DEVICE_DESCRIPTOR;
 127
 128 /* Special case related definitions */
 129
 130 /**
 131  * PCI special case save handler
 132  *
 133  * @param[in]     AccessWidth   8, 16, or 32 bit wide access
 134  * @param[in]     Address       full PCI address of the register to save
 135  * @param[out]    Value         Value read from the register
 136  * @param[in]     ConfigPtr     AMD standard header config parameter
 137  *
 138  */
 139 typedef VOID (*PF_S3_SPECIAL_PCI_SAVE) (
 140   IN       ACCESS_WIDTH AccessWidth,
 141   IN       PCI_ADDR     Address,
 142      OUT   VOID         *Value,
 143   IN       VOID         *ConfigPtr
 144   );
 145
 146 /**
 147  * PCI special case restore handler
 148  *
 149  * @param[in]     AccessWidth   8, 16, or 32 bit wide access
 150  * @param[in]     Address       full PCI address of the register to save
 151  * @param[in]     Value         Value to write to the register
 152  * @param[in]     ConfigPtr     AMD standard header config parameter
 153  *
 154  */
 155 typedef VOID (*PF_S3_SPECIAL_PCI_RESTORE) (
 156   IN       ACCESS_WIDTH       AccessWidth,
 157   IN       PCI_ADDR           PciAddress,
 158   IN       VOID               *Value,
 159   IN       VOID               *StdHeader
 160   );
 161
 162 /**
 163  * MSR special case save handler
 164  *
 165  * @param[in]     MsrAddress    Address of model specific register to save
 166  * @param[out]    Value         Value read from the register
 167  * @param[in]     ConfigPtr     AMD standard header config parameter
 168  *
 169  */
 170 typedef VOID (*PF_S3_SPECIAL_MSR_SAVE) (
 171   IN       UINT32             MsrAddress,
 172      OUT   UINT64             *Value,
 173   IN       VOID               *StdHeader
 174   );
 175
 176 /**
 177  * MSR special case restore handler
 178  *
 179  * @param[in]     MsrAddress    Address of model specific register to restore
 180  * @param[in]     Value         Value to write to the register
 181  * @param[in]     ConfigPtr     AMD standard header config parameter
 182  *
 183  */
 184 typedef VOID (*PF_S3_SPECIAL_MSR_RESTORE) (
 185   IN       UINT32             MsrAddress,
 186   IN       UINT64             *Value,
 187   IN       VOID               *StdHeader
 188   );
 189
 190 /// PCI special case save/restore structure.
 191 typedef struct {
 192   PF_S3_SPECIAL_PCI_SAVE     Save;    ///< Save routine
 193   PF_S3_SPECIAL_PCI_RESTORE  Restore; ///< Restore routine
 194 } PCI_SPECIAL_CASE;
 195
 196 /// MSR special case save/restore structure.
 197 typedef struct {
 198   PF_S3_SPECIAL_MSR_SAVE     Save;    ///< Save routine
 199   PF_S3_SPECIAL_MSR_RESTORE  Restore; ///< Restore routine
 200 } MSR_SPECIAL_CASE;
 201
 202 /* Register related definitions */
 203 /// S3 register type bit fields
 204 typedef struct {
 205   UINT8      SpecialCaseIndex:4;      ///< Special Case array index
 206   UINT8      RegisterSize:3;          ///< For PCI, 1 = byte, 2 = word, else = dword.
 207                                       ///< For MSR, don't care
 208   UINT8      SpecialCaseFlag:1;       ///< Indicates special case
 209 } S3_REGISTER_TYPE;
 210
 211 /// S3 PCI register descriptor.
 212 typedef struct {
 213   S3_REGISTER_TYPE  Type;             ///< Type[7] = special case flag,
 214                                       ///< Type[6:3] = register size in bytes,
 215                                       ///< Type[2:0] = special case index
 216   UINT8             Function;         ///< PCI function of the register
 217   UINT16            Offset;           ///< PCI offset of the register
 218   UINT32            AndMask;          ///< AND mask to be applied to the value before saving
 219 } PCI_REG_DESCRIPTOR;
 220
 221 /// S3 'conditional' PCI register descriptor.
 222 typedef struct {
 223   S3_REGISTER_TYPE  Type;             ///< Type[7] = special case flag,
 224                                       ///< Type[6:3] = register size in bytes,
 225                                       ///< Type[2:0] = special case index
 226   UINT8             Function;         ///< PCI function of the register
 227   UINT16            Offset;           ///< PCI offset of the register
 228   UINT32            AndMask;          ///< AND mask to be applied to the value before saving
 229   UINT8             Mask1;            ///< conditional mask 1
 230   UINT8             Mask2;            ///< conditional mask 2
 231 } CONDITIONAL_PCI_REG_DESCRIPTOR;
 232
 233 /// S3 MSR register descriptor.
 234 typedef struct {
 235   S3_REGISTER_TYPE  Type;             ///< Type[7] = special case flag,
 236                                       ///< Type[6:3] = reserved,
 237                                       ///< Type[2:0] = special case index
 238   UINT32            Address;          ///< MSR address
 239   UINT64            AndMask;          ///< AND mask to be applied to the value before saving
 240 } MSR_REG_DESCRIPTOR;
 241
 242 /// S3 'conditional' MSR register descriptor.
 243 typedef struct {
 244   S3_REGISTER_TYPE  Type;             ///< Type[7] = special case flag,
 245                                       ///< Type[6:3] = reserved,
 246                                       ///< Type[2:0] = special case index
 247   UINT32            Address;          ///< MSR address
 248   UINT64            AndMask;          ///< AND mask to be applied to the value before saving
 249   UINT8             Mask1;            ///< conditional mask 1
 250   UINT8             Mask2;            ///< conditional mask 2
 251 } CONDITIONAL_MSR_REG_DESCRIPTOR;
 252
 253 /// Common header at the beginning of an S3 register list.
 254 typedef struct {
 255   UINT16     Version;                 ///< Version of header
 256   UINT16     NumRegisters;            ///< Number of registers in the list
 257 } REGISTER_BLOCK_HEADER;
 258
 259 /// S3 PCI register list header.
 260 typedef struct {
 261   UINT16                  Version;       ///< Version of header
 262   UINT16                  NumRegisters;  ///< Number of registers in the list
 263   PCI_REG_DESCRIPTOR      *RegisterList; ///< Pointer to the first register descriptor
 264   PCI_SPECIAL_CASE        *SpecialCases; ///< Pointer to array of special case handlers
 265 } PCI_REGISTER_BLOCK_HEADER;
 266
 267 /// S3 'conditional' PCI register list header.
 268 typedef struct {
 269   UINT16                          Version;       ///< Version of header
 270   UINT16                          NumRegisters;  ///< Number of registers in the list
 271   CONDITIONAL_PCI_REG_DESCRIPTOR  *RegisterList; ///< Pointer to the first register descriptor
 272   PCI_SPECIAL_CASE                *SpecialCases; ///< Pointer to array of special case handlers
 273 } CPCI_REGISTER_BLOCK_HEADER;
 274
 275 /// S3 MSR register list header.
 276 typedef struct {
 277   UINT16                 Version;       ///< Version of header
 278   UINT16                 NumRegisters;  ///< Number of registers in the list
 279   MSR_REG_DESCRIPTOR     *RegisterList; ///< Pointer to the first register descriptor
 280   MSR_SPECIAL_CASE       *SpecialCases; ///< Pointer to array of special case handlers
 281 } MSR_REGISTER_BLOCK_HEADER;
 282
 283 /// S3 'conditional' MSR register list header.
 284 typedef struct {
 285   UINT16                          Version;       ///< Version of header
 286   UINT16                          NumRegisters;  ///< Number of registers in the list
 287   CONDITIONAL_MSR_REG_DESCRIPTOR  *RegisterList; ///< Pointer to the first register descriptor
 288   MSR_SPECIAL_CASE                *SpecialCases; ///< Pointer to array of special case handlers
 289 } CMSR_REGISTER_BLOCK_HEADER;
 290
 291 /// S3 device descriptor pointers for ease of proper pointer advancement.
 292 typedef union {
 293   DEVICE_DESCRIPTOR *CommonDeviceHeader;         ///< Common header
 294   PCI_DEVICE_DESCRIPTOR *PciDevice;              ///< PCI header
 295   CONDITIONAL_PCI_DEVICE_DESCRIPTOR *CPciDevice; ///< 'conditional' PCI header
 296   MSR_DEVICE_DESCRIPTOR *MsrDevice;              ///< MSR header
 297   CONDITIONAL_MSR_DEVICE_DESCRIPTOR *CMsrDevice; ///< 'conditional' MSR header
 298 } DEVICE_DESCRIPTORS;
 299
 300 /// S3 register list header pointers for ease of proper pointer advancement.
 301 typedef union {
 302   DEVICE_DESCRIPTOR          *CommonDeviceHeader; ///< Common header
 303   PCI_REGISTER_BLOCK_HEADER  *PciRegisters;       ///< PCI header
 304   CPCI_REGISTER_BLOCK_HEADER *CPciRegisters;      ///< 'conditional' PCI header
 305   MSR_REGISTER_BLOCK_HEADER  *MsrRegisters;       ///< MSR header
 306   CMSR_REGISTER_BLOCK_HEADER *CMsrRegisters;      ///< 'conditional' MSR header
 307 } REGISTER_BLOCK_HEADERS;
 308
 309 /// S3 Volatile Storage Header
 310 typedef struct {
 311   UINT32  HeapOffset;                             ///< Offset to beginning of heap data
 312   UINT32  HeapSize;                               ///< Size of the heap data
 313   UINT32  RegisterDataOffset;                     ///< Offset to beginning of raw save data
 314   UINT32  RegisterDataSize;                       ///< Size of raw save data
 315 } S3_VOLATILE_STORAGE_HEADER;
 316
 317
 318 /*---------------------------------------------------------------------------------------
 319  *                        F U N C T I O N    P R O T O T Y P E
 320  *---------------------------------------------------------------------------------------
 321  */
 322 UINT32
 323 GetWorstCaseContextSize (
 324   IN       DEVICE_BLOCK_HEADER *DeviceList,
 325   IN       CALL_POINTS         CallPoint,
 326   IN       AMD_CONFIG_PARAMS   *StdHeader
 327   );
 328
 329 VOID
 330 SaveDeviceListContext (
 331   IN       DEVICE_BLOCK_HEADER *DeviceList,
 332   IN       VOID                *Storage,
 333   IN       CALL_POINTS         CallPoint,
 334      OUT   UINT32              *ActualBufferSize,
 335   IN       AMD_CONFIG_PARAMS   *StdHeader
 336   );
 337
 338 VOID
 339 RestorePreESRContext (
 340      OUT   VOID **OrMaskPtr,
 341   IN       VOID *Storage,
 342   IN       CALL_POINTS       CallPoint,
 343   IN       AMD_CONFIG_PARAMS *StdHeader
 344   );
 345
 346 VOID
 347 RestorePostESRContext (
 348   IN       VOID *OrMaskPtr,
 349   IN       VOID *Storage,
 350   IN       CALL_POINTS       CallPoint,
 351   IN       AMD_CONFIG_PARAMS *StdHeader
 352   );
 353
 354 VOID
 355 AmdS3ParamsInitializer (
 356      OUT   AMD_S3_PARAMS *S3Params
 357   );
 358
 359 VOID
 360 GetNonMemoryRelatedDeviceList (
 361      OUT   DEVICE_BLOCK_HEADER **NonMemoryRelatedDeviceList,
 362   IN       AMD_CONFIG_PARAMS   *StdHeader
 363   );
 364
 365 AGESA_STATUS
 366 S3GetPciDeviceRegisterList (
 367   IN       PCI_DEVICE_DESCRIPTOR     *Device,
 368      OUT   PCI_REGISTER_BLOCK_HEADER **RegisterHdr,
 369   IN       AMD_CONFIG_PARAMS         *StdHeader
 370   );
 371
 372 AGESA_STATUS
 373 S3GetCPciDeviceRegisterList (
 374   IN       CONDITIONAL_PCI_DEVICE_DESCRIPTOR *Device,
 375      OUT   CPCI_REGISTER_BLOCK_HEADER        **RegisterHdr,
 376   IN       AMD_CONFIG_PARAMS                 *StdHeader
 377   );
 378
 379 AGESA_STATUS
 380 S3GetMsrDeviceRegisterList (
 381   IN       MSR_DEVICE_DESCRIPTOR     *Device,
 382      OUT   MSR_REGISTER_BLOCK_HEADER **RegisterHdr,
 383   IN       AMD_CONFIG_PARAMS         *StdHeader
 384   );
 385
 386 AGESA_STATUS
 387 S3GetCMsrDeviceRegisterList (
 388   IN       CONDITIONAL_MSR_DEVICE_DESCRIPTOR *Device,
 389      OUT   CMSR_REGISTER_BLOCK_HEADER        **RegisterHdr,
 390   IN       AMD_CONFIG_PARAMS                 *StdHeader
 391   );
 392
 393
 394 #endif  // _S3_H_