[mirror_edk2.git] / MdePkg / Include / Library / UefiLib.h

/** @file\r
  MDE UEFI library functions and macros\r
\r
  Copyright (c) 2006, 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
#ifndef __UEFI_LIB_H__\r
#define __UEFI_LIB_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
typedef enum {\r
  EfiLockUninitialized = 0,\r
  EfiLockReleased      = 1,\r
  EfiLockAcquired      = 2\r
} EFI_LOCK_STATE;\r
\r
//\r
// EFI Lock \r
//\r
typedef struct {\r
  EFI_TPL         Tpl;\r
  EFI_TPL         OwnerTpl;\r
  EFI_LOCK_STATE  Lock;\r
} EFI_LOCK;\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
  then a pointer to the configuration table is returned in Table, and EFI_SUCCESS \r
  is returned.  If a matching GUID is not found, then EFI_NOT_FOUND is returned.\r
\r
  @param  TableGuid       Pointer to table's GUID type..\r
  @param  Table           Pointer to the table associated with TableGuid in the EFI System Table.\r
\r
  @retval EFI_SUCCESS     A configuration table matching TableGuid was found.\r
  @retval EFI_NOT_FOUND   A configuration table matching TableGuid could not be found.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
EfiGetSystemConfigurationTable (  \r
  IN  EFI_GUID  *TableGuid,\r
  OUT VOID      **Table\r
  );\r
\r
/**\r
  This function causes the notification function to be executed for every protocol \r
  of type ProtocolGuid instance that exists in the system when this function is \r
  invoked.  In addition, every time a protocol of type ProtocolGuid instance is \r
  installed or reinstalled, the notification function is also executed.\r
\r
  @param  ProtocolGuid    Supplies GUID of the protocol upon whose installation the event is fired.\r
  @param  NotifyTpl       Supplies the task priority level of the event notifications.\r
  @param  NotifyFunction  Supplies the function to notify when the event is signaled.\r
  @param  NotifyContext   The context parameter to pass to NotifyFunction.\r
  @param  Registration    A pointer to a memory location to receive the registration value.\r
\r
  @return The notification event that was created. \r
\r
**/\r
EFI_EVENT\r
EFIAPI\r
EfiCreateProtocolNotifyEvent(\r
  IN  EFI_GUID          *ProtocolGuid,\r
  IN  EFI_TPL           NotifyTpl,\r
  IN  EFI_EVENT_NOTIFY  NotifyFunction,\r
  IN  VOID              *NotifyContext,  OPTIONAL\r
  OUT VOID              **Registration\r
  );\r
\r
/**\r
  This function creates an event using NotifyTpl, NoifyFunction, and NotifyContext.\r
  This event is signaled with EfiNamedEventSignal().  This provide the ability for \r
  one or more listeners on the same event named by the GUID specified by Name.\r
\r
  @param  Name                  Supplies GUID name of the event.\r
  @param  NotifyTpl             Supplies the task priority level of the event notifications.\r
  @param  NotifyFunction        Supplies the function to notify when the event is signaled.\r
  @param  NotifyContext         The context parameter to pass to NotifyFunction. \r
  @param  Registration          A pointer to a memory location to receive the registration value.\r
\r
  @retval EFI_SUCCESS           A named event was created.\r
  @retval EFI_OUT_OF_RESOURCES  There are not enough resource to create the named event.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
EfiNamedEventListen (\r
  IN CONST EFI_GUID    *Name,\r
  IN EFI_TPL           NotifyTpl,\r
  IN EFI_EVENT_NOTIFY  NotifyFunction,\r
  IN CONST VOID        *NotifyContext,  OPTIONAL\r
  OUT VOID             *Registration OPTIONAL\r
  );\r
\r
/**\r
  This function signals the named event specified by Name.  The named event must \r
  have been created with EfiNamedEventListen().\r
\r
  @param  Name                  Supplies GUID name of the event.\r
\r
  @retval EFI_SUCCESS           A named event was signaled.\r
  @retval EFI_OUT_OF_RESOURCES  There are not enough resource to signal the named event.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
EfiNamedEventSignal (\r
  IN CONST EFI_GUID  *Name\r
  );\r
\r
/**\r
  This function initializes a basic mutual exclusion lock to the released state \r
  and returns the lock.  Each lock provides mutual exclusion access at its task \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   EFI TPL associated with the lock.\r
\r
  @return The lock.\r
\r
**/\r
EFI_LOCK *\r
EFIAPI\r
EfiInitializeLock (\r
  IN OUT EFI_LOCK  *Lock,\r
  IN EFI_TPL        Priority\r
  );\r
\r
/**\r
  This macro initializes the contents of a basic mutual exclusion lock to the \r
  released state.  Each lock provides mutual exclusion access at its task \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
\r
**/\r
#define EFI_INITIALIZE_LOCK_VARIABLE(Priority) \\r
  {Priority, EFI_TPL_APPLICATION, EfiLockReleased }\r
\r
\r
/**\r
  \r
  Macro that calls DebugAssert() if an EFI_LOCK structure is not in the locked state.\r
\r
  If the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set, \r
  then this macro evaluates the EFI_LOCK structure specified by Lock.  If Lock \r
  is not in the locked state, then DebugAssert() is called passing in the source \r
  filename, source line number, and Lock.\r
\r
  If Lock is NULL, then ASSERT().\r
\r
  @param  LockParameter  A pointer to the lock to acquire.\r
\r
**/\r
#define ASSERT_LOCKED(LockParameter)                  \\r
  do {                                                \\r
    if (DebugAssertEnabled ()) {                      \\r
      ASSERT (LockParameter != NULL);                 \\r
      if ((LockParameter)->Lock != EfiLockAcquired) { \\r
        _ASSERT (LockParameter not locked);           \\r
      }                                               \\r
    }                                                 \\r
  } while (FALSE)\r
\r
\r
/**\r
  This function raises the system's current task priority level to the task \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
\r
**/\r
VOID\r
EFIAPI\r
EfiAcquireLock (\r
  IN EFI_LOCK  *Lock\r
  );\r
\r
/**\r
  This function raises the system's current task priority level to the task \r
  priority level of the mutual exclusion lock.  Then, it attempts to place the \r
  lock in the acquired state.\r
\r
  @param  Lock              A pointer to the lock to acquire.\r
\r
  @retval EFI_SUCCESS       The lock was acquired.\r
  @retval EFI_ACCESS_DENIED The lock could not be acquired because it is already owned.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
EfiAcquireLockOrFail (\r
  IN EFI_LOCK  *Lock\r
  );\r
\r
/**\r
  This function transitions a mutual exclusion lock from the acquired state to \r
  the released state, and restores the system's task priority level to its \r
  previous level.\r
\r
  @param  Lock  A pointer to the lock to release.\r
\r
**/\r
VOID\r
EFIAPI\r
EfiReleaseLock (\r
  IN EFI_LOCK  *Lock\r
  );\r
\r
/**\r
  This function looks up a Unicode string in UnicodeStringTable.  If Language is \r
  a member of SupportedLanguages and a Unicode string is found in UnicodeStringTable\r
  that matches the language code specified by Language, then it is returned in \r
  UnicodeString.\r
\r
  @param  Language                A pointer to the ISO 639-2 language code for the \r
                                  Unicode string to look up and return.\r
  @param  SupportedLanguages      A pointer to the set of ISO 639-2 language codes \r
                                  that the Unicode string table supports.  Language \r
                                  must be a member of this set.\r
  @param  UnicodeStringTable      A pointer to the table of Unicode strings.\r
  @param  UnicodeString           A pointer to the Unicode string from UnicodeStringTable\r
                                  that matches the language specified by Language.\r
\r
  @retval EFI_SUCCESS             The Unicode string that matches the language \r
                                  specified by Language was found\r
                                  in the table of Unicoide strings UnicodeStringTable, \r
                                  and it was returned in UnicodeString.\r
  @retval EFI_INVALID_PARAMETER   Language is NULL.\r
  @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.\r
  @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.\r
  @retval EFI_UNSUPPORTED         UnicodeStringTable is NULL.\r
  @retval EFI_UNSUPPORTED         The language specified by Language is not a \r
                                  member of SupportedLanguages.\r
  @retval EFI_UNSUPPORTED         The language specified by Language is not \r
                                  supported by UnicodeStringTable.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
LookupUnicodeString (\r
  IN CONST CHAR8                     *Language,\r
  IN CONST CHAR8                     *SupportedLanguages,\r
  IN CONST EFI_UNICODE_STRING_TABLE  *UnicodeStringTable,\r
  OUT CHAR16                         **UnicodeString\r
  );\r
\r
/**\r
  This function adds a Unicode string to UnicodeStringTable.\r
  If Language is a member of SupportedLanguages then UnicodeString is added to \r
  UnicodeStringTable.  New buffers are allocated for both Language and \r
  UnicodeString.  The contents of Language and UnicodeString are copied into \r
  these new buffers.  These buffers are automatically freed when \r
  FreeUnicodeStringTable() is called.\r
\r
  @param  Language                A pointer to the ISO 639-2 language code for the Unicode \r
                                  string to add.\r
  @param  SupportedLanguages      A pointer to the set of ISO 639-2 language codes\r
                                  that the Unicode string table supports.\r
                                  Language must be a member of this set.\r
  @param  UnicodeStringTable      A pointer to the table of Unicode strings.\r
  @param  UnicodeString           A pointer to the Unicode string to add.\r
\r
  @retval EFI_SUCCESS             The Unicode string that matches the language \r
                                  specified by Language was found in the table of \r
                                  Unicode strings UnicodeStringTable, and it was \r
                                  returned in UnicodeString.\r
  @retval EFI_INVALID_PARAMETER   Language is NULL.\r
  @retval EFI_INVALID_PARAMETER   UnicodeString is NULL.\r
  @retval EFI_INVALID_PARAMETER   UnicodeString is an empty string.\r
  @retval EFI_UNSUPPORTED         SupportedLanguages is NULL.\r
  @retval EFI_ALREADY_STARTED     A Unicode string with language Language is \r
                                  already present in UnicodeStringTable.\r
  @retval EFI_OUT_OF_RESOURCES    There is not enough memory to add another \r
                                  Unicode string to UnicodeStringTable.\r
  @retval EFI_UNSUPPORTED         The language specified by Language is not a \r
                                  member of SupportedLanguages.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
AddUnicodeString (\r
  IN CONST CHAR8               *Language,\r
  IN CONST CHAR8               *SupportedLanguages,\r
  IN EFI_UNICODE_STRING_TABLE  **UnicodeStringTable,\r
  IN CONST CHAR16              *UnicodeString\r
  );\r
\r
/**\r
  This function frees the table of Unicode strings in UnicodeStringTable.\r
  If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.\r
  Otherwise, each language code, and each Unicode string in the Unicode string \r
  table are freed, and EFI_SUCCESS is returned.\r
\r
  @param  UnicodeStringTable  A pointer to the table of Unicode strings.\r
\r
  @retval EFI_SUCCESS         The Unicode string table was freed.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FreeUnicodeStringTable (\r
  IN EFI_UNICODE_STRING_TABLE  *UnicodeStringTable\r
  );\r
\r
/**\r
  This function computes and returns the width of the Unicode character \r
  specified by UnicodeChar.\r
\r
  @param  UnicodeChar   A Unicode character.\r
\r
  @retval 0             The width if UnicodeChar could not be determined.\r
  @retval 1             UnicodeChar is a narrow glyph.\r
  @retval 2             UnicodeChar is a wide glyph.\r
\r
**/\r
UINTN\r
EFIAPI\r
GetGlyphWidth (\r
  IN CHAR16  UnicodeChar\r
  );\r
\r
/**\r
  This function computes and returns the display length of\r
  the Null-terminated Unicode string specified by String.\r
  If String is NULL, then 0 is returned.\r
  If any of the widths of the Unicode characters in String\r
  can not be determined, then 0 is returned.\r
\r
  @param  String      A pointer to a Null-terminated Unicode string.\r
\r
  @return The display length of the Null-terminated Unicode string specified by String.\r
  \r
**/\r
UINTN\r
EFIAPI\r
UnicodeStringDisplayLength (\r
  IN CONST CHAR16  *String\r
  );\r
\r
//\r
// Functions that abstract early Framework contamination of UEFI.\r
//\r
/**\r
  Signal a Ready to Boot Event.  \r
  \r
  Create a Ready to Boot Event. Signal it and close it. This causes other \r
  events of the same event group to be signaled in other modules. \r
\r
**/\r
VOID\r
EFIAPI\r
EfiSignalEventReadyToBoot (\r
  VOID\r
  );\r
\r
/**\r
  Signal a Legacy Boot Event.  \r
  \r
  Create a legacy Boot Event. Signal it and close it. This causes other \r
  events of the same event group to be signaled in other modules. \r
\r
**/\r
VOID\r
EFIAPI\r
EfiSignalEventLegacyBoot (\r
  VOID\r
  );\r
\r
/**\r
  Create a Legacy Boot Event.  \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
\r
  @param  LegacyBootEvent   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
**/\r
EFI_STATUS\r
EFIAPI\r
EfiCreateEventLegacyBoot (\r
  OUT EFI_EVENT  *LegacyBootEvent\r
  );\r
\r
/**\r
  Create an EFI event in the Legacy Boot Event Group and allows\r
  the caller to specify a notification function.  \r
  \r
  This function abstracts the creation of the Legacy Boot Event.\r
  The Framework moved from a proprietary to UEFI 2.0 based mechanism.\r
  This library abstracts the caller from how this event is created to prevent\r
  to code form having to change with the version of the specification supported.\r
  If LegacyBootEvent is NULL, then ASSERT().\r
\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
\r
  @retval EFI_SUCCESS       Event was created.\r
  @retval Other             Event was not created.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
EfiCreateEventLegacyBootEx (\r
  IN  EFI_TPL           NotifyTpl,\r
  IN  EFI_EVENT_NOTIFY  NotifyFunction,  OPTIONAL\r
  IN  VOID              *NotifyContext,  OPTIONAL\r
  OUT EFI_EVENT         *LegacyBootEvent\r
  );\r
\r
/**\r
  Create a Read to Boot Event.  \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
\r
  @param  LegacyBootEvent   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
**/\r
EFI_STATUS\r
EFIAPI\r
EfiCreateEventReadyToBoot (\r
  OUT EFI_EVENT  *ReadyToBootEvent\r
  );\r
\r
/**\r
  Create an EFI event in the Ready To Boot Event Group and allows\r
  the caller to specify a notification function.  \r
  \r
  This function abstracts the creation of the Ready to Boot Event.\r
  The Framework moved from a proprietary to UEFI 2.0 based mechanism.\r
  This library abstracts the caller from how this event is created to prevent\r
  to code form having to change with the version of the specification supported.\r
  If ReadyToBootEvent is NULL, then ASSERT().\r
\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
\r
  @retval EFI_SUCCESS       Event was created.\r
  @retval Other             Event was not created.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
EfiCreateEventReadyToBootEx (\r
  IN  EFI_TPL           NotifyTpl,\r
  IN  EFI_EVENT_NOTIFY  NotifyFunction,  OPTIONAL\r
  IN  VOID              *NotifyContext,  OPTIONAL\r
  OUT EFI_EVENT         *ReadyToBootEvent\r
  );\r
\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
  @param  FvDevicePathNode  Pointer to a FV device path node to initialize\r
  @param  NameGuid          FV file name to use in FvDevicePathNode\r
\r
**/\r
VOID\r
EFIAPI\r
EfiInitializeFwVolDevicepathNode (\r
  IN OUT MEDIA_FW_VOL_FILEPATH_DEVICE_PATH  *FvDevicePathNode,\r
  IN CONST EFI_GUID                         *NameGuid\r
  );\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
\r
  @param  FvDevicePathNode  Pointer to FV device path to check.\r
\r
  @retval NULL              FvDevicePathNode is not valid.\r
  @retval Other             FvDevicePathNode is valid and pointer to NameGuid was returned.\r
\r
**/\r
EFI_GUID *\r
EFIAPI\r
EfiGetNameGuidFromFwVolDevicePathNode (\r
  IN CONST MEDIA_FW_VOL_FILEPATH_DEVICE_PATH  *FvDevicePathNode\r
  );\r
\r
\r
#endif\r
Commit	Line	Data
878ddf1f	1	/** @file\r
	2	MDE UEFI library functions and macros\r
	3	\r
	4	Copyright (c) 2006, Intel Corporation \r
	5	All rights reserved. This program and the accompanying materials \r
	6	are licensed and made available under the terms and conditions of the BSD License \r
	7	which accompanies this distribution. The full text of the license may be found at \r
	8	http://opensource.org/licenses/bsd-license.php \r
	9	\r
	10	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
	11	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
	12	\r
	13	**/\r
	14	\r
	15	#ifndef __UEFI_LIB_H__\r
	16	#define __UEFI_LIB_H__\r
	17	\r
	18	//\r
	19	// Unicode String Table\r
	20	//\r
	21	typedef struct {\r
	22	CHAR8 *Language;\r
	23	CHAR16 *UnicodeString;\r
	24	} EFI_UNICODE_STRING_TABLE;\r
	25	\r
	26	//\r
	27	// EFI Lock Status\r
	28	//\r
	29	typedef enum {\r
	30	EfiLockUninitialized = 0,\r
	31	EfiLockReleased = 1,\r
	32	EfiLockAcquired = 2\r
	33	} EFI_LOCK_STATE;\r
	34	\r
	35	//\r
	36	// EFI Lock \r
	37	//\r
	38	typedef struct {\r
	39	EFI_TPL Tpl;\r
	40	EFI_TPL OwnerTpl;\r
	41	EFI_LOCK_STATE Lock;\r
	42	} EFI_LOCK;\r
	43	\r
	44	\r
	45	/**\r
	46	This function searches the list of configuration tables stored in the EFI System \r
	47	Table for a table with a GUID that matches TableGuid. If a match is found, \r
	48	then a pointer to the configuration table is returned in Table, and EFI_SUCCESS \r
	49	is returned. If a matching GUID is not found, then EFI_NOT_FOUND is returned.\r
	50	\r
	51	@param TableGuid Pointer to table's GUID type..\r
	52	@param Table Pointer to the table associated with TableGuid in the EFI System Table.\r
	53	\r
	54	@retval EFI_SUCCESS A configuration table matching TableGuid was found.\r
	55	@retval EFI_NOT_FOUND A configuration table matching TableGuid could not be found.\r
	56	\r
	57	**/\r
	58	EFI_STATUS\r
	59	EFIAPI\r
	60	EfiGetSystemConfigurationTable ( \r
	61	IN EFI_GUID *TableGuid,\r
	62	OUT VOID **Table\r
	63	);\r
	64	\r
65	/**\r
66	This function causes the notification function to be executed for every protocol \r
67	of type ProtocolGuid instance that exists in the system when this function is \r
68	invoked. In addition, every time a protocol of type ProtocolGuid instance is \r
69	installed or reinstalled, the notification function is also executed.\r
70	\r
71	@param ProtocolGuid Supplies GUID of the protocol upon whose installation the event is fired.\r
72	@param NotifyTpl Supplies the task priority level of the event notifications.\r
73	@param NotifyFunction Supplies the function to notify when the event is signaled.\r
74	@param NotifyContext The context parameter to pass to NotifyFunction.\r
75	@param Registration A pointer to a memory location to receive the registration value.\r
76	\r
77	@return The notification event that was created. \r
78	\r
79	**/\r
80	EFI_EVENT\r
81	EFIAPI\r
82	EfiCreateProtocolNotifyEvent(\r
83	IN EFI_GUID *ProtocolGuid,\r
84	IN EFI_TPL NotifyTpl,\r
85	IN EFI_EVENT_NOTIFY NotifyFunction,\r
86	IN VOID *NotifyContext, OPTIONAL\r
13c84604	87	OUT VOID **Registration\r
878ddf1f	88	);\r
	89	\r
	90	/**\r
	91	This function creates an event using NotifyTpl, NoifyFunction, and NotifyContext.\r
	92	This event is signaled with EfiNamedEventSignal(). This provide the ability for \r
	93	one or more listeners on the same event named by the GUID specified by Name.\r
	94	\r
	95	@param Name Supplies GUID name of the event.\r
	96	@param NotifyTpl Supplies the task priority level of the event notifications.\r
	97	@param NotifyFunction Supplies the function to notify when the event is signaled.\r
	98	@param NotifyContext The context parameter to pass to NotifyFunction. \r
	99	@param Registration A pointer to a memory location to receive the registration value.\r
	100	\r
	101	@retval EFI_SUCCESS A named event was created.\r
	102	@retval EFI_OUT_OF_RESOURCES There are not enough resource to create the named event.\r
	103	\r
	104	**/\r
	105	EFI_STATUS\r
	106	EFIAPI\r
	107	EfiNamedEventListen (\r
	108	IN CONST EFI_GUID *Name,\r
	109	IN EFI_TPL NotifyTpl,\r
	110	IN EFI_EVENT_NOTIFY NotifyFunction,\r
	111	IN CONST VOID *NotifyContext, OPTIONAL\r
13c84604	112	OUT VOID *Registration OPTIONAL\r
878ddf1f	113	);\r
	114	\r
	115	/**\r
	116	This function signals the named event specified by Name. The named event must \r
	117	have been created with EfiNamedEventListen().\r
	118	\r
	119	@param Name Supplies GUID name of the event.\r
	120	\r
	121	@retval EFI_SUCCESS A named event was signaled.\r
	122	@retval EFI_OUT_OF_RESOURCES There are not enough resource to signal the named event.\r
	123	\r
	124	**/\r
	125	EFI_STATUS\r
	126	EFIAPI\r
	127	EfiNamedEventSignal (\r
	128	IN CONST EFI_GUID *Name\r
	129	);\r
	130	\r
	131	/**\r
	132	This function initializes a basic mutual exclusion lock to the released state \r
	133	and returns the lock. Each lock provides mutual exclusion access at its task \r
	134	priority level. Since there is no preemption or multiprocessor support in EFI,\r
	135	acquiring the lock only consists of raising to the locks TPL.\r
	136	\r
	137	@param Lock A pointer to the lock data structure to initialize.\r
	138	@param Priority EFI TPL associated with the lock.\r
	139	\r
	140	@return The lock.\r
	141	\r
	142	**/\r
	143	EFI_LOCK *\r
	144	EFIAPI\r
	145	EfiInitializeLock (\r
	146	IN OUT EFI_LOCK *Lock,\r
	147	IN EFI_TPL Priority\r
	148	);\r
	149	\r
	150	/**\r
	151	This macro initializes the contents of a basic mutual exclusion lock to the \r
	152	released state. Each lock provides mutual exclusion access at its task \r
	153	priority level. Since there is no preemption or multiprocessor support in EFI,\r
	154	acquiring the lock only consists of raising to the locks TPL.\r
	155	\r
	156	@param Lock A pointer to the lock data structure to initialize.\r
	157	@param Priority The task priority level of the lock.\r
	158	\r
	159	@return The lock.\r
	160	\r
	161	**/\r
	162	#define EFI_INITIALIZE_LOCK_VARIABLE(Priority) \\r
	163	{Priority, EFI_TPL_APPLICATION, EfiLockReleased }\r
	164	\r
	165	\r
	166	/**\r
	167	\r
	168	Macro that calls DebugAssert() if an EFI_LOCK structure is not in the locked state.\r
	169	\r
	170	If the DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED bit of PcdDebugProperyMask is set, \r
	171	then this macro evaluates the EFI_LOCK structure specified by Lock. If Lock \r
	172	is not in the locked state, then DebugAssert() is called passing in the source \r
	173	filename, source line number, and Lock.\r
	174	\r
	175	If Lock is NULL, then ASSERT().\r
	176	\r
177	@param LockParameter A pointer to the lock to acquire.\r
178	\r
179	**/\r
180	#define ASSERT_LOCKED(LockParameter) \\r
181	do { \\r
182	if (DebugAssertEnabled ()) { \\r
183	ASSERT (LockParameter != NULL); \\r
184	if ((LockParameter)->Lock != EfiLockAcquired) { \\r
185	_ASSERT (LockParameter not locked); \\r
186	} \\r
187	} \\r
188	} while (FALSE)\r
189	\r
190	\r
191	/**\r
511710d6	192	This function raises the system's current task priority level to the task \r
878ddf1f	193	priority level of the mutual exclusion lock. Then, it places the lock in the \r
	194	acquired state.\r
	195	\r
	196	@param Priority The task priority level of the lock.\r
	197	\r
	198	**/\r
	199	VOID\r
	200	EFIAPI\r
	201	EfiAcquireLock (\r
	202	IN EFI_LOCK *Lock\r
	203	);\r
	204	\r
	205	/**\r
511710d6	206	This function raises the system's current task priority level to the task \r
878ddf1f	207	priority level of the mutual exclusion lock. Then, it attempts to place the \r
	208	lock in the acquired state.\r
	209	\r
	210	@param Lock A pointer to the lock to acquire.\r
	211	\r
	212	@retval EFI_SUCCESS The lock was acquired.\r
	213	@retval EFI_ACCESS_DENIED The lock could not be acquired because it is already owned.\r
	214	\r
	215	**/\r
	216	EFI_STATUS\r
	217	EFIAPI\r
	218	EfiAcquireLockOrFail (\r
	219	IN EFI_LOCK *Lock\r
	220	);\r
	221	\r
	222	/**\r
	223	This function transitions a mutual exclusion lock from the acquired state to \r
511710d6	224	the released state, and restores the system's task priority level to its \r
878ddf1f	225	previous level.\r
	226	\r
	227	@param Lock A pointer to the lock to release.\r
	228	\r
	229	**/\r
	230	VOID\r
	231	EFIAPI\r
	232	EfiReleaseLock (\r
	233	IN EFI_LOCK *Lock\r
	234	);\r
	235	\r
	236	/**\r
	237	This function looks up a Unicode string in UnicodeStringTable. If Language is \r
	238	a member of SupportedLanguages and a Unicode string is found in UnicodeStringTable\r
	239	that matches the language code specified by Language, then it is returned in \r
	240	UnicodeString.\r
	241	\r
	242	@param Language A pointer to the ISO 639-2 language code for the \r
	243	Unicode string to look up and return.\r
	244	@param SupportedLanguages A pointer to the set of ISO 639-2 language codes \r
	245	that the Unicode string table supports. Language \r
	246	must be a member of this set.\r
	247	@param UnicodeStringTable A pointer to the table of Unicode strings.\r
	248	@param UnicodeString A pointer to the Unicode string from UnicodeStringTable\r
	249	that matches the language specified by Language.\r
	250	\r
	251	@retval EFI_SUCCESS The Unicode string that matches the language \r
	252	specified by Language was found\r
	253	in the table of Unicoide strings UnicodeStringTable, \r
	254	and it was returned in UnicodeString.\r
	255	@retval EFI_INVALID_PARAMETER Language is NULL.\r
	256	@retval EFI_INVALID_PARAMETER UnicodeString is NULL.\r
	257	@retval EFI_UNSUPPORTED SupportedLanguages is NULL.\r
	258	@retval EFI_UNSUPPORTED UnicodeStringTable is NULL.\r
	259	@retval EFI_UNSUPPORTED The language specified by Language is not a \r
	260	member of SupportedLanguages.\r
	261	@retval EFI_UNSUPPORTED The language specified by Language is not \r
	262	supported by UnicodeStringTable.\r
	263	\r
	264	**/\r
	265	EFI_STATUS\r
	266	EFIAPI\r
	267	LookupUnicodeString (\r
	268	IN CONST CHAR8 *Language,\r
	269	IN CONST CHAR8 *SupportedLanguages,\r
	270	IN CONST EFI_UNICODE_STRING_TABLE *UnicodeStringTable,\r
	271	OUT CHAR16 **UnicodeString\r
	272	);\r
	273	\r
	274	/**\r
	275	This function adds a Unicode string to UnicodeStringTable.\r
	276	If Language is a member of SupportedLanguages then UnicodeString is added to \r
	277	UnicodeStringTable. New buffers are allocated for both Language and \r
	278	UnicodeString. The contents of Language and UnicodeString are copied into \r
	279	these new buffers. These buffers are automatically freed when \r
	280	FreeUnicodeStringTable() is called.\r
	281	\r
	282	@param Language A pointer to the ISO 639-2 language code for the Unicode \r
	283	string to add.\r
	284	@param SupportedLanguages A pointer to the set of ISO 639-2 language codes\r
	285	that the Unicode string table supports.\r
	286	Language must be a member of this set.\r
	287	@param UnicodeStringTable A pointer to the table of Unicode strings.\r
	288	@param UnicodeString A pointer to the Unicode string to add.\r
289	\r
290	@retval EFI_SUCCESS The Unicode string that matches the language \r
291	specified by Language was found in the table of \r
292	Unicode strings UnicodeStringTable, and it was \r
293	returned in UnicodeString.\r
294	@retval EFI_INVALID_PARAMETER Language is NULL.\r
295	@retval EFI_INVALID_PARAMETER UnicodeString is NULL.\r
296	@retval EFI_INVALID_PARAMETER UnicodeString is an empty string.\r
297	@retval EFI_UNSUPPORTED SupportedLanguages is NULL.\r
298	@retval EFI_ALREADY_STARTED A Unicode string with language Language is \r
299	already present in UnicodeStringTable.\r
300	@retval EFI_OUT_OF_RESOURCES There is not enough memory to add another \r
301	Unicode string to UnicodeStringTable.\r
302	@retval EFI_UNSUPPORTED The language specified by Language is not a \r
303	member of SupportedLanguages.\r
304	\r
305	**/\r
306	EFI_STATUS\r
307	EFIAPI\r
308	AddUnicodeString (\r
309	IN CONST CHAR8 *Language,\r
310	IN CONST CHAR8 *SupportedLanguages,\r
311	IN EFI_UNICODE_STRING_TABLE **UnicodeStringTable,\r
312	IN CONST CHAR16 *UnicodeString\r
313	);\r
314	\r
315	/**\r
316	This function frees the table of Unicode strings in UnicodeStringTable.\r
317	If UnicodeStringTable is NULL, then EFI_SUCCESS is returned.\r
318	Otherwise, each language code, and each Unicode string in the Unicode string \r
319	table are freed, and EFI_SUCCESS is returned.\r
320	\r
321	@param UnicodeStringTable A pointer to the table of Unicode strings.\r
322	\r
323	@retval EFI_SUCCESS The Unicode string table was freed.\r
324	\r
325	**/\r
326	EFI_STATUS\r
327	EFIAPI\r
328	FreeUnicodeStringTable (\r
329	IN EFI_UNICODE_STRING_TABLE *UnicodeStringTable\r
330	);\r
331	\r
332	/**\r
333	This function computes and returns the width of the Unicode character \r
334	specified by UnicodeChar.\r
335	\r
336	@param UnicodeChar A Unicode character.\r
337	\r
338	@retval 0 The width if UnicodeChar could not be determined.\r
339	@retval 1 UnicodeChar is a narrow glyph.\r
340	@retval 2 UnicodeChar is a wide glyph.\r
341	\r
342	**/\r
343	UINTN\r
344	EFIAPI\r
345	GetGlyphWidth (\r
346	IN CHAR16 UnicodeChar\r
347	);\r
348	\r
349	/**\r
350	This function computes and returns the display length of\r
351	the Null-terminated Unicode string specified by String.\r
352	If String is NULL, then 0 is returned.\r
353	If any of the widths of the Unicode characters in String\r
354	can not be determined, then 0 is returned.\r
355	\r
356	@param String A pointer to a Null-terminated Unicode string.\r
357	\r
358	@return The display length of the Null-terminated Unicode string specified by String.\r
359	\r
360	**/\r
361	UINTN\r
362	EFIAPI\r
363	UnicodeStringDisplayLength (\r
364	IN CONST CHAR16 *String\r
365	);\r
366	\r
367	//\r
368	// Functions that abstract early Framework contamination of UEFI.\r
369	//\r
370	/**\r
371	Signal a Ready to Boot Event. \r
372	\r
373	Create a Ready to Boot Event. Signal it and close it. This causes other \r
374	events of the same event group to be signaled in other modules. \r
375	\r
376	**/\r
377	VOID\r
378	EFIAPI\r
379	EfiSignalEventReadyToBoot (\r
380	VOID\r
381	);\r
382	\r
383	/**\r
384	Signal a Legacy Boot Event. \r
385	\r
386	Create a legacy Boot Event. Signal it and close it. This causes other \r
387	events of the same event group to be signaled in other modules. \r
388	\r
389	**/\r
390	VOID\r
391	EFIAPI\r
392	EfiSignalEventLegacyBoot (\r
393	VOID\r
394	);\r
395	\r
396	/**\r
397	Create a Legacy Boot Event. \r
398	\r
399	Tiano extended the CreateEvent Type enum to add a legacy boot event type. \r
400	This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was\r
401	added and now it's possible to not voilate the UEFI specification by \r
402	declaring a GUID for the legacy boot event class. This library supports\r
a537f148	403	the EDK/EFI 1.10 form and EDK II/UEFI 2.0 form and allows common code to \r
878ddf1f	404	work both ways.\r
	405	\r
	406	@param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).\r
	407	\r
	408	@retval EFI_SUCCESS Event was created.\r
	409	@retval Other Event was not created.\r
	410	\r
	411	**/\r
	412	EFI_STATUS\r
	413	EFIAPI\r
	414	EfiCreateEventLegacyBoot (\r
abea19db	415	OUT EFI_EVENT *LegacyBootEvent\r
878ddf1f	416	);\r
878ddf1f	417	\r
9a462b41	418	/**\r
	419	Create an EFI event in the Legacy Boot Event Group and allows\r
	420	the caller to specify a notification function. \r
	421	\r
	422	This function abstracts the creation of the Legacy Boot Event.\r
	423	The Framework moved from a proprietary to UEFI 2.0 based mechanism.\r
	424	This library abstracts the caller from how this event is created to prevent\r
	425	to code form having to change with the version of the specification supported.\r
	426	If LegacyBootEvent is NULL, then ASSERT().\r
	427	\r
	428	@param NotifyTpl The task priority level of the event.\r
	429	@param NotifyFunction The notification function to call when the event is signaled.\r
	430	@param NotifyContext The content to pass to NotifyFunction when the event is signaled.\r
	431	@param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).\r
	432	\r
	433	@retval EFI_SUCCESS Event was created.\r
	434	@retval Other Event was not created.\r
	435	\r
	436	**/\r
	437	EFI_STATUS\r
	438	EFIAPI\r
	439	EfiCreateEventLegacyBootEx (\r
	440	IN EFI_TPL NotifyTpl,\r
	441	IN EFI_EVENT_NOTIFY NotifyFunction, OPTIONAL\r
	442	IN VOID *NotifyContext, OPTIONAL\r
	443	OUT EFI_EVENT *LegacyBootEvent\r
	444	);\r
	445	\r
878ddf1f	446	/**\r
	447	Create a Read to Boot Event. \r
	448	\r
	449	Tiano extended the CreateEvent Type enum to add a ready to boot event type. \r
	450	This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was\r
	451	added and now it's possible to not voilate the UEFI specification and use \r
	452	the ready to boot event class defined in UEFI 2.0. This library supports\r
a537f148	453	the EDK/EFI 1.10 form and EDKII/UEFI 2.0 form and allows common code to \r
878ddf1f	454	work both ways.\r
	455	\r
	456	@param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).\r
	457	\r
	458	@retval EFI_SUCCESS Event was created.\r
	459	@retval Other Event was not created.\r
	460	\r
	461	**/\r
	462	EFI_STATUS\r
	463	EFIAPI\r
	464	EfiCreateEventReadyToBoot (\r
abea19db	465	OUT EFI_EVENT *ReadyToBootEvent\r
878ddf1f	466	);\r
878ddf1f	467	\r
9a462b41	468	/**\r
	469	Create an EFI event in the Ready To Boot Event Group and allows\r
	470	the caller to specify a notification function. \r
	471	\r
	472	This function abstracts the creation of the Ready to Boot Event.\r
	473	The Framework moved from a proprietary to UEFI 2.0 based mechanism.\r
	474	This library abstracts the caller from how this event is created to prevent\r
	475	to code form having to change with the version of the specification supported.\r
	476	If ReadyToBootEvent is NULL, then ASSERT().\r
	477	\r
	478	@param NotifyTpl The task priority level of the event.\r
	479	@param NotifyFunction The notification function to call when the event is signaled.\r
	480	@param NotifyContext The content to pass to NotifyFunction when the event is signaled.\r
	481	@param LegacyBootEvent Returns the EFI event returned from gBS->CreateEvent(Ex).\r
	482	\r
	483	@retval EFI_SUCCESS Event was created.\r
	484	@retval Other Event was not created.\r
	485	\r
	486	**/\r
	487	EFI_STATUS\r
	488	EFIAPI\r
	489	EfiCreateEventReadyToBootEx (\r
	490	IN EFI_TPL NotifyTpl,\r
	491	IN EFI_EVENT_NOTIFY NotifyFunction, OPTIONAL\r
	492	IN VOID *NotifyContext, OPTIONAL\r
	493	OUT EFI_EVENT *ReadyToBootEvent\r
	494	);\r
	495	\r
878ddf1f	496	/**\r
	497	Initialize a Firmware Volume (FV) Media Device Path node.\r
	498	\r
	499	Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum\r
	500	so as we move to UEFI 2.0 support we must use a mechanism that conforms with\r
	501	the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed \r
a537f148	502	device path is defined for Tiano extensions of device path. If the code \r
878ddf1f	503	is compiled to conform with the UEFI 2.0 specification use the new device path\r
	504	else use the old form for backwards compatability.\r
	505	\r
	506	@param FvDevicePathNode Pointer to a FV device path node to initialize\r
	507	@param NameGuid FV file name to use in FvDevicePathNode\r
	508	\r
	509	**/\r
	510	VOID\r
	511	EFIAPI\r
	512	EfiInitializeFwVolDevicepathNode (\r
abea19db	513	IN OUT MEDIA_FW_VOL_FILEPATH_DEVICE_PATH *FvDevicePathNode,\r
abea19db	514	IN CONST EFI_GUID *NameGuid\r
878ddf1f	515	);\r
	516	\r
	517	/**\r
	518	Check to see if the Firmware Volume (FV) Media Device Path is valid \r
	519	\r
	520	Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum\r
	521	so as we move to UEFI 2.0 support we must use a mechanism that conforms with\r
	522	the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed \r
a537f148	523	device path is defined for Tiano extensions of device path. If the code \r
878ddf1f	524	is compiled to conform with the UEFI 2.0 specification use the new device path\r
	525	else use the old form for backwards compatability. The return value to this\r
	526	function points to a location in FvDevicePathNode and it does not allocate\r
	527	new memory for the GUID pointer that is returned.\r
	528	\r
	529	@param FvDevicePathNode Pointer to FV device path to check.\r
	530	\r
	531	@retval NULL FvDevicePathNode is not valid.\r
	532	@retval Other FvDevicePathNode is valid and pointer to NameGuid was returned.\r
	533	\r
	534	**/\r
	535	EFI_GUID *\r
	536	EFIAPI\r
	537	EfiGetNameGuidFromFwVolDevicePathNode (\r
abea19db	538	IN CONST MEDIA_FW_VOL_FILEPATH_DEVICE_PATH *FvDevicePathNode\r
878ddf1f	539	);\r
	540	\r
	541	\r
	542	#endif\r