MdePkg/Include/Library/PcdLib.h

   1 /** @file
   2 PCD Library Class Interface Declarations
   3
   4 Copyright (c) 2006, Intel Corporation
   5 All rights reserved. This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13
  14 Module Name: PcdLib.h
  15
  16 **/
  17
  18 #ifndef __PCD_LIB_H__
  19 #define __PCD_LIB_H__
  20
  21
  22 #define PcdToken(TokenName)  _PCD_TOKEN_##TokenName
  23
  24
  25 //
  26 // Feature Flag is in the form of a global constant
  27 //
  28 #define FeaturePcdGet(TokenName)     _gPcd_FixedAtBuild_##TokenName
  29
  30
  31 //
  32 // Fixed is fixed at build time
  33 //
  34 #define FixedPcdGet8(TokenName)     _gPcd_FixedAtBuild_##TokenName
  35 #define FixedPcdGet16(TokenName)    _gPcd_FixedAtBuild_##TokenName
  36 #define FixedPcdGet32(TokenName)    _gPcd_FixedAtBuild_##TokenName
  37 #define FixedPcdGet64(TokenName)    _gPcd_FixedAtBuild_##TokenName
  38 #define FixedPcdGetBool(TokenName)  _gPcd_FixedAtBuild_##TokenName
  39
  40
  41 //
  42 // BugBug: This works for strings, but not constants.
  43 //
  44 #define FixedPcdGetPtr(TokenName)    ((VOID *)_gPcd_FixedAtBuild_##TokenName)
  45
  46
  47 //
  48 // (Binary) Patch is in the form of a global variable
  49 //
  50 #define PatchPcdGet8(TokenName)     _gPcd_BinaryPatch_##TokenName
  51 #define PatchPcdGet16(TokenName)    _gPcd_BinaryPatch_##TokenName
  52 #define PatchPcdGet32(TokenName)    _gPcd_BinaryPatch_##TokenName
  53 #define PatchPcdGet64(TokenName)    _gPcd_BinaryPatch_##TokenName
  54 #define PatchPcdGetBool(TokenName)  _gPcd_BinaryPatch_##TokenName
  55 #define PatchPcdGetPtr(TokenName)   ((VOID *)_gPcd_BinaryPatch_##TokenName)
  56
  57
  58 //
  59 // Dynamic is via the protocol with only the TokenNumber as argument
  60 //  It can also be Patch or Fixed type based on a build option
  61 //
  62 #define PcdGet8(TokenName)          _PCD_MODE_8_##TokenName
  63 #define PcdGet16(TokenName)         _PCD_MODE_16_##TokenName
  64 #define PcdGet32(TokenName)         _PCD_MODE_32_##TokenName
  65 #define PcdGet64(TokenName)         _PCD_MODE_64_##TokenName
  66 #define PcdGetPtr(TokenName)        _PCD_MODE_PTR_##TokenName
  67 #define PcdGetBool(TokenName)       _PCD_MODE_BOOL_##TokenName
  68
  69
  70 //
  71 // Dynamic Ex is to support binary distribution
  72 //
  73 #define PcdGetEx8(Guid, TokenName)     LibPcdGetEx8 (Guid, _PCD_TOKEN_##TokenName)
  74 #define PcdGetEx16(Guid, TokenName)    LibPcdGetEx16 (Guid, _PCD_TOKEN_##TokenName)
  75 #define PcdGetEx32(Guid, TokenName)    LibPcdGetEx32 (Guid, _PCD_TOKEN_##TokenName)
  76 #define PcdGetEx64(Guid, TokenName)    LibPcdGetEx64 (Guid, _PCD_TOKEN_##TokenName)
  77 #define PcdGetExPtr(Guid, TokenName)   LibPcdGetExPtr (Guid, _PCD_TOKEN_##TokenName)
  78 #define PcdGetExBool(Guid, TokenName)  LibPcdGetExBool (Guid, _PCD_TOKEN_##TokenName)
  79
  80
  81 //
  82 // Dynamic Set
  83 //
  84 #define PcdSet8(TokenName, Value)       LibPcdSet8   (_PCD_TOKEN_##TokenName, Value)
  85 #define PcdSet16(TokenName, Value)      LibPcdSet16  (_PCD_TOKEN_##TokenName, Value)
  86 #define PcdSet32(TokenName, Value)      LibPcdSet32  (_PCD_TOKEN_##TokenName, Value)
  87 #define PcdSet64(TokenName, Value)      LibPcdSet64  (_PCD_TOKEN_##TokenName, Value)
  88 #define PcdSetPtr(TokenName, Value)     LibPcdSetPtr (_PCD_TOKEN_##TokenName, Value)
  89 #define PcdSetBool(TokenName, Value)    LibPcdSetBool(_PCD_TOKEN_##TokenName, Value)
  90
  91
  92 //
  93 // Dynamic Set Ex
  94 //
  95 #define PcdSetEx8   (Guid, TokenName, Value)      LibPcdSetEx8   (Guid, _PCD_TOKEN_##TokenName, Value)
  96 #define PcdSetEx16  (Guid, TokenName, Value)      LibPcdSetEx16  (Guid, _PCD_TOKEN_##TokenName, Value)
  97 #define PcdSetEx32  (Guid, TokenName, Value)      LibPcdSetEx32  (Guid, _PCD_TOKEN_##TokenName, Value)
  98 #define PcdSetEx64  (Guid, TokenName, Value)      LibPcdSetEx64  (Guid, _PCD_TOKEN_##TokenName, Value)
  99 #define PcdSetExPtr (Guid, TokenName, Value)      LibPcdSetExPtr (Guid, _PCD_TOKEN_##TokenName, Value)
 100 #define PcdSetExBool(Guid, TokenName, Value)      LibPcdSetExBool(Guid, _PCD_TOKEN_##TokenName, Value)
 101
 102
 103 /**
 104   Sets the current SKU in the PCD database to the value specified by SkuId.  SkuId is returned.
 105
 106   @param[in]  SkuId The SKU value that will be used when the PCD service will retrieve and
 107               set values associated with a PCD token.
 108
 109   @retval UINTN Return the SKU ID that just be set.
 110
 111 **/
 112 UINTN
 113 EFIAPI
 114 LibPcdSetSku (
 115   IN UINTN   SkuId
 116   );
 117
 118
 119 /**
 120   Returns the 8-bit value for the token specified by TokenNumber.
 121
 122   @param[in]  The PCD token number to retrieve a current value for.
 123
 124   @retval UINT8 Returns the 8-bit value for the token specified by TokenNumber.
 125
 126 **/
 127 UINT8
 128 EFIAPI
 129 LibPcdGet8 (
 130   IN UINTN  TokenNumber
 131   );
 132
 133
 134 /**
 135   Returns the 16-bit value for the token specified by TokenNumber.
 136
 137   @param[in]  The PCD token number to retrieve a current value for.
 138
 139   @retval UINT16 Returns the 16-bit value for the token specified by TokenNumber.
 140
 141 **/
 142 UINT16
 143 EFIAPI
 144 LibPcdGet16 (
 145   IN UINTN  TokenNumber
 146   );
 147
 148
 149 /**
 150   Returns the 32-bit value for the token specified by TokenNumber.
 151
 152   @param[in]  TokenNumber The PCD token number to retrieve a current value for.
 153
 154   @retval UINT32 Returns the 32-bit value for the token specified by TokenNumber.
 155
 156 **/
 157 UINT32
 158 EFIAPI
 159 LibPcdGet32 (
 160   IN UINTN  TokenNumber
 161   );
 162
 163
 164 /**
 165   Returns the 64-bit value for the token specified by TokenNumber.
 166
 167   @param[in]  TokenNumber The PCD token number to retrieve a current value for.
 168
 169   @retval UINT64 Returns the 64-bit value for the token specified by TokenNumber.
 170
 171 **/
 172 UINT64
 173 EFIAPI
 174 LibPcdGet64 (
 175   IN UINTN  TokenNumber
 176   );
 177
 178
 179 /**
 180   Returns the pointer to the buffer of the token specified by TokenNumber.
 181
 182   @param[in]  TokenNumber The PCD token number to retrieve a current value for.
 183
 184   @retval VOID* Returns the pointer to the token specified by TokenNumber.
 185
 186 **/
 187 VOID *
 188 EFIAPI
 189 LibPcdGetPtr (
 190   IN UINTN  TokenNumber
 191   );
 192
 193
 194 /**
 195   Returns the Boolean value of the token specified by TokenNumber.
 196
 197   @param[in]  TokenNumber The PCD token number to retrieve a current value for.
 198
 199   @retval BOOLEAN Returns the Boolean value of the token specified by TokenNumber.
 200
 201 **/
 202 BOOLEAN
 203 EFIAPI
 204 LibPcdGetBool (
 205   IN UINTN  TokenNumber
 206   );
 207
 208
 209 /**
 210   Returns the size of the token specified by TokenNumber.
 211
 212   @param[in]  TokenNumber The PCD token number to retrieve a current value for.
 213
 214   @retval UINTN Returns the size of the token specified by TokenNumber.
 215
 216 **/
 217 UINTN
 218 EFIAPI
 219 LibPcdGetSize (
 220   IN UINTN  TokenNumber
 221   );
 222
 223
 224 /**
 225   Returns the 8-bit value for the token specified by TokenNumber and Guid.
 226   If Guid is NULL, then ASSERT().
 227
 228   @param[in]  Guid Pointer to a 128-bit unique value that designates
 229               which namespace to retrieve a value from.
 230   @param[in]  TokenNumber The PCD token number to retrieve a current value for.
 231
 232   @retval UINT8 Return the UINT8.
 233
 234 **/
 235 UINT8
 236 EFIAPI
 237 LibPcdGetEx8 (
 238   IN CONST GUID        *Guid,
 239   IN UINTN             TokenNumber
 240   );
 241
 242
 243 /**
 244   Returns the 16-bit value for the token specified by TokenNumber and Guid.
 245   If Guid is NULL, then ASSERT().
 246
 247   @param[in]  Guid Pointer to a 128-bit unique value that designates
 248               which namespace to retrieve a value from.
 249   @param[in]  TokenNumber The PCD token number to retrieve a current value for.
 250
 251   @retval UINT16 Return the UINT16.
 252
 253 **/
 254 UINT16
 255 EFIAPI
 256 LibPcdGetEx16 (
 257   IN CONST GUID        *Guid,
 258   IN UINTN             TokenNumber
 259   );
 260
 261
 262 /**
 263   Returns the 32-bit value for the token specified by TokenNumber and Guid.
 264   If Guid is NULL, then ASSERT().
 265
 266   @param[in]  Guid Pointer to a 128-bit unique value that designates
 267               which namespace to retrieve a value from.
 268   @param[in]  TokenNumber The PCD token number to retrieve a current value for.
 269
 270   @retval UINT32 Return the UINT32.
 271
 272 **/
 273 UINT32
 274 EFIAPI
 275 LibPcdGetEx32 (
 276   IN CONST GUID        *Guid,
 277   IN UINTN             TokenNumber
 278   );
 279
 280
 281 /**
 282   Returns the 64-bit value for the token specified by TokenNumber and Guid.
 283   If Guid is NULL, then ASSERT().
 284
 285   @param[in]  Guid Pointer to a 128-bit unique value that designates
 286               which namespace to retrieve a value from.
 287   @param[in]  TokenNumber The PCD token number to retrieve a current value for.
 288
 289   @retval UINT64 Return the UINT64.
 290
 291 **/
 292 UINT64
 293 EFIAPI
 294 LibPcdGetEx64 (
 295   IN CONST GUID        *Guid,
 296   IN UINTN             TokenNumber
 297   );
 298
 299
 300 /**
 301   Returns the pointer to the buffer of token specified by TokenNumber and Guid.
 302   If Guid is NULL, then ASSERT().
 303
 304   @param[in]  Guid Pointer to a 128-bit unique value that designates
 305               which namespace to retrieve a value from.
 306   @param[in]  TokenNumber The PCD token number to retrieve a current value for.
 307
 308   @retval VOID* Return the VOID* pointer.
 309
 310 **/
 311 VOID *
 312 EFIAPI
 313 LibPcdGetExPtr (
 314   IN CONST GUID        *Guid,
 315   IN UINTN             TokenNumber
 316   );
 317
 318
 319 /**
 320   Returns the Boolean value of the token specified by TokenNumber and Guid.
 321   If Guid is NULL, then ASSERT().
 322
 323   @param[in]  Guid Pointer to a 128-bit unique value that designates
 324               which namespace to retrieve a value from.
 325   @param[in]  TokenNumber The PCD token number to retrieve a current value for.
 326
 327   @retval BOOLEAN Return the BOOLEAN.
 328
 329 **/
 330 BOOLEAN
 331 EFIAPI
 332 LibPcdGetExBool (
 333   IN CONST GUID        *Guid,
 334   IN UINTN             TokenNumber
 335   );
 336
 337
 338 /**
 339   Returns the size of the token specified by TokenNumber and Guid.
 340   If Guid is NULL, then ASSERT().
 341
 342   @param[in]  Guid Pointer to a 128-bit unique value that designates
 343               which namespace to retrieve a value from.
 344   @param[in]  TokenNumber The PCD token number to retrieve a current value for.
 345
 346   @retval UINTN Return the size.
 347
 348 **/
 349 UINTN
 350 EFIAPI
 351 LibPcdGetExSize (
 352   IN CONST GUID        *Guid,
 353   IN UINTN             TokenNumber
 354   );
 355
 356
 357 /**
 358   Sets the 8-bit value for the token specified by TokenNumber
 359   to the value specified by Value.  Value is returned.
 360
 361   @param[in]  TokenNumber The PCD token number to set a current value for.
 362   @param[in]  Value The 8-bit value to set.
 363
 364   @retval UINT8 Return the value been set.
 365
 366 **/
 367 UINT8
 368 EFIAPI
 369 LibPcdSet8 (
 370   IN UINTN             TokenNumber,
 371   IN UINT8             Value
 372   );
 373
 374
 375 /**
 376   Sets the 16-bit value for the token specified by TokenNumber
 377   to the value specified by Value.  Value is returned.
 378
 379   @param[in]  TokenNumber The PCD token number to set a current value for.
 380   @param[in]  Value The 16-bit value to set.
 381
 382   @retval UINT16 Return the value been set.
 383
 384 **/
 385 UINT16
 386 EFIAPI
 387 LibPcdSet16 (
 388   IN UINTN             TokenNumber,
 389   IN UINT16            Value
 390   );
 391
 392
 393 /**
 394   Sets the 32-bit value for the token specified by TokenNumber
 395   to the value specified by Value.  Value is returned.
 396
 397   @param[in]  TokenNumber The PCD token number to set a current value for.
 398   @param[in]  Value The 32-bit value to set.
 399
 400   @retval UINT32 Return the value been set.
 401
 402 **/
 403 UINT32
 404 EFIAPI
 405 LibPcdSet32 (
 406   IN UINTN             TokenNumber,
 407   IN UINT32            Value
 408   );
 409
 410
 411 /**
 412   Sets the 64-bit value for the token specified by TokenNumber
 413   to the value specified by Value.  Value is returned.
 414
 415   @param[in]  TokenNumber The PCD token number to set a current value for.
 416   @param[in]  Value The 64-bit value to set.
 417
 418   @retval UINT64 Return the value been set.
 419
 420 **/
 421 UINT64
 422 EFIAPI
 423 LibPcdSet64 (
 424   IN UINTN             TokenNumber,
 425   IN UINT64            Value
 426   );
 427
 428
 429 /**
 430   Sets a buffer for the token specified by TokenNumber to
 431   the value specified by Value.     Value is returned.
 432   If Value is NULL, then ASSERT().
 433
 434   @param[in]  TokenNumber The PCD token number to set a current value for.
 435   @param[in]  Value A pointer to the buffer to set.
 436
 437   @retval VOID* Return the pointer for the buffer been set.
 438
 439 **/
 440 VOID*
 441 EFIAPI
 442 LibPcdSetPtr (
 443   IN UINTN             TokenNumber,
 444   IN CONST VOID        *Value
 445   );
 446
 447
 448 /**
 449   Sets the Boolean value for the token specified by TokenNumber
 450   to the value specified by Value.  Value is returned.
 451
 452   @param[in]  TokenNumber The PCD token number to set a current value for.
 453   @param[in]  Value The boolean value to set.
 454
 455   @retval BOOLEAN Return the value been set.
 456
 457 **/
 458 BOOLEAN
 459 EFIAPI
 460 LibPcdSetBool (
 461   IN UINTN             TokenNumber,
 462   IN BOOLEAN           Value
 463   );
 464
 465
 466 /**
 467   Sets the 8-bit value for the token specified by TokenNumber and
 468   Guid to the value specified by Value. Value is returned.
 469   If Guid is NULL, then ASSERT().
 470
 471   @param[in]  Guid Pointer to a 128-bit unique value that
 472               designates which namespace to set a value from.
 473   @param[in]  TokenNumber The PCD token number to set a current value for.
 474   @param[in]  Value The 8-bit value to set.
 475
 476   @retval UINT8 Return the value been set.
 477
 478 **/
 479 UINT8
 480 EFIAPI
 481 LibPcdSetEx8 (
 482   IN CONST GUID        *Guid,
 483   IN UINTN             TokenNumber,
 484   IN UINT8             Value
 485   );
 486
 487
 488 /**
 489   Sets the 16-bit value for the token specified by TokenNumber and
 490   Guid to the value specified by Value. Value is returned.
 491   If Guid is NULL, then ASSERT().
 492
 493   @param[in]  Guid Pointer to a 128-bit unique value that
 494               designates which namespace to set a value from.
 495   @param[in]  TokenNumber The PCD token number to set a current value for.
 496   @param[in]  Value The 16-bit value to set.
 497
 498   @retval UINT8 Return the value been set.
 499
 500 **/
 501 UINT16
 502 EFIAPI
 503 LibPcdSetEx16 (
 504   IN CONST GUID        *Guid,
 505   IN UINTN             TokenNumber,
 506   IN UINT16            Value
 507   );
 508
 509
 510 /**
 511   Sets the 32-bit value for the token specified by TokenNumber and
 512   Guid to the value specified by Value. Value is returned.
 513   If Guid is NULL, then ASSERT().
 514
 515   @param[in]  Guid Pointer to a 128-bit unique value that
 516               designates which namespace to set a value from.
 517   @param[in]  TokenNumber The PCD token number to set a current value for.
 518   @param[in]  Value The 32-bit value to set.
 519
 520   @retval UINT32 Return the value been set.
 521
 522 **/
 523 UINT32
 524 EFIAPI
 525 LibPcdSetEx32 (
 526   IN CONST GUID        *Guid,
 527   IN UINTN             TokenNumber,
 528   IN UINT32            Value
 529   );
 530
 531
 532 /**
 533   Sets the 64-bit value for the token specified by TokenNumber and
 534   Guid to the value specified by Value. Value is returned.
 535   If Guid is NULL, then ASSERT().
 536
 537   @param[in]  Guid Pointer to a 128-bit unique value that
 538               designates which namespace to set a value from.
 539   @param[in]  TokenNumber The PCD token number to set a current value for.
 540   @param[in]  Value The 64-bit value to set.
 541
 542   @retval UINT64 Return the value been set.
 543
 544 **/
 545 UINT64
 546 EFIAPI
 547 LibPcdSetEx64 (
 548   IN CONST GUID        *Guid,
 549   IN UINTN             TokenNumber,
 550   IN UINT64            Value
 551   );
 552
 553
 554 /**
 555   Sets a buffer for the token specified by TokenNumber and
 556   Guid to the value specified by Value. Value is returned.
 557   If Guid is NULL, then ASSERT().
 558   If Value is NULL, then ASSERT().
 559
 560   @param[in]  Guid Pointer to a 128-bit unique value that
 561               designates which namespace to set a value from.
 562   @param[in]  TokenNumber The PCD token number to set a current value for.
 563   @param[in]  Value The 8-bit value to set.
 564
 565   @retval VOID * Return the value been set.
 566
 567 **/
 568 VOID *
 569 EFIAPI
 570 LibPcdSetExPtr (
 571   IN CONST GUID        *Guid,
 572   IN UINTN             TokenNumber,
 573   IN CONST VOID        *Value
 574   );
 575
 576
 577 /**
 578   Sets the Boolean value for the token specified by TokenNumber and
 579   Guid to the value specified by Value. Value is returned.
 580   If Guid is NULL, then ASSERT().
 581
 582   @param[in]  Guid Pointer to a 128-bit unique value that
 583               designates which namespace to set a value from.
 584   @param[in]  TokenNumber The PCD token number to set a current value for.
 585   @param[in]  Value The Boolean value to set.
 586
 587   @retval Boolean Return the value been set.
 588
 589 **/
 590 BOOLEAN
 591 EFIAPI
 592 LibPcdSetExBool (
 593   IN CONST GUID        *Guid,
 594   IN UINTN             TokenNumber,
 595   IN BOOLEAN           Value
 596   );
 597
 598
 599 /**
 600   When the token specified by TokenNumber and Guid is set,
 601   then notification function specified by NotificationFunction is called.
 602   If Guid is NULL, then the default token space is used.
 603   If NotificationFunction is NULL, then ASSERT().
 604
 605   @param[in]  CallBackGuid The PCD token GUID being set.
 606   @param[in]  CallBackToken The PCD token number being set.
 607   @param[in]  TokenData A pointer to the token data being set.
 608   @param[in]  TokenDataSize The size, in bytes, of the data being set.
 609
 610   @retval VOID
 611
 612 **/
 613 typedef
 614 VOID
 615 (EFIAPI *PCD_CALLBACK) (
 616   IN  CONST GUID   *CallBackGuid, OPTIONAL
 617   IN  UINTN        CallBackToken,
 618   IN  VOID         *TokenData,
 619   IN  UINTN        TokenDataSize
 620   );
 621
 622
 623 /**
 624   When the token specified by TokenNumber and Guid is set,
 625   then notification function specified by NotificationFunction is called.
 626   If Guid is NULL, then the default token space is used.
 627   If NotificationFunction is NULL, then ASSERT().
 628
 629   @param[in]  Guid Pointer to a 128-bit unique value that designates which
 630               namespace to set a value from.  If NULL, then the default
 631               token space is used.
 632   @param[in]  TokenNumber The PCD token number to monitor.
 633   @param[in]  NotificationFunction The function to call when the token
 634               specified by Guid and TokenNumber is set.
 635
 636   @retval VOID
 637
 638 **/
 639 VOID
 640 EFIAPI
 641 LibPcdCallbackOnSet (
 642   IN CONST GUID               *Guid,       OPTIONAL
 643   IN UINTN                    TokenNumber,
 644   IN PCD_CALLBACK             NotificationFunction
 645   );
 646
 647
 648 /**
 649   Disable a notification function that was established with LibPcdCallbackonSet().
 650
 651   @param[in]  Guid Specify the GUID token space.
 652   @param[in]  TokenNumber Specify the token number.
 653   @param[in]  NotificationFunction The callback function to be unregistered.
 654
 655   @retval VOID
 656
 657 **/
 658 VOID
 659 EFIAPI
 660 LibPcdCancelCallback (
 661   IN CONST GUID               *Guid,       OPTIONAL
 662   IN UINTN                    TokenNumber,
 663   IN PCD_CALLBACK             NotificationFunction
 664   );
 665
 666
 667 /**
 668   Retrieves the next PCD token number from the token space specified by Guid.
 669   If Guid is NULL, then the default token space is used.  If TokenNumber is 0,
 670   then the first token number is returned.  Otherwise, the token number that
 671   follows TokenNumber in the token space is returned.  If TokenNumber is the last
 672   token number in the token space, then 0 is returned.  If TokenNumber is not 0 and
 673   is not in the token space specified by Guid, then ASSERT().
 674
 675   @param[in]  Pointer to a 128-bit unique value that designates which namespace
 676               to set a value from.  If NULL, then the default token space is used.
 677   @param[in]  The previous PCD token number.  If 0, then retrieves the first PCD
 678               token number.
 679
 680   @retval UINTN The next valid token number.
 681
 682 **/
 683 UINTN
 684 EFIAPI
 685 LibPcdGetNextToken (
 686   IN CONST GUID               *Guid,       OPTIONAL
 687   IN UINTN                    *TokenNumber
 688   );
 689
 690 #endif