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 425