src/vendorcode/amd/agesa/f15/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-30 11:27:42 -0600 (Wed, 30 Mar 2011) $
  11  *
  12  */
  13 /*
  14 *****************************************************************************
  15 *
  16 * Copyright (C) 2012 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
  45 #ifndef _S3_H_
  46 #define _S3_H_
  47
  48
  49 /*---------------------------------------------------------------------------------------
  50  *          M I X E D   (Definitions And Macros / Typedefs, Structures, Enums)
  51  *---------------------------------------------------------------------------------------
  52  */
  53
  54
  55 /*---------------------------------------------------------------------------------------
  56  *                 D E F I N I T I O N S     A N D     M A C R O S
  57  *---------------------------------------------------------------------------------------
  58  */
  59 #define RESTART_FROM_BEGINNING_LIST 0xFFFFFFFF
  60
  61 /*---------------------------------------------------------------------------------------
  62  *               T Y P E D E F S,   S T R U C T U R E S,    E N U M S
  63  *---------------------------------------------------------------------------------------
  64  */
  65
  66 /* Device related definitions */
  67
  68 /// Header at the beginning of a context save buffer.
  69 typedef struct {
  70   UINT16     Version;                 ///< Version of header
  71   UINT16     NumDevices;              ///< Number of devices in the list
  72   UINT16     RelativeOrMaskOffset;    ///< Size of device list + header
  73 } DEVICE_BLOCK_HEADER;
  74
  75 /// S3 device types
  76 typedef enum {
  77   DEV_TYPE_PCI_PRE_ESR,               ///< PCI device before exiting self-refresh
  78   DEV_TYPE_PCI,                       ///< PCI device after exiting self-refresh
  79   DEV_TYPE_CPCI_PRE_ESR,              ///< 'conditional' PCI device before exiting self-refresh
  80   DEV_TYPE_CPCI,                      ///< 'conditional' PCI device after exiting self-refresh
  81   DEV_TYPE_MSR_PRE_ESR,               ///< MSR device before exiting self-refresh
  82   DEV_TYPE_MSR,                       ///< MSR device after exiting self-refresh
  83   DEV_TYPE_CMSR_PRE_ESR,              ///< 'conditional' MSR device before exiting self-refresh
  84   DEV_TYPE_CMSR                       ///< 'conditional' MSR device after exiting self-refresh
  85 } S3_DEVICE_TYPES;
  86
  87 /// S3 restoration call points
  88 typedef enum {
  89   INIT_RESUME,                        ///< AMD_INIT_RESUME
  90   S3_LATE_RESTORE                     ///< AMD_S3LATE_RESTORE
  91 } CALL_POINTS;
  92
  93 /// S3 device common header
  94 typedef struct {
  95   UINT32     RegisterListID;          ///< Unique ID of this device
  96   UINT8      Type;                    ///< Appropriate S3_DEVICE_TYPES type
  97 } DEVICE_DESCRIPTOR;
  98
  99 /// S3 PCI device header
 100 typedef struct {
 101   UINT32     RegisterListID;          ///< Unique ID of this device
 102   UINT8      Type;                    ///< DEV_TYPE_PCI / DEV_TYPE_PCI_PRE_ESR
 103   UINT8      Node;                    ///< Zero-based node number
 104 } PCI_DEVICE_DESCRIPTOR;
 105
 106 /// S3 'conditional' PCI device header
 107 typedef struct {
 108   UINT32     RegisterListID;          ///< Unique ID of this device
 109   UINT8      Type;                    ///< DEV_TYPE_CPCI / DEV_TYPE_CPCI_PRE_ESR
 110   UINT8      Node;                    ///< Zero-based node number
 111   UINT8      Mask1;                   ///< Conditional mask 1
 112   UINT8      Mask2;                   ///< Conditional mask 2
 113 } CONDITIONAL_PCI_DEVICE_DESCRIPTOR;
 114
 115 /// S3 MSR device header
 116 typedef struct {
 117   UINT32     RegisterListID;          ///< Unique ID of this device
 118   UINT8      Type;                    ///< DEV_TYPE_MSR / DEV_TYPE_MSR_PRE_ESR
 119 } MSR_DEVICE_DESCRIPTOR;
 120
 121 /// S3 'conditional' MSR device header
 122 typedef struct {
 123   UINT32     RegisterListID;          ///< Unique ID of this device
 124   UINT8      Type;                    ///< DEV_TYPE_CMSR / DEV_TYPE_CMSR_PRE_ESR
 125   UINT8      Mask1;                   ///< Conditional mask 1
 126   UINT8      Mask2;                   ///< Conditional mask 2
 127 } CONDITIONAL_MSR_DEVICE_DESCRIPTOR;
 128
 129 /* Special case related definitions */
 130
 131 /**
 132  * PCI special case save handler
 133  *
 134  * @param[in]     AccessWidth   8, 16, or 32 bit wide access
 135  * @param[in]     Address       full PCI address of the register to save
 136  * @param[out]    Value         Value read from the register
 137  * @param[in]     ConfigPtr     AMD standard header config parameter
 138  *
 139  */
 140 typedef VOID (*PF_S3_SPECIAL_PCI_SAVE) (
 141   IN       ACCESS_WIDTH AccessWidth,
 142   IN       PCI_ADDR     Address,
 143      OUT   VOID         *Value,
 144   IN       VOID         *ConfigPtr
 145   );
 146
 147 /**
 148  * PCI special case restore handler
 149  *
 150  * @param[in]     AccessWidth   8, 16, or 32 bit wide access
 151  * @param[in]     Address       full PCI address of the register to save
 152  * @param[in]     Value         Value to write to the register
 153  * @param[in]     ConfigPtr     AMD standard header config parameter
 154  *
 155  */
 156 typedef VOID (*PF_S3_SPECIAL_PCI_RESTORE) (
 157   IN       ACCESS_WIDTH       AccessWidth,
 158   IN       PCI_ADDR           PciAddress,
 159   IN       VOID               *Value,
 160   IN       VOID               *StdHeader
 161   );
 162
 163 /**
 164  * MSR special case save handler
 165  *
 166  * @param[in]     MsrAddress    Address of model specific register to save
 167  * @param[out]    Value         Value read from the register
 168  * @param[in]     ConfigPtr     AMD standard header config parameter
 169  *
 170  */
 171 typedef VOID (*PF_S3_SPECIAL_MSR_SAVE) (
 172   IN       UINT32             MsrAddress,
 173      OUT   UINT64             *Value,
 174   IN       VOID               *StdHeader
 175   );
 176
 177 /**
 178  * MSR special case restore handler
 179  *
 180  * @param[in]     MsrAddress    Address of model specific register to restore
 181  * @param[in]     Value         Value to write to the register
 182  * @param[in]     ConfigPtr     AMD standard header config parameter
 183  *
 184  */
 185 typedef VOID (*PF_S3_SPECIAL_MSR_RESTORE) (
 186   IN       UINT32             MsrAddress,
 187   IN       UINT64             *Value,
 188   IN       VOID               *StdHeader
 189   );
 190
 191 /// PCI special case save/restore structure.
 192 typedef struct {
 193   PF_S3_SPECIAL_PCI_SAVE     Save;    ///< Save routine
 194   PF_S3_SPECIAL_PCI_RESTORE  Restore; ///< Restore routine
 195 } PCI_SPECIAL_CASE;
 196
 197 /// MSR special case save/restore structure.
 198 typedef struct {
 199   PF_S3_SPECIAL_MSR_SAVE     Save;    ///< Save routine
 200   PF_S3_SPECIAL_MSR_RESTORE  Restore; ///< Restore routine
 201 } MSR_SPECIAL_CASE;
 202
 203 /* Register related definitions */
 204 /// S3 register type bit fields
 205 typedef struct {
 206   UINT8      SpecialCaseIndex:4;      ///< Special Case array index
 207   UINT8      RegisterSize:3;          ///< For PCI, 1 = byte, 2 = word, else = dword.
 208                                       ///< For MSR, don't care
 209   UINT8      SpecialCaseFlag:1;       ///< Indicates special case
 210 } S3_REGISTER_TYPE;
 211
 212 /// S3 PCI register descriptor.
 213 typedef struct {
 214   S3_REGISTER_TYPE  Type;             ///< Type[7] = special case flag,
 215                                       ///< Type[6:3] = register size in bytes,
 216                                       ///< Type[2:0] = special case index
 217   UINT8             Function;         ///< PCI function of the register
 218   UINT16            Offset;           ///< PCI offset of the register
 219   UINT32            AndMask;          ///< AND mask to be applied to the value before saving
 220 } PCI_REG_DESCRIPTOR;
 221
 222 /// S3 'conditional' PCI register descriptor.
 223 typedef struct {
 224   S3_REGISTER_TYPE  Type;             ///< Type[7] = special case flag,
 225                                       ///< Type[6:3] = register size in bytes,
 226                                       ///< Type[2:0] = special case index
 227   UINT8             Function;         ///< PCI function of the register
 228   UINT16            Offset;           ///< PCI offset of the register
 229   UINT32            AndMask;          ///< AND mask to be applied to the value before saving
 230   UINT8             Mask1;            ///< conditional mask 1
 231   UINT8             Mask2;            ///< conditional mask 2
 232 } CONDITIONAL_PCI_REG_DESCRIPTOR;
 233
 234 /// S3 MSR register descriptor.
 235 typedef struct {
 236   S3_REGISTER_TYPE  Type;             ///< Type[7] = special case flag,
 237                                       ///< Type[6:3] = reserved,
 238                                       ///< Type[2:0] = special case index
 239   UINT32            Address;          ///< MSR address
 240   UINT64            AndMask;          ///< AND mask to be applied to the value before saving
 241 } MSR_REG_DESCRIPTOR;
 242
 243 /// S3 'conditional' MSR register descriptor.
 244 typedef struct {
 245   S3_REGISTER_TYPE  Type;             ///< Type[7] = special case flag,
 246                                       ///< Type[6:3] = reserved,
 247                                       ///< Type[2:0] = special case index
 248   UINT32            Address;          ///< MSR address
 249   UINT64            AndMask;          ///< AND mask to be applied to the value before saving
 250   UINT8             Mask1;            ///< conditional mask 1
 251   UINT8             Mask2;            ///< conditional mask 2
 252 } CONDITIONAL_MSR_REG_DESCRIPTOR;
 253
 254 /// Common header at the beginning of an S3 register list.
 255 typedef struct {
 256   UINT16     Version;                 ///< Version of header
 257   UINT16     NumRegisters;            ///< Number of registers in the list
 258 } REGISTER_BLOCK_HEADER;
 259
 260 /// S3 PCI register list header.
 261 typedef struct {
 262   UINT16                  Version;       ///< Version of header
 263   UINT16                  NumRegisters;  ///< Number of registers in the list
 264   PCI_REG_DESCRIPTOR      *RegisterList; ///< Pointer to the first register descriptor
 265   PCI_SPECIAL_CASE        *SpecialCases; ///< Pointer to array of special case handlers
 266 } PCI_REGISTER_BLOCK_HEADER;
 267
 268 /// S3 'conditional' PCI register list header.
 269 typedef struct {
 270   UINT16                          Version;       ///< Version of header
 271   UINT16                          NumRegisters;  ///< Number of registers in the list
 272   CONDITIONAL_PCI_REG_DESCRIPTOR  *RegisterList; ///< Pointer to the first register descriptor
 273   PCI_SPECIAL_CASE                *SpecialCases; ///< Pointer to array of special case handlers
 274 } CPCI_REGISTER_BLOCK_HEADER;
 275
 276 /// S3 MSR register list header.
 277 typedef struct {
 278   UINT16                 Version;       ///< Version of header
 279   UINT16                 NumRegisters;  ///< Number of registers in the list
 280   MSR_REG_DESCRIPTOR     *RegisterList; ///< Pointer to the first register descriptor
 281   MSR_SPECIAL_CASE       *SpecialCases; ///< Pointer to array of special case handlers
 282 } MSR_REGISTER_BLOCK_HEADER;
 283
 284 /// S3 'conditional' MSR register list header.
 285 typedef struct {
 286   UINT16                          Version;       ///< Version of header
 287   UINT16                          NumRegisters;  ///< Number of registers in the list
 288   CONDITIONAL_MSR_REG_DESCRIPTOR  *RegisterList; ///< Pointer to the first register descriptor
 289   MSR_SPECIAL_CASE                *SpecialCases; ///< Pointer to array of special case handlers
 290 } CMSR_REGISTER_BLOCK_HEADER;
 291
 292 /// S3 device descriptor pointers for ease of proper pointer advancement.
 293 typedef union {
 294   DEVICE_DESCRIPTOR *CommonDeviceHeader;         ///< Common header
 295   PCI_DEVICE_DESCRIPTOR *PciDevice;              ///< PCI header
 296   CONDITIONAL_PCI_DEVICE_DESCRIPTOR *CPciDevice; ///< 'conditional' PCI header
 297   MSR_DEVICE_DESCRIPTOR *MsrDevice;              ///< MSR header
 298   CONDITIONAL_MSR_DEVICE_DESCRIPTOR *CMsrDevice; ///< 'conditional' MSR header
 299 } DEVICE_DESCRIPTORS;
 300
 301 /// S3 register list header pointers for ease of proper pointer advancement.
 302 typedef union {
 303   DEVICE_DESCRIPTOR          *CommonDeviceHeader; ///< Common header
 304   PCI_REGISTER_BLOCK_HEADER  *PciRegisters;       ///< PCI header
 305   CPCI_REGISTER_BLOCK_HEADER *CPciRegisters;      ///< 'conditional' PCI header
 306   MSR_REGISTER_BLOCK_HEADER  *MsrRegisters;       ///< MSR header
 307   CMSR_REGISTER_BLOCK_HEADER *CMsrRegisters;      ///< 'conditional' MSR header
 308 } REGISTER_BLOCK_HEADERS;
 309
 310 /// S3 Volatile Storage Header
 311 typedef struct {
 312   UINT32  HeapOffset;                             ///< Offset to beginning of heap data
 313   UINT32  HeapSize;                               ///< Size of the heap data
 314   UINT32  RegisterDataOffset;                     ///< Offset to beginning of raw save data
 315   UINT32  RegisterDataSize;                       ///< Size of raw save data
 316 } S3_VOLATILE_STORAGE_HEADER;
 317
 318
 319 /*---------------------------------------------------------------------------------------
 320  *                        F U N C T I O N    P R O T O T Y P E
 321  *---------------------------------------------------------------------------------------
 322  */
 323 UINT32
 324 GetWorstCaseContextSize (
 325   IN       DEVICE_BLOCK_HEADER *DeviceList,
 326   IN       CALL_POINTS         CallPoint,
 327   IN       AMD_CONFIG_PARAMS   *StdHeader
 328   );
 329
 330 VOID
 331 SaveDeviceListContext (
 332   IN       DEVICE_BLOCK_HEADER *DeviceList,
 333   IN       VOID                *Storage,
 334   IN       CALL_POINTS         CallPoint,
 335      OUT   UINT32              *ActualBufferSize,
 336   IN       AMD_CONFIG_PARAMS   *StdHeader
 337   );
 338
 339 VOID
 340 RestorePreESRContext (
 341      OUT   VOID **OrMaskPtr,
 342   IN       VOID *Storage,
 343   IN       CALL_POINTS       CallPoint,
 344   IN       AMD_CONFIG_PARAMS *StdHeader
 345   );
 346
 347 VOID
 348 RestorePostESRContext (
 349   IN       VOID *OrMaskPtr,
 350   IN       VOID *Storage,
 351   IN       CALL_POINTS       CallPoint,
 352   IN       AMD_CONFIG_PARAMS *StdHeader
 353   );
 354
 355 VOID
 356 AmdS3ParamsInitializer (
 357      OUT   AMD_S3_PARAMS *S3Params
 358   );
 359
 360 VOID
 361 GetNonMemoryRelatedDeviceList (
 362      OUT   DEVICE_BLOCK_HEADER **NonMemoryRelatedDeviceList,
 363   IN       AMD_CONFIG_PARAMS   *StdHeader
 364   );
 365
 366 AGESA_STATUS
 367 S3GetPciDeviceRegisterList (
 368   IN       PCI_DEVICE_DESCRIPTOR     *Device,
 369      OUT   PCI_REGISTER_BLOCK_HEADER **RegisterHdr,
 370   IN       AMD_CONFIG_PARAMS         *StdHeader
 371   );
 372
 373 AGESA_STATUS
 374 S3GetCPciDeviceRegisterList (
 375   IN       CONDITIONAL_PCI_DEVICE_DESCRIPTOR *Device,
 376      OUT   CPCI_REGISTER_BLOCK_HEADER        **RegisterHdr,
 377   IN       AMD_CONFIG_PARAMS                 *StdHeader
 378   );
 379
 380 AGESA_STATUS
 381 S3GetMsrDeviceRegisterList (
 382   IN       MSR_DEVICE_DESCRIPTOR     *Device,
 383      OUT   MSR_REGISTER_BLOCK_HEADER **RegisterHdr,
 384   IN       AMD_CONFIG_PARAMS         *StdHeader
 385   );
 386
 387 AGESA_STATUS
 388 S3GetCMsrDeviceRegisterList (
 389   IN       CONDITIONAL_MSR_DEVICE_DESCRIPTOR *Device,
 390      OUT   CMSR_REGISTER_BLOCK_HEADER        **RegisterHdr,
 391   IN       AMD_CONFIG_PARAMS                 *StdHeader
 392   );
 393
 394
 395 #endif  // _S3_H_