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, Intel Corporation
  16   All rights reserved. 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_EX_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_EX_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_EX_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_EX_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_EX_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_EX_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_EX_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_EX_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_EX_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_EX_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_EX_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.
 278   @param[in]    Buffer      A pointer to the buffer containing the value to set for the PCD token.
 279
 280   @retval   EFI_SUCCESS             The PCD service has set the value requested
 281   @retval   EFI_INVALID_PARAMETER   The PCD service determined that the size of the data being set was
 282                                     incompatible with a call to this function. Use GetSizeEx() to
 283                                     retrieve the size of the target data.
 284   @retval   EFI_NOT_FOUND           The PCD service could not find the requested token number.
 285 **/
 286 typedef
 287 EFI_STATUS
 288 (EFIAPI *EFI_PCD_PROTOCOL_SET_POINTER_EX)(
 289   IN CONST  EFI_GUID  *Guid,
 290   IN        UINTN     TokenNumber,
 291   IN        UINTN     SizeOfValue,
 292   IN        VOID      *Buffer
 293 );
 294
 295 /**
 296   Sets a Boolean value for a given PCD token.
 297
 298   When the PCD service sets a value, it will check to ensure that the size of the value being set is
 299   compatible with the Token's existing definition. If it is not, an error will be returned.
 300
 301   @param[in]    Guid        The 128-bit unique value that designates the namespace from which to extract the value.
 302   @param[in]    TokenNumber The PCD token number.
 303   @param[in]    Value       The value to set for the PCD token.
 304
 305   @retval   EFI_SUCCESS             The PCD service has set the value requested
 306   @retval   EFI_INVALID_PARAMETER   The PCD service determined that the size of the data being set was
 307                                     incompatible with a call to this function. Use GetSizeEx() to
 308                                     retrieve the size of the target data.
 309   @retval   EFI_NOT_FOUND           The PCD service could not find the requested token number.
 310 **/
 311 typedef
 312 EFI_STATUS
 313 (EFIAPI *EFI_PCD_PROTOCOL_SET_EX_BOOLEAN)(
 314   IN CONST  EFI_GUID  *Guid,
 315   IN        UINTN     TokenNumber,
 316   IN        BOOLEAN   Value
 317 );
 318
 319 typedef
 320 VOID
 321 (EFIAPI *EFI_PCD_PROTOCOL_CALLBACK)(
 322   IN EFI_GUID *Guid           OPTIONAL,
 323   IN UINTN    CallBackToken,
 324   IN VOID     *TokenData,
 325   IN UINTN    TokenDataSize
 326 );
 327
 328 /**
 329   Specifies a function to be called anytime the value of a designated token is changed.
 330
 331   @param[in]    Guid              The 128-bit unique value that designates the namespace from which to extract the value.
 332   @param[in]    CallBackToken     The PCD token number to monitor.
 333   @param[in]    CallBackFunction  The function prototype called when the value associated with the CallBackToken is set.
 334
 335   @retval EFI_SUCCESS     The PCD service has successfully established a call event for the CallBackToken requested.
 336   @retval EFI_NOT_FOUND   The PCD service could not find the referenced token number.
 337 **/
 338 typedef
 339 EFI_STATUS
 340 (EFIAPI *EFI_PCD_PROTOCOL_CALLBACK_ON_SET)(
 341   IN CONST  EFI_GUID                  *Guid           OPTIONAL,
 342   IN        UINTN                     CallBackToken,
 343   IN        EFI_PCD_PROTOCOL_CALLBACK CallBackFunction
 344 );
 345
 346 /**
 347   Cancels a callback function that was set through a previous call to the CallBackOnSet function.
 348
 349   @param[in]    Guid              The 128-bit unique value that designates the namespace from which to extract the value.
 350   @param[in]    CallBackToken     The PCD token number to monitor.
 351   @param[in]    CallBackFunction  The function prototype called when the value associated with the CallBackToken is set.
 352
 353   @retval EFI_SUCCESS     The PCD service has successfully established a call event for the CallBackToken requested.
 354   @retval EFI_NOT_FOUND   The PCD service could not find the referenced token number.
 355 **/
 356 typedef
 357 EFI_STATUS
 358 (EFIAPI *EFI_PCD_PROTOCOL_CANCEL_CALLBACK)(
 359   IN CONST  EFI_GUID                  *Guid OPTIONAL,
 360   IN        UINTN                     CallBackToken,
 361   IN        EFI_PCD_PROTOCOL_CALLBACK CallBackFunction
 362 );
 363
 364 /**
 365   Gets the next valid token number in a given namespace. This is useful since the PCD infrastructure
 366   contains a sparse list of token numbers, and one cannot a priori know what token numbers are valid
 367   in the database.
 368
 369   @param[in]    Guid              The 128-bit unique value that designates the namespace from which to retrieve the next token.
 370   @param[in]    TokenNumber       A pointer to the PCD token number to use to find the subsequent token number. To
 371                                   retrieve the "first" token, have the pointer reference a TokenNumber value of 0.
 372   @retval EFI_SUCCESS           The PCD service has retrieved the value requested
 373   @retval EFI_NOT_FOUND         The PCD service could not find data from the requested token number.
 374 **/
 375 typedef
 376 EFI_STATUS
 377 (EFIAPI *EFI_PCD_PROTOCOL_GET_NEXT_TOKEN)(
 378   IN CONST  EFI_GUID  *Guid, OPTIONAL
 379   IN        UINTN     *TokenNumber
 380 );
 381
 382 /**
 383   Gets the next valid token namespace for a given namespace. This is useful to traverse the valid
 384   token namespaces on a platform.
 385
 386   @param[in, out]   Guid    An indirect pointer to EFI_GUID. On input it designates a known token namespace
 387                             from which the search will start. On output, it designates the next valid token
 388                             namespace on the platform. If *Guid is NULL, then the GUID of the first token
 389                             space of the current platform is returned. If the search cannot locate the next valid
 390                             token namespace, an error is returned and the value of *Guid is undefined.
 391
 392   @retval   EFI_SUCCESS   The PCD service retrieved the value requested.
 393   @retval   EFI_NOT_FOUND The PCD service could not find the next valid token namespace.
 394 **/
 395 typedef
 396 EFI_STATUS
 397 (EFIAPI *EFI_PCD_PROTOCOL_GET_NEXT_TOKEN_SPACE)(
 398   IN OUT CONST EFI_GUID **Guid
 399 );
 400
 401 typedef struct _EFI_PCD_PROTOCOL {
 402   EFI_PCD_PROTOCOL_SET_SKU              SetSku;
 403   EFI_PCD_PROTOCOL_GET_EX_8             Get8Ex;
 404   EFI_PCD_PROTOCOL_GET_EX_16            Get16Ex;
 405   EFI_PCD_PROTOCOL_GET_EX_32            Get32Ex;
 406   EFI_PCD_PROTOCOL_GET_EX_64            Get64Ex;
 407   EFI_PCD_PROTOCOL_GET_EX_POINTER       GetPtrEx;
 408   EFI_PCD_PROTOCOL_GET_EX_BOOLEAN       GetBoolEx;
 409   EFI_PCD_PROTOCOL_GET_EX_SIZE          GetSizeEx;
 410   EFI_PCD_PROTOCOL_SET_EX_8             Set8Ex;
 411   EFI_PCD_PROTOCOL_SET_EX_16            Set16Ex;
 412   EFI_PCD_PROTOCOL_SET_EX_32            Set32Ex;
 413   EFI_PCD_PROTOCOL_SET_EX_64            Set64Ex;
 414   EFI_PCD_PROTOCOL_SET_EX_POINTER       SetPtrEx;
 415   EFI_PCD_PROTOCOL_SET_EX_BOOLEAN       SetBoolEx;
 416   EFI_PCD_PROTOCOL_CALLBACK_ON_SET      CallbackOnSet;
 417   EFI_PCD_PROTOCOL_CANCEL_CALLBACK      CancelCallback;
 418   EFI_PCD_PROTOCOL_GET_NEXT_TOKEN       GetNextToken;
 419   EFI_PCD_PROTOCOL_GET_NEXT_TOKEN_SPACE GetNextTokenSpace;
 420 } EFI_PCD_PROTOCOL;
 421
 422 #endif