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