SmmCpuFeaturesLib.h@ 85805

Last change on this file since 85805 was 85718, checked in by vboxsync, 5 years ago
Devices/EFI: Merge edk-stable202005 and make it build, bugref:4643
Property svn:eol-style set to `native`
File size: 16.1 KB

Line
1	/** @file
2	Library that provides CPU specific functions to support the PiSmmCpuDxeSmm module.
3
4	Copyright (c) 2015 - 2019, Intel Corporation. All rights reserved.<BR>
5	SPDX-License-Identifier: BSD-2-Clause-Patent
6
7	**/
8
9	#ifndef __SMM_FEATURES_LIB_H__
10	#define __SMM_FEATURES_LIB_H__
11
12	#include <Protocol/MpService.h>
13	#include <Protocol/SmmCpu.h>
14	#include <Register/Intel/SmramSaveStateMap.h>
15	#include <CpuHotPlugData.h>
16
17	///
18	/// Enumeration of SMM registers that are accessed using the library functions
19	/// SmmCpuFeaturesIsSmmRegisterSupported (), SmmCpuFeaturesGetSmmRegister (),
20	/// and SmmCpuFeaturesSetSmmRegister ().
21	///
22	typedef enum {
23	///
24	/// Read-write register to provides access to MSR_SMM_FEATURE_CONTROL if the
25	/// CPU supports this MSR.
26	///
27	SmmRegFeatureControl,
28	///
29	/// Read-only register that returns a non-zero value if the CPU is able to
30	/// respond to SMIs.
31	///
32	SmmRegSmmEnable,
33	///
34	/// Read-only register that returns a non-zero value if the CPU is able to
35	/// respond to SMIs, but is busy with other actions that are causing a delay
36	/// in responding to an SMI. This register abstracts access to MSR_SMM_DELAYED
37	/// if the CPU supports this MSR.
38	///
39	SmmRegSmmDelayed,
40	///
41	/// Read-only register that returns a non-zero value if the CPU is able to
42	/// respond to SMIs, but is busy with other actions that are blocking its
43	/// ability to respond to an SMI. This register abstracts access to
44	/// MSR_SMM_BLOCKED if the CPU supports this MSR.
45	///
46	SmmRegSmmBlocked
47	} SMM_REG_NAME;
48
49	/**
50	Called during the very first SMI into System Management Mode to initialize
51	CPU features, including SMBASE, for the currently executing CPU. Since this
52	is the first SMI, the SMRAM Save State Map is at the default address of
53	SMM_DEFAULT_SMBASE + SMRAM_SAVE_STATE_MAP_OFFSET. The currently executing
54	CPU is specified by CpuIndex and CpuIndex can be used to access information
55	about the currently executing CPU in the ProcessorInfo array and the
56	HotPlugCpuData data structure.
57
58	@param[in] CpuIndex The index of the CPU to initialize. The value
59	must be between 0 and the NumberOfCpus field in
60	the System Management System Table (SMST).
61	@param[in] IsMonarch TRUE if the CpuIndex is the index of the CPU that
62	was elected as monarch during System Management
63	Mode initialization.
64	FALSE if the CpuIndex is not the index of the CPU
65	that was elected as monarch during System
66	Management Mode initialization.
67	@param[in] ProcessorInfo Pointer to an array of EFI_PROCESSOR_INFORMATION
68	structures. ProcessorInfo[CpuIndex] contains the
69	information for the currently executing CPU.
70	@param[in] CpuHotPlugData Pointer to the CPU_HOT_PLUG_DATA structure that
71	contains the ApidId and SmBase arrays.
72	**/
73	VOID
74	EFIAPI
75	SmmCpuFeaturesInitializeProcessor (
76	IN UINTN CpuIndex,
77	IN BOOLEAN IsMonarch,
78	IN EFI_PROCESSOR_INFORMATION *ProcessorInfo,
79	IN CPU_HOT_PLUG_DATA *CpuHotPlugData
80	);
81
82	/**
83	This function updates the SMRAM save state on the currently executing CPU
84	to resume execution at a specific address after an RSM instruction. This
85	function must evaluate the SMRAM save state to determine the execution mode
86	the RSM instruction resumes and update the resume execution address with
87	either NewInstructionPointer32 or NewInstructionPoint. The auto HALT restart
88	flag in the SMRAM save state must always be cleared. This function returns
89	the value of the instruction pointer from the SMRAM save state that was
90	replaced. If this function returns 0, then the SMRAM save state was not
91	modified.
92
93	This function is called during the very first SMI on each CPU after
94	SmmCpuFeaturesInitializeProcessor() to set a flag in normal execution mode
95	to signal that the SMBASE of each CPU has been updated before the default
96	SMBASE address is used for the first SMI to the next CPU.
97
98	@param[in] CpuIndex The index of the CPU to hook. The value
99	must be between 0 and the NumberOfCpus
100	field in the System Management System Table
101	(SMST).
102	@param[in] CpuState Pointer to SMRAM Save State Map for the
103	currently executing CPU.
104	@param[in] NewInstructionPointer32 Instruction pointer to use if resuming to
105	32-bit execution mode from 64-bit SMM.
106	@param[in] NewInstructionPointer Instruction pointer to use if resuming to
107	same execution mode as SMM.
108
109	@retval 0 This function did modify the SMRAM save state.
110	@retval > 0 The original instruction pointer value from the SMRAM save state
111	before it was replaced.
112	**/
113	UINT64
114	EFIAPI
115	SmmCpuFeaturesHookReturnFromSmm (
116	IN UINTN CpuIndex,
117	IN SMRAM_SAVE_STATE_MAP *CpuState,
118	IN UINT64 NewInstructionPointer32,
119	IN UINT64 NewInstructionPointer
120	);
121
122	/**
123	Hook point in normal execution mode that allows the one CPU that was elected
124	as monarch during System Management Mode initialization to perform additional
125	initialization actions immediately after all of the CPUs have processed their
126	first SMI and called SmmCpuFeaturesInitializeProcessor() relocating SMBASE
127	into a buffer in SMRAM and called SmmCpuFeaturesHookReturnFromSmm().
128	**/
129	VOID
130	EFIAPI
131	SmmCpuFeaturesSmmRelocationComplete (
132	VOID
133	);
134
135	/**
136	Return the size, in bytes, of a custom SMI Handler in bytes. If 0 is
137	returned, then a custom SMI handler is not provided by this library,
138	and the default SMI handler must be used.
139
140	@retval 0 Use the default SMI handler.
141	@retval > 0 Use the SMI handler installed by SmmCpuFeaturesInstallSmiHandler()
142	The caller is required to allocate enough SMRAM for each CPU to
143	support the size of the custom SMI handler.
144	**/
145	UINTN
146	EFIAPI
147	SmmCpuFeaturesGetSmiHandlerSize (
148	VOID
149	);
150
151	/**
152	Install a custom SMI handler for the CPU specified by CpuIndex. This function
153	is only called if SmmCpuFeaturesGetSmiHandlerSize() returns a size is greater
154	than zero and is called by the CPU that was elected as monarch during System
155	Management Mode initialization.
156
157	//
158	// Append Shadow Stack after normal stack
159	//
160	// \|= SmiStack
161	// +--------------------------------------------------+---------------------------------------------------------------+
162	// \| Known Good Stack \| Guard Page \| SMM Stack \| Known Good Shadow Stack \| Guard Page \| SMM Shadow Stack \|
163	// +--------------------------------------------------+---------------------------------------------------------------+
164	// \| \|PcdCpuSmmStackSize\| \|PcdCpuSmmShadowStackSize\|
165	// \|<-------------------- StackSize ----------------->\|<------------------------- ShadowStackSize ------------------->\|
166	// \| \|
167	// \|<-------------------------------------------- Processor N ------------------------------------------------------->\|
168	// \| low address (bottom) high address (top) \|
169	//
170
171	@param[in] CpuIndex The index of the CPU to install the custom SMI handler.
172	The value must be between 0 and the NumberOfCpus field
173	in the System Management System Table (SMST).
174	@param[in] SmBase The SMBASE address for the CPU specified by CpuIndex.
175	@param[in] SmiStack The bottom of stack to use when an SMI is processed by the
176	the CPU specified by CpuIndex.
177	@param[in] StackSize The size, in bytes, if the stack used when an SMI is
178	processed by the CPU specified by CpuIndex.
179	StackSize should be PcdCpuSmmStackSize, with 2 more pages
180	if PcdCpuSmmStackGuard is true.
181	If ShadowStack is enabled, the shadow stack is allocated
182	after the normal Stack. The size is PcdCpuSmmShadowStackSize.
183	with 2 more pages if PcdCpuSmmStackGuard is true.
184	@param[in] GdtBase The base address of the GDT to use when an SMI is
185	processed by the CPU specified by CpuIndex.
186	@param[in] GdtSize The size, in bytes, of the GDT used when an SMI is
187	processed by the CPU specified by CpuIndex.
188	@param[in] IdtBase The base address of the IDT to use when an SMI is
189	processed by the CPU specified by CpuIndex.
190	@param[in] IdtSize The size, in bytes, of the IDT used when an SMI is
191	processed by the CPU specified by CpuIndex.
192	@param[in] Cr3 The base address of the page tables to use when an SMI
193	is processed by the CPU specified by CpuIndex.
194	**/
195	VOID
196	EFIAPI
197	SmmCpuFeaturesInstallSmiHandler (
198	IN UINTN CpuIndex,
199	IN UINT32 SmBase,
200	IN VOID *SmiStack,
201	IN UINTN StackSize,
202	IN UINTN GdtBase,
203	IN UINTN GdtSize,
204	IN UINTN IdtBase,
205	IN UINTN IdtSize,
206	IN UINT32 Cr3
207	);
208
209	/**
210	Determines if MTRR registers must be configured to set SMRAM cache-ability
211	when executing in System Management Mode.
212
213	@retval TRUE MTRR registers must be configured to set SMRAM cache-ability.
214	@retval FALSE MTRR registers do not need to be configured to set SMRAM
215	cache-ability.
216	**/
217	BOOLEAN
218	EFIAPI
219	SmmCpuFeaturesNeedConfigureMtrrs (
220	VOID
221	);
222
223	/**
224	Disable SMRR register if SMRR is supported and SmmCpuFeaturesNeedConfigureMtrrs()
225	returns TRUE.
226	**/
227	VOID
228	EFIAPI
229	SmmCpuFeaturesDisableSmrr (
230	VOID
231	);
232
233	/**
234	Enable SMRR register if SMRR is supported and SmmCpuFeaturesNeedConfigureMtrrs()
235	returns TRUE.
236	**/
237	VOID
238	EFIAPI
239	SmmCpuFeaturesReenableSmrr (
240	VOID
241	);
242
243	/**
244	Processor specific hook point each time a CPU enters System Management Mode.
245
246	@param[in] CpuIndex The index of the CPU that has entered SMM. The value
247	must be between 0 and the NumberOfCpus field in the
248	System Management System Table (SMST).
249	**/
250	VOID
251	EFIAPI
252	SmmCpuFeaturesRendezvousEntry (
253	IN UINTN CpuIndex
254	);
255
256	/**
257	Processor specific hook point each time a CPU exits System Management Mode.
258
259	@param[in] CpuIndex The index of the CPU that is exiting SMM. The value must
260	be between 0 and the NumberOfCpus field in the System
261	Management System Table (SMST).
262	**/
263	VOID
264	EFIAPI
265	SmmCpuFeaturesRendezvousExit (
266	IN UINTN CpuIndex
267	);
268
269	/**
270	Check to see if an SMM register is supported by a specified CPU.
271
272	@param[in] CpuIndex The index of the CPU to check for SMM register support.
273	The value must be between 0 and the NumberOfCpus field
274	in the System Management System Table (SMST).
275	@param[in] RegName Identifies the SMM register to check for support.
276
277	@retval TRUE The SMM register specified by RegName is supported by the CPU
278	specified by CpuIndex.
279	@retval FALSE The SMM register specified by RegName is not supported by the
280	CPU specified by CpuIndex.
281	**/
282	BOOLEAN
283	EFIAPI
284	SmmCpuFeaturesIsSmmRegisterSupported (
285	IN UINTN CpuIndex,
286	IN SMM_REG_NAME RegName
287	);
288
289	/**
290	Returns the current value of the SMM register for the specified CPU.
291	If the SMM register is not supported, then 0 is returned.
292
293	@param[in] CpuIndex The index of the CPU to read the SMM register. The
294	value must be between 0 and the NumberOfCpus field in
295	the System Management System Table (SMST).
296	@param[in] RegName Identifies the SMM register to read.
297
298	@return The value of the SMM register specified by RegName from the CPU
299	specified by CpuIndex.
300	**/
301	UINT64
302	EFIAPI
303	SmmCpuFeaturesGetSmmRegister (
304	IN UINTN CpuIndex,
305	IN SMM_REG_NAME RegName
306	);
307
308	/**
309	Sets the value of an SMM register on a specified CPU.
310	If the SMM register is not supported, then no action is performed.
311
312	@param[in] CpuIndex The index of the CPU to write the SMM register. The
313	value must be between 0 and the NumberOfCpus field in
314	the System Management System Table (SMST).
315	@param[in] RegName Identifies the SMM register to write.
316	registers are read-only.
317	@param[in] Value The value to write to the SMM register.
318	**/
319	VOID
320	EFIAPI
321	SmmCpuFeaturesSetSmmRegister (
322	IN UINTN CpuIndex,
323	IN SMM_REG_NAME RegName,
324	IN UINT64 Value
325	);
326
327	/**
328	Read an SMM Save State register on the target processor. If this function
329	returns EFI_UNSUPPORTED, then the caller is responsible for reading the
330	SMM Save Sate register.
331
332	@param[in] CpuIndex The index of the CPU to read the SMM Save State. The
333	value must be between 0 and the NumberOfCpus field in
334	the System Management System Table (SMST).
335	@param[in] Register The SMM Save State register to read.
336	@param[in] Width The number of bytes to read from the CPU save state.
337	@param[out] Buffer Upon return, this holds the CPU register value read
338	from the save state.
339
340	@retval EFI_SUCCESS The register was read from Save State.
341	@retval EFI_INVALID_PARAMETER Buffer is NULL.
342	@retval EFI_UNSUPPORTED This function does not support reading Register.
343
344	**/
345	EFI_STATUS
346	EFIAPI
347	SmmCpuFeaturesReadSaveStateRegister (
348	IN UINTN CpuIndex,
349	IN EFI_SMM_SAVE_STATE_REGISTER Register,
350	IN UINTN Width,
351	OUT VOID *Buffer
352	);
353
354	/**
355	Writes an SMM Save State register on the target processor. If this function
356	returns EFI_UNSUPPORTED, then the caller is responsible for writing the
357	SMM Save Sate register.
358
359	@param[in] CpuIndex The index of the CPU to write the SMM Save State. The
360	value must be between 0 and the NumberOfCpus field in
361	the System Management System Table (SMST).
362	@param[in] Register The SMM Save State register to write.
363	@param[in] Width The number of bytes to write to the CPU save state.
364	@param[in] Buffer Upon entry, this holds the new CPU register value.
365
366	@retval EFI_SUCCESS The register was written to Save State.
367	@retval EFI_INVALID_PARAMETER Buffer is NULL.
368	@retval EFI_UNSUPPORTED This function does not support writing Register.
369	**/
370	EFI_STATUS
371	EFIAPI
372	SmmCpuFeaturesWriteSaveStateRegister (
373	IN UINTN CpuIndex,
374	IN EFI_SMM_SAVE_STATE_REGISTER Register,
375	IN UINTN Width,
376	IN CONST VOID *Buffer
377	);
378
379	/**
380	This function is hook point called after the gEfiSmmReadyToLockProtocolGuid
381	notification is completely processed.
382	**/
383	VOID
384	EFIAPI
385	SmmCpuFeaturesCompleteSmmReadyToLock (
386	VOID
387	);
388
389	/**
390	This API provides a method for a CPU to allocate a specific region for storing page tables.
391
392	This API can be called more once to allocate memory for page tables.
393
394	Allocates the number of 4KB pages of type EfiRuntimeServicesData and returns a pointer to the
395	allocated buffer. The buffer returned is aligned on a 4KB boundary. If Pages is 0, then NULL
396	is returned. If there is not enough memory remaining to satisfy the request, then NULL is
397	returned.
398
399	This function can also return NULL if there is no preference on where the page tables are allocated in SMRAM.
400
401	@param Pages The number of 4 KB pages to allocate.
402
403	@return A pointer to the allocated buffer for page tables.
404	@retval NULL Fail to allocate a specific region for storing page tables,
405	Or there is no preference on where the page tables are allocated in SMRAM.
406
407	**/
408	VOID *
409	EFIAPI
410	SmmCpuFeaturesAllocatePageTableMemory (
411	IN UINTN Pages
412	);
413
414	#endif

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Devices/EFI/Firmware/UefiCpuPkg/Include/Library/SmmCpuFeaturesLib.h@ 85805

Download in other formats: