MdePkg/Library/UefiLib/UefiNotTiano.c

   1 /** @file
   2   Library functions that abstract areas of conflict between framework and UEFI 2.0.
   3
   4   Help Port Framework code that has conflicts with UEFI 2.0 by hiding the
   5   old conflicts with library functions and supporting implementations of the old
   6   (EDK/EFI 1.10) and new (EDK II/UEFI 2.0) way. This module is a DXE driver as
   7   it contains DXE enum extensions for EFI event services.
   8
   9 Copyright (c) 2006 - 2007, Intel Corporation<BR>
  10 All rights reserved. This program and the accompanying materials
  11 are licensed and made available under the terms and conditions of the BSD License
  12 which accompanies this distribution.  The full text of the license may be found at
  13 http://opensource.org/licenses/bsd-license.php
  14
  15 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  16 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  17
  18 **/
  19
  20
  21
  22 #include "UefiLibInternal.h"
  23
  24 /**
  25   An empty function to pass error checking of CreateEventEx ().
  26
  27   This empty function ensures that EVT_NOTIFY_SIGNAL_ALL is error
  28   checked correctly since it is now mapped into CreateEventEx() in UEFI 2.0.
  29
  30   @param  Event                 Event whose notification function is being invoked.
  31   @param  Context               Pointer to the notification function's context,
  32                                 which is implementation-dependent.
  33
  34 **/
  35 VOID
  36 EFIAPI
  37 InternalEmptyFuntion (
  38   IN EFI_EVENT                Event,
  39   IN VOID                     *Context
  40   )
  41 {
  42   return;
  43 }
  44
  45 /**
  46   Create a Legacy Boot Event.
  47
  48   Tiano extended the CreateEvent Type enum to add a legacy boot event type.
  49   This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
  50   added and now it's possible to not voilate the UEFI specification by
  51   declaring a GUID for the legacy boot event class. This library supports
  52   the EDK/EFI 1.10 form and EDK II/UEFI 2.0 form and allows common code to
  53   work both ways.
  54
  55   @param  LegacyBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
  56
  57   @retval EFI_SUCCESS       Event was created.
  58   @retval Other             Event was not created.
  59
  60 **/
  61 EFI_STATUS
  62 EFIAPI
  63 EfiCreateEventLegacyBoot (
  64   OUT EFI_EVENT  *LegacyBootEvent
  65   )
  66 {
  67   return EfiCreateEventLegacyBootEx (
  68            TPL_CALLBACK,
  69            InternalEmptyFuntion,
  70            NULL,
  71            LegacyBootEvent
  72            );
  73 }
  74
  75 /**
  76   Create an EFI event in the Legacy Boot Event Group and allows
  77   the caller to specify a notification function.
  78
  79   This function abstracts the creation of the Legacy Boot Event.
  80   The Framework moved from a proprietary to UEFI 2.0 based mechanism.
  81   This library abstracts the caller from how this event is created to prevent
  82   to code form having to change with the version of the specification supported.
  83   If LegacyBootEvent is NULL, then ASSERT().
  84
  85   @param  NotifyTpl         The task priority level of the event.
  86   @param  NotifyFunction    The notification function to call when the event is signaled.
  87   @param  NotifyContext     The content to pass to NotifyFunction when the event is signaled.
  88   @param  LegacyBootEvent   Returns the EFI event returned from gBS->CreateEvent(Ex).
  89
  90   @retval EFI_SUCCESS       Event was created.
  91   @retval Other             Event was not created.
  92
  93 **/
  94 EFI_STATUS
  95 EFIAPI
  96 EfiCreateEventLegacyBootEx (
  97   IN  EFI_TPL           NotifyTpl,
  98   IN  EFI_EVENT_NOTIFY  NotifyFunction,  OPTIONAL
  99   IN  VOID              *NotifyContext,  OPTIONAL
 100   OUT EFI_EVENT         *LegacyBootEvent
 101   )
 102 {
 103   EFI_STATUS    Status;
 104
 105   ASSERT (LegacyBootEvent != NULL);
 106
 107   if (gST->Hdr.Revision < EFI_2_00_SYSTEM_TABLE_REVISION) {
 108     DEBUG ((EFI_D_ERROR, "EFI1.1 can't support LegacyBootEvent!"));
 109     ASSERT (FALSE);
 110
 111     return EFI_UNSUPPORTED;
 112   } else {
 113     //
 114     // For UEFI 2.0 and the future use an Event Group
 115     //
 116     Status = gBS->CreateEventEx (
 117                     EVT_NOTIFY_SIGNAL,
 118                     NotifyTpl,
 119                     NotifyFunction,
 120                     NotifyContext,
 121                     &gEfiEventLegacyBootGuid,
 122                     LegacyBootEvent
 123                     );
 124   }
 125
 126   return Status;
 127 }
 128
 129 /**
 130   Create a "Ready to Boot" Event.
 131
 132   Tiano extended the CreateEvent Type enum to add a ready to boot event type.
 133   This was bad as Tiano did not own the enum. In UEFI 2.0 CreateEventEx was
 134   added and now it's possible to not voilate the UEFI specification and use
 135   the ready to boot event class defined in UEFI 2.0. This library supports
 136   the EDK/EFI 1.10 form and EDK II/UEFI 2.0 form and allows common code to
 137   work both ways.
 138
 139   @param  ReadyToBootEvent  Returns the EFI event returned from gBS->CreateEvent(Ex).
 140
 141   @retval EFI_SUCCESS       Event was created.
 142   @retval Other             Event was not created.
 143
 144 **/
 145 EFI_STATUS
 146 EFIAPI
 147 EfiCreateEventReadyToBoot (
 148   OUT EFI_EVENT  *ReadyToBootEvent
 149   )
 150 {
 151   return EfiCreateEventReadyToBootEx (
 152            TPL_CALLBACK,
 153            InternalEmptyFuntion,
 154            NULL,
 155            ReadyToBootEvent
 156            );
 157 }
 158
 159 /**
 160   Create an EFI event in the Ready To Boot Event Group and allows
 161   the caller to specify a notification function.
 162
 163   This function abstracts the creation of the Ready to Boot Event.
 164   The Framework moved from a proprietary to UEFI 2.0 based mechanism.
 165   This library abstracts the caller from how this event is created to prevent
 166   to code form having to change with the version of the specification supported.
 167   If ReadyToBootEvent is NULL, then ASSERT().
 168
 169   @param  NotifyTpl         The task priority level of the event.
 170   @param  NotifyFunction    The notification function to call when the event is signaled.
 171   @param  NotifyContext     The content to pass to NotifyFunction when the event is signaled.
 172   @param  ReadyToBootEvent  Returns the EFI event returned from gBS->CreateEvent(Ex).
 173
 174   @retval EFI_SUCCESS       Event was created.
 175   @retval Other             Event was not created.
 176
 177 **/
 178 EFI_STATUS
 179 EFIAPI
 180 EfiCreateEventReadyToBootEx (
 181   IN  EFI_TPL           NotifyTpl,
 182   IN  EFI_EVENT_NOTIFY  NotifyFunction,  OPTIONAL
 183   IN  VOID              *NotifyContext,  OPTIONAL
 184   OUT EFI_EVENT         *ReadyToBootEvent
 185   )
 186 {
 187   EFI_STATUS    Status;
 188
 189   ASSERT (ReadyToBootEvent != NULL);
 190
 191   if (gST->Hdr.Revision < EFI_2_00_SYSTEM_TABLE_REVISION) {
 192     DEBUG ((EFI_D_ERROR, "EFI1.1 can't support ReadyToBootEvent!"));
 193     ASSERT (FALSE);
 194
 195     return EFI_UNSUPPORTED;
 196   } else {
 197     //
 198     // For UEFI 2.0 and the future use an Event Group
 199     //
 200     Status = gBS->CreateEventEx (
 201                     EVT_NOTIFY_SIGNAL,
 202                     NotifyTpl,
 203                     NotifyFunction,
 204                     NotifyContext,
 205                     &gEfiEventReadyToBootGuid,
 206                     ReadyToBootEvent
 207                     );
 208   }
 209
 210   return Status;
 211 }
 212
 213
 214 /**
 215   Signal a Ready to Boot Event.
 216
 217   Create a Ready to Boot Event. Signal it and close it. This causes other
 218   events of the same event group to be signaled in other modules.
 219
 220 **/
 221 VOID
 222 EFIAPI
 223 EfiSignalEventReadyToBoot (
 224   VOID
 225   )
 226 {
 227   EFI_STATUS    Status;
 228   EFI_EVENT     ReadyToBootEvent;
 229
 230   Status = EfiCreateEventReadyToBoot (&ReadyToBootEvent);
 231   if (!EFI_ERROR (Status)) {
 232     gBS->SignalEvent (ReadyToBootEvent);
 233     gBS->CloseEvent (ReadyToBootEvent);
 234   }
 235 }
 236
 237 /**
 238   Signal a Legacy Boot Event.
 239
 240   Create a legacy Boot Event. Signal it and close it. This causes other
 241   events of the same event group to be signaled in other modules.
 242
 243 **/
 244 VOID
 245 EFIAPI
 246 EfiSignalEventLegacyBoot (
 247   VOID
 248   )
 249 {
 250   EFI_STATUS    Status;
 251   EFI_EVENT     LegacyBootEvent;
 252
 253   Status = EfiCreateEventLegacyBoot (&LegacyBootEvent);
 254   if (!EFI_ERROR (Status)) {
 255     gBS->SignalEvent (LegacyBootEvent);
 256     gBS->CloseEvent (LegacyBootEvent);
 257   }
 258 }
 259
 260
 261 /**
 262   Check to see if the Firmware Volume (FV) Media Device Path is valid
 263
 264   Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum
 265   so as we move to UEFI 2.0 support we must use a mechanism that conforms with
 266   the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed
 267   device path is defined for Tiano extensions of device path. If the code
 268   is compiled to conform with the UEFI 2.0 specification use the new device path
 269   else use the old form for backwards compatability. The return value to this
 270   function points to a location in FvDevicePathNode and it does not allocate
 271   new memory for the GUID pointer that is returned.
 272   If FvDevicePathNode is NULL, then ASSERT().
 273
 274   @param  FvFileDevicePathNode  Pointer to FV device path to check.
 275
 276   @retval NULL              FvDevicePathNode is not valid.
 277   @retval Other             FvDevicePathNode is valid and pointer to NameGuid was returned.
 278
 279 **/
 280 EFI_GUID*
 281 EFIAPI
 282 EfiGetNameGuidFromFwVolDevicePathNode (
 283   IN CONST MEDIA_FW_VOL_FILEPATH_DEVICE_PATH  *FvFileDevicePathNode
 284   )
 285 {
 286   ASSERT (FvFileDevicePathNode != NULL);
 287
 288   if (DevicePathType (&FvFileDevicePathNode->Header) == MEDIA_DEVICE_PATH &&
 289       DevicePathSubType (&FvFileDevicePathNode->Header) == MEDIA_PIWG_FW_FILE_DP) {
 290     return (EFI_GUID *) &FvFileDevicePathNode->FvFileName;
 291   }
 292
 293   return NULL;
 294 }
 295
 296
 297 /**
 298   Initialize a Firmware Volume (FV) Media Device Path node.
 299
 300   Tiano extended the EFI 1.10 device path nodes. Tiano does not own this enum
 301   so as we move to UEFI 2.0 support we must use a mechanism that conforms with
 302   the UEFI 2.0 specification to define the FV device path. An UEFI GUIDed
 303   device path is defined for Tiano extensions of device path. If the code
 304   is compiled to conform with the UEFI 2.0 specification use the new device path
 305   else use the old form for backwards compatability.
 306   If FvDevicePathNode is NULL, then ASSERT().
 307   If NameGuid is NULL, then ASSERT().
 308
 309   @param  FvFileDevicePathNode  Pointer to a FV device path node to initialize
 310   @param  NameGuid          FV file name to use in FvDevicePathNode
 311
 312 **/
 313 VOID
 314 EFIAPI
 315 EfiInitializeFwVolDevicepathNode (
 316   IN OUT    MEDIA_FW_VOL_FILEPATH_DEVICE_PATH *FvFileDevicePathNode,
 317   IN CONST  EFI_GUID                          *NameGuid
 318   )
 319 {
 320   ASSERT (FvFileDevicePathNode  != NULL);
 321   ASSERT (NameGuid          != NULL);
 322
 323   //
 324   // Use the new Device path that does not conflict with the UEFI
 325   //
 326   FvFileDevicePathNode->Header.Type     = MEDIA_DEVICE_PATH;
 327   FvFileDevicePathNode->Header.SubType  = MEDIA_PIWG_FW_FILE_DP;
 328   SetDevicePathNodeLength (&FvFileDevicePathNode->Header, sizeof (MEDIA_FW_VOL_FILEPATH_DEVICE_PATH));
 329
 330   CopyGuid (&FvFileDevicePathNode->FvFileName, NameGuid);
 331 }
 332