8c10d833e2aebe1f98e1745067d3ce67d28daa41
[mirror_edk2.git] / MdeModulePkg / Core / PiSmmCore / PiSmmCore.h
1 /** @file
2 The internal header file includes the common header files, defines
3 internal structure and functions used by SmmCore module.
4
5 Copyright (c) 2009 - 2017, Intel Corporation. All rights reserved.<BR>
6 This program and the accompanying materials are licensed and made available
7 under the terms and conditions of the BSD License which accompanies this
8 distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php
10
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13
14 **/
15
16 #ifndef _SMM_CORE_H_
17 #define _SMM_CORE_H_
18
19 #include <PiSmm.h>
20
21 #include <Protocol/DxeSmmReadyToLock.h>
22 #include <Protocol/SmmReadyToLock.h>
23 #include <Protocol/SmmEndOfDxe.h>
24 #include <Protocol/CpuIo2.h>
25 #include <Protocol/SmmCommunication.h>
26 #include <Protocol/SmmAccess2.h>
27 #include <Protocol/FirmwareVolume2.h>
28 #include <Protocol/LoadedImage.h>
29 #include <Protocol/DevicePath.h>
30 #include <Protocol/Security.h>
31 #include <Protocol/Security2.h>
32 #include <Protocol/SmmExitBootServices.h>
33 #include <Protocol/SmmLegacyBoot.h>
34 #include <Protocol/SmmReadyToBoot.h>
35 #include <Protocol/SmmMemoryAttribute.h>
36 #include <Protocol/SmmSxDispatch2.h>
37
38 #include <Guid/Apriori.h>
39 #include <Guid/EventGroup.h>
40 #include <Guid/EventLegacyBios.h>
41 #include <Guid/MemoryProfile.h>
42 #include <Guid/LoadModuleAtFixedAddress.h>
43 #include <Guid/SmiHandlerProfile.h>
44 #include <Guid/EndOfS3Resume.h>
45
46 #include <Library/BaseLib.h>
47 #include <Library/BaseMemoryLib.h>
48 #include <Library/PeCoffLib.h>
49 #include <Library/PeCoffGetEntryPointLib.h>
50 #include <Library/CacheMaintenanceLib.h>
51 #include <Library/DebugLib.h>
52 #include <Library/ReportStatusCodeLib.h>
53 #include <Library/MemoryAllocationLib.h>
54 #include <Library/DevicePathLib.h>
55 #include <Library/UefiLib.h>
56 #include <Library/UefiBootServicesTableLib.h>
57 #include <Library/PcdLib.h>
58 #include <Library/SmmCorePlatformHookLib.h>
59 #include <Library/PerformanceLib.h>
60 #include <Library/TimerLib.h>
61 #include <Library/HobLib.h>
62 #include <Library/SmmMemLib.h>
63
64 #include "PiSmmCorePrivateData.h"
65 #include "HeapGuard.h"
66
67 //
68 // Used to build a table of SMI Handlers that the SMM Core registers
69 //
70 typedef struct {
71 EFI_SMM_HANDLER_ENTRY_POINT2 Handler;
72 EFI_GUID *HandlerType;
73 EFI_HANDLE DispatchHandle;
74 BOOLEAN UnRegister;
75 } SMM_CORE_SMI_HANDLERS;
76
77 //
78 // SMM_HANDLER - used for each SMM handler
79 //
80
81 #define SMI_ENTRY_SIGNATURE SIGNATURE_32('s','m','i','e')
82
83 typedef struct {
84 UINTN Signature;
85 LIST_ENTRY AllEntries; // All entries
86
87 EFI_GUID HandlerType; // Type of interrupt
88 LIST_ENTRY SmiHandlers; // All handlers
89 } SMI_ENTRY;
90
91 #define SMI_HANDLER_SIGNATURE SIGNATURE_32('s','m','i','h')
92
93 typedef struct {
94 UINTN Signature;
95 LIST_ENTRY Link; // Link on SMI_ENTRY.SmiHandlers
96 EFI_SMM_HANDLER_ENTRY_POINT2 Handler; // The smm handler's entry point
97 UINTN CallerAddr; // The address of caller who register the SMI handler.
98 SMI_ENTRY *SmiEntry;
99 VOID *Context; // for profile
100 UINTN ContextSize; // for profile
101 } SMI_HANDLER;
102
103 //
104 // Structure for recording the state of an SMM Driver
105 //
106 #define EFI_SMM_DRIVER_ENTRY_SIGNATURE SIGNATURE_32('s', 'd','r','v')
107
108 typedef struct {
109 UINTN Signature;
110 LIST_ENTRY Link; // mDriverList
111
112 LIST_ENTRY ScheduledLink; // mScheduledQueue
113
114 EFI_HANDLE FvHandle;
115 EFI_GUID FileName;
116 EFI_DEVICE_PATH_PROTOCOL *FvFileDevicePath;
117 EFI_FIRMWARE_VOLUME2_PROTOCOL *Fv;
118
119 VOID *Depex;
120 UINTN DepexSize;
121
122 BOOLEAN Before;
123 BOOLEAN After;
124 EFI_GUID BeforeAfterGuid;
125
126 BOOLEAN Dependent;
127 BOOLEAN Scheduled;
128 BOOLEAN Initialized;
129 BOOLEAN DepexProtocolError;
130
131 EFI_HANDLE ImageHandle;
132 EFI_LOADED_IMAGE_PROTOCOL *LoadedImage;
133 //
134 // Image EntryPoint in SMRAM
135 //
136 PHYSICAL_ADDRESS ImageEntryPoint;
137 //
138 // Image Buffer in SMRAM
139 //
140 PHYSICAL_ADDRESS ImageBuffer;
141 //
142 // Image Page Number
143 //
144 UINTN NumberOfPage;
145 EFI_HANDLE SmmImageHandle;
146 EFI_LOADED_IMAGE_PROTOCOL SmmLoadedImage;
147 } EFI_SMM_DRIVER_ENTRY;
148
149 #define EFI_HANDLE_SIGNATURE SIGNATURE_32('h','n','d','l')
150
151 ///
152 /// IHANDLE - contains a list of protocol handles
153 ///
154 typedef struct {
155 UINTN Signature;
156 /// All handles list of IHANDLE
157 LIST_ENTRY AllHandles;
158 /// List of PROTOCOL_INTERFACE's for this handle
159 LIST_ENTRY Protocols;
160 UINTN LocateRequest;
161 } IHANDLE;
162
163 #define ASSERT_IS_HANDLE(a) ASSERT((a)->Signature == EFI_HANDLE_SIGNATURE)
164
165 #define PROTOCOL_ENTRY_SIGNATURE SIGNATURE_32('p','r','t','e')
166
167 ///
168 /// PROTOCOL_ENTRY - each different protocol has 1 entry in the protocol
169 /// database. Each handler that supports this protocol is listed, along
170 /// with a list of registered notifies.
171 ///
172 typedef struct {
173 UINTN Signature;
174 /// Link Entry inserted to mProtocolDatabase
175 LIST_ENTRY AllEntries;
176 /// ID of the protocol
177 EFI_GUID ProtocolID;
178 /// All protocol interfaces
179 LIST_ENTRY Protocols;
180 /// Registerd notification handlers
181 LIST_ENTRY Notify;
182 } PROTOCOL_ENTRY;
183
184 #define PROTOCOL_INTERFACE_SIGNATURE SIGNATURE_32('p','i','f','c')
185
186 ///
187 /// PROTOCOL_INTERFACE - each protocol installed on a handle is tracked
188 /// with a protocol interface structure
189 ///
190 typedef struct {
191 UINTN Signature;
192 /// Link on IHANDLE.Protocols
193 LIST_ENTRY Link;
194 /// Back pointer
195 IHANDLE *Handle;
196 /// Link on PROTOCOL_ENTRY.Protocols
197 LIST_ENTRY ByProtocol;
198 /// The protocol ID
199 PROTOCOL_ENTRY *Protocol;
200 /// The interface value
201 VOID *Interface;
202 } PROTOCOL_INTERFACE;
203
204 #define PROTOCOL_NOTIFY_SIGNATURE SIGNATURE_32('p','r','t','n')
205
206 ///
207 /// PROTOCOL_NOTIFY - used for each register notification for a protocol
208 ///
209 typedef struct {
210 UINTN Signature;
211 PROTOCOL_ENTRY *Protocol;
212 /// All notifications for this protocol
213 LIST_ENTRY Link;
214 /// Notification function
215 EFI_SMM_NOTIFY_FN Function;
216 /// Last position notified
217 LIST_ENTRY *Position;
218 } PROTOCOL_NOTIFY;
219
220 //
221 // SMM Core Global Variables
222 //
223 extern SMM_CORE_PRIVATE_DATA *gSmmCorePrivate;
224 extern EFI_SMM_SYSTEM_TABLE2 gSmmCoreSmst;
225 extern LIST_ENTRY gHandleList;
226 extern EFI_PHYSICAL_ADDRESS gLoadModuleAtFixAddressSmramBase;
227
228 /**
229 Called to initialize the memory service.
230
231 @param SmramRangeCount Number of SMRAM Regions
232 @param SmramRanges Pointer to SMRAM Descriptors
233
234 **/
235 VOID
236 SmmInitializeMemoryServices (
237 IN UINTN SmramRangeCount,
238 IN EFI_SMRAM_DESCRIPTOR *SmramRanges
239 );
240
241 /**
242 The SmmInstallConfigurationTable() function is used to maintain the list
243 of configuration tables that are stored in the System Management System
244 Table. The list is stored as an array of (GUID, Pointer) pairs. The list
245 must be allocated from pool memory with PoolType set to EfiRuntimeServicesData.
246
247 @param SystemTable A pointer to the SMM System Table (SMST).
248 @param Guid A pointer to the GUID for the entry to add, update, or remove.
249 @param Table A pointer to the buffer of the table to add.
250 @param TableSize The size of the table to install.
251
252 @retval EFI_SUCCESS The (Guid, Table) pair was added, updated, or removed.
253 @retval EFI_INVALID_PARAMETER Guid is not valid.
254 @retval EFI_NOT_FOUND An attempt was made to delete a non-existent entry.
255 @retval EFI_OUT_OF_RESOURCES There is not enough memory available to complete the operation.
256
257 **/
258 EFI_STATUS
259 EFIAPI
260 SmmInstallConfigurationTable (
261 IN CONST EFI_SMM_SYSTEM_TABLE2 *SystemTable,
262 IN CONST EFI_GUID *Guid,
263 IN VOID *Table,
264 IN UINTN TableSize
265 );
266
267 /**
268 Wrapper function to SmmInstallProtocolInterfaceNotify. This is the public API which
269 Calls the private one which contains a BOOLEAN parameter for notifications
270
271 @param UserHandle The handle to install the protocol handler on,
272 or NULL if a new handle is to be allocated
273 @param Protocol The protocol to add to the handle
274 @param InterfaceType Indicates whether Interface is supplied in
275 native form.
276 @param Interface The interface for the protocol being added
277
278 @return Status code
279
280 **/
281 EFI_STATUS
282 EFIAPI
283 SmmInstallProtocolInterface (
284 IN OUT EFI_HANDLE *UserHandle,
285 IN EFI_GUID *Protocol,
286 IN EFI_INTERFACE_TYPE InterfaceType,
287 IN VOID *Interface
288 );
289
290 /**
291 Allocates pages from the memory map.
292
293 @param Type The type of allocation to perform
294 @param MemoryType The type of memory to turn the allocated pages
295 into
296 @param NumberOfPages The number of pages to allocate
297 @param Memory A pointer to receive the base allocated memory
298 address
299
300 @retval EFI_INVALID_PARAMETER Parameters violate checking rules defined in spec.
301 @retval EFI_NOT_FOUND Could not allocate pages match the requirement.
302 @retval EFI_OUT_OF_RESOURCES No enough pages to allocate.
303 @retval EFI_SUCCESS Pages successfully allocated.
304
305 **/
306 EFI_STATUS
307 EFIAPI
308 SmmAllocatePages (
309 IN EFI_ALLOCATE_TYPE Type,
310 IN EFI_MEMORY_TYPE MemoryType,
311 IN UINTN NumberOfPages,
312 OUT EFI_PHYSICAL_ADDRESS *Memory
313 );
314
315 /**
316 Allocates pages from the memory map.
317
318 @param Type The type of allocation to perform
319 @param MemoryType The type of memory to turn the allocated pages
320 into
321 @param NumberOfPages The number of pages to allocate
322 @param Memory A pointer to receive the base allocated memory
323 address
324 @param NeedGuard Flag to indicate Guard page is needed or not
325
326 @retval EFI_INVALID_PARAMETER Parameters violate checking rules defined in spec.
327 @retval EFI_NOT_FOUND Could not allocate pages match the requirement.
328 @retval EFI_OUT_OF_RESOURCES No enough pages to allocate.
329 @retval EFI_SUCCESS Pages successfully allocated.
330
331 **/
332 EFI_STATUS
333 EFIAPI
334 SmmInternalAllocatePages (
335 IN EFI_ALLOCATE_TYPE Type,
336 IN EFI_MEMORY_TYPE MemoryType,
337 IN UINTN NumberOfPages,
338 OUT EFI_PHYSICAL_ADDRESS *Memory,
339 IN BOOLEAN NeedGuard
340 );
341
342 /**
343 Frees previous allocated pages.
344
345 @param Memory Base address of memory being freed
346 @param NumberOfPages The number of pages to free
347
348 @retval EFI_NOT_FOUND Could not find the entry that covers the range
349 @retval EFI_INVALID_PARAMETER Address not aligned, Address is zero or NumberOfPages is zero.
350 @return EFI_SUCCESS Pages successfully freed.
351
352 **/
353 EFI_STATUS
354 EFIAPI
355 SmmFreePages (
356 IN EFI_PHYSICAL_ADDRESS Memory,
357 IN UINTN NumberOfPages
358 );
359
360 /**
361 Frees previous allocated pages.
362
363 @param Memory Base address of memory being freed
364 @param NumberOfPages The number of pages to free
365 @param IsGuarded Flag to indicate if the memory is guarded
366 or not
367
368 @retval EFI_NOT_FOUND Could not find the entry that covers the range
369 @retval EFI_INVALID_PARAMETER Address not aligned, Address is zero or NumberOfPages is zero.
370 @return EFI_SUCCESS Pages successfully freed.
371
372 **/
373 EFI_STATUS
374 EFIAPI
375 SmmInternalFreePages (
376 IN EFI_PHYSICAL_ADDRESS Memory,
377 IN UINTN NumberOfPages,
378 IN BOOLEAN IsGuarded
379 );
380
381 /**
382 Allocate pool of a particular type.
383
384 @param PoolType Type of pool to allocate
385 @param Size The amount of pool to allocate
386 @param Buffer The address to return a pointer to the allocated
387 pool
388
389 @retval EFI_INVALID_PARAMETER PoolType not valid
390 @retval EFI_OUT_OF_RESOURCES Size exceeds max pool size or allocation failed.
391 @retval EFI_SUCCESS Pool successfully allocated.
392
393 **/
394 EFI_STATUS
395 EFIAPI
396 SmmAllocatePool (
397 IN EFI_MEMORY_TYPE PoolType,
398 IN UINTN Size,
399 OUT VOID **Buffer
400 );
401
402 /**
403 Allocate pool of a particular type.
404
405 @param PoolType Type of pool to allocate
406 @param Size The amount of pool to allocate
407 @param Buffer The address to return a pointer to the allocated
408 pool
409
410 @retval EFI_INVALID_PARAMETER PoolType not valid
411 @retval EFI_OUT_OF_RESOURCES Size exceeds max pool size or allocation failed.
412 @retval EFI_SUCCESS Pool successfully allocated.
413
414 **/
415 EFI_STATUS
416 EFIAPI
417 SmmInternalAllocatePool (
418 IN EFI_MEMORY_TYPE PoolType,
419 IN UINTN Size,
420 OUT VOID **Buffer
421 );
422
423 /**
424 Frees pool.
425
426 @param Buffer The allocated pool entry to free
427
428 @retval EFI_INVALID_PARAMETER Buffer is not a valid value.
429 @retval EFI_SUCCESS Pool successfully freed.
430
431 **/
432 EFI_STATUS
433 EFIAPI
434 SmmFreePool (
435 IN VOID *Buffer
436 );
437
438 /**
439 Frees pool.
440
441 @param Buffer The allocated pool entry to free
442
443 @retval EFI_INVALID_PARAMETER Buffer is not a valid value.
444 @retval EFI_SUCCESS Pool successfully freed.
445
446 **/
447 EFI_STATUS
448 EFIAPI
449 SmmInternalFreePool (
450 IN VOID *Buffer
451 );
452
453 /**
454 Installs a protocol interface into the boot services environment.
455
456 @param UserHandle The handle to install the protocol handler on,
457 or NULL if a new handle is to be allocated
458 @param Protocol The protocol to add to the handle
459 @param InterfaceType Indicates whether Interface is supplied in
460 native form.
461 @param Interface The interface for the protocol being added
462 @param Notify indicates whether notify the notification list
463 for this protocol
464
465 @retval EFI_INVALID_PARAMETER Invalid parameter
466 @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
467 @retval EFI_SUCCESS Protocol interface successfully installed
468
469 **/
470 EFI_STATUS
471 SmmInstallProtocolInterfaceNotify (
472 IN OUT EFI_HANDLE *UserHandle,
473 IN EFI_GUID *Protocol,
474 IN EFI_INTERFACE_TYPE InterfaceType,
475 IN VOID *Interface,
476 IN BOOLEAN Notify
477 );
478
479 /**
480 Uninstalls all instances of a protocol:interfacer from a handle.
481 If the last protocol interface is remove from the handle, the
482 handle is freed.
483
484 @param UserHandle The handle to remove the protocol handler from
485 @param Protocol The protocol, of protocol:interface, to remove
486 @param Interface The interface, of protocol:interface, to remove
487
488 @retval EFI_INVALID_PARAMETER Protocol is NULL.
489 @retval EFI_SUCCESS Protocol interface successfully uninstalled.
490
491 **/
492 EFI_STATUS
493 EFIAPI
494 SmmUninstallProtocolInterface (
495 IN EFI_HANDLE UserHandle,
496 IN EFI_GUID *Protocol,
497 IN VOID *Interface
498 );
499
500 /**
501 Queries a handle to determine if it supports a specified protocol.
502
503 @param UserHandle The handle being queried.
504 @param Protocol The published unique identifier of the protocol.
505 @param Interface Supplies the address where a pointer to the
506 corresponding Protocol Interface is returned.
507
508 @return The requested protocol interface for the handle
509
510 **/
511 EFI_STATUS
512 EFIAPI
513 SmmHandleProtocol (
514 IN EFI_HANDLE UserHandle,
515 IN EFI_GUID *Protocol,
516 OUT VOID **Interface
517 );
518
519 /**
520 Add a new protocol notification record for the request protocol.
521
522 @param Protocol The requested protocol to add the notify
523 registration
524 @param Function Points to the notification function
525 @param Registration Returns the registration record
526
527 @retval EFI_INVALID_PARAMETER Invalid parameter
528 @retval EFI_SUCCESS Successfully returned the registration record
529 that has been added
530
531 **/
532 EFI_STATUS
533 EFIAPI
534 SmmRegisterProtocolNotify (
535 IN CONST EFI_GUID *Protocol,
536 IN EFI_SMM_NOTIFY_FN Function,
537 OUT VOID **Registration
538 );
539
540 /**
541 Locates the requested handle(s) and returns them in Buffer.
542
543 @param SearchType The type of search to perform to locate the
544 handles
545 @param Protocol The protocol to search for
546 @param SearchKey Dependant on SearchType
547 @param BufferSize On input the size of Buffer. On output the
548 size of data returned.
549 @param Buffer The buffer to return the results in
550
551 @retval EFI_BUFFER_TOO_SMALL Buffer too small, required buffer size is
552 returned in BufferSize.
553 @retval EFI_INVALID_PARAMETER Invalid parameter
554 @retval EFI_SUCCESS Successfully found the requested handle(s) and
555 returns them in Buffer.
556
557 **/
558 EFI_STATUS
559 EFIAPI
560 SmmLocateHandle (
561 IN EFI_LOCATE_SEARCH_TYPE SearchType,
562 IN EFI_GUID *Protocol OPTIONAL,
563 IN VOID *SearchKey OPTIONAL,
564 IN OUT UINTN *BufferSize,
565 OUT EFI_HANDLE *Buffer
566 );
567
568 /**
569 Return the first Protocol Interface that matches the Protocol GUID. If
570 Registration is pasased in return a Protocol Instance that was just add
571 to the system. If Retistration is NULL return the first Protocol Interface
572 you find.
573
574 @param Protocol The protocol to search for
575 @param Registration Optional Registration Key returned from
576 RegisterProtocolNotify()
577 @param Interface Return the Protocol interface (instance).
578
579 @retval EFI_SUCCESS If a valid Interface is returned
580 @retval EFI_INVALID_PARAMETER Invalid parameter
581 @retval EFI_NOT_FOUND Protocol interface not found
582
583 **/
584 EFI_STATUS
585 EFIAPI
586 SmmLocateProtocol (
587 IN EFI_GUID *Protocol,
588 IN VOID *Registration OPTIONAL,
589 OUT VOID **Interface
590 );
591
592 /**
593 Function returns an array of handles that support the requested protocol
594 in a buffer allocated from pool. This is a version of SmmLocateHandle()
595 that allocates a buffer for the caller.
596
597 @param SearchType Specifies which handle(s) are to be returned.
598 @param Protocol Provides the protocol to search by. This
599 parameter is only valid for SearchType
600 ByProtocol.
601 @param SearchKey Supplies the search key depending on the
602 SearchType.
603 @param NumberHandles The number of handles returned in Buffer.
604 @param Buffer A pointer to the buffer to return the requested
605 array of handles that support Protocol.
606
607 @retval EFI_SUCCESS The result array of handles was returned.
608 @retval EFI_NOT_FOUND No handles match the search.
609 @retval EFI_OUT_OF_RESOURCES There is not enough pool memory to store the
610 matching results.
611 @retval EFI_INVALID_PARAMETER One or more paramters are not valid.
612
613 **/
614 EFI_STATUS
615 EFIAPI
616 SmmLocateHandleBuffer (
617 IN EFI_LOCATE_SEARCH_TYPE SearchType,
618 IN EFI_GUID *Protocol OPTIONAL,
619 IN VOID *SearchKey OPTIONAL,
620 IN OUT UINTN *NumberHandles,
621 OUT EFI_HANDLE **Buffer
622 );
623
624 /**
625 Manage SMI of a particular type.
626
627 @param HandlerType Points to the handler type or NULL for root SMI handlers.
628 @param Context Points to an optional context buffer.
629 @param CommBuffer Points to the optional communication buffer.
630 @param CommBufferSize Points to the size of the optional communication buffer.
631
632 @retval EFI_SUCCESS Interrupt source was processed successfully but not quiesced.
633 @retval EFI_INTERRUPT_PENDING One or more SMI sources could not be quiesced.
634 @retval EFI_WARN_INTERRUPT_SOURCE_PENDING Interrupt source was not handled or quiesced.
635 @retval EFI_WARN_INTERRUPT_SOURCE_QUIESCED Interrupt source was handled and quiesced.
636
637 **/
638 EFI_STATUS
639 EFIAPI
640 SmiManage (
641 IN CONST EFI_GUID *HandlerType,
642 IN CONST VOID *Context OPTIONAL,
643 IN OUT VOID *CommBuffer OPTIONAL,
644 IN OUT UINTN *CommBufferSize OPTIONAL
645 );
646
647 /**
648 Registers a handler to execute within SMM.
649
650 @param Handler Handler service funtion pointer.
651 @param HandlerType Points to the handler type or NULL for root SMI handlers.
652 @param DispatchHandle On return, contains a unique handle which can be used to later unregister the handler function.
653
654 @retval EFI_SUCCESS Handler register success.
655 @retval EFI_INVALID_PARAMETER Handler or DispatchHandle is NULL.
656
657 **/
658 EFI_STATUS
659 EFIAPI
660 SmiHandlerRegister (
661 IN EFI_SMM_HANDLER_ENTRY_POINT2 Handler,
662 IN CONST EFI_GUID *HandlerType OPTIONAL,
663 OUT EFI_HANDLE *DispatchHandle
664 );
665
666 /**
667 Unregister a handler in SMM.
668
669 @param DispatchHandle The handle that was specified when the handler was registered.
670
671 @retval EFI_SUCCESS Handler function was successfully unregistered.
672 @retval EFI_INVALID_PARAMETER DispatchHandle does not refer to a valid handle.
673
674 **/
675 EFI_STATUS
676 EFIAPI
677 SmiHandlerUnRegister (
678 IN EFI_HANDLE DispatchHandle
679 );
680
681 /**
682 This function is the main entry point for an SMM handler dispatch
683 or communicate-based callback.
684
685 @param DispatchHandle The unique handle assigned to this handler by SmiHandlerRegister().
686 @param Context Points to an optional handler context which was specified when the handler was registered.
687 @param CommBuffer A pointer to a collection of data in memory that will
688 be conveyed from a non-SMM environment into an SMM environment.
689 @param CommBufferSize The size of the CommBuffer.
690
691 @return Status Code
692
693 **/
694 EFI_STATUS
695 EFIAPI
696 SmmDriverDispatchHandler (
697 IN EFI_HANDLE DispatchHandle,
698 IN CONST VOID *Context, OPTIONAL
699 IN OUT VOID *CommBuffer, OPTIONAL
700 IN OUT UINTN *CommBufferSize OPTIONAL
701 );
702
703 /**
704 This function is the main entry point for an SMM handler dispatch
705 or communicate-based callback.
706
707 @param DispatchHandle The unique handle assigned to this handler by SmiHandlerRegister().
708 @param Context Points to an optional handler context which was specified when the handler was registered.
709 @param CommBuffer A pointer to a collection of data in memory that will
710 be conveyed from a non-SMM environment into an SMM environment.
711 @param CommBufferSize The size of the CommBuffer.
712
713 @return Status Code
714
715 **/
716 EFI_STATUS
717 EFIAPI
718 SmmLegacyBootHandler (
719 IN EFI_HANDLE DispatchHandle,
720 IN CONST VOID *Context, OPTIONAL
721 IN OUT VOID *CommBuffer, OPTIONAL
722 IN OUT UINTN *CommBufferSize OPTIONAL
723 );
724
725 /**
726 This function is the main entry point for an SMM handler dispatch
727 or communicate-based callback.
728
729 @param DispatchHandle The unique handle assigned to this handler by SmiHandlerRegister().
730 @param Context Points to an optional handler context which was specified when the handler was registered.
731 @param CommBuffer A pointer to a collection of data in memory that will
732 be conveyed from a non-SMM environment into an SMM environment.
733 @param CommBufferSize The size of the CommBuffer.
734
735 @return Status Code
736
737 **/
738 EFI_STATUS
739 EFIAPI
740 SmmReadyToLockHandler (
741 IN EFI_HANDLE DispatchHandle,
742 IN CONST VOID *Context, OPTIONAL
743 IN OUT VOID *CommBuffer, OPTIONAL
744 IN OUT UINTN *CommBufferSize OPTIONAL
745 );
746
747 /**
748 This function is the main entry point for an SMM handler dispatch
749 or communicate-based callback.
750
751 @param DispatchHandle The unique handle assigned to this handler by SmiHandlerRegister().
752 @param Context Points to an optional handler context which was specified when the handler was registered.
753 @param CommBuffer A pointer to a collection of data in memory that will
754 be conveyed from a non-SMM environment into an SMM environment.
755 @param CommBufferSize The size of the CommBuffer.
756
757 @return Status Code
758
759 **/
760 EFI_STATUS
761 EFIAPI
762 SmmEndOfDxeHandler (
763 IN EFI_HANDLE DispatchHandle,
764 IN CONST VOID *Context, OPTIONAL
765 IN OUT VOID *CommBuffer, OPTIONAL
766 IN OUT UINTN *CommBufferSize OPTIONAL
767 );
768
769 /**
770 This function is the main entry point for an SMM handler dispatch
771 or communicate-based callback.
772
773 @param DispatchHandle The unique handle assigned to this handler by SmiHandlerRegister().
774 @param Context Points to an optional handler context which was specified when the handler was registered.
775 @param CommBuffer A pointer to a collection of data in memory that will
776 be conveyed from a non-SMM environment into an SMM environment.
777 @param CommBufferSize The size of the CommBuffer.
778
779 @return Status Code
780
781 **/
782 EFI_STATUS
783 EFIAPI
784 SmmExitBootServicesHandler (
785 IN EFI_HANDLE DispatchHandle,
786 IN CONST VOID *Context, OPTIONAL
787 IN OUT VOID *CommBuffer, OPTIONAL
788 IN OUT UINTN *CommBufferSize OPTIONAL
789 );
790
791 /**
792 This function is the main entry point for an SMM handler dispatch
793 or communicate-based callback.
794
795 @param DispatchHandle The unique handle assigned to this handler by SmiHandlerRegister().
796 @param Context Points to an optional handler context which was specified when the handler was registered.
797 @param CommBuffer A pointer to a collection of data in memory that will
798 be conveyed from a non-SMM environment into an SMM environment.
799 @param CommBufferSize The size of the CommBuffer.
800
801 @return Status Code
802
803 **/
804 EFI_STATUS
805 EFIAPI
806 SmmReadyToBootHandler (
807 IN EFI_HANDLE DispatchHandle,
808 IN CONST VOID *Context, OPTIONAL
809 IN OUT VOID *CommBuffer, OPTIONAL
810 IN OUT UINTN *CommBufferSize OPTIONAL
811 );
812
813 /**
814 Software SMI handler that is called when the EndOfS3Resume event is trigged.
815 This function installs the SMM EndOfS3Resume Protocol so SMM Drivers are informed that
816 S3 resume has finished.
817
818 @param DispatchHandle The unique handle assigned to this handler by SmiHandlerRegister().
819 @param Context Points to an optional handler context which was specified when the handler was registered.
820 @param CommBuffer A pointer to a collection of data in memory that will
821 be conveyed from a non-SMM environment into an SMM environment.
822 @param CommBufferSize The size of the CommBuffer.
823
824 @return Status Code
825
826 **/
827 EFI_STATUS
828 EFIAPI
829 SmmEndOfS3ResumeHandler (
830 IN EFI_HANDLE DispatchHandle,
831 IN CONST VOID *Context, OPTIONAL
832 IN OUT VOID *CommBuffer, OPTIONAL
833 IN OUT UINTN *CommBufferSize OPTIONAL
834 );
835
836 /**
837 Place holder function until all the SMM System Table Service are available.
838
839 @param Arg1 Undefined
840 @param Arg2 Undefined
841 @param Arg3 Undefined
842 @param Arg4 Undefined
843 @param Arg5 Undefined
844
845 @return EFI_NOT_AVAILABLE_YET
846
847 **/
848 EFI_STATUS
849 EFIAPI
850 SmmEfiNotAvailableYetArg5 (
851 UINTN Arg1,
852 UINTN Arg2,
853 UINTN Arg3,
854 UINTN Arg4,
855 UINTN Arg5
856 );
857
858 //
859 //Functions used during debug buils
860 //
861
862 /**
863 Traverse the discovered list for any drivers that were discovered but not loaded
864 because the dependency experessions evaluated to false.
865
866 **/
867 VOID
868 SmmDisplayDiscoveredNotDispatched (
869 VOID
870 );
871
872 /**
873 Add free SMRAM region for use by memory service.
874
875 @param MemBase Base address of memory region.
876 @param MemLength Length of the memory region.
877 @param Type Memory type.
878 @param Attributes Memory region state.
879
880 **/
881 VOID
882 SmmAddMemoryRegion (
883 IN EFI_PHYSICAL_ADDRESS MemBase,
884 IN UINT64 MemLength,
885 IN EFI_MEMORY_TYPE Type,
886 IN UINT64 Attributes
887 );
888
889 /**
890 Finds the protocol entry for the requested protocol.
891
892 @param Protocol The ID of the protocol
893 @param Create Create a new entry if not found
894
895 @return Protocol entry
896
897 **/
898 PROTOCOL_ENTRY *
899 SmmFindProtocolEntry (
900 IN EFI_GUID *Protocol,
901 IN BOOLEAN Create
902 );
903
904 /**
905 Signal event for every protocol in protocol entry.
906
907 @param Prot Protocol interface
908
909 **/
910 VOID
911 SmmNotifyProtocol (
912 IN PROTOCOL_INTERFACE *Prot
913 );
914
915 /**
916 Finds the protocol instance for the requested handle and protocol.
917 Note: This function doesn't do parameters checking, it's caller's responsibility
918 to pass in valid parameters.
919
920 @param Handle The handle to search the protocol on
921 @param Protocol GUID of the protocol
922 @param Interface The interface for the protocol being searched
923
924 @return Protocol instance (NULL: Not found)
925
926 **/
927 PROTOCOL_INTERFACE *
928 SmmFindProtocolInterface (
929 IN IHANDLE *Handle,
930 IN EFI_GUID *Protocol,
931 IN VOID *Interface
932 );
933
934 /**
935 Removes Protocol from the protocol list (but not the handle list).
936
937 @param Handle The handle to remove protocol on.
938 @param Protocol GUID of the protocol to be moved
939 @param Interface The interface of the protocol
940
941 @return Protocol Entry
942
943 **/
944 PROTOCOL_INTERFACE *
945 SmmRemoveInterfaceFromProtocol (
946 IN IHANDLE *Handle,
947 IN EFI_GUID *Protocol,
948 IN VOID *Interface
949 );
950
951 /**
952 This is the POSTFIX version of the dependency evaluator. This code does
953 not need to handle Before or After, as it is not valid to call this
954 routine in this case. POSTFIX means all the math is done on top of the stack.
955
956 @param DriverEntry DriverEntry element to update.
957
958 @retval TRUE If driver is ready to run.
959 @retval FALSE If driver is not ready to run or some fatal error
960 was found.
961
962 **/
963 BOOLEAN
964 SmmIsSchedulable (
965 IN EFI_SMM_DRIVER_ENTRY *DriverEntry
966 );
967
968 //
969 // SmramProfile
970 //
971
972 /**
973 Initialize SMRAM profile.
974
975 **/
976 VOID
977 SmramProfileInit (
978 VOID
979 );
980
981 /**
982 Install SMRAM profile protocol.
983
984 **/
985 VOID
986 SmramProfileInstallProtocol (
987 VOID
988 );
989
990 /**
991 Register SMM image to SMRAM profile.
992
993 @param DriverEntry SMM image info.
994 @param RegisterToDxe Register image to DXE.
995
996 @return EFI_SUCCESS Register successfully.
997 @return EFI_UNSUPPORTED Memory profile unsupported,
998 or memory profile for the image is not required.
999 @return EFI_OUT_OF_RESOURCES No enough resource for this register.
1000
1001 **/
1002 EFI_STATUS
1003 RegisterSmramProfileImage (
1004 IN EFI_SMM_DRIVER_ENTRY *DriverEntry,
1005 IN BOOLEAN RegisterToDxe
1006 );
1007
1008 /**
1009 Unregister image from SMRAM profile.
1010
1011 @param DriverEntry SMM image info.
1012 @param UnregisterToDxe Unregister image from DXE.
1013
1014 @return EFI_SUCCESS Unregister successfully.
1015 @return EFI_UNSUPPORTED Memory profile unsupported,
1016 or memory profile for the image is not required.
1017 @return EFI_NOT_FOUND The image is not found.
1018
1019 **/
1020 EFI_STATUS
1021 UnregisterSmramProfileImage (
1022 IN EFI_SMM_DRIVER_ENTRY *DriverEntry,
1023 IN BOOLEAN UnregisterToDxe
1024 );
1025
1026 /**
1027 Update SMRAM profile information.
1028
1029 @param CallerAddress Address of caller who call Allocate or Free.
1030 @param Action This Allocate or Free action.
1031 @param MemoryType Memory type.
1032 EfiMaxMemoryType means the MemoryType is unknown.
1033 @param Size Buffer size.
1034 @param Buffer Buffer address.
1035 @param ActionString String for memory profile action.
1036 Only needed for user defined allocate action.
1037
1038 @return EFI_SUCCESS Memory profile is updated.
1039 @return EFI_UNSUPPORTED Memory profile is unsupported,
1040 or memory profile for the image is not required,
1041 or memory profile for the memory type is not required.
1042 @return EFI_ACCESS_DENIED It is during memory profile data getting.
1043 @return EFI_ABORTED Memory profile recording is not enabled.
1044 @return EFI_OUT_OF_RESOURCES No enough resource to update memory profile for allocate action.
1045 @return EFI_NOT_FOUND No matched allocate info found for free action.
1046
1047 **/
1048 EFI_STATUS
1049 EFIAPI
1050 SmmCoreUpdateProfile (
1051 IN PHYSICAL_ADDRESS CallerAddress,
1052 IN MEMORY_PROFILE_ACTION Action,
1053 IN EFI_MEMORY_TYPE MemoryType, // Valid for AllocatePages/AllocatePool
1054 IN UINTN Size, // Valid for AllocatePages/FreePages/AllocatePool
1055 IN VOID *Buffer,
1056 IN CHAR8 *ActionString OPTIONAL
1057 );
1058
1059 /**
1060 Register SMRAM profile handler.
1061
1062 **/
1063 VOID
1064 RegisterSmramProfileHandler (
1065 VOID
1066 );
1067
1068 /**
1069 SMRAM profile ready to lock callback function.
1070
1071 **/
1072 VOID
1073 SmramProfileReadyToLock (
1074 VOID
1075 );
1076
1077 /**
1078 Initialize MemoryAttributes support.
1079 **/
1080 VOID
1081 EFIAPI
1082 SmmCoreInitializeMemoryAttributesTable (
1083 VOID
1084 );
1085
1086 /**
1087 This function returns a copy of the current memory map. The map is an array of
1088 memory descriptors, each of which describes a contiguous block of memory.
1089
1090 @param[in, out] MemoryMapSize A pointer to the size, in bytes, of the
1091 MemoryMap buffer. On input, this is the size of
1092 the buffer allocated by the caller. On output,
1093 it is the size of the buffer returned by the
1094 firmware if the buffer was large enough, or the
1095 size of the buffer needed to contain the map if
1096 the buffer was too small.
1097 @param[in, out] MemoryMap A pointer to the buffer in which firmware places
1098 the current memory map.
1099 @param[out] MapKey A pointer to the location in which firmware
1100 returns the key for the current memory map.
1101 @param[out] DescriptorSize A pointer to the location in which firmware
1102 returns the size, in bytes, of an individual
1103 EFI_MEMORY_DESCRIPTOR.
1104 @param[out] DescriptorVersion A pointer to the location in which firmware
1105 returns the version number associated with the
1106 EFI_MEMORY_DESCRIPTOR.
1107
1108 @retval EFI_SUCCESS The memory map was returned in the MemoryMap
1109 buffer.
1110 @retval EFI_BUFFER_TOO_SMALL The MemoryMap buffer was too small. The current
1111 buffer size needed to hold the memory map is
1112 returned in MemoryMapSize.
1113 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
1114
1115 **/
1116 EFI_STATUS
1117 EFIAPI
1118 SmmCoreGetMemoryMap (
1119 IN OUT UINTN *MemoryMapSize,
1120 IN OUT EFI_MEMORY_DESCRIPTOR *MemoryMap,
1121 OUT UINTN *MapKey,
1122 OUT UINTN *DescriptorSize,
1123 OUT UINT32 *DescriptorVersion
1124 );
1125
1126 /**
1127 Initialize SmiHandler profile feature.
1128 **/
1129 VOID
1130 SmmCoreInitializeSmiHandlerProfile (
1131 VOID
1132 );
1133
1134 /**
1135 This function is called by SmmChildDispatcher module to report
1136 a new SMI handler is registered, to SmmCore.
1137
1138 @param This The protocol instance
1139 @param HandlerGuid The GUID to identify the type of the handler.
1140 For the SmmChildDispatch protocol, the HandlerGuid
1141 must be the GUID of SmmChildDispatch protocol.
1142 @param Handler The SMI handler.
1143 @param CallerAddress The address of the module who registers the SMI handler.
1144 @param Context The context of the SMI handler.
1145 For the SmmChildDispatch protocol, the Context
1146 must match the one defined for SmmChildDispatch protocol.
1147 @param ContextSize The size of the context in bytes.
1148 For the SmmChildDispatch protocol, the Context
1149 must match the one defined for SmmChildDispatch protocol.
1150
1151 @retval EFI_SUCCESS The information is recorded.
1152 @retval EFI_OUT_OF_RESOURCES There is no enough resource to record the information.
1153 **/
1154 EFI_STATUS
1155 EFIAPI
1156 SmiHandlerProfileRegisterHandler (
1157 IN SMI_HANDLER_PROFILE_PROTOCOL *This,
1158 IN EFI_GUID *HandlerGuid,
1159 IN EFI_SMM_HANDLER_ENTRY_POINT2 Handler,
1160 IN PHYSICAL_ADDRESS CallerAddress,
1161 IN VOID *Context, OPTIONAL
1162 IN UINTN ContextSize OPTIONAL
1163 );
1164
1165 /**
1166 This function is called by SmmChildDispatcher module to report
1167 an existing SMI handler is unregistered, to SmmCore.
1168
1169 @param This The protocol instance
1170 @param HandlerGuid The GUID to identify the type of the handler.
1171 For the SmmChildDispatch protocol, the HandlerGuid
1172 must be the GUID of SmmChildDispatch protocol.
1173 @param Handler The SMI handler.
1174 @param Context The context of the SMI handler.
1175 If it is NOT NULL, it will be used to check what is registered.
1176 @param ContextSize The size of the context in bytes.
1177 If Context is NOT NULL, it will be used to check what is registered.
1178
1179 @retval EFI_SUCCESS The original record is removed.
1180 @retval EFI_NOT_FOUND There is no record for the HandlerGuid and handler.
1181 **/
1182 EFI_STATUS
1183 EFIAPI
1184 SmiHandlerProfileUnregisterHandler (
1185 IN SMI_HANDLER_PROFILE_PROTOCOL *This,
1186 IN EFI_GUID *HandlerGuid,
1187 IN EFI_SMM_HANDLER_ENTRY_POINT2 Handler,
1188 IN VOID *Context, OPTIONAL
1189 IN UINTN ContextSize OPTIONAL
1190 );
1191
1192 extern UINTN mFullSmramRangeCount;
1193 extern EFI_SMRAM_DESCRIPTOR *mFullSmramRanges;
1194
1195 extern EFI_SMM_DRIVER_ENTRY *mSmmCoreDriverEntry;
1196
1197 extern EFI_LOADED_IMAGE_PROTOCOL *mSmmCoreLoadedImage;
1198
1199 //
1200 // Page management
1201 //
1202
1203 typedef struct {
1204 LIST_ENTRY Link;
1205 UINTN NumberOfPages;
1206 } FREE_PAGE_LIST;
1207
1208 extern LIST_ENTRY mSmmMemoryMap;
1209
1210 //
1211 // Pool management
1212 //
1213
1214 //
1215 // MIN_POOL_SHIFT must not be less than 5
1216 //
1217 #define MIN_POOL_SHIFT 6
1218 #define MIN_POOL_SIZE (1 << MIN_POOL_SHIFT)
1219
1220 //
1221 // MAX_POOL_SHIFT must not be less than EFI_PAGE_SHIFT - 1
1222 //
1223 #define MAX_POOL_SHIFT (EFI_PAGE_SHIFT - 1)
1224 #define MAX_POOL_SIZE (1 << MAX_POOL_SHIFT)
1225
1226 //
1227 // MAX_POOL_INDEX are calculated by maximum and minimum pool sizes
1228 //
1229 #define MAX_POOL_INDEX (MAX_POOL_SHIFT - MIN_POOL_SHIFT + 1)
1230
1231 #define POOL_HEAD_SIGNATURE SIGNATURE_32('p','h','d','0')
1232
1233 typedef struct {
1234 UINT32 Signature;
1235 BOOLEAN Available;
1236 EFI_MEMORY_TYPE Type;
1237 UINTN Size;
1238 } POOL_HEADER;
1239
1240 #define POOL_TAIL_SIGNATURE SIGNATURE_32('p','t','a','l')
1241
1242 typedef struct {
1243 UINT32 Signature;
1244 UINT32 Reserved;
1245 UINTN Size;
1246 } POOL_TAIL;
1247
1248 #define POOL_OVERHEAD (sizeof(POOL_HEADER) + sizeof(POOL_TAIL))
1249
1250 #define HEAD_TO_TAIL(a) \
1251 ((POOL_TAIL *) (((CHAR8 *) (a)) + (a)->Size - sizeof(POOL_TAIL)));
1252
1253 typedef struct {
1254 POOL_HEADER Header;
1255 LIST_ENTRY Link;
1256 } FREE_POOL_HEADER;
1257
1258 typedef enum {
1259 SmmPoolTypeCode,
1260 SmmPoolTypeData,
1261 SmmPoolTypeMax,
1262 } SMM_POOL_TYPE;
1263
1264 extern LIST_ENTRY mSmmPoolLists[SmmPoolTypeMax][MAX_POOL_INDEX];
1265
1266 /**
1267 Internal Function. Allocate n pages from given free page node.
1268
1269 @param Pages The free page node.
1270 @param NumberOfPages Number of pages to be allocated.
1271 @param MaxAddress Request to allocate memory below this address.
1272
1273 @return Memory address of allocated pages.
1274
1275 **/
1276 UINTN
1277 InternalAllocPagesOnOneNode (
1278 IN OUT FREE_PAGE_LIST *Pages,
1279 IN UINTN NumberOfPages,
1280 IN UINTN MaxAddress
1281 );
1282
1283 /**
1284 Update SMM memory map entry.
1285
1286 @param[in] Type The type of allocation to perform.
1287 @param[in] Memory The base of memory address.
1288 @param[in] NumberOfPages The number of pages to allocate.
1289 @param[in] AddRegion If this memory is new added region.
1290 **/
1291 VOID
1292 ConvertSmmMemoryMapEntry (
1293 IN EFI_MEMORY_TYPE Type,
1294 IN EFI_PHYSICAL_ADDRESS Memory,
1295 IN UINTN NumberOfPages,
1296 IN BOOLEAN AddRegion
1297 );
1298
1299 /**
1300 Internal function. Moves any memory descriptors that are on the
1301 temporary descriptor stack to heap.
1302
1303 **/
1304 VOID
1305 CoreFreeMemoryMapStack (
1306 VOID
1307 );
1308
1309 /**
1310 Frees previous allocated pages.
1311
1312 @param[in] Memory Base address of memory being freed.
1313 @param[in] NumberOfPages The number of pages to free.
1314 @param[in] AddRegion If this memory is new added region.
1315
1316 @retval EFI_NOT_FOUND Could not find the entry that covers the range.
1317 @retval EFI_INVALID_PARAMETER Address not aligned, Address is zero or NumberOfPages is zero.
1318 @return EFI_SUCCESS Pages successfully freed.
1319
1320 **/
1321 EFI_STATUS
1322 SmmInternalFreePagesEx (
1323 IN EFI_PHYSICAL_ADDRESS Memory,
1324 IN UINTN NumberOfPages,
1325 IN BOOLEAN AddRegion
1326 );
1327
1328 /**
1329 Hook function used to set all Guard pages after entering SMM mode.
1330 **/
1331 VOID
1332 SmmEntryPointMemoryManagementHook (
1333 VOID
1334 );
1335
1336 #endif