diff options
Diffstat (limited to 'Board/EM/RapidStartWrapper/Library/RapidStartPlatformLib/Pei/RapidStartPeiLib.h')
| -rw-r--r-- | Board/EM/RapidStartWrapper/Library/RapidStartPlatformLib/Pei/RapidStartPeiLib.h | 306 |
1 files changed, 306 insertions, 0 deletions
diff --git a/Board/EM/RapidStartWrapper/Library/RapidStartPlatformLib/Pei/RapidStartPeiLib.h b/Board/EM/RapidStartWrapper/Library/RapidStartPlatformLib/Pei/RapidStartPeiLib.h new file mode 100644 index 0000000..7eb2422 --- /dev/null +++ b/Board/EM/RapidStartWrapper/Library/RapidStartPlatformLib/Pei/RapidStartPeiLib.h @@ -0,0 +1,306 @@ +//********************************************************************** +//********************************************************************** +//** ** +//** (C)Copyright 1985-2012, American Megatrends, Inc. ** +//** ** +//** All Rights Reserved. ** +//** ** +//** 5555 Oakbrook Parkway, Suite 200, Norcross, GA 30093 ** +//** ** +//** Phone: (770)-246-8600 ** +//** ** +//********************************************************************** +//********************************************************************** + +//********************************************************************** +// $Header: /Alaska/SOURCE/Modules/Intel Fast Flash Standby/iRST_SharkBay/RapidStartWrapper/RapidStartPeiLib/RapidStartPeiLib.h 2 12/18/12 12:19a Bensonlai $ +// +// $Revision: 2 $ +// +// $Date: 12/18/12 12:19a $ +//********************************************************************** +// Revision History +// ---------------- +// $Log: /Alaska/SOURCE/Modules/Intel Fast Flash Standby/iRST_SharkBay/RapidStartWrapper/RapidStartPeiLib/RapidStartPeiLib.h $ +// +// 2 12/18/12 12:19a Bensonlai +// [TAG] EIP109701 +// [Category] Spec Update +// [Severity] Normal +// [Description] Updated to Shark Bay Rapid Start Reference Code +// Version 0.8.1 +// [Files] RapidStartPeiLib.c, RapidStartPeiLib.h +// +// 1 10/15/12 4:41a Bensonlai +// [TAG] EIPNone +// [Category] Improvement +// [Description] [Category] Improvement +// [Severity] Important +// [Description] Rename all IFFS sting to Rapid Start. +// [Files] Board\EM\RapidStartWrapper\*.*, ReferenceCode\RapidStart\*.* +// [Files] RapidStartPeiLib.cif +// RapidStartPeiLib.sdl +// RapidStartPeiLib.mak +// RapidStartPeiLib.c +// RapidStartPeiLib.h +// RapidStartPeiLib.inf +// RapidStartPeiLib.lib +// PeiCryptLib.lib +// OpensslLib.lib +// +//********************************************************************** +//<AMI_FHDR_START> +// +// Name: RapidStartPeiLib.h +// +// Description: Defines and prototypes for the library module. +// +//<AMI_FHDR_END> +//********************************************************************** + +#ifndef _RAPID_START_PEI_LIB_H_ +#define _RAPID_START_PEI_LIB_H_ + +#if !defined(EDK_RELEASE_VERSION) || (EDK_RELEASE_VERSION < 0x00020000) +#include "RapidStartConfig.h" +#include EFI_PPI_DEFINITION (RapidStart) +#endif + +#ifndef RAPID_START_NO_SMRAM_INTEGRITY_CHECK +// +// Secure hash definitions for SMRAM integrity check +// +#include "BaseCryptLib.h" +#define RAPID_START_SECURE_HASH_LENGTH SHA256_DIGEST_SIZE +#define IfsSecureHashGetContextSize() (Sha256GetContextSize ()) +#define RapidStartSecureHashInit(state) (Sha256Init (state)) +#define RapidStartSecureHashUpdate(state, data, len) (Sha256Update ((state), (data), (len))) +#define RapidStartSecureHashFinal(state, output) (Sha256Final ((state), (output))) + +/** + Saves SMRAM Secure Hash to non-volatile secure location. + + Only available when "RAPID_START_NO_SMRAM_INTEGRITY_CHECK" not defined. This + function requires porting to support SMRAM Hash algorithm. + + This function will save SMRAM Hash value into non-volatile memory, platform code + has to provide the available non-volatile memory space and modify this function + to save SMRAM Hash value into that space. Reference code by default uses SHA256 + hashing algorithm in UDK2010 "Crypto library". See section "Porting + Recommendation" for more information. The hash needs to be as strong as the + one used to produce security measurements stored in the TPM, so as to not weaken + the overall security level provided by the platform. + "RAPID_START_SECURE_HASH_LENGTH" is defined as "SHA256_DIGEST_SIZE", + which is defined as 32 in BaseCryptLib.h See "Porting Recommendation" + section in this document for SMRAM Hashing implementation. + + @param[in] Hash[] - hash value + + @retval EFI_SUCCESS - Hash value has been saved successfully + @retval EFI_NOT_FOUND - Hash value not found +**/ +EFI_STATUS +RapidStartSaveSecureHash ( + IN UINT8 Hash[RAPID_START_SECURE_HASH_LENGTH] + ); + +/** + Retrieves and removes SMRAM hash from non-volatile memory + + Only available when "RAPID_START_NO_SMRAM_INTEGRITY_CHECK" not defined. This + function requires porting to support SMRAM Hash algorithm. + + This function will retrieve SMRAM Hash value from non-volatile memory and then + remove it from non-volatile memory. Platform code has to provide the available + non-volatile memory space and modify this function to retrieve SMRAM Hash value + from that space. After hash value retrieved, the hash value has to be scrubbed + from non-volatile memory immediately. Reference code by default uses SHA256 + hashing algorithm in UDK2010 "Crypto library". See section "Porting + Recommendation" for more information. The hash needs to be as strong as the + one used to produce security measurements stored in the TPM, so as to not weaken + the overall security level provided by the platform. + "RAPID_START_SECURE_HASH_LENGTH" is defined as "SHA256_DIGEST_SIZE", + which is defined as 32 in BaseCryptLib.h + + @param[out] Hash[] - hash value + + @retval EFI_SUCCESS - Hash value has been restored and cleared successfully + @retval EFI_NOT_FOUND - Hash value not found +**/ +EFI_STATUS +RapidStartRestoreAndClearSecureHash ( + OUT UINT8 Hash[RAPID_START_SECURE_HASH_LENGTH] + ); + +#endif /* RAPID_START_NO_SMRAM_INTEGRITY_CHECK */ + +/** + Enables ACPI mode after RapidStart resume. + + This function will do the platform specific initialization for switching to ACPI + mode by issuing ACPI_ENABLE SWSMI in the end of Rapid Start Exit transition. OS + will treat Rapid Start Exit as same as regular S3 resume so it will not + re-initialize certain tasks, like ACPI_ENABLE SMI will be skipped by OS, but + those tasks still required for Rapid Start Exit because it could be resume from + S4 or G3 state. This function may need some porting to fit platform design. + + @param[in] PeiServices - Pointer to PEI Services Table. + + @retval EFI_SUCCESS - enabled ACPI mode +**/ +EFI_STATUS +RapidStartEnableAcpi ( + IN EFI_PEI_SERVICES **PeiServices + ); + +/** + This callback is provided to support drive password locking interoperability with RapidStart. + It is called before RapidStart transition is to occur. If SSD partiotion is located on password + locked drive this function must copy the password to the output buffer. + Size of the buffer equals ATA_PASSWORD_LEN. + + Normally the drive password is kept in SMRAM so it can be used to unlock the drive at S3 resume, + thus during RapidStartEntry the password from SMRAM shall be returned. However at RapidStartExit the content + of SMRAM is not yet available so the password has to be preserved in a non-volatile memory + during RapidStartEntry (in RapidStartAfterTransition callback) and retrieved by this function. + + For security reasons the password must be scrubbed from non-volatile memory on RapidStartExit before + returning from this function. On RapidStartEntry the password must not be stored to non-volatile memory + sooner than RapidStartAfterTransition is called (that is after RapidStart non-volatile flag is set). + + @param[in] PeiServices - Pointer to PEI Services Table + @param[in] Transition - RapidStart transition being performed + @param[in] SataPort - locked SATA port + @param[out] Password - output buffer to place the password in + @param[out] FreezeLock - set to TRUE to freeze drive lock, set to FALSE otherwise + + @retval EFI_SUCCESS - Unlock password copied to the buffer + @retval EFI_NOT_FOUND - No password provided (will break the transition) +**/ +EFI_STATUS +RapidStartGetDriveUnlockPassword ( + IN EFI_PEI_SERVICES **PeiServices, + IN RAPID_START_TRANSITION Transition, + IN UINT8 SataPort, + OUT UINT8 *Password, + OUT BOOLEAN *FreezeLock + ); + +/** + This callback is executed before RapidStart transition is performed, but after RapidStart transition conditions has been met. + + This callback is executed before Rapid Start transition is performed, but after + Rapid Start transition conditions have been met. This callback provides + capability to cancel Rapid Start transition if required by platform specific + condition. + + @param[in] PeiServices - Pointer to PEI Services Table + @param[in] Transition - RapidStart transition being performed + @param[in] SataPort - SATA port of RapidStart storage drive + + @retval EFI_SUCCESS - RapidStart transition will follow + @retval EFI_ABORTED - RapidStart transition will not be performed +**/ +EFI_STATUS +RapidStartBeforeTransition ( + IN EFI_PEI_SERVICES **PeiServices, + IN RAPID_START_TRANSITION Transition, + IN UINT8 SataPort + ); + +/** + This callback is executed at the end of RapidStart transition whether succesfull ot not. + + If RapidStart partition is located on password locked drive the drive password must be + copied to non-volatile memory during RapidStartEntry in this function, so it is available + on RapidStartExit (see RapidStartGetDriveUnlockPassword). + + @param[in] PeiServices - Pointer to PEI Services Table + @param[in] Transition - RapidStart transition being performed + @param[in] TransitionStatus - Status of the RapidStart transition + @param[in] SataPort - SATA port of RapidStart storage drive +**/ +VOID +RapidStartAfterTransition ( + IN EFI_PEI_SERVICES **PeiServices, + IN RAPID_START_TRANSITION Transition, + IN EFI_STATUS TransitionStatus, + IN UINT8 SataPort + ); + +/** + Provide a hook for OEM to cancel RapidStart flow. + This function may impact RapidStart Entry performance since it's polled frequently. + + This routine is a callback for platform designer to cancel the Rapid Start Entry + process and do S3 resume back to OS immediately (e.g. Lid opening). Since the + time for Rapid Start Entry might be long and user might want to cancel it for + any urgent scenario. This required condition check for when the Rapid Start + Entry should be canceled. Note: This callback will be polled frequently during + Rapid Start Entry process, so the implementation may impact Rapid Start Entry + performance. + + A callback for platform designer to cancel Rapid Start Entry process when + specific condition happened (e.g. Lid opening). This is optional, required + porting and might impact Rapid Start Entry performance. + + @retval FALSE - Do not cancel RapidStart flow + @retval TRUE - The RapidStart Entry flow should be canceled and do S3 resume back to OS +**/ +BOOLEAN +RapidStartShouldCancelEntry ( + VOID + ); + +/** + This callback is executed to clear all PEM events before Rapid Start enter S4. + + @retval EFI_SUCCESS - Operation successfully performed +**/ +EFI_STATUS +RapidStartClearOemPmeEvent ( + VOID + ); + +// +// Max uCode time out is 100 Milli second +// +#define MAX_UCODE_TIMEOUT 100000 +#define STALL_1_MICROSECONDS 1 + +/** + This function is work around for NetDetect and WakeOnLan when RapidStart enabled. + + @param EFI_SUCCESS - Operation successfully performed +**/ +EFI_STATUS +RapidStartWANetDetect ( + IN EFI_PEI_SERVICES **PeiServices, + IN UINT32 WlanMmioSpace + ); + +/** + Provide a hook for OEM to cancel RapidStart Instant-On function. + This function may impact RapidStart Resume performance since it's polled frequently. + + @retval FALSE - Do not cancel RapidStart Instant-On + @retval TRUE - The RapidStart Resume will have no Instant-On function +**/ +BOOLEAN +RapidStartUnattendedWake ( + VOID + ); +#endif +//************************************************************************* +//************************************************************************* +//** ** +//** (C)Copyright 1985-2012, American Megatrends, Inc. ** +//** ** +//** All Rights Reserved. ** +//** ** +//** 5555 Oakbrook Parkway, Suite 200, Norcross, GA 30093 ** +//** ** +//** Phone: (770)-246-8600 ** +//** ** +//************************************************************************* +//************************************************************************* |