MdePkg/Include/Protocol/PiPcd.h

   1 /** @file
   2   Platform Configuration Database (PCD) Protocol defined in PI 1.2 Vol3
   3
   4   A platform database that contains a variety of current platform settings or
   5   directives that can be accessed by a driver or application.
   6   PI PCD protocol only provide the accessing interfaces for Dynamic-Ex type PCD.
   7
   8   Callers to this protocol must be at a TPL_APPLICATION task priority level.
   9   This is the base PCD service API that provides an abstraction for accessing configuration content in
  10   the platform. It a seamless mechanism for extracting information regardless of where the
  11   information is stored (such as in Read-only data, or an EFI Variable).
  12   This protocol allows access to data through size-granular APIs and provides a mechanism for a
  13   firmware component to monitor specific settings and be alerted when a setting is changed.
  14
  15   Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR>
  16   This program and the accompanying materials
  17   are licensed and made available under the terms and conditions of the BSD License
  18   which accompanies this distribution.  The full text of the license may be found at
  19   http://opensource.org/licenses/bsd-license.php
  20
  21   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  22   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  23
  24   @par Revision Reference:
  25   PI Version 1.2 Vol 3.
  26 **/
  27
  28 #ifndef __PI_PCD_H__
  29 #define __PI_PCD_H__
  30
  31 extern EFI_GUID gEfiPcdProtocolGuid;
  32
  33 #define EFI_PCD_PROTOCOL_GUID \
  34   { 0x13a3f0f6, 0x264a, 0x3ef0, { 0xf2, 0xe0, 0xde, 0xc5, 0x12, 0x34, 0x2f, 0x34 } }
  35
  36 #define EFI_PCD_INVALID_TOKEN_NUMBER ((UINTN) 0)
  37
  38 /**
  39   SetSku() sets the SKU Id to be used for subsequent calls to set or get PCD values. SetSku() is
  40   normally called only once by the system.
  41   For each item (token), the database can hold a single value that applies to all SKUs, or multiple
  42   values, where each value is associated with a specific SKU Id. Items with multiple, SKU-specific
  43   values are called SKU enabled.
  44   The SKU Id of zero is reserved as a default. The valid SkuId range is 1 to 255. For tokens that are
  45   not SKU enabled, the system ignores any set SKU Id and works with the single value for that token.
  46   For SKU-enabled tokens, the system will use the SKU Id set by the last call to SetSku(). If no SKU
  47   Id is set or the currently set SKU Id isn't valid for the specified token, the system uses the default
  48   SKU Id. If the system attempts to use the default SKU Id and no value has been set for that Id, the
  49   results are unpredictable.
  50
  51   @param[in]  SkuId   The SKU value to set.
  52 **/
  53 typedef
  54 VOID
  55 (EFIAPI *EFI_PCD_PROTOCOL_SET_SKU)(
  56   IN UINTN SkuId
  57 );
  58
  59 /**
  60   Retrieves an 8-bit value for a given PCD token.
  61   If the TokenNumber is invalid, the results are unpredictable.
  62
  63   @param[in]    Guid        The 128-bit unique value that designates the namespace from which to extract the value.
  64   @param[in]    TokenNumber The PCD token number.
  65
  66   @return 8-bit value for a given PCD token.
  67 **/
  68 typedef
  69 UINT8
  70 (EFIAPI *EFI_PCD_PROTOCOL_GET_8)(
  71   IN CONST EFI_GUID   *Guid,
  72   IN       UINTN      TokenNumber
  73 );
  74
  75 /**
  76   Retrieves the current word-sized value for a PCD token number.
  77   If the TokenNumber is invalid, the results are unpredictable.
  78
  79   @param[in]    Guid        The 128-bit unique value that designates the namespace from which to extract the value.
  80   @param[in]    TokenNumber The PCD token number.
  81
  82   @return word-sized value for a given PCD token.
  83 **/
  84 typedef
  85 UINT16
  86 (EFIAPI *EFI_PCD_PROTOCOL_GET_16)(
  87   IN CONST  EFI_GUID  *Guid,
  88   IN        UINTN     TokenNumber
  89 );
  90
  91 /**
  92   Retrieves the current 32-bit sized value for a PCD token number.
  93   If the TokenNumber is invalid, the results are unpredictable.
  94
  95   @param[in]    Guid        The 128-bit unique value that designates the namespace from which to extract the value.
  96   @param[in]    TokenNumber The PCD token number.
  97
  98   @return 32-bit value for a given PCD token.
  99 **/
 100 typedef
 101 UINT32
 102 (EFIAPI *EFI_PCD_PROTOCOL_GET_32)(
 103   IN CONST  EFI_GUID  *Guid,
 104   IN        UINTN     TokenNumber
 105 );
 106
 107 /**
 108   Retrieves the 64-bit sized value for a PCD token number.
 109   If the TokenNumber is invalid, the results are unpredictable.
 110
 111   @param[in]    Guid        The 128-bit unique value that designates the namespace from which to extract the value.
 112   @param[in]    TokenNumber The PCD token number.
 113
 114   @return 64-bit value for a given PCD token.
 115
 116 **/
 117 typedef
 118 UINT64
 119 (EFIAPI *EFI_PCD_PROTOCOL_GET_64)(
 120   IN CONST  EFI_GUID  *Guid,
 121   IN        UINTN     TokenNumber
 122 );
 123
 124 /**
 125   Retrieves the current pointer to the value for a PCD token number. Do not make any assumptions
 126   about the alignment of the pointer that is returned by this function call. If the TokenNumber is
 127   invalid, the results are unpredictable.
 128
 129   @param[in]    Guid        The 128-bit unique value that designates the namespace from which to extract the value.
 130   @param[in]    TokenNumber The PCD token number.
 131
 132   @return pointer to a value for a given PCD token.
 133 **/
 134 typedef
 135 VOID *
 136 (EFIAPI *EFI_PCD_PROTOCOL_GET_POINTER)(
 137   IN CONST  EFI_GUID  *Guid,
 138   IN        UINTN     TokenNumber
 139 );
 140
 141 /**
 142   Retrieves the current BOOLEAN-sized value for a PCD token number. If the TokenNumber is
 143   invalid, the results are unpredictable.
 144
 145   @param[in]    Guid        The 128-bit unique value that designates the namespace from which to extract the value.
 146   @param[in]    TokenNumber The PCD token number.
 147
 148   @return Boolean value for a given PCD token.
 149 **/
 150 typedef
 151 BOOLEAN
 152 (EFIAPI *EFI_PCD_PROTOCOL_GET_BOOLEAN)(
 153   IN CONST  EFI_GUID  *Guid,
 154   IN        UINTN     TokenNumber
 155 );
 156
 157 /**
 158   Retrieves the current size of a particular PCD token. If the TokenNumber is invalid, the results are
 159   unpredictable.
 160
 161   @param[in]    Guid        The 128-bit unique value that designates the namespace from which to extract the value.
 162   @param[in]    TokenNumber The PCD token number.
 163
 164   @return the size of the value for a given PCD token.
 165 **/
 166 typedef
 167 UINTN
 168 (EFIAPI *EFI_PCD_PROTOCOL_GET_SIZE)(
 169   IN CONST  EFI_GUID  *Guid,
 170   IN        UINTN     TokenNumber
 171 );
 172
 173 /**
 174   Sets an 8-bit value for a given PCD token.
 175
 176   When the PCD service sets a value, it will check to ensure that the size of the value being set is
 177   compatible with the Token's existing definition. If it is not, an error will be returned.
 178
 179   @param[in]    Guid        The 128-bit unique value that designates the namespace from which to extract the value.
 180   @param[in]    TokenNumber The PCD token number.
 181   @param[in]    Value       The value to set for the PCD token.
 182
 183   @retval   EFI_SUCCESS             The PCD service has set the value requested
 184   @retval   EFI_INVALID_PARAMETER   The PCD service determined that the size of the data being set was
 185                                     incompatible with a call to this function. Use GetSizeEx() to
 186                                     retrieve the size of the target data.
 187   @retval   EFI_NOT_FOUND           The PCD service could not find the requested token number.
 188 **/
 189 typedef
 190 EFI_STATUS
 191 (EFIAPI *EFI_PCD_PROTOCOL_SET_8)(
 192   IN CONST  EFI_GUID  *Guid,
 193   IN        UINTN     TokenNumber,
 194   IN        UINT8     Value
 195 );
 196
 197 /**
 198   Sets an 16-bit value for a given PCD token.
 199
 200   When the PCD service sets a value, it will check to ensure that the size of the value being set is
 201   compatible with the Token's existing definition. If it is not, an error will be returned.
 202
 203   @param[in]    Guid        The 128-bit unique value that designates the namespace from which to extract the value.
 204   @param[in]    TokenNumber The PCD token number.
 205   @param[in]    Value       The value to set for the PCD token.
 206
 207   @retval   EFI_SUCCESS             The PCD service has set the value requested
 208   @retval   EFI_INVALID_PARAMETER   The PCD service determined that the size of the data being set was
 209                                     incompatible with a call to this function. Use GetSizeEx() to
 210                                     retrieve the size of the target data.
 211   @retval   EFI_NOT_FOUND           The PCD service could not find the requested token number.
 212 **/
 213 typedef
 214 EFI_STATUS
 215 (EFIAPI *EFI_PCD_PROTOCOL_SET_16)(
 216   IN CONST  EFI_GUID  *Guid,
 217   IN        UINTN     TokenNumber,
 218   IN        UINT16    Value
 219 );
 220
 221 /**
 222   Sets an 32-bit value for a given PCD token.
 223
 224   When the PCD service sets a value, it will check to ensure that the size of the value being set is
 225   compatible with the Token's existing definition. If it is not, an error will be returned.
 226
 227   @param[in]    Guid        The 128-bit unique value that designates the namespace from which to extract the value.
 228   @param[in]    TokenNumber The PCD token number.
 229   @param[in]    Value       The value to set for the PCD token.
 230
 231   @retval   EFI_SUCCESS             The PCD service has set the value requested
 232   @retval   EFI_INVALID_PARAMETER   The PCD service determined that the size of the data being set was
 233                                     incompatible with a call to this function. Use GetSizeEx() to
 234                                     retrieve the size of the target data.
 235   @retval   EFI_NOT_FOUND           The PCD service could not find the requested token number.
 236 **/
 237 typedef
 238 EFI_STATUS
 239 (EFIAPI *EFI_PCD_PROTOCOL_SET_32)(
 240   IN CONST  EFI_GUID  *Guid,
 241   IN        UINTN     TokenNumber,
 242   IN        UINT32    Value
 243 );
 244
 245 /**
 246   Sets an 64-bit value for a given PCD token.
 247
 248   When the PCD service sets a value, it will check to ensure that the size of the value being set is
 249   compatible with the Token's existing definition. If it is not, an error will be returned.
 250
 251   @param[in]    Guid        The 128-bit unique value that designates the namespace from which to extract the value.
 252   @param[in]    TokenNumber The PCD token number.
 253   @param[in]    Value       The value to set for the PCD token.
 254
 255   @retval   EFI_SUCCESS             The PCD service has set the value requested
 256   @retval   EFI_INVALID_PARAMETER   The PCD service determined that the size of the data being set was
 257                                     incompatible with a call to this function. Use GetSizeEx() to
 258                                     retrieve the size of the target data.
 259   @retval   EFI_NOT_FOUND           The PCD service could not find the requested token number.
 260 **/
 261 typedef
 262 EFI_STATUS
 263 (EFIAPI *EFI_PCD_PROTOCOL_SET_64)(
 264   IN CONST  EFI_GUID  *Guid,
 265   IN        UINTN     TokenNumber,
 266   IN        UINT64    Value
 267 );
 268
 269 /**
 270   Sets a value of a specified size for a given PCD token.
 271
 272   When the PCD service sets a value, it will check to ensure that the size of the value being set is
 273   compatible with the Token's existing definition. If it is not, an error will be returned.
 274
 275   @param[in]    Guid        The 128-bit unique value that designates the namespace from which to extract the value.
 276   @param[in]    TokenNumber The PCD token number.
 277   @param[in]    SizeOfValue The length of the value being set for the PCD token. If too large of a length is
 278                             specified, upon return from this function the value of SizeOfValue will
 279                             reflect the maximum size for the PCD token.
 280   @param[in]    Buffer      A pointer to the buffer containing the value to set for the PCD token.
 281
 282   @retval   EFI_SUCCESS             The PCD service has set the value requested
 283   @retval   EFI_INVALID_PARAMETER   The PCD service determined that the size of the data being set was
 284                                     incompatible with a call to this function. Use GetSizeEx() to
 285                                     retrieve the size of the target data.
 286   @retval   EFI_NOT_FOUND           The PCD service could not find the requested token number.
 287 **/
 288 typedef
 289 EFI_STATUS
 290 (EFIAPI *EFI_PCD_PROTOCOL_SET_POINTER)(
 291   IN CONST  EFI_GUID  *Guid,
 292   IN        UINTN     TokenNumber,
 293   IN OUT    UINTN     *SizeOfValue,
 294   IN        VOID      *Buffer
 295 );
 296
 297 /**
 298   Sets a Boolean value for a given PCD token.
 299
 300   When the PCD service sets a value, it will check to ensure that the size of the value being set is
 301   compatible with the Token's existing definition. If it is not, an error will be returned.
 302
 303   @param[in]    Guid        The 128-bit unique value that designates the namespace from which to extract the value.
 304   @param[in]    TokenNumber The PCD token number.
 305   @param[in]    Value       The value to set for the PCD token.
 306
 307   @retval   EFI_SUCCESS             The PCD service has set the value requested
 308   @retval   EFI_INVALID_PARAMETER   The PCD service determined that the size of the data being set was
 309                                     incompatible with a call to this function. Use GetSizeEx() to
 310                                     retrieve the size of the target data.
 311   @retval   EFI_NOT_FOUND           The PCD service could not find the requested token number.
 312 **/
 313 typedef
 314 EFI_STATUS
 315 (EFIAPI *EFI_PCD_PROTOCOL_SET_BOOLEAN)(
 316   IN CONST  EFI_GUID  *Guid,
 317   IN        UINTN     TokenNumber,
 318   IN        BOOLEAN   Value
 319 );
 320
 321 typedef
 322 VOID
 323 (EFIAPI *EFI_PCD_PROTOCOL_CALLBACK)(
 324   IN     EFI_GUID *Guid           OPTIONAL,
 325   IN     UINTN    CallBackToken,
 326   IN OUT VOID     *TokenData,
 327   IN     UINTN    TokenDataSize
 328 );
 329
 330 /**
 331   Specifies a function to be called anytime the value of a designated token is changed.
 332
 333   @param[in]    Guid              The 128-bit unique value that designates the namespace from which to extract the value.
 334   @param[in]    CallBackToken     The PCD token number to monitor.
 335   @param[in]    CallBackFunction  The function prototype called when the value associated with the CallBackToken is set.
 336
 337   @retval EFI_SUCCESS     The PCD service has successfully established a call event for the CallBackToken requested.
 338   @retval EFI_NOT_FOUND   The PCD service could not find the referenced token number.
 339 **/
 340 typedef
 341 EFI_STATUS
 342 (EFIAPI *EFI_PCD_PROTOCOL_CALLBACK_ON_SET)(
 343   IN CONST  EFI_GUID                  *Guid           OPTIONAL,
 344   IN        UINTN                     CallBackToken,
 345   IN        EFI_PCD_PROTOCOL_CALLBACK CallBackFunction
 346 );
 347
 348 /**
 349   Cancels a callback function that was set through a previous call to the CallBackOnSet function.
 350
 351   @param[in]    Guid              The 128-bit unique value that designates the namespace from which to extract the value.
 352   @param[in]    CallBackToken     The PCD token number to monitor.
 353   @param[in]    CallBackFunction  The function prototype called when the value associated with the CallBackToken is set.
 354
 355   @retval EFI_SUCCESS     The PCD service has successfully established a call event for the CallBackToken requested.
 356   @retval EFI_NOT_FOUND   The PCD service could not find the referenced token number.
 357 **/
 358 typedef
 359 EFI_STATUS
 360 (EFIAPI *EFI_PCD_PROTOCOL_CANCEL_CALLBACK)(
 361   IN CONST  EFI_GUID                  *Guid OPTIONAL,
 362   IN        UINTN                     CallBackToken,
 363   IN        EFI_PCD_PROTOCOL_CALLBACK CallBackFunction
 364 );
 365
 366 /**
 367   Gets the next valid token number in a given namespace. This is useful since the PCD infrastructure
 368   contains a sparse list of token numbers, and one cannot a priori know what token numbers are valid
 369   in the database.
 370
 371   @param[in]    Guid              The 128-bit unique value that designates the namespace from which to retrieve the next token.
 372   @param[in]    TokenNumber       A pointer to the PCD token number to use to find the subsequent token number. To
 373                                   retrieve the "first" token, have the pointer reference a TokenNumber value of 0.
 374   @retval EFI_SUCCESS           The PCD service has retrieved the value requested
 375   @retval EFI_NOT_FOUND         The PCD service could not find data from the requested token number.
 376 **/
 377 typedef
 378 EFI_STATUS
 379 (EFIAPI *EFI_PCD_PROTOCOL_GET_NEXT_TOKEN)(
 380   IN CONST  EFI_GUID  *Guid, OPTIONAL
 381   IN        UINTN     *TokenNumber
 382 );
 383
 384 /**
 385   Gets the next valid token namespace for a given namespace. This is useful to traverse the valid
 386   token namespaces on a platform.
 387
 388   @param[in, out]   Guid    An indirect pointer to EFI_GUID. On input it designates a known token namespace
 389                             from which the search will start. On output, it designates the next valid token
 390                             namespace on the platform. If *Guid is NULL, then the GUID of the first token
 391                             space of the current platform is returned. If the search cannot locate the next valid
 392                             token namespace, an error is returned and the value of *Guid is undefined.
 393
 394   @retval   EFI_SUCCESS   The PCD service retrieved the value requested.
 395   @retval   EFI_NOT_FOUND The PCD service could not find the next valid token namespace.
 396 **/
 397 typedef
 398 EFI_STATUS
 399 (EFIAPI *EFI_PCD_PROTOCOL_GET_NEXT_TOKEN_SPACE)(
 400   IN OUT CONST EFI_GUID **Guid
 401 );
 402
 403 typedef struct _EFI_PCD_PROTOCOL {
 404   EFI_PCD_PROTOCOL_SET_SKU              SetSku;
 405   EFI_PCD_PROTOCOL_GET_8                Get8;
 406   EFI_PCD_PROTOCOL_GET_16               Get16;
 407   EFI_PCD_PROTOCOL_GET_32               Get32;
 408   EFI_PCD_PROTOCOL_GET_64               Get64;
 409   EFI_PCD_PROTOCOL_GET_POINTER          GetPtr;
 410   EFI_PCD_PROTOCOL_GET_BOOLEAN          GetBool;
 411   EFI_PCD_PROTOCOL_GET_SIZE             GetSize;
 412   EFI_PCD_PROTOCOL_SET_8                Set8;
 413   EFI_PCD_PROTOCOL_SET_16               Set16;
 414   EFI_PCD_PROTOCOL_SET_32               Set32;
 415   EFI_PCD_PROTOCOL_SET_64               Set64;
 416   EFI_PCD_PROTOCOL_SET_POINTER          SetPtr;
 417   EFI_PCD_PROTOCOL_SET_BOOLEAN          SetBool;
 418   EFI_PCD_PROTOCOL_CALLBACK_ON_SET      CallbackOnSet;
 419   EFI_PCD_PROTOCOL_CANCEL_CALLBACK      CancelCallback;
 420   EFI_PCD_PROTOCOL_GET_NEXT_TOKEN       GetNextToken;
 421   EFI_PCD_PROTOCOL_GET_NEXT_TOKEN_SPACE GetNextTokenSpace;
 422 } EFI_PCD_PROTOCOL;
 423
 424 #endif