/** @file

  This is an implementation of the ACPI S3 Save protocol.  This is defined in 

  S3 boot path specification 0.9.



Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR>



This program and the accompanying materials

are licensed and made available under the terms and conditions

of the BSD License which accompanies this distribution.  The

full text of the license may be found at

http://opensource.org/licenses/bsd-license.php



THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.



**/



#ifndef _ACPI_S3_SAVE_H_

#define _ACPI_S3_SAVE_H_



#pragma pack(1)



typedef union {

  struct {

    UINT32  LimitLow    : 16;

    UINT32  BaseLow     : 16;

    UINT32  BaseMid     : 8;

    UINT32  Type        : 4;

    UINT32  System      : 1;

    UINT32  Dpl         : 2;

    UINT32  Present     : 1;

    UINT32  LimitHigh   : 4;

    UINT32  Software    : 1;

    UINT32  Reserved    : 1;

    UINT32  DefaultSize : 1;

    UINT32  Granularity : 1;

    UINT32  BaseHigh    : 8;

  } Bits;

  UINT64  Uint64;

} IA32_GDT;



typedef struct {

  IA32_IDT_GATE_DESCRIPTOR  Ia32IdtEntry;

  UINT32                    Offset32To63;

  UINT32                    Reserved;

} X64_IDT_GATE_DESCRIPTOR;



//

// Page-Map Level-4 Offset (PML4) and

// Page-Directory-Pointer Offset (PDPE) entries 4K & 2MB

//



typedef union {

  struct {

    UINT64  Present:1;                // 0 = Not present in memory, 1 = Present in memory

    UINT64  ReadWrite:1;              // 0 = Read-Only, 1= Read/Write

    UINT64  UserSupervisor:1;         // 0 = Supervisor, 1=User

    UINT64  WriteThrough:1;           // 0 = Write-Back caching, 1=Write-Through caching

    UINT64  CacheDisabled:1;          // 0 = Cached, 1=Non-Cached

    UINT64  Accessed:1;               // 0 = Not accessed, 1 = Accessed (set by CPU)

    UINT64  Reserved:1;               // Reserved

    UINT64  MustBeZero:2;             // Must Be Zero

    UINT64  Available:3;              // Available for use by system software

    UINT64  PageTableBaseAddress:40;  // Page Table Base Address

    UINT64  AvabilableHigh:11;        // Available for use by system software

    UINT64  Nx:1;                     // No Execute bit

  } Bits;

  UINT64    Uint64;

} PAGE_MAP_AND_DIRECTORY_POINTER;



//

// Page Table Entry 2MB

//

typedef union {

  struct {

    UINT64  Present:1;                // 0 = Not present in memory, 1 = Present in memory

    UINT64  ReadWrite:1;              // 0 = Read-Only, 1= Read/Write

    UINT64  UserSupervisor:1;         // 0 = Supervisor, 1=User

    UINT64  WriteThrough:1;           // 0 = Write-Back caching, 1=Write-Through caching

    UINT64  CacheDisabled:1;          // 0 = Cached, 1=Non-Cached

    UINT64  Accessed:1;               // 0 = Not accessed, 1 = Accessed (set by CPU)

    UINT64  Dirty:1;                  // 0 = Not Dirty, 1 = written by processor on access to page

    UINT64  MustBe1:1;                // Must be 1 

    UINT64  Global:1;                 // 0 = Not global page, 1 = global page TLB not cleared on CR3 write

    UINT64  Available:3;              // Available for use by system software

    UINT64  PAT:1;                    //

    UINT64  MustBeZero:8;             // Must be zero;

    UINT64  PageTableBaseAddress:31;  // Page Table Base Address

    UINT64  AvabilableHigh:11;        // Available for use by system software

    UINT64  Nx:1;                     // 0 = Execute Code, 1 = No Code Execution

  } Bits;

  UINT64    Uint64;

} PAGE_TABLE_ENTRY;



//

// Page Table Entry 1GB

//

typedef union {

  struct {

    UINT64  Present:1;                // 0 = Not present in memory, 1 = Present in memory

    UINT64  ReadWrite:1;              // 0 = Read-Only, 1= Read/Write

    UINT64  UserSupervisor:1;         // 0 = Supervisor, 1=User

    UINT64  WriteThrough:1;           // 0 = Write-Back caching, 1=Write-Through caching

    UINT64  CacheDisabled:1;          // 0 = Cached, 1=Non-Cached

    UINT64  Accessed:1;               // 0 = Not accessed, 1 = Accessed (set by CPU)

    UINT64  Dirty:1;                  // 0 = Not Dirty, 1 = written by processor on access to page

    UINT64  MustBe1:1;                // Must be 1 

    UINT64  Global:1;                 // 0 = Not global page, 1 = global page TLB not cleared on CR3 write

    UINT64  Available:3;              // Available for use by system software

    UINT64  PAT:1;                    //

    UINT64  MustBeZero:17;            // Must be zero;

    UINT64  PageTableBaseAddress:22;  // Page Table Base Address

    UINT64  AvabilableHigh:11;        // Available for use by system software

    UINT64  Nx:1;                     // 0 = Execute Code, 1 = No Code Execution

  } Bits;

  UINT64    Uint64;

} PAGE_TABLE_1G_ENTRY;



#pragma pack()



/**

  Gets the buffer of legacy memory below 1 MB 

  This function is to get the buffer in legacy memory below 1MB that is required during S3 resume.



  @param This           A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance.

  @param Size           The returned size of legacy memory below 1 MB.



  @retval EFI_SUCCESS           Size is successfully returned.

  @retval EFI_INVALID_PARAMETER The pointer Size is NULL.



**/

EFI_STATUS

EFIAPI

LegacyGetS3MemorySize (

  IN  EFI_ACPI_S3_SAVE_PROTOCOL    * This,

  OUT UINTN                        * Size

  );



/**

  Prepares all information that is needed in the S3 resume boot path.

  

  Allocate the resources or prepare informations and save in ACPI variable set for S3 resume boot path  

  

  @param This                 A pointer to the EFI_ACPI_S3_SAVE_PROTOCOL instance.

  @param LegacyMemoryAddress  The base address of legacy memory.



  @retval EFI_NOT_FOUND         Some necessary information cannot be found.

  @retval EFI_SUCCESS           All information was saved successfully.

  @retval EFI_OUT_OF_RESOURCES  Resources were insufficient to save all the information.

  @retval EFI_INVALID_PARAMETER The memory range is not located below 1 MB.



**/

EFI_STATUS

EFIAPI

S3Ready (

  IN EFI_ACPI_S3_SAVE_PROTOCOL     *This,

  IN VOID                          *LegacyMemoryAddress   

  );

#endif