/** @file\r
- MDE UEFI library functions and macros\r
+ Provides library functions for common UEFI operations. Only available to DXE\r
+ and UEFI module types.\r
\r
- Copyright (c) 2006 - 2007, Intel Corporation \r
- All rights reserved. This program and the accompanying materials \r
- are licensed and made available under the terms and conditions of the BSD License \r
- which accompanies this distribution. The full text of the license may be found at \r
- http://opensource.org/licenses/bsd-license.php \r
+ The UEFI Library provides functions and macros that simplify the development of \r
+ UEFI Drivers and UEFI Applications. These functions and macros help manage EFI \r
+ events, build simple locks utilizing EFI Task Priority Levels (TPLs), install \r
+ EFI Driver Model related protocols, manage Unicode string tables for UEFI Drivers, \r
+ and print messages on the console output and standard error devices.\r
\r
- THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
- WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
+Copyright (c) 2006 - 2008, Intel Corporation\r
+All rights reserved. This program and the accompanying materials\r
+are licensed and made available under the terms and conditions of the BSD License\r
+which accompanies this distribution. The full text of the license may be found at\r
+http://opensource.org/licenses/bsd-license.php\r
+\r
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
#include <Protocol/DriverDiagnostics.h>\r
#include <Protocol/DriverDiagnostics2.h>\r
\r
-//\r
-// Unicode String Table\r
-//\r
+#include <Library/BaseLib.h>\r
+\r
+///\r
+/// Unicode String Table\r
+///\r
typedef struct {\r
CHAR8 *Language;\r
CHAR16 *UnicodeString;\r
} EFI_UNICODE_STRING_TABLE;\r
\r
-//\r
-// EFI Lock Status\r
-//\r
+///\r
+/// EFI Lock Status\r
+///\r
typedef enum {\r
EfiLockUninitialized = 0,\r
EfiLockReleased = 1,\r
EfiLockAcquired = 2\r
} EFI_LOCK_STATE;\r
\r
-//\r
-// EFI Lock \r
-//\r
+///\r
+/// EFI Lock \r
+///\r
typedef struct {\r
EFI_TPL Tpl;\r
EFI_TPL OwnerTpl;\r
} EFI_LOCK;\r
\r
\r
+/**\r
+ Macro that returns the number of 100 ns units for a specified number of microseconds.\r
+ Useful for managing EFI timer events.\r
+\r
+ @param Microseconds Number of microseonds.\r
+\r
+ @return The number of 100 ns units equivalent to the number of microseconds specified\r
+ by Microseconds.\r
+\r
+**/\r
+#define EFI_TIMER_PERIOD_MICROSECONDS(Microseconds) MultU64x32((UINT64)(Microseconds), 10)\r
+\r
+\r
+/**\r
+ Macro that returns the number of 100 ns units for a specified number of milliseoconds.\r
+ Useful for managing EFI timer events.\r
+\r
+ @param Milliseconds Number of milliseconds.\r
+\r
+ @return The number of 100 ns units equivalent to the number of milliseconds specified\r
+ by Milliseconds.\r
+\r
+**/\r
+#define EFI_TIMER_PERIOD_MILLISECONDS(Milliseconds) MultU64x32((UINT64)(Milliseconds), 10000)\r
+\r
+\r
+/**\r
+ Macro that returns the number of 100 ns units for a specified number of seoconds.\r
+ Useful for managing EFI timer events.\r
+\r
+ @param Seconds Number of seconds.\r
+\r
+ @return The number of 100 ns units equivalent to the number of seconds specified\r
+ by Seconds.\r
+\r
+**/\r
+#define EFI_TIMER_PERIOD_SECONDS(Seconds) MultU64x32((UINT64)(Seconds), 10000000)\r
+\r
+\r
/**\r
This function searches the list of configuration tables stored in the EFI System \r
Table for a table with a GUID that matches TableGuid. If a match is found, \r
can then immediately be restored back to the current TPL level with a call \r
to RestoreTPL().\r
\r
- @param VOID\r
-\r
- @retvale EFI_TPL The current TPL.\r
+ @return The current TPL.\r
\r
**/\r
EFI_TPL\r
priority level. Since there is no preemption or multiprocessor support in EFI,\r
acquiring the lock only consists of raising to the locks TPL.\r
\r
- @param Lock A pointer to the lock data structure to initialize.\r
@param Priority The task priority level of the lock.\r
\r
@return The lock.\r
priority level of the mutual exclusion lock. Then, it places the lock in the \r
acquired state.\r
\r
- @param Priority The task priority level of the lock.\r
+ @param Lock A pointer to the lock to acquire.\r
\r
**/\r
VOID\r
\r
@param ControllerHandle A handle for a (parent) controller to test. \r
@param ChildHandle A child handle to test.\r
- @param ConsumsedGuid Supplies the protocol that the child controller\r
+ @param ProtocolGuid Supplies the protocol that the child controller\r
opens on its parent controller. \r
\r
@retval EFI_SUCCESS ChildHandle is a child of the ControllerHandle.\r
IN CONST EFI_UNICODE_STRING_TABLE *UnicodeStringTable,\r
OUT CHAR16 **UnicodeString,\r
IN BOOLEAN Iso639Language\r
- )\r
-;\r
+ );\r
\r
/**\r
This function adds a Unicode string to UnicodeStringTable.\r
IN EFI_UNICODE_STRING_TABLE **UnicodeStringTable,\r
IN CONST CHAR16 *UnicodeString,\r
IN BOOLEAN Iso639Language\r
- )\r
-;\r
+ );\r
\r
/**\r
This function frees the table of Unicode strings in UnicodeStringTable.\r
);\r
\r
/**\r
- Create a Legacy Boot Event. \r
+ Creates an EFI event in the Legacy Boot Event Group. Prior to UEFI 2.0 this \r
+ was done via a non blessed UEFI extensions and this library abstracts the \r
+ implementation mechanism of this event from the caller.\r
\r
- Tiano extended the CreateEvent Type enum to add a legacy boot event type. \r
- This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was\r
- added and now it's possible to not voilate the UEFI specification by \r
- declaring a GUID for the legacy boot event class. This library supports\r
- the EDK/EFI 1.10 form and EDK II/UEFI 2.0 form and allows common code to \r
- work both ways.\r
+ This function abstracts the creation of the Legacy Boot Event. The Framework \r
+ moved from a proprietary to UEFI 2.0 based mechanism. This library abstracts \r
+ the caller from how this event is created to prevent to code form having to \r
+ change with the version of the specification supported.\r
+ If LegacyBootEvent is NULL, then ASSERT().\r
\r
@param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).\r
\r
);\r
\r
/**\r
- Create a Read to Boot Event. \r
+ Create an EFI event in the Ready To Boot Event Group. Prior to UEFI 2.0 this \r
+ was done via a non-standard UEFI extension, and this library abstracts the \r
+ implementation mechanism of this event from the caller. \r
\r
- Tiano extended the CreateEvent Type enum to add a ready to boot event type. \r
- This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was\r
- added and now it's possible to not voilate the UEFI specification and use \r
- the ready to boot event class defined in UEFI 2.0. This library supports\r
- the EDK/EFI 1.10 form and EDKII/UEFI 2.0 form and allows common code to \r
- work both ways.\r
+ This function abstracts the creation of the Ready to Boot Event. The Framework \r
+ moved from a proprietary to UEFI 2.0-based mechanism. This library abstracts \r
+ the caller from how this event is created to prevent the code form having to \r
+ change with the version of the specification supported.\r
+ If ReadyToBootEvent is NULL, then ASSERT().\r
\r
- @param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).\r
+ @param ReadyToBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).\r
\r
@retval EFI_SUCCESS Event was created.\r
@retval Other Event was not created.\r
@param NotifyTpl The task priority level of the event.\r
@param NotifyFunction The notification function to call when the event is signaled.\r
@param NotifyContext The content to pass to NotifyFunction when the event is signaled.\r
- @param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).\r
+ @param ReadyToBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).\r
\r
@retval EFI_SUCCESS Event was created.\r
@retval Other Event was not created.\r
/**\r
Initialize a Firmware Volume (FV) Media Device Path node.\r
\r
- Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum\r
- so as we move to UEFI 2.0 support we must use a mechanism that conforms with\r
- the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed \r
- device path is defined for Tiano extensions of device path. If the code \r
- is compiled to conform with the UEFI 2.0 specification use the new device path\r
- else use the old form for backwards compatability.\r
-\r
+ The Framework FwVol Device Path changed to conform to the UEFI 2.0 specification. \r
+ This library function abstracts initializing a device path node.\r
+ \r
+ Initialize the MEDIA_FW_VOL_FILEPATH_DEVICE_PATH data structure. This device \r
+ path changed in the DXE CIS version 0.92 in a non back ward compatible way to \r
+ not conflict with the UEFI 2.0 specification. This function abstracts the \r
+ differences from the caller.\r
+ \r
+ If FvDevicePathNode is NULL, then ASSERT().\r
+ If NameGuid is NULL, then ASSERT().\r
+ \r
@param FvDevicePathNode Pointer to a FV device path node to initialize\r
@param NameGuid FV file name to use in FvDevicePathNode\r
\r
/**\r
Check to see if the Firmware Volume (FV) Media Device Path is valid \r
\r
- Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum\r
- so as we move to UEFI 2.0 support we must use a mechanism that conforms with\r
- the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed \r
- device path is defined for Tiano extensions of device path. If the code \r
- is compiled to conform with the UEFI 2.0 specification use the new device path\r
- else use the old form for backwards compatability. The return value to this\r
- function points to a location in FvDevicePathNode and it does not allocate\r
- new memory for the GUID pointer that is returned.\r
+ The Framework FwVol Device Path changed to conform to the UEFI 2.0 specification. \r
+ This library function abstracts validating a device path node.\r
+ \r
+ Check the MEDIA_FW_VOL_FILEPATH_DEVICE_PATH data structure to see if it's valid. \r
+ If it is valid, then return the GUID file name from the device path node. Otherwise, \r
+ return NULL. This device path changed in the DXE CIS version 0.92 in a non back ward \r
+ compatible way to not conflict with the UEFI 2.0 specification. This function abstracts \r
+ the differences from the caller.\r
+ If FvDevicePathNode is NULL, then ASSERT().\r
\r
@param FvDevicePathNode Pointer to FV device path to check.\r
\r
@param ... VARARG list consumed to process Format.\r
If Format is NULL, then ASSERT().\r
If Format is not aligned on a 16-bit boundary, then ASSERT().\r
+ \r
+ @return Number of Unicode characters printed to ConOut.\r
\r
**/\r
UINTN\r
@param ... VARARG list consumed to process Format.\r
If Format is NULL, then ASSERT().\r
If Format is not aligned on a 16-bit boundary, then ASSERT().\r
+ \r
+ @return Number of Unicode characters printed to StdErr.\r
\r
**/\r
UINTN\r
@param ... VARARG list consumed to process Format.\r
If Format is NULL, then ASSERT().\r
If Format is not aligned on a 16-bit boundary, then ASSERT().\r
+ \r
+ @return Number of ASCII characters printed to ConOut.\r
\r
**/\r
UINTN\r
@param ... VARARG list consumed to process Format.\r
If Format is NULL, then ASSERT().\r
If Format is not aligned on a 16-bit boundary, then ASSERT().\r
+ \r
+ @return Number of ASCII characters printed to ConErr.\r
\r
**/\r
UINTN\r
\r
\r
/**\r
- Initializes a driver by installing the Driver Binding Protocol together with the optional Component Name,\r
+ Intialize a driver by installing the Driver Binding Protocol together with the optional Component Name,\r
Component Name 2, Driver Configure, Driver Diagnostic and Driver Diagnostic 2 Protocols onto the driver's\r
DriverBindingHandle. This is typically the same as the driver's ImageHandle, but it can be different if\r
the driver produces multiple DriverBinding Protocols. \r
- If the Driver Binding Protocol interface is NULL, then ASSERT (). \r
+ If the Drvier Binding Protocol interface is NULL, then ASSERT (). \r
If the installation fails, then ASSERT ().\r
\r
@param ImageHandle The image handle of the driver.\r
@param SystemTable The EFI System Table that was passed to the driver's entry point.\r
@param DriverBinding A Driver Binding Protocol instance that this driver is producing.\r
- @param DriverBindingHandle The handle that DriverBinding is to be installed onto. If this\r
+ @param DriverBindingHandle The handle that DriverBinding is to be installe onto. If this\r
parameter is NULL, then a new handle is created.\r
@param ComponentName A Component Name Protocol instance that this driver is producing.\r
@param ComponentName2 A Component Name 2 Protocol instance that this driver is producing.\r
@param DriverConfiguration A Driver Configuration Protocol instance that this driver is producing.\r
+ @param DriverConfiguration2 A Driver Configuration Protocol 2 instance that this driver is producing.\r
@param DriverDiagnostics A Driver Diagnostics Protocol instance that this driver is producing.\r
@param DriverDiagnostics2 A Driver Diagnostics Protocol 2 instance that this driver is producing.\r
\r
IN CONST EFI_SYSTEM_TABLE *SystemTable,\r
IN EFI_DRIVER_BINDING_PROTOCOL *DriverBinding,\r
IN EFI_HANDLE DriverBindingHandle,\r
- IN CONST EFI_COMPONENT_NAME_PROTOCOL *ComponentName, OPTIONAL\r
- IN CONST EFI_COMPONENT_NAME2_PROTOCOL *ComponentName2, OPTIONAL\r
- IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL *DriverConfiguration, OPTIONAL\r
- IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL *DriverDiagnostics, OPTIONAL\r
- IN CONST EFI_DRIVER_DIAGNOSTICS2_PROTOCOL *DriverDiagnostics2 OPTIONAL\r
+ IN CONST EFI_COMPONENT_NAME_PROTOCOL *ComponentName, OPTIONAL\r
+ IN CONST EFI_COMPONENT_NAME2_PROTOCOL *ComponentName2, OPTIONAL\r
+ IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL *DriverConfiguration, OPTIONAL\r
+ IN CONST EFI_DRIVER_CONFIGURATION_PROTOCOL *DriverConfiguration2, OPTIONAL\r
+ IN CONST EFI_DRIVER_DIAGNOSTICS_PROTOCOL *DriverDiagnostics, OPTIONAL\r
+ IN CONST EFI_DRIVER_DIAGNOSTICS2_PROTOCOL *DriverDiagnostics2 OPTIONAL\r
);\r
\r
+/**\r
+ Determine what is the current language setting. The space reserved for Lang\r
+ must be at least RFC_3066_ENTRY_SIZE bytes;\r
+\r
+ If Lang is NULL, then ASSERT.\r
+\r
+ @param Lang Pointer of system language. Lang will always be filled with \r
+ a valid RFC 3066 language string. If "PlatformLang" is not\r
+ set in the system, the default language specifed by PcdUefiVariableDefaultPlatformLang\r
+ is returned.\r
+\r
+ @return EFI_SUCCESS If the EFI Variable with "PlatformLang" is set and return in Lang.\r
+ @return EFI_NOT_FOUND If the EFI Variable with "PlatformLang" is not set, but a valid default language is return in Lang.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+GetCurrentLanguage (\r
+ OUT CHAR8 *Lang\r
+ );\r
+\r
+\r
#endif\r
projects / mirror_edk2.git / blobdiff