Initial import.

[mirror_edk2.git] / MdePkg / Library / UefiLib / UefiLib.c

/** @file\r
  Mde UEFI library functions.\r
\r
  Copyright (c) 2006, Intel Corporation<BR>\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
  Module Name:  UefiLib.c\r
\r
**/\r
\r
/**\r
  Compare whether two names of languages are identical.\r
\r
  @param  Language1 Name of language 1.\r
  @param  Language2 Name of language 2.\r
\r
  @retval TRUE      Language 1 and language 2 are the same.\r
  @retval FALSE     Language 1 and language 2 are not the same.\r
\r
**/\r
BOOLEAN\r
CompareIso639LanguageCode (\r
  IN CONST CHAR8  *Language1,\r
  IN CONST CHAR8  *Language2\r
  )\r
{\r
  return (BOOLEAN) (ReadUnaligned24 ((CONST UINT32 *) Language1) == ReadUnaligned24 ((CONST UINT32 *) Language2));\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
  EFI_SYSTEM_TABLE  *SystemTable;\r
  UINTN             Index;\r
\r
  ASSERT (TableGuid != NULL);\r
  ASSERT (Table != NULL);\r
\r
  SystemTable = gST;\r
  *Table = NULL;\r
  for (Index = 0; Index < SystemTable->NumberOfTableEntries; Index++) {\r
    if (CompareGuid (TableGuid, &(SystemTable->ConfigurationTable[Index].VendorGuid))) {\r
      *Table = SystemTable->ConfigurationTable[Index].VendorTable;\r
      return EFI_SUCCESS;\r
    }\r
  }\r
\r
  return EFI_NOT_FOUND;\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
  EFI_STATUS  Status;\r
  EFI_EVENT   Event;\r
\r
  //\r
  // Create the event\r
  //\r
\r
  Status = gBS->CreateEvent (\r
                  EFI_EVENT_NOTIFY_SIGNAL,\r
                  NotifyTpl,\r
                  NotifyFunction,\r
                  NotifyContext,\r
                  &Event\r
                  );\r
  ASSERT_EFI_ERROR (Status);\r
\r
  //\r
  // Register for protocol notifactions on this event\r
  //\r
\r
  Status = gBS->RegisterProtocolNotify (\r
                  ProtocolGuid,\r
                  Event,\r
                  Registration\r
                  );\r
\r
  ASSERT_EFI_ERROR (Status);\r
\r
  //\r
  // Kick the event so we will perform an initial pass of\r
  // current installed drivers\r
  //\r
\r
  gBS->SignalEvent (Event);\r
  return Event;\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
  EFI_STATUS  Status;\r
  EFI_EVENT   Event;\r
  VOID        *RegistrationLocal;\r
\r
  //\r
  // Create event\r
  //\r
  Status = gBS->CreateEvent (\r
                  EFI_EVENT_NOTIFY_SIGNAL,\r
                  NotifyTpl,\r
                  NotifyFunction,\r
                  (VOID *) NotifyContext,\r
                  &Event\r
                  );\r
  ASSERT_EFI_ERROR (Status);\r
\r
  //\r
  // The Registration is not optional to RegisterProtocolNotify().\r
  // To make it optional to EfiNamedEventListen(), may need to substitute with a local.\r
  //\r
  if (Registration != NULL) {\r
    RegistrationLocal = Registration;\r
  } else {\r
    RegistrationLocal = &RegistrationLocal;\r
  }\r
\r
  //\r
  // Register for an installation of protocol interface\r
  //\r
\r
  Status = gBS->RegisterProtocolNotify (\r
                  (EFI_GUID *) Name,\r
                  Event,\r
                  RegistrationLocal\r
                  );\r
  ASSERT_EFI_ERROR (Status);\r
\r
  return EFI_SUCCESS;\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
  EFI_STATUS  Status;\r
  EFI_HANDLE  Handle;\r
\r
  Handle = NULL;\r
  Status = gBS->InstallProtocolInterface (\r
                  &Handle,\r
                  (EFI_GUID *) Name,\r
                  EFI_NATIVE_INTERFACE,\r
                  NULL\r
                  );\r
  ASSERT_EFI_ERROR (Status);\r
\r
  Status = gBS->UninstallProtocolInterface (\r
                  Handle,\r
                  (EFI_GUID *) Name,\r
                  NULL\r
                  );\r
  ASSERT_EFI_ERROR (Status);\r
\r
  return EFI_SUCCESS;\r
}\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
  ASSERT (Lock != NULL);\r
  ASSERT (Priority <= EFI_TPL_HIGH_LEVEL);\r
\r
  Lock->Tpl       = Priority;\r
  Lock->OwnerTpl  = EFI_TPL_APPLICATION;\r
  Lock->Lock      = EfiLockReleased ;\r
  return Lock;\r
}\r
\r
/**\r