3 Copyright (c) 2004 - 2007, Intel Corporation
4 All rights reserved. This program and the accompanying materials
5 are licensed and made available under the terms and conditions of the BSD License
6 which accompanies this distribution. The full text of the license may be found at
7 http://opensource.org/licenses/bsd-license.php
9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
18 Light weight lib to support EFI drivers.
22 #ifndef _EFI_RUNTIME_LIB_H_
23 #define _EFI_RUNTIME_LIB_H_
24 #define MAX_FVB_COUNT 16
25 #include "EfiStatusCode.h"
26 #include "EfiCommonLib.h"
28 #include "LinkedList.h"
30 #include "RtDevicePath.h"
32 #include EFI_GUID_DEFINITION (DxeServices)
33 #include EFI_GUID_DEFINITION (EventGroup)
34 #include EFI_GUID_DEFINITION (EventLegacyBios)
35 #include EFI_PROTOCOL_DEFINITION (CpuIo)
36 #include EFI_PROTOCOL_DEFINITION (FirmwareVolume)
37 #include EFI_PROTOCOL_DEFINITION (FirmwareVolume2)
38 #include EFI_PROTOCOL_DEFINITION (FirmwareVolumeBlock)
39 #include EFI_PROTOCOL_DEFINITION (FvbExtension)
44 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
;
45 EFI_FVB_EXTENSION_PROTOCOL
*FvbExtension
;
49 // Driver Lib Globals.
51 extern EFI_BOOT_SERVICES
*gBS
;
52 extern EFI_SYSTEM_TABLE
*gST
;
53 extern EFI_DXE_SERVICES
*gDS
;
54 extern UINTN gRtErrorLevel
;
55 extern FVB_ENTRY
*mFvbEntry
;
57 #if defined(__GNUC__) && defined(ECP_CPU_IPF)
68 Generates a breakpoint on the CPU.
70 Generates a breakpoint on the CPU. The breakpoint must be implemented such
71 that code can resume normal execution after the breakpoint.
93 Used to serialize load and store operations.
95 All loads and stores that proceed calls to this function are guaranteed to be
96 globally visible when this function returns.
113 EfiRuntimeLibFvbVirtualNotifyEvent (
121 Notify function to convert pointers to Fvb functions after ExitBootServices
125 Event - Event whose notification function is being invoked.
126 Context - Pointer to the notification function's context, which is
127 implementation-dependent.
137 EfiInitializeRuntimeDriverLib (
138 IN EFI_HANDLE ImageHandle
,
139 IN EFI_SYSTEM_TABLE
*SystemTable
,
140 IN EFI_EVENT_NOTIFY RuntimeNotifyEventHandler
146 Intialize Runtime Driver Lib if it has not yet been initialized.
150 ImageHandle - The firmware allocated handle for the EFI image.
152 SystemTable - A pointer to the EFI System Table.
154 RuntimeNotifyEventHandler - Virtual address change notification event
158 EFI_STATUS always returns EFI_SUCCESS
164 EfiShutdownRuntimeDriverLib (
171 This routine will free some resources which have been allocated in
172 EfiInitializeRuntimeDriverLib(). If a runtime driver exits with an error,
173 it must call this routine to free the allocated resource before the exiting.
181 EFI_SUCCESS - Shotdown the Runtime Driver Lib successfully
182 EFI_UNSUPPORTED - Runtime Driver lib was not initialized at all
188 EfiInitializeSmmDriverLib (
189 IN EFI_HANDLE ImageHandle
,
190 IN EFI_SYSTEM_TABLE
*SystemTable
196 Intialize Smm Driver Lib if it has not yet been initialized.
200 ImageHandle - The firmware allocated handle for the EFI image.
202 SystemTable - A pointer to the EFI System Table.
206 EFI_STATUS always returns EFI_SUCCESS
212 EfiLibGetSystemConfigurationTable (
213 IN EFI_GUID
*TableGuid
,
220 Return the EFI 1.0 System Tabl entry with TableGuid
224 TableGuid - Name of entry to return in the system table
225 Table - Pointer in EFI system table associated with TableGuid
229 EFI_SUCCESS - Table returned;
230 EFI_NOT_FOUND - TableGuid not in EFI system table
252 FALSE - Not at runtime
264 Return TRUE if SetVirtualAddressMap () has been called
270 TRUE - If SetVirtualAddressMap () has been called
271 FALSE - If SetVirtualAddressMap () has not been called
277 EfiLibGetSystemConfigurationTable (
278 IN EFI_GUID
*TableGuid
,
289 Get table from configuration table by name
297 TableGuid - Table name to search
301 Table - Pointer to the table caller wants
309 EFI_NOT_FOUND - Not found the table
313 EFI_SUCCESS - Found the table
322 RtEfiLibCreateProtocolNotifyEvent (
323 IN EFI_GUID
*ProtocolGuid
,
324 IN EFI_TPL NotifyTpl
,
325 IN EFI_EVENT_NOTIFY NotifyFunction
,
326 IN VOID
*NotifyContext
,
327 OUT VOID
**Registration
333 Create a protocol notification event and return it.
337 ProtocolGuid - Protocol to register notification event on.
339 NotifyTpl - Maximum TPL to single the NotifyFunction.
341 NotifyFunction - EFI notification routine.
343 NotifyContext - Context passed into Event when it is created.
345 Registration - Registration key returned from RegisterProtocolNotify().
349 The EFI_EVENT that has been registered to be signaled when a ProtocolGuid
350 is added to the system.
366 IN OUT EFI_LOCK
*Lock
,
373 Initialize a basic mutual exclusion lock. Each lock
374 provides mutual exclusion access at it's task priority
375 level. Since there is no-premption (at any TPL) or
376 multiprocessor support, acquiring the lock only consists
377 of raising to the locks TPL.
379 Note on a check build ASSERT()s are used to ensure proper
384 Lock - The EFI_LOCK structure to initialize
386 Priority - The task priority level of the lock
391 An initialized Efi Lock structure.
397 // Macro to initialize the state of a lock when a lock variable is declared
399 #define EFI_INITIALIZE_LOCK_VARIABLE(Tpl) {Tpl,0,0}
410 Raising to the task priority level of the mutual exclusion
411 lock, and then acquires ownership of the lock.
415 Lock - The lock to acquire
425 EfiAcquireLockOrFail (
432 Initialize a basic mutual exclusion lock. Each lock
433 provides mutual exclusion access at it's task priority
434 level. Since there is no-premption (at any TPL) or
435 multiprocessor support, acquiring the lock only consists
436 of raising to the locks TPL.
440 Lock - The EFI_LOCK structure to initialize
444 EFI_SUCCESS - Lock Owned.
445 EFI_ACCESS_DENIED - Reentrant Lock Acquisition, Lock not Owned.
458 Releases ownership of the mutual exclusion lock, and
459 restores the previous task priority level.
463 Lock - The lock to release
472 #define EfiCopyMem EfiCommonLibCopyMem
473 #define EfiSetMem EfiCommonLibSetMem
474 #define EfiZeroMem EfiCommonLibZeroMem
486 Compares two memory buffers of a given length.
490 MemOne - First memory buffer
492 MemTwo - Second memory buffer
494 Len - Length of Mem1 and Mem2 memory regions to compare
498 = 0 if MemOne == MemTwo
500 > 0 if MemOne > MemTwo
502 < 0 if MemOne < MemTwo
518 Locate Debug Assert Protocol and set as mDebugAssert
532 // Wrapper for EFI runtime functions
536 IN EFI_RESET_TYPE ResetType
,
537 IN EFI_STATUS ResetStatus
,
545 Resets the entire platform.
549 ResetType - The type of reset to perform.
550 ResetStatus - The status code for the reset.
551 DataSize - The size, in bytes, of ResetData.
552 ResetData - A data buffer that includes a Null-terminated Unicode string, optionally
553 followed by additional binary data.
563 EfiGetNextHighMonotonicCount (
564 OUT UINT32
*HighCount
570 Returns the next high 32 bits of the platform's monotonic counter.
574 HighCount - Pointer to returned value.
586 OUT EFI_TIME_CAPABILITIES
*Capabilities
592 Returns the current time and date information, and the time-keeping
593 capabilities of the hardware platform.
597 Time - A pointer to storage to receive a snapshot of the current time.
598 Capabilities - An optional pointer to a buffer to receive the real time clock device's
616 Sets the current local time and date information.
620 Time - A pointer to the current time.
631 OUT BOOLEAN
*Enabled
,
632 OUT BOOLEAN
*Pending
,
639 Returns the current wakeup alarm clock setting.
643 Enabled - Indicates if the alarm is currently enabled or disabled.
644 Pending - Indicates if the alarm signal is pending and requires acknowledgement.
645 Time - The current alarm setting.
663 Sets the system wakeup alarm clock time.
667 Enable - Enable or disable the wakeup alarm.
668 Time - If Enable is TRUE, the time to set the wakeup alarm for.
669 If Enable is FALSE, then this parameter is optional, and may be NULL.
680 IN CHAR16
*VariableName
,
681 IN EFI_GUID
* VendorGuid
,
682 OUT UINT32
*Attributes OPTIONAL
,
683 IN OUT UINTN
*DataSize
,
690 Returns the value of a variable.
694 VariableName - A Null-terminated Unicode string that is the name of the
696 VendorGuid - A unique identifier for the vendor.
697 Attributes - If not NULL, a pointer to the memory location to return the
698 attributes bitmask for the variable.
699 DataSize - On input, the size in bytes of the return Data buffer.
700 On output the size of data returned in Data.
701 Data - The buffer to return the contents of the variable.
711 EfiGetNextVariableName (
712 IN OUT UINTN
*VariableNameSize
,
713 IN OUT CHAR16
*VariableName
,
714 IN OUT EFI_GUID
*VendorGuid
720 Enumerates the current variable names.
724 VariableNameSize - The size of the VariableName buffer.
725 VariableName - On input, supplies the last VariableName that was returned
726 by GetNextVariableName().
727 On output, returns the Nullterminated Unicode string of the
729 VendorGuid - On input, supplies the last VendorGuid that was returned by
730 GetNextVariableName().
731 On output, returns the VendorGuid of the current variable.
742 IN CHAR16
*VariableName
,
743 IN EFI_GUID
*VendorGuid
,
744 IN UINT32 Attributes
,
752 Sets the value of a variable.
756 VariableName - A Null-terminated Unicode string that is the name of the
758 VendorGuid - A unique identifier for the vendor.
759 Attributes - Attributes bitmask to set for the variable.
760 DataSize - The size in bytes of the Data buffer.
761 Data - The contents for the variable.
770 #if (EFI_SPECIFICATION_VERSION >= 0x00020000)
773 EfiQueryVariableInfo (
774 IN UINT32 Attributes
,
775 OUT UINT64
*MaximumVariableStorageSize
,
776 OUT UINT64
*RemainingVariableStorageSize
,
777 OUT UINT64
*MaximumVariableSize
783 This code returns information about the EFI variables.
787 Attributes Attributes bitmask to specify the type of variables
788 on which to return information.
789 MaximumVariableStorageSize Pointer to the maximum size of the storage space available
790 for the EFI variables associated with the attributes specified.
791 RemainingVariableStorageSize Pointer to the remaining size of the storage space available
792 for the EFI variables associated with the attributes specified.
793 MaximumVariableSize Pointer to the maximum size of the individual EFI variables
794 associated with the attributes specified.
806 EfiReportStatusCode (
807 IN EFI_STATUS_CODE_TYPE CodeType
,
808 IN EFI_STATUS_CODE_VALUE Value
,
810 IN EFI_GUID
* CallerId
,
811 IN EFI_STATUS_CODE_DATA
* Data OPTIONAL
821 CodeType - Type of Status Code.
823 Value - Value to output for Status Code.
825 Instance - Instance Number of this status code.
827 CallerId - ID of the caller of this status code.
829 Data - Optional data associated with this status code.
840 IN UINTN DebugDisposition
,
847 Determines the new virtual address that is to be used on subsequent memory accesses.
851 DebugDisposition - Supplies type information for the pointer being converted.
852 Address - A pointer to a pointer that is to be fixed to be the value needed
853 for the new virtual address mappings being applied.
864 IN UINTN DebugDisposition
,
865 IN OUT EFI_LIST_ENTRY
*ListHead
871 Conver the standard Lib double linked list to a virtual mapping.
875 DebugDisposition - Argument to EfiConvertPointer (EFI 1.0 API)
877 ListHead - Head of linked list to convert
887 // Base IO Class Functions
891 IN EFI_CPU_IO_PROTOCOL_WIDTH Width
,
899 Perform an IO read into Buffer.
902 Width - Width of read transaction, and repeat operation to use
903 Address - IO address to read
904 Count - Number of times to read the IO address.
905 Buffer - Buffer to read data into. size is Width * Count
920 Do a one byte IO read
923 Address - IO address to read
938 Do a two byte IO read
941 Address - IO address to read
956 Do a four byte IO read
959 Address - IO address to read
969 IN EFI_CPU_IO_PROTOCOL_WIDTH Width
,
977 Perform an IO write into Buffer.
980 Width - Width of write transaction, and repeat operation to use
981 Address - IO address to write
982 Count - Number of times to write the IO address.
983 Buffer - Buffer to write data from. size is Width * Count
999 Do a one byte IO write
1002 Address - IO address to write
1003 Data - Data to write to Address
1018 Routine Description:
1019 Do a two byte IO write
1022 Address - IO address to write
1023 Data - Data to write to Address
1038 Routine Description:
1039 Do a four byte IO write
1042 Address - IO address to write
1043 Data - Data to write to Address
1053 IN EFI_CPU_IO_PROTOCOL_WIDTH Width
,
1060 Routine Description:
1061 Perform a Memory mapped IO read into Buffer.
1064 Width - Width of each read transaction.
1065 Address - Memory mapped IO address to read
1066 Count - Number of Width quanta to read
1067 Buffer - Buffer to read data into. size is Width * Count
1081 Routine Description:
1082 Do a one byte Memory mapped IO read
1085 Address - Memory mapped IO address to read
1099 Routine Description:
1100 Do a two byte Memory mapped IO read
1103 Address - Memory mapped IO address to read
1117 Routine Description:
1118 Do a four byte Memory mapped IO read
1121 Address - Memory mapped IO address to read
1135 Routine Description:
1136 Do a eight byte Memory mapped IO read
1139 Address - Memory mapped IO address to read
1149 IN EFI_CPU_IO_PROTOCOL_WIDTH Width
,
1156 Routine Description:
1157 Perform a memory mapped IO write into Buffer.
1160 Width - Width of write transaction, and repeat operation to use
1161 Address - IO address to write
1162 Count - Number of times to write the IO address.
1163 Buffer - Buffer to write data from. size is Width * Count
1178 Routine Description:
1179 Do a one byte Memory mapped IO write
1182 Address - Memory mapped IO address to write
1183 Data - Data to write to Address
1198 Routine Description:
1199 Do a two byte Memory mapped IO write
1202 Address - Memory mapped IO address to write
1203 Data - Data to write to Address
1218 Routine Description:
1219 Do a four byte Memory mapped IO write
1222 Address - Memory mapped IO address to write
1223 Data - Data to write to Address
1238 Routine Description:
1239 Do a eight byte Memory mapped IO write
1242 Address - Memory mapped IO address to write
1243 Data - Data to write to Address
1252 // Platform specific functions
1263 Routine Description:
1264 Perform an one byte PCI config cycle read
1267 Segment - PCI Segment ACPI _SEG
1269 DevFunc - PCI Device(7:3) and Func(2:0)
1270 Register - PCI config space register
1273 Data read from PCI config space
1287 Routine Description:
1288 Perform an two byte PCI config cycle read
1291 Segment - PCI Segment ACPI _SEG
1293 DevFunc - PCI Device(7:3) and Func(2:0)
1294 Register - PCI config space register
1297 Data read from PCI config space
1311 Routine Description:
1312 Perform an four byte PCI config cycle read
1315 Segment - PCI Segment ACPI _SEG
1317 DevFunc - PCI Device(7:3) and Func(2:0)
1318 Register - PCI config space register
1321 Data read from PCI config space
1336 Routine Description:
1337 Perform an one byte PCI config cycle write
1340 Segment - PCI Segment ACPI _SEG
1342 DevFunc - PCI Device(7:3) and Func(2:0)
1343 Register - PCI config space register
1344 Data - Data to write
1362 Routine Description:
1363 Perform an two byte PCI config cycle write
1366 Segment - PCI Segment ACPI _SEG
1368 DevFunc - PCI Device(7:3) and Func(2:0)
1369 Register - PCI config space register
1370 Data - Data to write
1388 Routine Description:
1389 Perform an four byte PCI config cycle write
1392 Segment - PCI Segment ACPI _SEG
1394 DevFunc - PCI Device(7:3) and Func(2:0)
1395 Register - PCI config space register
1396 Data - Data to write
1406 IN UINTN Microseconds
1410 Routine Description:
1411 Delay for at least the request number of microseconds
1414 Microseconds - Number of microseconds to delay.
1431 Routine Description:
1432 Initialize globals and register Fvb Protocol notification function.
1449 Routine Description:
1450 Release resources allocated in EfiFvbInitialize.
1466 IN OUT UINTN
*NumBytes
,
1471 Routine Description:
1472 Reads specified number of bytes into a buffer from the specified block
1475 Instance - The FV instance to be read from
1476 Lba - The logical block address to be read from
1477 Offset - Offset into the block at which to begin reading
1478 NumBytes - Pointer that on input contains the total size of
1479 the buffer. On output, it contains the total number
1481 Buffer - Pointer to a caller allocated buffer that will be
1482 used to hold the data read
1495 IN OUT UINTN
*NumBytes
,
1500 Routine Description:
1501 Writes specified number of bytes from the input buffer to the block
1504 Instance - The FV instance to be written to
1505 Lba - The starting logical block index to write to
1506 Offset - Offset into the block at which to begin writing
1507 NumBytes - Pointer that on input contains the total size of
1508 the buffer. On output, it contains the total number
1509 of bytes actually written
1510 Buffer - Pointer to a caller allocated buffer that contains
1511 the source for the write
1526 Routine Description:
1527 Erases and initializes a firmware volume block
1530 Instance - The FV instance to be erased
1531 Lba - The logical block index to be erased
1540 EfiFvbGetVolumeAttributes (
1542 OUT EFI_FVB_ATTRIBUTES
*Attributes
1546 Routine Description:
1547 Retrieves attributes, insures positive polarity of attribute bits, returns
1548 resulting attributes in output parameter
1551 Instance - The FV instance whose attributes is going to be
1553 Attributes - Output buffer which contains attributes
1562 EfiFvbSetVolumeAttributes (
1564 IN EFI_FVB_ATTRIBUTES Attributes
1568 Routine Description:
1569 Modifies the current settings of the firmware volume according to the
1573 Instance - The FV instance whose attributes is going to be
1575 Attributes - It is a pointer to EFI_FVB_ATTRIBUTES
1576 containing the desired firmware volume settings.
1585 EfiFvbGetPhysicalAddress (
1587 OUT EFI_PHYSICAL_ADDRESS
*Address
1591 Routine Description:
1592 Retrieves the physical address of a memory mapped FV
1595 Instance - The FV instance whose base address is going to be
1597 Address - Pointer to a caller allocated EFI_PHYSICAL_ADDRESS
1598 that on successful return, contains the base address
1599 of the firmware volume.
1608 EfiFvbGetBlockSize (
1611 OUT UINTN
*BlockSize
,
1612 OUT UINTN
*NumOfBlocks
1616 Routine Description:
1617 Retrieve the size of a logical block
1620 Instance - The FV instance whose block size is going to be
1622 Lba - Indicates which block to return the size for.
1623 BlockSize - A pointer to a caller allocated UINTN in which
1624 the size of the block is returned
1625 NumOfBlocks - a pointer to a caller allocated UINTN in which the
1626 number of consecutive blocks starting with Lba is
1627 returned. All blocks in this range have a size of
1631 EFI_SUCCESS - The firmware volume was read successfully and
1632 contents are in Buffer
1637 EfiFvbEraseCustomBlockRange (
1639 IN EFI_LBA StartLba
,
1640 IN UINTN OffsetStartLba
,
1642 IN UINTN OffsetLastLba
1646 Routine Description:
1647 Erases and initializes a specified range of a firmware volume
1650 Instance - The FV instance to be erased
1651 StartLba - The starting logical block index to be erased
1652 OffsetStartLba - Offset into the starting block at which to
1654 LastLba - The last logical block index to be erased
1655 OffsetLastLba - Offset into the last block at which to end erasing
1665 IN EFI_PHYSICAL_ADDRESS Start
,
1670 Routine Description:
1672 Flush cache with specified range.
1676 Start - Start address
1677 Length - Length in bytes
1688 RtEfiCreateEventLegacyBoot (
1689 IN EFI_TPL NotifyTpl
,
1690 IN EFI_EVENT_NOTIFY NotifyFunction
,
1691 IN VOID
*NotifyContext
,
1692 OUT EFI_EVENT
*LegacyBootEvent
1696 Routine Description:
1697 Create a Legacy Boot Event.
1698 Tiano extended the CreateEvent Type enum to add a legacy boot event type.
1699 This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
1700 added and now it's possible to not voilate the UEFI specification by
1701 declaring a GUID for the legacy boot event class. This library supports
1702 the R8.5/EFI 1.10 form and R8.6/UEFI 2.0 form and allows common code to
1706 LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex)
1709 EFI_SUCCESS Event was created.
1710 Other Event was not created.
1717 RtEfiCreateEventReadyToBoot (
1718 IN EFI_TPL NotifyTpl
,
1719 IN EFI_EVENT_NOTIFY NotifyFunction
,
1720 IN VOID
*NotifyContext
,
1721 OUT EFI_EVENT
*ReadyToBootEvent
1725 Routine Description:
1726 Create a Read to Boot Event.
1728 Tiano extended the CreateEvent Type enum to add a ready to boot event type.
1729 This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
1730 added and now it's possible to not voilate the UEFI specification and use
1731 the ready to boot event class defined in UEFI 2.0. This library supports
1732 the R8.5/EFI 1.10 form and R8.6/UEFI 2.0 form and allows common code to
1736 ReadyToBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex)
1739 EFI_SUCCESS - Event was created.
1740 Other - Event was not created.