MdeModulePkg PCD: Enable Firmware to retrieve the default setting
[mirror_edk2.git] / MdeModulePkg / Universal / PCD / Pei / Service.h
1 /** @file
2 The internal header file declares the private functions used by PeiPcd driver.
3
4 Copyright (c) 2006 - 2016, Intel Corporation. All rights reserved.<BR>
5 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
15 #ifndef _PEI_PCD_SERVICE_H_
16 #define _PEI_PCD_SERVICE_H_
17
18 #include <PiPei.h>
19 #include <Ppi/ReadOnlyVariable2.h>
20 #include <Ppi/Pcd.h>
21 #include <Ppi/PiPcd.h>
22 #include <Ppi/PcdInfo.h>
23 #include <Ppi/PiPcdInfo.h>
24 #include <Guid/PcdDataBaseHobGuid.h>
25 #include <Guid/PcdDataBaseSignatureGuid.h>
26 #include <Guid/VariableFormat.h>
27 #include <Library/DebugLib.h>
28 #include <Library/PeimEntryPoint.h>
29 #include <Library/BaseLib.h>
30 #include <Library/HobLib.h>
31 #include <Library/PeiServicesLib.h>
32 #include <Library/PcdLib.h>
33 #include <Library/BaseMemoryLib.h>
34 #include <Library/MemoryAllocationLib.h>
35
36 //
37 // Please make sure the PCD Serivce PEIM Version is consistent with
38 // the version of the generated PEIM PCD Database by build tool.
39 //
40 #define PCD_SERVICE_PEIM_VERSION 7
41
42 //
43 // PCD_PEI_SERVICE_DRIVER_VERSION is defined in Autogen.h.
44 //
45 #if (PCD_SERVICE_PEIM_VERSION != PCD_PEI_SERVICE_DRIVER_VERSION)
46 #error "Please make sure the version of PCD PEIM Service and the generated PCD PEI Database match."
47 #endif
48
49 /**
50 Retrieve additional information associated with a PCD token in the default token space.
51
52 This includes information such as the type of value the TokenNumber is associated with as well as possible
53 human readable name that is associated with the token.
54
55 @param[in] TokenNumber The PCD token number.
56 @param[out] PcdInfo The returned information associated with the requested TokenNumber.
57 The caller is responsible for freeing the buffer that is allocated by callee for PcdInfo->PcdName.
58
59 @retval EFI_SUCCESS The PCD information was returned successfully.
60 @retval EFI_NOT_FOUND The PCD service could not find the requested token number.
61 **/
62 EFI_STATUS
63 EFIAPI
64 PeiGetPcdInfoGetInfo (
65 IN UINTN TokenNumber,
66 OUT EFI_PCD_INFO *PcdInfo
67 );
68
69 /**
70 Retrieve additional information associated with a PCD token.
71
72 This includes information such as the type of value the TokenNumber is associated with as well as possible
73 human readable name that is associated with the token.
74
75 @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value.
76 @param[in] TokenNumber The PCD token number.
77 @param[out] PcdInfo The returned information associated with the requested TokenNumber.
78 The caller is responsible for freeing the buffer that is allocated by callee for PcdInfo->PcdName.
79
80 @retval EFI_SUCCESS The PCD information was returned successfully.
81 @retval EFI_NOT_FOUND The PCD service could not find the requested token number.
82 **/
83 EFI_STATUS
84 EFIAPI
85 PeiGetPcdInfoGetInfoEx (
86 IN CONST EFI_GUID *Guid,
87 IN UINTN TokenNumber,
88 OUT EFI_PCD_INFO *PcdInfo
89 );
90
91 /**
92 Retrieve the currently set SKU Id.
93
94 @return The currently set SKU Id. If the platform has not set at a SKU Id, then the
95 default SKU Id value of 0 is returned. If the platform has set a SKU Id, then the currently set SKU
96 Id is returned.
97 **/
98 UINTN
99 EFIAPI
100 PeiGetPcdInfoGetSku (
101 VOID
102 );
103
104 //
105 // PPI Interface Implementation Declaration.
106 //
107
108 /**
109 Sets the SKU value for subsequent calls to set or get PCD token values.
110
111 SetSku() sets the SKU Id to be used for subsequent calls to set or get PCD values.
112 SetSku() is normally called only once by the system.
113
114 For each item (token), the database can hold a single value that applies to all SKUs,
115 or multiple values, where each value is associated with a specific SKU Id. Items with multiple,
116 SKU-specific values are called SKU enabled.
117
118 The SKU Id of zero is reserved as a default. The valid SkuId range is 1 to 255.
119 For tokens that are not SKU enabled, the system ignores any set SKU Id and works with the
120 single value for that token. For SKU-enabled tokens, the system will use the SKU Id set by the
121 last call to SetSku(). If no SKU Id is set or the currently set SKU Id isn't valid for the specified token,
122 the system uses the default SKU Id. If the system attempts to use the default SKU Id and no value has been
123 set for that Id, the results are unpredictable.
124
125 @param[in] SkuId The SKU value that will be used when the PCD service will retrieve and
126 set values associated with a PCD token.
127
128 **/
129 VOID
130 EFIAPI
131 PeiPcdSetSku (
132 IN UINTN SkuId
133 );
134
135 /**
136 Retrieves an 8-bit value for a given PCD token.
137
138 Retrieves the current byte-sized value for a PCD token number.
139 If the TokenNumber is invalid, the results are unpredictable.
140
141 @param[in] TokenNumber The PCD token number.
142
143 @return The UINT8 value.
144
145 **/
146 UINT8
147 EFIAPI
148 PeiPcdGet8 (
149 IN UINTN TokenNumber
150 );
151
152 /**
153 Retrieves an 16-bit value for a given PCD token.
154
155 Retrieves the current 16-bits value for a PCD token number.
156 If the TokenNumber is invalid, the results are unpredictable.
157
158 @param[in] TokenNumber The PCD token number.
159
160 @return The UINT16 value.
161
162 **/
163 UINT16
164 EFIAPI
165 PeiPcdGet16 (
166 IN UINTN TokenNumber
167 );
168
169 /**
170 Retrieves an 32-bit value for a given PCD token.
171
172 Retrieves the current 32-bits value for a PCD token number.
173 If the TokenNumber is invalid, the results are unpredictable.
174
175 @param[in] TokenNumber The PCD token number.
176
177 @return The UINT32 value.
178
179 **/
180 UINT32
181 EFIAPI
182 PeiPcdGet32 (
183 IN UINTN TokenNumber
184 );
185
186 /**
187 Retrieves an 64-bit value for a given PCD token.
188
189 Retrieves the current 64-bits value for a PCD token number.
190 If the TokenNumber is invalid, the results are unpredictable.
191
192 @param[in] TokenNumber The PCD token number.
193
194 @return The UINT64 value.
195
196 **/
197 UINT64
198 EFIAPI
199 PeiPcdGet64 (
200 IN UINTN TokenNumber
201 );
202
203 /**
204 Retrieves a pointer to a value for a given PCD token.
205
206 Retrieves the current pointer to the buffer for a PCD token number.
207 Do not make any assumptions about the alignment of the pointer that
208 is returned by this function call. If the TokenNumber is invalid,
209 the results are unpredictable.
210
211 @param[in] TokenNumber The PCD token number.
212
213 @return The pointer to the buffer to be retrived.
214
215 **/
216 VOID *
217 EFIAPI
218 PeiPcdGetPtr (
219 IN UINTN TokenNumber
220 );
221
222 /**
223 Retrieves a Boolean value for a given PCD token.
224
225 Retrieves the current boolean value for a PCD token number.
226 Do not make any assumptions about the alignment of the pointer that
227 is returned by this function call. If the TokenNumber is invalid,
228 the results are unpredictable.
229
230 @param[in] TokenNumber The PCD token number.
231
232 @return The Boolean value.
233
234 **/
235 BOOLEAN
236 EFIAPI
237 PeiPcdGetBool (
238 IN UINTN TokenNumber
239 );
240
241 /**
242 Retrieves the size of the value for a given PCD token.
243
244 Retrieves the current size of a particular PCD token.
245 If the TokenNumber is invalid, the results are unpredictable.
246
247 @param[in] TokenNumber The PCD token number.
248
249 @return The size of the value for the PCD token.
250
251 **/
252 UINTN
253 EFIAPI
254 PeiPcdGetSize (
255 IN UINTN TokenNumber
256 );
257
258 /**
259 Retrieves an 8-bit value for a given PCD token.
260
261 Retrieves the 8-bit value of a particular PCD token.
262 If the TokenNumber is invalid or the token space
263 specified by Guid does not exist, the results are
264 unpredictable.
265
266 @param[in] Guid The token space for the token number.
267 @param[in] TokenNumber The PCD token number.
268
269 @return The size 8-bit value for the PCD token.
270
271 **/
272 UINT8
273 EFIAPI
274 PeiPcdGet8Ex (
275 IN CONST EFI_GUID *Guid,
276 IN UINTN TokenNumber
277 );
278
279 /**
280 Retrieves an 16-bit value for a given PCD token.
281
282 Retrieves the 16-bit value of a particular PCD token.
283 If the TokenNumber is invalid or the token space
284 specified by Guid does not exist, the results are
285 unpredictable.
286
287 @param[in] Guid The token space for the token number.
288 @param[in] TokenNumber The PCD token number.
289
290 @return The size 16-bit value for the PCD token.
291
292 **/
293 UINT16
294 EFIAPI
295 PeiPcdGet16Ex (
296 IN CONST EFI_GUID *Guid,
297 IN UINTN TokenNumber
298 );
299
300 /**
301 Retrieves an 32-bit value for a given PCD token.
302
303 Retrieves the 32-bit value of a particular PCD token.
304 If the TokenNumber is invalid or the token space
305 specified by Guid does not exist, the results are
306 unpredictable.
307
308 @param[in] Guid The token space for the token number.
309 @param[in] TokenNumber The PCD token number.
310
311 @return The size 32-bit value for the PCD token.
312
313 **/
314 UINT32
315 EFIAPI
316 PeiPcdGet32Ex (
317 IN CONST EFI_GUID *Guid,
318 IN UINTN TokenNumber
319 );
320
321 /**
322 Retrieves an 64-bit value for a given PCD token.
323
324 Retrieves the 64-bit value of a particular PCD token.
325 If the TokenNumber is invalid or the token space
326 specified by Guid does not exist, the results are
327 unpredictable.
328
329 @param[in] Guid The token space for the token number.
330 @param[in] TokenNumber The PCD token number.
331
332 @return The size 64-bit value for the PCD token.
333
334 **/
335 UINT64
336 EFIAPI
337 PeiPcdGet64Ex (
338 IN CONST EFI_GUID *Guid,
339 IN UINTN TokenNumber
340 );
341
342 /**
343 Retrieves a pointer to a value for a given PCD token.
344
345 Retrieves the current pointer to the buffer for a PCD token number.
346 Do not make any assumptions about the alignment of the pointer that
347 is returned by this function call. If the TokenNumber is invalid,
348 the results are unpredictable.
349
350 @param[in] Guid The token space for the token number.
351 @param[in] TokenNumber The PCD token number.
352
353 @return The pointer to the buffer to be retrived.
354
355 **/
356 VOID *
357 EFIAPI
358 PeiPcdGetPtrEx (
359 IN CONST EFI_GUID *Guid,
360 IN UINTN TokenNumber
361 );
362
363 /**
364 Retrieves an Boolean value for a given PCD token.
365
366 Retrieves the Boolean value of a particular PCD token.
367 If the TokenNumber is invalid or the token space
368 specified by Guid does not exist, the results are
369 unpredictable.
370
371 @param[in] Guid The token space for the token number.
372 @param[in] TokenNumber The PCD token number.
373
374 @return The size Boolean value for the PCD token.
375
376 **/
377 BOOLEAN
378 EFIAPI
379 PeiPcdGetBoolEx (
380 IN CONST EFI_GUID *Guid,
381 IN UINTN TokenNumber
382 );
383
384 /**
385 Retrieves the size of the value for a given PCD token.
386
387 Retrieves the current size of a particular PCD token.
388 If the TokenNumber is invalid, the results are unpredictable.
389
390 @param[in] Guid The token space for the token number.
391 @param[in] TokenNumber The PCD token number.
392
393 @return The size of the value for the PCD token.
394
395 **/
396 UINTN
397 EFIAPI
398 PeiPcdGetSizeEx (
399 IN CONST EFI_GUID *Guid,
400 IN UINTN TokenNumber
401 );
402
403 /**
404 Sets an 8-bit value for a given PCD token.
405
406 When the PCD service sets a value, it will check to ensure that the
407 size of the value being set is compatible with the Token's existing definition.
408 If it is not, an error will be returned.
409
410 @param[in] TokenNumber The PCD token number.
411 @param[in] Value The value to set for the PCD token.
412
413 @retval EFI_SUCCESS Procedure returned successfully.
414 @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data
415 being set was incompatible with a call to this function.
416 Use GetSize() to retrieve the size of the target data.
417 @retval EFI_NOT_FOUND The PCD service could not find the requested token number.
418
419 **/
420 EFI_STATUS
421 EFIAPI
422 PeiPcdSet8 (
423 IN UINTN TokenNumber,
424 IN UINT8 Value
425 );
426
427 /**
428 Sets an 16-bit value for a given PCD token.
429
430 When the PCD service sets a value, it will check to ensure that the
431 size of the value being set is compatible with the Token's existing definition.
432 If it is not, an error will be returned.
433
434 @param[in] TokenNumber The PCD token number.
435 @param[in] Value The value to set for the PCD token.
436
437 @retval EFI_SUCCESS Procedure returned successfully.
438 @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data
439 being set was incompatible with a call to this function.
440 Use GetSize() to retrieve the size of the target data.
441 @retval EFI_NOT_FOUND The PCD service could not find the requested token number.
442
443 **/
444 EFI_STATUS
445 EFIAPI
446 PeiPcdSet16 (
447 IN UINTN TokenNumber,
448 IN UINT16 Value
449 );
450
451 /**
452 Sets an 32-bit value for a given PCD token.
453
454 When the PCD service sets a value, it will check to ensure that the
455 size of the value being set is compatible with the Token's existing definition.
456 If it is not, an error will be returned.
457
458 @param[in] TokenNumber The PCD token number.
459 @param[in] Value The value to set for the PCD token.
460
461 @retval EFI_SUCCESS Procedure returned successfully.
462 @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data
463 being set was incompatible with a call to this function.
464 Use GetSize() to retrieve the size of the target data.
465 @retval EFI_NOT_FOUND The PCD service could not find the requested token number.
466
467 **/
468 EFI_STATUS
469 EFIAPI
470 PeiPcdSet32 (
471 IN UINTN TokenNumber,
472 IN UINT32 Value
473 );
474
475 /**
476 Sets an 64-bit value for a given PCD token.
477
478 When the PCD service sets a value, it will check to ensure that the
479 size of the value being set is compatible with the Token's existing definition.
480 If it is not, an error will be returned.
481
482 @param[in] TokenNumber The PCD token number.
483 @param[in] Value The value to set for the PCD token.
484
485 @retval EFI_SUCCESS Procedure returned successfully.
486 @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data
487 being set was incompatible with a call to this function.
488 Use GetSize() to retrieve the size of the target data.
489 @retval EFI_NOT_FOUND The PCD service could not find the requested token number.
490
491 **/
492 EFI_STATUS
493 EFIAPI
494 PeiPcdSet64 (
495 IN UINTN TokenNumber,
496 IN UINT64 Value
497 );
498
499 /**
500 Sets a value of a specified size for a given PCD token.
501
502 When the PCD service sets a value, it will check to ensure that the
503 size of the value being set is compatible with the Token's existing definition.
504 If it is not, an error will be returned.
505
506 @param[in] TokenNumber The PCD token number.
507 @param[in, out] SizeOfBuffer A pointer to the length of the value being set for the PCD token.
508 On input, if the SizeOfValue is greater than the maximum size supported
509 for this TokenNumber then the output value of SizeOfValue will reflect
510 the maximum size supported for this TokenNumber.
511 @param[in] Buffer The buffer to set for the PCD token.
512
513 @retval EFI_SUCCESS Procedure returned successfully.
514 @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data
515 being set was incompatible with a call to this function.
516 Use GetSize() to retrieve the size of the target data.
517 @retval EFI_NOT_FOUND The PCD service could not find the requested token number.
518
519 **/
520 EFI_STATUS
521 EFIAPI
522 PeiPcdSetPtr (
523 IN UINTN TokenNumber,
524 IN OUT UINTN *SizeOfBuffer,
525 IN VOID *Buffer
526 );
527
528 /**
529 Sets an Boolean value for a given PCD token.
530
531 When the PCD service sets a value, it will check to ensure that the
532 size of the value being set is compatible with the Token's existing definition.
533 If it is not, an error will be returned.
534
535 @param[in] TokenNumber The PCD token number.
536 @param[in] Value The value to set for the PCD token.
537
538 @retval EFI_SUCCESS Procedure returned successfully.
539 @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data
540 being set was incompatible with a call to this function.
541 Use GetSize() to retrieve the size of the target data.
542 @retval EFI_NOT_FOUND The PCD service could not find the requested token number.
543
544 **/
545 EFI_STATUS
546 EFIAPI
547 PeiPcdSetBool (
548 IN UINTN TokenNumber,
549 IN BOOLEAN Value
550 );
551
552 /**
553 Sets an 8-bit value for a given PCD token.
554
555 When the PCD service sets a value, it will check to ensure that the
556 size of the value being set is compatible with the Token's existing definition.
557 If it is not, an error will be returned.
558
559 @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value.
560 @param[in] TokenNumber The PCD token number.
561 @param[in] Value The value to set for the PCD token.
562
563 @retval EFI_SUCCESS Procedure returned successfully.
564 @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data
565 being set was incompatible with a call to this function.
566 Use GetSize() to retrieve the size of the target data.
567 @retval EFI_NOT_FOUND The PCD service could not find the requested token number.
568
569 **/
570 EFI_STATUS
571 EFIAPI
572 PeiPcdSet8Ex (
573 IN CONST EFI_GUID *Guid,
574 IN UINTN TokenNumber,
575 IN UINT8 Value
576 );
577
578 /**
579 Sets an 16-bit value for a given PCD token.
580
581 When the PCD service sets a value, it will check to ensure that the
582 size of the value being set is compatible with the Token's existing definition.
583 If it is not, an error will be returned.
584
585 @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value.
586 @param[in] TokenNumber The PCD token number.
587 @param[in] Value The value to set for the PCD token.
588
589 @retval EFI_SUCCESS Procedure returned successfully.
590 @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data
591 being set was incompatible with a call to this function.
592 Use GetSize() to retrieve the size of the target data.
593 @retval EFI_NOT_FOUND The PCD service could not find the requested token number.
594
595 **/
596 EFI_STATUS
597 EFIAPI
598 PeiPcdSet16Ex (
599 IN CONST EFI_GUID *Guid,
600 IN UINTN TokenNumber,
601 IN UINT16 Value
602 );
603
604 /**
605 Sets an 32-bit value for a given PCD token.
606
607 When the PCD service sets a value, it will check to ensure that the
608 size of the value being set is compatible with the Token's existing definition.
609 If it is not, an error will be returned.
610
611 @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value.
612 @param[in] TokenNumber The PCD token number.
613 @param[in] Value The value to set for the PCD token.
614
615 @retval EFI_SUCCESS Procedure returned successfully.
616 @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data
617 being set was incompatible with a call to this function.
618 Use GetSize() to retrieve the size of the target data.
619 @retval EFI_NOT_FOUND The PCD service could not find the requested token number.
620
621 **/
622 EFI_STATUS
623 EFIAPI
624 PeiPcdSet32Ex (
625 IN CONST EFI_GUID *Guid,
626 IN UINTN TokenNumber,
627 IN UINT32 Value
628 );
629
630 /**
631 Sets an 64-bit value for a given PCD token.
632
633 When the PCD service sets a value, it will check to ensure that the
634 size of the value being set is compatible with the Token's existing definition.
635 If it is not, an error will be returned.
636
637 @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value.
638 @param[in] TokenNumber The PCD token number.
639 @param[in] Value The value to set for the PCD token.
640
641 @retval EFI_SUCCESS Procedure returned successfully.
642 @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data
643 being set was incompatible with a call to this function.
644 Use GetSize() to retrieve the size of the target data.
645 @retval EFI_NOT_FOUND The PCD service could not find the requested token number.
646
647 **/
648 EFI_STATUS
649 EFIAPI
650 PeiPcdSet64Ex (
651 IN CONST EFI_GUID *Guid,
652 IN UINTN TokenNumber,
653 IN UINT64 Value
654 );
655
656 /**
657 Sets a value of a specified size for a given PCD token.
658
659 When the PCD service sets a value, it will check to ensure that the
660 size of the value being set is compatible with the Token's existing definition.
661 If it is not, an error will be returned.
662
663 @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value.
664 @param[in] TokenNumber The PCD token number.
665 @param[in, out] SizeOfBuffer A pointer to the length of the value being set for the PCD token.
666 On input, if the SizeOfValue is greater than the maximum size supported
667 for this TokenNumber then the output value of SizeOfValue will reflect
668 the maximum size supported for this TokenNumber.
669 @param[in] Buffer The buffer to set for the PCD token.
670
671 @retval EFI_SUCCESS Procedure returned successfully.
672 @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data
673 being set was incompatible with a call to this function.
674 Use GetSize() to retrieve the size of the target data.
675 @retval EFI_NOT_FOUND The PCD service could not find the requested token number.
676
677 **/
678 EFI_STATUS
679 EFIAPI
680 PeiPcdSetPtrEx (
681 IN CONST EFI_GUID *Guid,
682 IN UINTN TokenNumber,
683 IN OUT UINTN *SizeOfBuffer,
684 IN VOID *Buffer
685 );
686
687 /**
688 Sets an Boolean value for a given PCD token.
689
690 When the PCD service sets a value, it will check to ensure that the
691 size of the value being set is compatible with the Token's existing definition.
692 If it is not, an error will be returned.
693
694 @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value.
695 @param[in] TokenNumber The PCD token number.
696 @param[in] Value The value to set for the PCD token.
697
698 @retval EFI_SUCCESS Procedure returned successfully.
699 @retval EFI_INVALID_PARAMETER The PCD service determined that the size of the data
700 being set was incompatible with a call to this function.
701 Use GetSize() to retrieve the size of the target data.
702 @retval EFI_NOT_FOUND The PCD service could not find the requested token number.
703
704 **/
705 EFI_STATUS
706 EFIAPI
707 PeiPcdSetBoolEx (
708 IN CONST EFI_GUID *Guid,
709 IN UINTN TokenNumber,
710 IN BOOLEAN Value
711 );
712
713 /**
714 Specifies a function to be called anytime the value of a designated token is changed.
715
716 @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value.
717 @param[in] TokenNumber The PCD token number.
718 @param[in] CallBackFunction The function prototype called when the value associated with the CallBackToken is set.
719
720 @retval EFI_SUCCESS The PCD service has successfully established a call event
721 for the CallBackToken requested.
722 @retval EFI_NOT_FOUND The PCD service could not find the referenced token number.
723
724 **/
725 EFI_STATUS
726 EFIAPI
727 PeiRegisterCallBackOnSet (
728 IN CONST EFI_GUID *Guid, OPTIONAL
729 IN UINTN TokenNumber,
730 IN PCD_PPI_CALLBACK CallBackFunction
731 );
732
733 /**
734 Cancels a previously set callback function for a particular PCD token number.
735
736 @param [in] Guid The 128-bit unique value that designates the namespace from which to extract the value.
737 @param [in] TokenNumber The PCD token number.
738 @param [in] CallBackFunction The function prototype called when the value associated with the CallBackToken is set.
739
740 @retval EFI_SUCCESS The PCD service has successfully established a call event
741 for the CallBackToken requested.
742 @retval EFI_NOT_FOUND The PCD service could not find the referenced token number.
743
744 **/
745 EFI_STATUS
746 EFIAPI
747 PcdUnRegisterCallBackOnSet (
748 IN CONST EFI_GUID *Guid, OPTIONAL
749 IN UINTN TokenNumber,
750 IN PCD_PPI_CALLBACK CallBackFunction
751 );
752
753 /**
754 Retrieves the next valid token number in a given namespace.
755
756 This is useful since the PCD infrastructure contains a sparse list of token numbers,
757 and one cannot a priori know what token numbers are valid in the database.
758
759 If TokenNumber is 0 and Guid is not NULL, then the first token from the token space specified by Guid is returned.
760 If TokenNumber is not 0 and Guid is not NULL, then the next token in the token space specified by Guid is returned.
761 If TokenNumber is 0 and Guid is NULL, then the first token in the default token space is returned.
762 If TokenNumber is not 0 and Guid is NULL, then the next token in the default token space is returned.
763 The token numbers in the default token space may not be related to token numbers in token spaces that are named by Guid.
764 If the next token number can be retrieved, then it is returned in TokenNumber, and EFI_SUCCESS is returned.
765 If TokenNumber represents the last token number in the token space specified by Guid, then EFI_NOT_FOUND is returned.
766 If TokenNumber is not present in the token space specified by Guid, then EFI_NOT_FOUND is returned.
767
768
769 @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value.
770 This is an optional parameter that may be NULL. If this parameter is NULL, then a request
771 is being made to retrieve tokens from the default token space.
772 @param[in, out] TokenNumber A pointer to the PCD token number to use to find the subsequent token number.
773
774 @retval EFI_SUCCESS The PCD service has retrieved the next valid token number.
775 Or the input token number is already the last valid token number in the PCD database.
776 In the later case, *TokenNumber is updated with the value of 0.
777 @retval EFI_NOT_FOUND If this input token number and token namespace does not exist on the platform.
778
779 **/
780 EFI_STATUS
781 EFIAPI
782 PeiPcdGetNextToken (
783 IN CONST EFI_GUID *Guid, OPTIONAL
784 IN OUT UINTN *TokenNumber
785 );
786
787 /**
788 Retrieves the next valid PCD token namespace for a given namespace.
789
790 @param[in, out] Guid An indirect pointer to EFI_GUID. On input it designates
791 a known token namespace from which the search will start. On output,
792 it designates the next valid token namespace on the platform. If the input
793 token namespace does not exist on the platform, an error is returned and
794 the value of *Guid is undefined. If *Guid is NULL, then the GUID of the
795 first token space of the current platform is assigned to *Guid the function
796 return EFI_SUCCESS. If *Guid is NULL and there is no namespace exist in
797 the platform other than the default (NULL) tokennamespace, *Guid is unchanged
798 and the function return EFI_SUCCESS. If this input token namespace is the last
799 namespace on the platform, *Guid will be assigned to NULL and the function return
800 EFI_SUCCESS.
801
802 @retval EFI_SUCCESS The PCD service retrieved the next valid token space Guid.
803 Or the input token space Guid is already the last valid token space Guid
804 in the PCD database. In the later case, *Guid is updated with the value of NULL.
805 @retval EFI_NOT_FOUND If the input token namespace does not exist on the platform.
806
807 **/
808 EFI_STATUS
809 EFIAPI
810 PeiPcdGetNextTokenSpace (
811 IN OUT CONST EFI_GUID **Guid
812 );
813
814 /**
815 Retrieve additional information associated with a PCD token.
816
817 This includes information such as the type of value the TokenNumber is associated with as well as possible
818 human readable name that is associated with the token.
819
820 @param[in] Guid The 128-bit unique value that designates the namespace from which to extract the value.
821 @param[in] TokenNumber The PCD token number.
822 @param[out] PcdInfo The returned information associated with the requested TokenNumber.
823 The caller is responsible for freeing the buffer that is allocated by callee for PcdInfo->PcdName.
824
825 @retval EFI_SUCCESS The PCD information was returned successfully
826 @retval EFI_NOT_FOUND The PCD service could not find the requested token number.
827 **/
828 EFI_STATUS
829 PeiGetPcdInfo (
830 IN CONST EFI_GUID *Guid,
831 IN UINTN TokenNumber,
832 OUT EFI_PCD_INFO *PcdInfo
833 );
834
835 /* Internal Function definitions */
836 /**
837 Get PCD database from GUID HOB in PEI phase.
838
839 @return Pointer to PCD database.
840
841 **/
842 PEI_PCD_DATABASE *
843 GetPcdDatabase (
844 VOID
845 );
846
847 /**
848 Wrapper function for setting non-pointer type value for a PCD entry.
849
850 @param TokenNumber Pcd token number autogenerated by build tools.
851 @param Data Value want to be set for PCD entry
852 @param Size Size of value.
853
854 @return status of SetWorker.
855
856 **/
857 EFI_STATUS
858 SetValueWorker (
859 IN UINTN TokenNumber,
860 IN VOID *Data,
861 IN UINTN Size
862 );
863
864 /**
865 Set value for an PCD entry
866
867 @param TokenNumber Pcd token number autogenerated by build tools.
868 @param Data Value want to be set for PCD entry
869 @param Size Size of value.
870 @param PtrType If TRUE, the type of PCD entry's value is Pointer.
871 If False, the type of PCD entry's value is not Pointer.
872
873 @retval EFI_INVALID_PARAMETER If this PCD type is VPD, VPD PCD can not be set.
874 @retval EFI_INVALID_PARAMETER If Size can not be set to size table.
875 @retval EFI_INVALID_PARAMETER If Size of non-Ptr type PCD does not match the size information in PCD database.
876 @retval EFI_NOT_FOUND If value type of PCD entry is intergrate, but not in
877 range of UINT8, UINT16, UINT32, UINT64
878 @retval EFI_NOT_FOUND Can not find the PCD type according to token number.
879 **/
880 EFI_STATUS
881 SetWorker (
882 IN UINTN TokenNumber,
883 IN VOID *Data,
884 IN OUT UINTN *Size,
885 IN BOOLEAN PtrType
886 );
887
888 /**
889 Wrapper function for set PCD value for non-Pointer type dynamic-ex PCD.
890
891 @param ExTokenNumber Token number for dynamic-ex PCD.
892 @param Guid Token space guid for dynamic-ex PCD.
893 @param Data Value want to be set.
894 @param SetSize The size of value.
895
896 @return status of ExSetWorker().
897
898 **/
899 EFI_STATUS
900 ExSetValueWorker (
901 IN UINTN ExTokenNumber,
902 IN CONST EFI_GUID *Guid,
903 IN VOID *Data,
904 IN UINTN Size
905 );
906
907 /**
908 Set value for a dynamic PCD entry.
909
910 This routine find the local token number according to dynamic-ex PCD's token
911 space guid and token number firstly, and invoke callback function if this PCD
912 entry registered callback function. Finally, invoken general SetWorker to set
913 PCD value.
914
915 @param ExTokenNumber Dynamic-ex PCD token number.
916 @param Guid Token space guid for dynamic-ex PCD.
917 @param Data PCD value want to be set
918 @param SetSize Size of value.
919 @param PtrType If TRUE, this PCD entry is pointer type.
920 If FALSE, this PCD entry is not pointer type.
921
922 @return status of SetWorker().
923
924 **/
925 EFI_STATUS
926 ExSetWorker (
927 IN UINTN ExTokenNumber,
928 IN CONST EFI_GUID *Guid,
929 IN VOID *Data,
930 IN OUT UINTN *Size,
931 IN BOOLEAN PtrType
932 );
933
934 /**
935 Get the PCD entry pointer in PCD database.
936
937 This routine will visit PCD database to find the PCD entry according to given
938 token number. The given token number is autogened by build tools and it will be
939 translated to local token number. Local token number contains PCD's type and
940 offset of PCD entry in PCD database.
941
942 @param TokenNumber Token's number, it is autogened by build tools
943 @param GetSize The size of token's value
944
945 @return PCD entry pointer in PCD database
946
947 **/
948 VOID *
949 GetWorker (
950 IN UINTN TokenNumber,
951 IN UINTN GetSize
952 );
953
954 /**
955 Wrapper function for get PCD value for dynamic-ex PCD.
956
957 @param Guid Token space guid for dynamic-ex PCD.
958 @param ExTokenNumber Token number for dyanmic-ex PCD.
959 @param GetSize The size of dynamic-ex PCD value.
960
961 @return PCD entry in PCD database.
962
963 **/
964 VOID *
965 ExGetWorker (
966 IN CONST EFI_GUID *Guid,
967 IN UINTN ExTokenNumber,
968 IN UINTN GetSize
969 );
970
971 typedef struct {
972 UINTN TokenNumber;
973 UINTN Size;
974 UINT32 LocalTokenNumberAlias;
975 } EX_PCD_ENTRY_ATTRIBUTE;
976
977 /**
978 Get Token Number according to dynamic-ex PCD's {token space guid:token number}
979
980 A dynamic-ex type PCD, developer must provide pair of token space guid: token number
981 in DEC file. PCD database maintain a mapping table that translate pair of {token
982 space guid: token number} to Token Number.
983
984 @param Guid Token space guid for dynamic-ex PCD entry.
985 @param ExTokenNumber Token number for dynamic-ex PCD.
986
987 @return Token Number for dynamic-ex PCD.
988
989 **/
990 UINTN
991 GetExPcdTokenNumber (
992 IN CONST EFI_GUID *Guid,
993 IN UINTN ExTokenNumber
994 );
995
996 /**
997 Find the local token number according to system SKU ID.
998
999 @param LocalTokenNumber PCD token number
1000 @param Size The size of PCD entry.
1001
1002 @return Token number according to system SKU ID.
1003
1004 **/
1005 UINT32
1006 GetSkuEnabledTokenNumber (
1007 UINT32 LocalTokenNumber,
1008 UINTN Size
1009 );
1010
1011 /**
1012 The function registers the CallBackOnSet fucntion
1013 according to TokenNumber and EFI_GUID space.
1014
1015 @param TokenNumber The token number.
1016 @param Guid The GUID space.
1017 @param CallBackFunction The Callback function to be registered.
1018 @param Register To register or unregister the callback function.
1019
1020 @retval EFI_SUCCESS If the Callback function is registered.
1021 @retval EFI_NOT_FOUND If the PCD Entry is not found according to Token Number and GUID space.
1022 @retval EFI_OUT_OF_RESOURCES If the callback function can't be registered because there is not free
1023 slot left in the CallbackFnTable.
1024 **/
1025 EFI_STATUS
1026 PeiRegisterCallBackWorker (
1027 IN UINTN TokenNumber,
1028 IN CONST EFI_GUID *Guid, OPTIONAL
1029 IN PCD_PPI_CALLBACK CallBackFunction,
1030 IN BOOLEAN Register
1031 );
1032
1033 /**
1034 The function builds the PCD database.
1035
1036 @param FileHandle Handle of the file the external PCD database binary located.
1037
1038 @return Pointer to PCD database.
1039
1040 **/
1041 PEI_PCD_DATABASE *
1042 BuildPcdDatabase (
1043 IN EFI_PEI_FILE_HANDLE FileHandle
1044 );
1045
1046 /**
1047 Get SKU ID tabble from PCD database.
1048
1049 @param LocalTokenNumberTableIdx Index of local token number in token number table.
1050 @param Database PCD Database in PEI phase
1051
1052 @return Pointer to SKU ID array table
1053
1054 **/
1055 SKU_ID *
1056 GetSkuIdArray (
1057 IN UINTN LocalTokenNumberTableIdx,
1058 IN PEI_PCD_DATABASE *Database
1059 );
1060
1061 /**
1062 Get index of PCD entry in size table.
1063
1064 @param LocalTokenNumberTableIdx Index of this PCD in local token number table.
1065 @param Database Pointer to PCD database.
1066
1067 @return index of PCD entry in size table.
1068
1069 **/
1070 UINTN
1071 GetSizeTableIndex (
1072 IN UINTN LocalTokenNumberTableIdx,
1073 IN PEI_PCD_DATABASE *Database
1074 );
1075
1076 /**
1077 Get PCD value's size for POINTER type PCD.
1078
1079 The POINTER type PCD's value will be stored into a buffer in specificed size.
1080 The max size of this PCD's value is described in PCD's definition in DEC file.
1081
1082 @param LocalTokenNumberTableIdx Index of PCD token number in PCD token table
1083 @param MaxSize Maxmium size of PCD's value
1084 @param Database Pcd database in PEI phase.
1085
1086 @return PCD value's size for POINTER type PCD.
1087
1088 **/
1089 UINTN
1090 GetPtrTypeSize (
1091 IN UINTN LocalTokenNumberTableIdx,
1092 OUT UINTN *MaxSize,
1093 IN PEI_PCD_DATABASE *Database
1094 );
1095
1096 /**
1097 Set PCD value's size for POINTER type PCD.
1098
1099 The POINTER type PCD's value will be stored into a buffer in specificed size.
1100 The max size of this PCD's value is described in PCD's definition in DEC file.
1101
1102 @param LocalTokenNumberTableIdx Index of PCD token number in PCD token table
1103 @param CurrentSize Maxmium size of PCD's value
1104 @param Database Pcd database in PEI phase.
1105
1106 @retval TRUE Success to set PCD's value size, which is not exceed maxmium size
1107 @retval FALSE Fail to set PCD's value size, which maybe exceed maxmium size
1108
1109 **/
1110 BOOLEAN
1111 SetPtrTypeSize (
1112 IN UINTN LocalTokenNumberTableIdx,
1113 IN OUT UINTN *CurrentSize,
1114 IN PEI_PCD_DATABASE *Database
1115 );
1116
1117 #endif
1118