1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
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 **
//** **
//*************************************************************************
//*************************************************************************
|