EdkModulePkg/Library/EdkIfrSupportLib/IfrVariable.c

   1 /*++
   2
   3 Copyright (c) 2006, Intel Corporation
   4 All rights reserved. This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 Module Name:
  13   IfrVariable.c
  14
  15 Abstract:
  16   Variable/Map manipulations routines
  17
  18 --*/
  19
  20 VOID
  21 EfiLibHiiVariablePackGetMap (
  22   IN    EFI_HII_VARIABLE_PACK       *Pack,
  23   OUT   CHAR16                      **Name,  OPTIONAL
  24   OUT   EFI_GUID                    **Guid,  OPTIONAL
  25   OUT   UINT16                      *Id,     OPTIONAL
  26   OUT   VOID                        **Var,   OPTIONAL
  27   OUT   UINTN                       *Size    OPTIONAL
  28   )
  29 /*++
  30
  31 Routine Description:
  32
  33   Extracts a variable form a Pack.
  34
  35 Arguments:
  36
  37   Pack - List of variables
  38   Name - Name of the variable/map
  39   Guid - GUID of the variable/map
  40   Var  - Pointer to the variable/map
  41   Size - Size of the variable/map in bytes
  42
  43 Returns:
  44
  45   VOID
  46
  47 --*/
  48 {
  49   if (NULL != Name) {
  50     *Name = (VOID *) (Pack + 1);
  51   }
  52
  53   if (NULL != Guid) {
  54     *Guid = (EFI_GUID *)(UINTN)&Pack->VariableGuid;
  55   }
  56
  57
  58   if (NULL != Id) {
  59     *Id   = Pack->VariableId;
  60   }
  61
  62   if (NULL != Var) {
  63     *Var  = (VOID *) ((CHAR8 *) (Pack + 1) + Pack->VariableNameLength);
  64   }
  65
  66   if (NULL != Size) {
  67     *Size = Pack->Header.Length - sizeof (*Pack) - Pack->VariableNameLength;
  68   }
  69 }
  70
  71
  72 UINTN
  73 EfiLibHiiVariablePackListGetMapCnt (
  74   IN    EFI_HII_VARIABLE_PACK_LIST   *List
  75   )
  76
  77 /*++
  78
  79 Routine Description:
  80
  81   Finds a count of the variables/maps in the List.
  82
  83 Arguments:
  84
  85   List - List of variables
  86
  87 Returns:
  88
  89   UINTN - The number of map count.
  90
  91 --*/
  92
  93 {
  94   UINTN   Cnt = 0;
  95   while (NULL != List) {
  96     Cnt++;
  97     List = List->NextVariablePack;
  98   }
  99   return Cnt;
 100 }
 101
 102
 103 VOID
 104 EfiLibHiiVariablePackListForEachVar (
 105   IN    EFI_HII_VARIABLE_PACK_LIST               *List,
 106   IN    EFI_LIB_HII_VARIABLE_PACK_LIST_CALLBACK  *Callback
 107   )
 108 /*++
 109
 110 Routine Description:
 111
 112   Will iterate all variable/maps as appearing
 113   in List and for each, it will call the Callback.
 114
 115 Arguments:
 116
 117   List     - List of variables
 118   Callback - Routine to be called for each iterated variable.
 119
 120 Returns:
 121
 122   VOID
 123
 124 --*/
 125
 126 {
 127   CHAR16    *MapName;
 128   EFI_GUID  *MapGuid;
 129   UINT16    MapId;
 130   VOID      *Map;
 131   UINTN     MapSize;
 132
 133   while (NULL != List) {
 134     EfiLibHiiVariablePackGetMap (List->VariablePack, &MapName, &MapGuid, &MapId, &Map, &MapSize);
 135     //
 136     // call the callback
 137     //
 138     Callback (MapName, MapGuid, MapId, Map, MapSize);
 139     List = List->NextVariablePack;
 140   }
 141 }
 142
 143
 144 EFI_STATUS
 145 EfiLibHiiVariablePackListGetMapByIdx (
 146   IN    UINTN                       Idx,
 147   IN    EFI_HII_VARIABLE_PACK_LIST  *List,
 148   OUT   CHAR16                      **Name,  OPTIONAL
 149   OUT   EFI_GUID                    **Guid,  OPTIONAL
 150   OUT   UINT16                      *Id,     OPTIONAL
 151   OUT   VOID                        **Var,
 152   OUT   UINTN                       *Size
 153   )
 154
 155 /*++
 156
 157 Routine Description:
 158
 159   Finds a variable form List given
 160   the order number as appears in the List.
 161
 162 Arguments:
 163
 164   Idx  - The index of the variable/map to retrieve
 165   List - List of variables
 166   Name - Name of the variable/map
 167   Guid - GUID of the variable/map
 168   Var  - Pointer to the variable/map
 169   Size - Size of the variable/map in bytes
 170
 171 Returns:
 172
 173   EFI_SUCCESS   - Variable is found, OUT parameters are valid
 174   EFI_NOT_FOUND - Variable is not found, OUT parameters are not valid
 175
 176 --*/
 177 {
 178   CHAR16     *MapName;
 179   EFI_GUID   *MapGuid;
 180   UINT16     MapId;
 181   VOID       *Map;
 182   UINTN      MapSize;
 183
 184   while (NULL != List) {
 185     EfiLibHiiVariablePackGetMap (List->VariablePack, &MapName, &MapGuid, &MapId, &Map, &MapSize);
 186     if (0 == Idx--) {
 187       *Var  = Map;
 188       *Size = MapSize;
 189
 190       if (NULL != Name) {
 191         *Name = MapName;
 192       }
 193
 194       if (NULL != Guid) {
 195         *Guid = MapGuid;
 196       }
 197
 198       if (NULL != Id) {
 199         *Id   = MapId;
 200       }
 201
 202       return EFI_SUCCESS; // Map found
 203     }
 204     List = List->NextVariablePack;
 205   }
 206   //
 207   // If here, the map is not found
 208   //
 209   return EFI_NOT_FOUND;
 210 }
 211
 212
 213 EFI_STATUS
 214 EfiLibHiiVariablePackListGetMapById (
 215   IN    UINT16                        Id,
 216   IN    EFI_HII_VARIABLE_PACK_LIST    *List,
 217   OUT   CHAR16                        **Name,  OPTIONAL
 218   OUT   EFI_GUID                      **Guid,  OPTIONAL
 219   OUT   VOID                          **Var,
 220   OUT   UINTN                         *Size
 221   )
 222
 223 /*++
 224
 225 Routine Description:
 226
 227   Finds a variable form List given the
 228   order number as appears in the List.
 229
 230 Arguments:
 231
 232   Id   - The ID of the variable/map to retrieve
 233   List - List of variables
 234   Name - Name of the variable/map
 235   Guid - GUID of the variable/map
 236   Var  - Pointer to the variable/map
 237   Size - Size of the variable/map in bytes
 238
 239 Returns:
 240
 241   EFI_SUCCESS   - Variable is found, OUT parameters are valid
 242   EFI_NOT_FOUND - Variable is not found, OUT parameters are not valid
 243
 244 --*/
 245
 246 {
 247   CHAR16    *MapName;
 248   EFI_GUID  *MapGuid;
 249   UINT16    MapId;
 250   VOID      *Map;
 251   UINTN     MapSize;
 252
 253   while (NULL != List) {
 254     EfiLibHiiVariablePackGetMap (List->VariablePack, &MapName, &MapGuid, &MapId, &Map, &MapSize);
 255     if (MapId == Id) {
 256       *Var  = Map;
 257       *Size = MapSize;
 258       if (NULL != Name) {
 259          *Name = MapName;
 260       }
 261       if (NULL != Guid) {
 262         *Guid = MapGuid;
 263       }
 264       //
 265       // Map found
 266       //
 267       return EFI_SUCCESS;
 268     }
 269     List = List->NextVariablePack;
 270   }
 271   //
 272   // If here, the map is not found
 273   //
 274   return EFI_NOT_FOUND;
 275 }
 276
 277
 278 EFI_STATUS
 279 EfiLibHiiVariablePackListGetMap (
 280   IN    EFI_HII_VARIABLE_PACK_LIST   *List,
 281   IN    CHAR16                       *Name,
 282   IN    EFI_GUID                     *Guid,
 283   OUT   UINT16                       *Id,
 284   OUT   VOID                         **Var,
 285   OUT   UINTN                        *Size
 286   )
 287
 288 /*++
 289
 290 Routine Description:
 291
 292   Finds a variable form EFI_HII_VARIABLE_PACK_LIST given name and GUID.
 293
 294 Arguments:
 295
 296   List - List of variables
 297   Name - Name of the variable/map to be found
 298   Guid - GUID of the variable/map to be found
 299   Var  - Pointer to the variable/map found
 300   Size - Size of the variable/map in bytes found
 301
 302 Returns:
 303
 304   EFI_SUCCESS   - variable is found, OUT parameters are valid
 305   EFI_NOT_FOUND - variable is not found, OUT parameters are not valid
 306
 307 --*/
 308
 309 {
 310   VOID      *Map;
 311   UINTN     MapSize;
 312   UINT16    MapId;
 313   CHAR16    *MapName;
 314   EFI_GUID  *MapGuid;
 315
 316   while (NULL != List) {
 317     EfiLibHiiVariablePackGetMap (List->VariablePack, &MapName, &MapGuid, &MapId, &Map, &MapSize);
 318     if ((0 == StrCmp (Name, MapName)) && CompareGuid (Guid, MapGuid)) {
 319       *Id   = MapId;
 320       *Var  = Map;
 321       *Size = MapSize;
 322       return EFI_SUCCESS;
 323     }
 324     List = List->NextVariablePack;
 325   }
 326   //
 327   // If here, the map is not found
 328   //
 329   return EFI_NOT_FOUND;
 330 }
 331
 332 EFI_STATUS
 333 EfiLibHiiVariableRetrieveFromNv (
 334   IN  CHAR16                 *Name,
 335   IN  EFI_GUID               *Guid,
 336   IN  UINTN                   Size,
 337   OUT VOID                  **Var
 338   )
 339 /*++
 340
 341 Routine Description:
 342   Finds out if a variable of specific Name/Guid/Size exists in NV.
 343   If it does, it will retrieve it into the Var.
 344
 345 Arguments:
 346   Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
 347   Var              - Variable will be retrieved into buffer pointed by this pointer.
 348                      If pointing to NULL, the buffer will be allocated. Caller is responsible for releasing the buffer.
 349 Returns:
 350   EFI_SUCCESS    - The variable of exact Name/Guid/Size parameters was retrieved and written to Var.
 351   EFI_NOT_FOUND  - The variable of this Name/Guid was not found in the NV.
 352   EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.
 353
 354 --*/
 355 {
 356   EFI_STATUS                  Status;
 357   UINTN                       SizeNv;
 358
 359   //
 360   // Test for existence of the variable.
 361   //
 362   SizeNv = 0;
 363   Status = gRT->GetVariable (Name, Guid, NULL, &SizeNv, NULL);
 364   if (EFI_BUFFER_TOO_SMALL != Status) {
 365     ASSERT (EFI_SUCCESS != Status);
 366     return EFI_NOT_FOUND;
 367   }
 368   if (SizeNv != Size) {
 369     //
 370     // The variable is considered corrupt, as it has different size from expected.
 371     //
 372     return EFI_LOAD_ERROR;
 373   }
 374
 375   if (NULL == *Var) {
 376     *Var = AllocatePool (Size);
 377     ASSERT (NULL != *Var);
 378   }
 379   SizeNv = Size;
 380   //
 381   // Final read into the Var
 382   //
 383   Status = gRT->GetVariable (Name, Guid, NULL, &SizeNv, *Var);
 384   //
 385   // No tolerance for random failures. Such behavior is undetermined and not validated.
 386   //
 387   ASSERT_EFI_ERROR (Status);
 388   ASSERT (SizeNv == Size);
 389   return EFI_SUCCESS;
 390 }
 391
 392
 393
 394 EFI_STATUS
 395 EfiLibHiiVariableOverrideIfSuffix (
 396   IN  CHAR16                 *Suffix,
 397   IN  CHAR16                 *Name,
 398   IN  EFI_GUID               *Guid,
 399   IN  UINTN                   Size,
 400   OUT VOID                   *Var
 401   )
 402 /*++
 403
 404 Routine Description:
 405   Overrrides the variable with NV data if found.
 406   But it only does it if the Name ends with specified Suffix.
 407   For example, if Suffix="MyOverride" and the Name="XyzSetupMyOverride",
 408   the Suffix matches the end of Name, so the variable will be loaded from NV
 409   provided the variable exists and the GUID and Size matches.
 410
 411 Arguments:
 412   Suffix           - Suffix the Name should end with.
 413   Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
 414   Var              - Variable will be retrieved into this buffer.
 415                      Caller is responsible for providing storage of exactly Size size in bytes.
 416 Returns:
 417   EFI_SUCCESS           - The variable was overriden with NV variable of same Name/Guid/Size.
 418   EFI_INVALID_PARAMETER - The name of the variable does not end with <Suffix>.
 419   EFI_NOT_FOUND         - The variable of this Name/Guid was not found in the NV.
 420   EFI_LOAD_ERROR        - The variable in the NV was of different size, or NV API returned error.
 421
 422 --*/
 423 {
 424   UINTN         StrLength;
 425   UINTN         StrLenSuffix;
 426
 427   StrLength       = StrLen (Name);
 428   StrLenSuffix    = StrLen (Suffix);
 429   if ((StrLength <= StrLenSuffix) || (0 != StrCmp (Suffix, &Name[StrLength - StrLenSuffix]))) {
 430     //
 431     // Not ending with <Suffix>.
 432     //
 433     return EFI_INVALID_PARAMETER;
 434   }
 435   return EfiLibHiiVariableRetrieveFromNv (Name, Guid, Size, &Var);
 436 }
 437
 438 EFI_STATUS
 439 EfiLibHiiVariableOverrideBySuffix (
 440   IN  CHAR16                 *Suffix,
 441   IN  CHAR16                 *Name,
 442   IN  EFI_GUID               *Guid,
 443   IN  UINTN                   Size,
 444   OUT VOID                   *Var
 445   )
 446 /*++
 447
 448 Routine Description:
 449   Overrrides the variable with NV data if found.
 450   But it only does it if the NV contains the same variable with Name is appended with Suffix.
 451   For example, if Suffix="MyOverride" and the Name="XyzSetup",
 452   the Suffix will be appended to the end of Name, and the variable with Name="XyzSetupMyOverride"
 453   will be loaded from NV provided the variable exists and the GUID and Size matches.
 454
 455 Arguments:
 456   Suffix           - Suffix the variable will be appended with.
 457   Name, Guid, Size - Parameters of the variable to retrieve. Must match exactly.
 458   Var              - Variable will be retrieved into this buffer.
 459                      Caller is responsible for providing storage of exactly Size size in bytes.
 460
 461 Returns:
 462   EFI_SUCCESS    - The variable was overriden with NV variable of same Name/Guid/Size.
 463   EFI_NOT_FOUND  - The variable of this Name/Guid was not found in the NV.
 464   EFI_LOAD_ERROR - The variable in the NV was of different size, or NV API returned error.
 465
 466 --*/
 467 {
 468   EFI_STATUS    Status;
 469   CHAR16       *NameSuffixed;
 470
 471   //
 472   // enough to concatenate both strings.
 473   //
 474   NameSuffixed = AllocateZeroPool ((StrLen (Name) + StrLen (Suffix) + 1) * sizeof (CHAR16));
 475
 476   StrCpy (NameSuffixed, Name);
 477   StrCat (NameSuffixed, Suffix);
 478
 479   Status = EfiLibHiiVariableRetrieveFromNv (NameSuffixed, Guid, Size, &Var);
 480   gBS->FreePool (NameSuffixed);
 481
 482   return Status;
 483 }
 484