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