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