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
;
59 EfiRuntimeLibFvbVirtualNotifyEvent (
67 Notify function to convert pointers to Fvb functions after ExitBootServices
71 Event - Event whose notification function is being invoked.
72 Context - Pointer to the notification function's context, which is
73 implementation-dependent.
83 EfiInitializeRuntimeDriverLib (
84 IN EFI_HANDLE ImageHandle
,
85 IN EFI_SYSTEM_TABLE
*SystemTable
,
86 IN EFI_EVENT_NOTIFY RuntimeNotifyEventHandler
92 Intialize Runtime Driver Lib if it has not yet been initialized.
96 ImageHandle - The firmware allocated handle for the EFI image.
98 SystemTable - A pointer to the EFI System Table.
100 RuntimeNotifyEventHandler - Virtual address change notification event
104 EFI_STATUS always returns EFI_SUCCESS
110 EfiShutdownRuntimeDriverLib (
117 This routine will free some resources which have been allocated in
118 EfiInitializeRuntimeDriverLib(). If a runtime driver exits with an error,
119 it must call this routine to free the allocated resource before the exiting.
127 EFI_SUCCESS - Shotdown the Runtime Driver Lib successfully
128 EFI_UNSUPPORTED - Runtime Driver lib was not initialized at all
134 EfiInitializeSmmDriverLib (
135 IN EFI_HANDLE ImageHandle
,
136 IN EFI_SYSTEM_TABLE
*SystemTable
142 Intialize Smm Driver Lib if it has not yet been initialized.
146 ImageHandle - The firmware allocated handle for the EFI image.
148 SystemTable - A pointer to the EFI System Table.
152 EFI_STATUS always returns EFI_SUCCESS
158 EfiLibGetSystemConfigurationTable (
159 IN EFI_GUID
*TableGuid
,
166 Return the EFI 1.0 System Tabl entry with TableGuid
170 TableGuid - Name of entry to return in the system table
171 Table - Pointer in EFI system table associated with TableGuid
175 EFI_SUCCESS - Table returned;
176 EFI_NOT_FOUND - TableGuid not in EFI system table
198 FALSE - Not at runtime
210 Return TRUE if SetVirtualAddressMap () has been called
216 TRUE - If SetVirtualAddressMap () has been called
217 FALSE - If SetVirtualAddressMap () has not been called
223 EfiLibGetSystemConfigurationTable (
224 IN EFI_GUID
*TableGuid
,
235 Get table from configuration table by name
243 TableGuid - Table name to search
247 Table - Pointer to the table caller wants
255 EFI_NOT_FOUND - Not found the table
259 EFI_SUCCESS - Found the table
268 RtEfiLibCreateProtocolNotifyEvent (
269 IN EFI_GUID
*ProtocolGuid
,
270 IN EFI_TPL NotifyTpl
,
271 IN EFI_EVENT_NOTIFY NotifyFunction
,
272 IN VOID
*NotifyContext
,
273 OUT VOID
**Registration
279 Create a protocol notification event and return it.
283 ProtocolGuid - Protocol to register notification event on.
285 NotifyTpl - Maximum TPL to single the NotifyFunction.
287 NotifyFunction - EFI notification routine.
289 NotifyContext - Context passed into Event when it is created.
291 Registration - Registration key returned from RegisterProtocolNotify().
295 The EFI_EVENT that has been registered to be signaled when a ProtocolGuid
296 is added to the system.
312 IN OUT EFI_LOCK
*Lock
,
319 Initialize a basic mutual exclusion lock. Each lock
320 provides mutual exclusion access at it's task priority
321 level. Since there is no-premption (at any TPL) or
322 multiprocessor support, acquiring the lock only consists
323 of raising to the locks TPL.
325 Note on a check build ASSERT()s are used to ensure proper
330 Lock - The EFI_LOCK structure to initialize
332 Priority - The task priority level of the lock
337 An initialized Efi Lock structure.
343 // Macro to initialize the state of a lock when a lock variable is declared
345 #define EFI_INITIALIZE_LOCK_VARIABLE(Tpl) {Tpl,0,0}
356 Raising to the task priority level of the mutual exclusion
357 lock, and then acquires ownership of the lock.
361 Lock - The lock to acquire
371 EfiAcquireLockOrFail (
378 Initialize a basic mutual exclusion lock. Each lock
379 provides mutual exclusion access at it's task priority
380 level. Since there is no-premption (at any TPL) or
381 multiprocessor support, acquiring the lock only consists
382 of raising to the locks TPL.
386 Lock - The EFI_LOCK structure to initialize
390 EFI_SUCCESS - Lock Owned.
391 EFI_ACCESS_DENIED - Reentrant Lock Acquisition, Lock not Owned.
404 Releases ownership of the mutual exclusion lock, and
405 restores the previous task priority level.
409 Lock - The lock to release
418 #define EfiCopyMem EfiCommonLibCopyMem
419 #define EfiSetMem EfiCommonLibSetMem
420 #define EfiZeroMem EfiCommonLibZeroMem
432 Compares two memory buffers of a given length.
436 MemOne - First memory buffer
438 MemTwo - Second memory buffer
440 Len - Length of Mem1 and Mem2 memory regions to compare
444 = 0 if MemOne == MemTwo
446 > 0 if MemOne > MemTwo
448 < 0 if MemOne < MemTwo
464 Locate Debug Assert Protocol and set as mDebugAssert
478 // Wrapper for EFI runtime functions
482 IN EFI_RESET_TYPE ResetType
,
483 IN EFI_STATUS ResetStatus
,
491 Resets the entire platform.
495 ResetType - The type of reset to perform.
496 ResetStatus - The status code for the reset.
497 DataSize - The size, in bytes, of ResetData.
498 ResetData - A data buffer that includes a Null-terminated Unicode string, optionally
499 followed by additional binary data.
509 EfiGetNextHighMonotonicCount (
510 OUT UINT32
*HighCount
516 Returns the next high 32 bits of the platform's monotonic counter.
520 HighCount - Pointer to returned value.
532 OUT EFI_TIME_CAPABILITIES
*Capabilities
538 Returns the current time and date information, and the time-keeping
539 capabilities of the hardware platform.
543 Time - A pointer to storage to receive a snapshot of the current time.
544 Capabilities - An optional pointer to a buffer to receive the real time clock device's
562 Sets the current local time and date information.
566 Time - A pointer to the current time.
577 OUT BOOLEAN
*Enabled
,
578 OUT BOOLEAN
*Pending
,
585 Returns the current wakeup alarm clock setting.
589 Enabled - Indicates if the alarm is currently enabled or disabled.
590 Pending - Indicates if the alarm signal is pending and requires acknowledgement.
591 Time - The current alarm setting.
609 Sets the system wakeup alarm clock time.
613 Enable - Enable or disable the wakeup alarm.
614 Time - If Enable is TRUE, the time to set the wakeup alarm for.
615 If Enable is FALSE, then this parameter is optional, and may be NULL.
626 IN CHAR16
*VariableName
,
627 IN EFI_GUID
* VendorGuid
,
628 OUT UINT32
*Attributes OPTIONAL
,
629 IN OUT UINTN
*DataSize
,
636 Returns the value of a variable.
640 VariableName - A Null-terminated Unicode string that is the name of the
642 VendorGuid - A unique identifier for the vendor.
643 Attributes - If not NULL, a pointer to the memory location to return the
644 attributes bitmask for the variable.
645 DataSize - On input, the size in bytes of the return Data buffer.
646 On output the size of data returned in Data.
647 Data - The buffer to return the contents of the variable.
657 EfiGetNextVariableName (
658 IN OUT UINTN
*VariableNameSize
,
659 IN OUT CHAR16
*VariableName
,
660 IN OUT EFI_GUID
*VendorGuid
666 Enumerates the current variable names.
670 VariableNameSize - The size of the VariableName buffer.
671 VariableName - On input, supplies the last VariableName that was returned
672 by GetNextVariableName().
673 On output, returns the Nullterminated Unicode string of the
675 VendorGuid - On input, supplies the last VendorGuid that was returned by
676 GetNextVariableName().
677 On output, returns the VendorGuid of the current variable.
688 IN CHAR16
*VariableName
,
689 IN EFI_GUID
*VendorGuid
,
690 IN UINT32 Attributes
,
698 Sets the value of a variable.
702 VariableName - A Null-terminated Unicode string that is the name of the
704 VendorGuid - A unique identifier for the vendor.
705 Attributes - Attributes bitmask to set for the variable.
706 DataSize - The size in bytes of the Data buffer.
707 Data - The contents for the variable.
716 #if (EFI_SPECIFICATION_VERSION >= 0x00020000)
719 EfiQueryVariableInfo (
720 IN UINT32 Attributes
,
721 OUT UINT64
*MaximumVariableStorageSize
,
722 OUT UINT64
*RemainingVariableStorageSize
,
723 OUT UINT64
*MaximumVariableSize
729 This code returns information about the EFI variables.
733 Attributes Attributes bitmask to specify the type of variables
734 on which to return information.
735 MaximumVariableStorageSize Pointer to the maximum size of the storage space available
736 for the EFI variables associated with the attributes specified.
737 RemainingVariableStorageSize Pointer to the remaining size of the storage space available
738 for the EFI variables associated with the attributes specified.
739 MaximumVariableSize Pointer to the maximum size of the individual EFI variables
740 associated with the attributes specified.
752 EfiReportStatusCode (
753 IN EFI_STATUS_CODE_TYPE CodeType
,
754 IN EFI_STATUS_CODE_VALUE Value
,
756 IN EFI_GUID
* CallerId
,
757 IN EFI_STATUS_CODE_DATA
* Data OPTIONAL
767 CodeType - Type of Status Code.
769 Value - Value to output for Status Code.
771 Instance - Instance Number of this status code.
773 CallerId - ID of the caller of this status code.
775 Data - Optional data associated with this status code.
786 IN UINTN DebugDisposition
,
793 Determines the new virtual address that is to be used on subsequent memory accesses.
797 DebugDisposition - Supplies type information for the pointer being converted.
798 Address - A pointer to a pointer that is to be fixed to be the value needed
799 for the new virtual address mappings being applied.
810 IN UINTN DebugDisposition
,
811 IN OUT EFI_LIST_ENTRY
*ListHead
817 Conver the standard Lib double linked list to a virtual mapping.
821 DebugDisposition - Argument to EfiConvertPointer (EFI 1.0 API)
823 ListHead - Head of linked list to convert
833 // Base IO Class Functions
837 IN EFI_CPU_IO_PROTOCOL_WIDTH Width
,
845 Perform an IO read into Buffer.
848 Width - Width of read transaction, and repeat operation to use
849 Address - IO address to read
850 Count - Number of times to read the IO address.
851 Buffer - Buffer to read data into. size is Width * Count
866 Do a one byte IO read
869 Address - IO address to read
884 Do a two byte IO read
887 Address - IO address to read
902 Do a four byte IO read
905 Address - IO address to read
915 IN EFI_CPU_IO_PROTOCOL_WIDTH Width
,
923 Perform an IO write into Buffer.
926 Width - Width of write transaction, and repeat operation to use
927 Address - IO address to write
928 Count - Number of times to write the IO address.
929 Buffer - Buffer to write data from. size is Width * Count
945 Do a one byte IO write
948 Address - IO address to write
949 Data - Data to write to Address
965 Do a two byte IO write
968 Address - IO address to write
969 Data - Data to write to Address
985 Do a four byte IO write
988 Address - IO address to write
989 Data - Data to write to Address
999 IN EFI_CPU_IO_PROTOCOL_WIDTH Width
,
1006 Routine Description:
1007 Perform a Memory mapped IO read into Buffer.
1010 Width - Width of each read transaction.
1011 Address - Memory mapped IO address to read
1012 Count - Number of Width quanta to read
1013 Buffer - Buffer to read data into. size is Width * Count
1027 Routine Description:
1028 Do a one byte Memory mapped IO read
1031 Address - Memory mapped IO address to read
1045 Routine Description:
1046 Do a two byte Memory mapped IO read
1049 Address - Memory mapped IO address to read
1063 Routine Description:
1064 Do a four byte Memory mapped IO read
1067 Address - Memory mapped IO address to read
1081 Routine Description:
1082 Do a eight byte Memory mapped IO read
1085 Address - Memory mapped IO address to read
1095 IN EFI_CPU_IO_PROTOCOL_WIDTH Width
,
1102 Routine Description:
1103 Perform a memory mapped IO write into Buffer.
1106 Width - Width of write transaction, and repeat operation to use
1107 Address - IO address to write
1108 Count - Number of times to write the IO address.
1109 Buffer - Buffer to write data from. size is Width * Count
1124 Routine Description:
1125 Do a one byte Memory mapped IO write
1128 Address - Memory mapped IO address to write
1129 Data - Data to write to Address
1144 Routine Description:
1145 Do a two byte Memory mapped IO write
1148 Address - Memory mapped IO address to write
1149 Data - Data to write to Address
1164 Routine Description:
1165 Do a four byte Memory mapped IO write
1168 Address - Memory mapped IO address to write
1169 Data - Data to write to Address
1184 Routine Description:
1185 Do a eight byte Memory mapped IO write
1188 Address - Memory mapped IO address to write
1189 Data - Data to write to Address
1198 // Platform specific functions
1209 Routine Description:
1210 Perform an one byte PCI config cycle read
1213 Segment - PCI Segment ACPI _SEG
1215 DevFunc - PCI Device(7:3) and Func(2:0)
1216 Register - PCI config space register
1219 Data read from PCI config space
1233 Routine Description:
1234 Perform an two byte PCI config cycle read
1237 Segment - PCI Segment ACPI _SEG
1239 DevFunc - PCI Device(7:3) and Func(2:0)
1240 Register - PCI config space register
1243 Data read from PCI config space
1257 Routine Description:
1258 Perform an four byte PCI config cycle read
1261 Segment - PCI Segment ACPI _SEG
1263 DevFunc - PCI Device(7:3) and Func(2:0)
1264 Register - PCI config space register
1267 Data read from PCI config space
1282 Routine Description:
1283 Perform an one byte PCI config cycle write
1286 Segment - PCI Segment ACPI _SEG
1288 DevFunc - PCI Device(7:3) and Func(2:0)
1289 Register - PCI config space register
1290 Data - Data to write
1308 Routine Description:
1309 Perform an two byte PCI config cycle write
1312 Segment - PCI Segment ACPI _SEG
1314 DevFunc - PCI Device(7:3) and Func(2:0)
1315 Register - PCI config space register
1316 Data - Data to write
1334 Routine Description:
1335 Perform an four byte PCI config cycle write
1338 Segment - PCI Segment ACPI _SEG
1340 DevFunc - PCI Device(7:3) and Func(2:0)
1341 Register - PCI config space register
1342 Data - Data to write
1352 IN UINTN Microseconds
1356 Routine Description:
1357 Delay for at least the request number of microseconds
1360 Microseconds - Number of microseconds to delay.
1377 Routine Description:
1378 Initialize globals and register Fvb Protocol notification function.
1395 Routine Description:
1396 Release resources allocated in EfiFvbInitialize.
1412 IN OUT UINTN
*NumBytes
,
1417 Routine Description:
1418 Reads specified number of bytes into a buffer from the specified block
1421 Instance - The FV instance to be read from
1422 Lba - The logical block address to be read from
1423 Offset - Offset into the block at which to begin reading
1424 NumBytes - Pointer that on input contains the total size of
1425 the buffer. On output, it contains the total number
1427 Buffer - Pointer to a caller allocated buffer that will be
1428 used to hold the data read
1441 IN OUT UINTN
*NumBytes
,
1446 Routine Description:
1447 Writes specified number of bytes from the input buffer to the block
1450 Instance - The FV instance to be written to
1451 Lba - The starting logical block index to write to
1452 Offset - Offset into the block at which to begin writing
1453 NumBytes - Pointer that on input contains the total size of
1454 the buffer. On output, it contains the total number
1455 of bytes actually written
1456 Buffer - Pointer to a caller allocated buffer that contains
1457 the source for the write
1472 Routine Description:
1473 Erases and initializes a firmware volume block
1476 Instance - The FV instance to be erased
1477 Lba - The logical block index to be erased
1486 EfiFvbGetVolumeAttributes (
1488 OUT EFI_FVB_ATTRIBUTES
*Attributes
1492 Routine Description:
1493 Retrieves attributes, insures positive polarity of attribute bits, returns
1494 resulting attributes in output parameter
1497 Instance - The FV instance whose attributes is going to be
1499 Attributes - Output buffer which contains attributes
1508 EfiFvbSetVolumeAttributes (
1510 IN EFI_FVB_ATTRIBUTES Attributes
1514 Routine Description:
1515 Modifies the current settings of the firmware volume according to the
1519 Instance - The FV instance whose attributes is going to be
1521 Attributes - It is a pointer to EFI_FVB_ATTRIBUTES
1522 containing the desired firmware volume settings.
1531 EfiFvbGetPhysicalAddress (
1533 OUT EFI_PHYSICAL_ADDRESS
*Address
1537 Routine Description:
1538 Retrieves the physical address of a memory mapped FV
1541 Instance - The FV instance whose base address is going to be
1543 Address - Pointer to a caller allocated EFI_PHYSICAL_ADDRESS
1544 that on successful return, contains the base address
1545 of the firmware volume.
1554 EfiFvbGetBlockSize (
1557 OUT UINTN
*BlockSize
,
1558 OUT UINTN
*NumOfBlocks
1562 Routine Description:
1563 Retrieve the size of a logical block
1566 Instance - The FV instance whose block size is going to be
1568 Lba - Indicates which block to return the size for.
1569 BlockSize - A pointer to a caller allocated UINTN in which
1570 the size of the block is returned
1571 NumOfBlocks - a pointer to a caller allocated UINTN in which the
1572 number of consecutive blocks starting with Lba is
1573 returned. All blocks in this range have a size of
1577 EFI_SUCCESS - The firmware volume was read successfully and
1578 contents are in Buffer
1583 EfiFvbEraseCustomBlockRange (
1585 IN EFI_LBA StartLba
,
1586 IN UINTN OffsetStartLba
,
1588 IN UINTN OffsetLastLba
1592 Routine Description:
1593 Erases and initializes a specified range of a firmware volume
1596 Instance - The FV instance to be erased
1597 StartLba - The starting logical block index to be erased
1598 OffsetStartLba - Offset into the starting block at which to
1600 LastLba - The last logical block index to be erased
1601 OffsetLastLba - Offset into the last block at which to end erasing
1611 IN EFI_PHYSICAL_ADDRESS Start
,
1616 Routine Description:
1618 Flush cache with specified range.
1622 Start - Start address
1623 Length - Length in bytes
1634 RtEfiCreateEventLegacyBoot (
1635 IN EFI_TPL NotifyTpl
,
1636 IN EFI_EVENT_NOTIFY NotifyFunction
,
1637 IN VOID
*NotifyContext
,
1638 OUT EFI_EVENT
*LegacyBootEvent
1642 Routine Description:
1643 Create a Legacy Boot Event.
1644 Tiano extended the CreateEvent Type enum to add a legacy boot event type.
1645 This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
1646 added and now it's possible to not voilate the UEFI specification by
1647 declaring a GUID for the legacy boot event class. This library supports
1648 the R8.5/EFI 1.10 form and R8.6/UEFI 2.0 form and allows common code to
1652 LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex)
1655 EFI_SUCCESS Event was created.
1656 Other Event was not created.
1663 RtEfiCreateEventReadyToBoot (
1664 IN EFI_TPL NotifyTpl
,
1665 IN EFI_EVENT_NOTIFY NotifyFunction
,
1666 IN VOID
*NotifyContext
,
1667 OUT EFI_EVENT
*ReadyToBootEvent
1671 Routine Description:
1672 Create a Read to Boot Event.
1674 Tiano extended the CreateEvent Type enum to add a ready to boot event type.
1675 This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
1676 added and now it's possible to not voilate the UEFI specification and use
1677 the ready to boot event class defined in UEFI 2.0. This library supports
1678 the R8.5/EFI 1.10 form and R8.6/UEFI 2.0 form and allows common code to
1682 ReadyToBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex)
1685 EFI_SUCCESS - Event was created.
1686 Other - Event was not created.