1375e0039f17328ef8b5a2f45a7dc6b780b90db3
[mirror_edk2.git] / MdePkg / Include / Library / PcdLib.h
1 /** @file
2 PCD Library Class Interface Declarations
3
4 Copyright (c) 2006, Intel Corporation
5 All rights reserved. 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 Module Name: PcdLib.h
15
16 **/
17
18 #ifndef __PCD_LIB_H__
19 #define __PCD_LIB_H__
20
21
22 #define PcdToken(TokenName) _PCD_TOKEN_##TokenName
23
24
25 //
26 // Feature Flag is in the form of a global constant
27 //
28 #define FeaturePcdGet(TokenName) _gPcd_FixedAtBuild_##TokenName
29
30
31 //
32 // Fixed is fixed at build time
33 //
34 #define FixedPcdGet8(TokenName) _gPcd_FixedAtBuild_##TokenName
35 #define FixedPcdGet16(TokenName) _gPcd_FixedAtBuild_##TokenName
36 #define FixedPcdGet32(TokenName) _gPcd_FixedAtBuild_##TokenName
37 #define FixedPcdGet64(TokenName) _gPcd_FixedAtBuild_##TokenName
38 #define FixedPcdGetBool(TokenName) _gPcd_FixedAtBuild_##TokenName
39
40
41 //
42 // BugBug: This works for strings, but not constants.
43 //
44 #define FixedPcdGetPtr(TokenName) ((VOID *)_gPcd_FixedAtBuild_##TokenName)
45
46
47 //
48 // (Binary) Patch is in the form of a global variable
49 //
50 #define PatchPcdGet8(TokenName) _gPcd_BinaryPatch_##TokenName
51 #define PatchPcdGet16(TokenName) _gPcd_BinaryPatch_##TokenName
52 #define PatchPcdGet32(TokenName) _gPcd_BinaryPatch_##TokenName
53 #define PatchPcdGet64(TokenName) _gPcd_BinaryPatch_##TokenName
54 #define PatchPcdGetBool(TokenName) _gPcd_BinaryPatch_##TokenName
55 #define PatchPcdGetPtr(TokenName) ((VOID *)_gPcd_BinaryPatch_##TokenName)
56
57
58 //
59 // Dynamic is via the protocol with only the TokenNumber as argument
60 // It can also be Patch or Fixed type based on a build option
61 //
62 #define PcdGet8(TokenName) _PCD_MODE_8_##TokenName
63 #define PcdGet16(TokenName) _PCD_MODE_16_##TokenName
64 #define PcdGet32(TokenName) _PCD_MODE_32_##TokenName
65 #define PcdGet64(TokenName) _PCD_MODE_64_##TokenName
66 #define PcdGetPtr(TokenName) _PCD_MODE_PTR_##TokenName
67 #define PcdGetBool(TokenName) _PCD_MODE_BOOL_##TokenName
68
69
70 //
71 // Dynamic Ex is to support binary distribution
72 //
73 #define PcdGetEx8(Guid, TokenName) LibPcdGetEx8 (Guid, _PCD_TOKEN_##TokenName)
74 #define PcdGetEx16(Guid, TokenName) LibPcdGetEx16 (Guid, _PCD_TOKEN_##TokenName)
75 #define PcdGetEx32(Guid, TokenName) LibPcdGetEx32 (Guid, _PCD_TOKEN_##TokenName)
76 #define PcdGetEx64(Guid, TokenName) LibPcdGetEx64 (Guid, _PCD_TOKEN_##TokenName)
77 #define PcdGetExPtr(Guid, TokenName) LibPcdGetExPtr (Guid, _PCD_TOKEN_##TokenName)
78 #define PcdGetExBool(Guid, TokenName) LibPcdGetExBool (Guid, _PCD_TOKEN_##TokenName)
79
80
81 //
82 // Dynamic Set
83 //
84 #define PcdSet8(TokenName, Value) LibPcdSet8 (_PCD_TOKEN_##TokenName, Value)
85 #define PcdSet16(TokenName, Value) LibPcdSet16 (_PCD_TOKEN_##TokenName, Value)
86 #define PcdSet32(TokenName, Value) LibPcdSet32 (_PCD_TOKEN_##TokenName, Value)
87 #define PcdSet64(TokenName, Value) LibPcdSet64 (_PCD_TOKEN_##TokenName, Value)
88 #define PcdSetPtr(TokenName, Value) LibPcdSetPtr (_PCD_TOKEN_##TokenName, Value)
89 #define PcdSetBool(TokenName, Value) LibPcdSetBool(_PCD_TOKEN_##TokenName, Value)
90
91
92 //
93 // Dynamic Set Ex
94 //
95 #define PcdSetEx8 (Guid, TokenName, Value) LibPcdSetEx8 (Guid, _PCD_TOKEN_##TokenName, Value)
96 #define PcdSetEx16 (Guid, TokenName, Value) LibPcdSetEx16 (Guid, _PCD_TOKEN_##TokenName, Value)
97 #define PcdSetEx32 (Guid, TokenName, Value) LibPcdSetEx32 (Guid, _PCD_TOKEN_##TokenName, Value)
98 #define PcdSetEx64 (Guid, TokenName, Value) LibPcdSetEx64 (Guid, _PCD_TOKEN_##TokenName, Value)
99 #define PcdSetExPtr (Guid, TokenName, Value) LibPcdSetExPtr (Guid, _PCD_TOKEN_##TokenName, Value)
100 #define PcdSetExBool(Guid, TokenName, Value) LibPcdSetExBool(Guid, _PCD_TOKEN_##TokenName, Value)
101
102
103 /**
104 Sets the current SKU in the PCD database to the value specified by SkuId. SkuId is returned.
105
106 @param[in] SkuId The SKU value that will be used when the PCD service will retrieve and
107 set values associated with a PCD token.
108
109 @retval UINTN Return the SKU ID that just be set.
110
111 **/
112 UINTN
113 EFIAPI
114 LibPcdSetSku (
115 IN UINTN SkuId
116 );
117
118
119 /**
120 Returns the 8-bit value for the token specified by TokenNumber.
121
122 @param[in] The PCD token number to retrieve a current value for.
123
124 @retval UINT8 Returns the 8-bit value for the token specified by TokenNumber.
125
126 **/
127 UINT8
128 EFIAPI
129 LibPcdGet8 (
130 IN UINTN TokenNumber
131 );
132
133
134 /**
135 Returns the 16-bit value for the token specified by TokenNumber.
136
137 @param[in] The PCD token number to retrieve a current value for.
138
139 @retval UINT16 Returns the 16-bit value for the token specified by TokenNumber.
140
141 **/
142 UINT16
143 EFIAPI
144 LibPcdGet16 (
145 IN UINTN TokenNumber
146 );
147
148
149 /**
150 Returns the 32-bit value for the token specified by TokenNumber.
151
152 @param[in] TokenNumber The PCD token number to retrieve a current value for.
153
154 @retval UINT32 Returns the 32-bit value for the token specified by TokenNumber.
155
156 **/
157 UINT32
158 EFIAPI
159 LibPcdGet32 (
160 IN UINTN TokenNumber
161 );
162
163
164 /**
165 Returns the 64-bit value for the token specified by TokenNumber.
166
167 @param[in] TokenNumber The PCD token number to retrieve a current value for.
168
169 @retval UINT64 Returns the 64-bit value for the token specified by TokenNumber.
170
171 **/
172 UINT64
173 EFIAPI
174 LibPcdGet64 (
175 IN UINTN TokenNumber
176 );
177
178
179 /**
180 Returns the pointer to the buffer of the token specified by TokenNumber.
181
182 @param[in] TokenNumber The PCD token number to retrieve a current value for.
183
184 @retval VOID* Returns the pointer to the token specified by TokenNumber.
185
186 **/
187 VOID *
188 EFIAPI
189 LibPcdGetPtr (
190 IN UINTN TokenNumber
191 );
192
193
194 /**
195 Returns the Boolean value of the token specified by TokenNumber.
196
197 @param[in] TokenNumber The PCD token number to retrieve a current value for.
198
199 @retval BOOLEAN Returns the Boolean value of the token specified by TokenNumber.
200
201 **/
202 BOOLEAN
203 EFIAPI
204 LibPcdGetBool (
205 IN UINTN TokenNumber
206 );
207
208
209 /**
210 Returns the size of the token specified by TokenNumber.
211
212 @param[in] TokenNumber The PCD token number to retrieve a current value for.
213
214 @retval UINTN Returns the size of the token specified by TokenNumber.
215
216 **/
217 UINTN
218 EFIAPI
219 LibPcdGetSize (
220 IN UINTN TokenNumber
221 );
222
223
224 /**
225 Returns the 8-bit value for the token specified by TokenNumber and Guid.
226 If Guid is NULL, then ASSERT().
227
228 @param[in] Guid Pointer to a 128-bit unique value that designates
229 which namespace to retrieve a value from.
230 @param[in] TokenNumber The PCD token number to retrieve a current value for.
231
232 @retval UINT8 Return the UINT8.
233
234 **/
235 UINT8
236 EFIAPI
237 LibPcdGetEx8 (
238 IN CONST GUID *Guid,
239 IN UINTN TokenNumber
240 );
241
242
243 /**
244 Returns the 16-bit value for the token specified by TokenNumber and Guid.
245 If Guid is NULL, then ASSERT().
246
247 @param[in] Guid Pointer to a 128-bit unique value that designates
248 which namespace to retrieve a value from.
249 @param[in] TokenNumber The PCD token number to retrieve a current value for.
250
251 @retval UINT16 Return the UINT16.
252
253 **/
254 UINT16
255 EFIAPI
256 LibPcdGetEx16 (
257 IN CONST GUID *Guid,
258 IN UINTN TokenNumber
259 );
260
261
262 /**
263 Returns the 32-bit value for the token specified by TokenNumber and Guid.
264 If Guid is NULL, then ASSERT().
265
266 @param[in] Guid Pointer to a 128-bit unique value that designates
267 which namespace to retrieve a value from.
268 @param[in] TokenNumber The PCD token number to retrieve a current value for.
269
270 @retval UINT32 Return the UINT32.
271
272 **/
273 UINT32
274 EFIAPI
275 LibPcdGetEx32 (
276 IN CONST GUID *Guid,
277 IN UINTN TokenNumber
278 );
279
280
281 /**
282 Returns the 64-bit value for the token specified by TokenNumber and Guid.
283 If Guid is NULL, then ASSERT().
284
285 @param[in] Guid Pointer to a 128-bit unique value that designates
286 which namespace to retrieve a value from.
287 @param[in] TokenNumber The PCD token number to retrieve a current value for.
288
289 @retval UINT64 Return the UINT64.
290
291 **/
292 UINT64
293 EFIAPI
294 LibPcdGetEx64 (
295 IN CONST GUID *Guid,
296 IN UINTN TokenNumber
297 );
298
299
300 /**
301 Returns the pointer to the buffer of token specified by TokenNumber and Guid.
302 If Guid is NULL, then ASSERT().
303
304 @param[in] Guid Pointer to a 128-bit unique value that designates
305 which namespace to retrieve a value from.
306 @param[in] TokenNumber The PCD token number to retrieve a current value for.
307
308 @retval VOID* Return the VOID* pointer.
309
310 **/
311 VOID *
312 EFIAPI
313 LibPcdGetExPtr (
314 IN CONST GUID *Guid,
315 IN UINTN TokenNumber
316 );
317
318
319 /**
320 Returns the Boolean value of the token specified by TokenNumber and Guid.
321 If Guid is NULL, then ASSERT().
322
323 @param[in] Guid Pointer to a 128-bit unique value that designates
324 which namespace to retrieve a value from.
325 @param[in] TokenNumber The PCD token number to retrieve a current value for.
326
327 @retval BOOLEAN Return the BOOLEAN.
328
329 **/
330 BOOLEAN
331 EFIAPI
332 LibPcdGetExBool (
333 IN CONST GUID *Guid,
334 IN UINTN TokenNumber
335 );
336
337
338 /**
339 Returns the size of the token specified by TokenNumber and Guid.
340 If Guid is NULL, then ASSERT().
341
342 @param[in] Guid Pointer to a 128-bit unique value that designates
343 which namespace to retrieve a value from.
344 @param[in] TokenNumber The PCD token number to retrieve a current value for.
345
346 @retval UINTN Return the size.
347
348 **/
349 UINTN
350 EFIAPI
351 LibPcdGetExSize (
352 IN CONST GUID *Guid,
353 IN UINTN TokenNumber
354 );
355
356
357 /**
358 Sets the 8-bit value for the token specified by TokenNumber
359 to the value specified by Value. Value is returned.
360
361 @param[in] TokenNumber The PCD token number to set a current value for.
362 @param[in] Value The 8-bit value to set.
363
364 @retval UINT8 Return the value been set.
365
366 **/
367 UINT8
368 EFIAPI
369 LibPcdSet8 (
370 IN UINTN TokenNumber,
371 IN UINT8 Value
372 );
373
374
375 /**
376 Sets the 16-bit value for the token specified by TokenNumber
377 to the value specified by Value. Value is returned.
378
379 @param[in] TokenNumber The PCD token number to set a current value for.
380 @param[in] Value The 16-bit value to set.
381
382 @retval UINT16 Return the value been set.
383
384 **/
385 UINT16
386 EFIAPI
387 LibPcdSet16 (
388 IN UINTN TokenNumber,
389 IN UINT16 Value
390 );
391
392
393 /**
394 Sets the 32-bit value for the token specified by TokenNumber
395 to the value specified by Value. Value is returned.
396
397 @param[in] TokenNumber The PCD token number to set a current value for.
398 @param[in] Value The 32-bit value to set.
399
400 @retval UINT32 Return the value been set.
401
402 **/
403 UINT32
404 EFIAPI
405 LibPcdSet32 (
406 IN UINTN TokenNumber,
407 IN UINT32 Value
408 );
409
410
411 /**
412 Sets the 64-bit value for the token specified by TokenNumber
413 to the value specified by Value. Value is returned.
414
415 @param[in] TokenNumber The PCD token number to set a current value for.
416 @param[in] Value The 64-bit value to set.
417
418 @retval UINT64 Return the value been set.
419
420 **/
421 UINT64
422 EFIAPI
423 LibPcdSet64 (
424 IN UINTN TokenNumber,
425 IN UINT64 Value
426 );
427
428
429 /**
430 Sets a buffer for the token specified by TokenNumber to
431 the value specified by Value. Value is returned.
432 If Value is NULL, then ASSERT().
433
434 @param[in] TokenNumber The PCD token number to set a current value for.
435 @param[in] Value A pointer to the buffer to set.
436
437 @retval VOID* Return the pointer for the buffer been set.
438
439 **/
440 VOID*
441 EFIAPI
442 LibPcdSetPtr (
443 IN UINTN TokenNumber,
444 IN CONST VOID *Value
445 );
446
447
448 /**
449 Sets the Boolean value for the token specified by TokenNumber
450 to the value specified by Value. Value is returned.
451
452 @param[in] TokenNumber The PCD token number to set a current value for.
453 @param[in] Value The boolean value to set.
454
455 @retval BOOLEAN Return the value been set.
456
457 **/
458 BOOLEAN
459 EFIAPI
460 LibPcdSetBool (
461 IN UINTN TokenNumber,
462 IN BOOLEAN Value
463 );
464
465
466 /**
467 Sets the 8-bit value for the token specified by TokenNumber and
468 Guid to the value specified by Value. Value is returned.
469 If Guid is NULL, then ASSERT().
470
471 @param[in] Guid Pointer to a 128-bit unique value that
472 designates which namespace to set a value from.
473 @param[in] TokenNumber The PCD token number to set a current value for.
474 @param[in] Value The 8-bit value to set.
475
476 @retval UINT8 Return the value been set.
477
478 **/
479 UINT8
480 EFIAPI
481 LibPcdSetEx8 (
482 IN CONST GUID *Guid,
483 IN UINTN TokenNumber,
484 IN UINT8 Value
485 );
486
487
488 /**
489 Sets the 16-bit value for the token specified by TokenNumber and
490 Guid to the value specified by Value. Value is returned.
491 If Guid is NULL, then ASSERT().
492
493 @param[in] Guid Pointer to a 128-bit unique value that
494 designates which namespace to set a value from.
495 @param[in] TokenNumber The PCD token number to set a current value for.
496 @param[in] Value The 16-bit value to set.
497
498 @retval UINT8 Return the value been set.
499
500 **/
501 UINT16
502 EFIAPI
503 LibPcdSetEx16 (
504 IN CONST GUID *Guid,
505 IN UINTN TokenNumber,
506 IN UINT16 Value
507 );
508
509
510 /**
511 Sets the 32-bit value for the token specified by TokenNumber and
512 Guid to the value specified by Value. Value is returned.
513 If Guid is NULL, then ASSERT().
514
515 @param[in] Guid Pointer to a 128-bit unique value that
516 designates which namespace to set a value from.
517 @param[in] TokenNumber The PCD token number to set a current value for.
518 @param[in] Value The 32-bit value to set.
519
520 @retval UINT32 Return the value been set.
521
522 **/
523 UINT32
524 EFIAPI
525 LibPcdSetEx32 (
526 IN CONST GUID *Guid,
527 IN UINTN TokenNumber,
528 IN UINT32 Value
529 );
530
531
532 /**
533 Sets the 64-bit value for the token specified by TokenNumber and
534 Guid to the value specified by Value. Value is returned.
535 If Guid is NULL, then ASSERT().
536
537 @param[in] Guid Pointer to a 128-bit unique value that
538 designates which namespace to set a value from.
539 @param[in] TokenNumber The PCD token number to set a current value for.
540 @param[in] Value The 64-bit value to set.
541
542 @retval UINT64 Return the value been set.
543
544 **/
545 UINT64
546 EFIAPI
547 LibPcdSetEx64 (
548 IN CONST GUID *Guid,
549 IN UINTN TokenNumber,
550 IN UINT64 Value
551 );
552
553
554 /**
555 Sets a buffer for the token specified by TokenNumber and
556 Guid to the value specified by Value. Value is returned.
557 If Guid is NULL, then ASSERT().
558 If Value is NULL, then ASSERT().
559
560 @param[in] Guid Pointer to a 128-bit unique value that
561 designates which namespace to set a value from.
562 @param[in] TokenNumber The PCD token number to set a current value for.
563 @param[in] Value The 8-bit value to set.
564
565 @retval VOID * Return the value been set.
566
567 **/
568 VOID *
569 EFIAPI
570 LibPcdSetExPtr (
571 IN CONST GUID *Guid,
572 IN UINTN TokenNumber,
573 IN CONST VOID *Value
574 );
575
576
577 /**
578 Sets the Boolean value for the token specified by TokenNumber and
579 Guid to the value specified by Value. Value is returned.
580 If Guid is NULL, then ASSERT().
581
582 @param[in] Guid Pointer to a 128-bit unique value that
583 designates which namespace to set a value from.
584 @param[in] TokenNumber The PCD token number to set a current value for.
585 @param[in] Value The Boolean value to set.
586
587 @retval Boolean Return the value been set.
588
589 **/
590 BOOLEAN
591 EFIAPI
592 LibPcdSetExBool (
593 IN CONST GUID *Guid,
594 IN UINTN TokenNumber,
595 IN BOOLEAN Value
596 );
597
598
599 /**
600 When the token specified by TokenNumber and Guid is set,
601 then notification function specified by NotificationFunction is called.
602 If Guid is NULL, then the default token space is used.
603 If NotificationFunction is NULL, then ASSERT().
604
605 @param[in] CallBackGuid The PCD token GUID being set.
606 @param[in] CallBackToken The PCD token number being set.
607 @param[in] TokenData A pointer to the token data being set.
608 @param[in] TokenDataSize The size, in bytes, of the data being set.
609
610 @retval VOID
611
612 **/
613 typedef
614 VOID
615 (EFIAPI *PCD_CALLBACK) (
616 IN CONST GUID *CallBackGuid, OPTIONAL
617 IN UINTN CallBackToken,
618 IN VOID *TokenData,
619 IN UINTN TokenDataSize
620 );
621
622
623 /**
624 When the token specified by TokenNumber and Guid is set,
625 then notification function specified by NotificationFunction is called.
626 If Guid is NULL, then the default token space is used.
627 If NotificationFunction is NULL, then ASSERT().
628
629 @param[in] Guid Pointer to a 128-bit unique value that designates which
630 namespace to set a value from. If NULL, then the default
631 token space is used.
632 @param[in] TokenNumber The PCD token number to monitor.
633 @param[in] NotificationFunction The function to call when the token
634 specified by Guid and TokenNumber is set.
635
636 @retval VOID
637
638 **/
639 VOID
640 EFIAPI
641 LibPcdCallbackOnSet (
642 IN CONST GUID *Guid, OPTIONAL
643 IN UINTN TokenNumber,
644 IN PCD_CALLBACK NotificationFunction
645 );
646
647
648 /**
649 Disable a notification function that was established with LibPcdCallbackonSet().
650
651 @param[in] Guid Specify the GUID token space.
652 @param[in] TokenNumber Specify the token number.
653 @param[in] NotificationFunction The callback function to be unregistered.
654
655 @retval VOID
656
657 **/
658 VOID
659 EFIAPI
660 LibPcdCancelCallback (
661 IN CONST GUID *Guid, OPTIONAL
662 IN UINTN TokenNumber,
663 IN PCD_CALLBACK NotificationFunction
664 );
665
666
667 /**
668 Retrieves the next PCD token number from the token space specified by Guid.
669 If Guid is NULL, then the default token space is used. If TokenNumber is 0,
670 then the first token number is returned. Otherwise, the token number that
671 follows TokenNumber in the token space is returned. If TokenNumber is the last
672 token number in the token space, then 0 is returned. If TokenNumber is not 0 and
673 is not in the token space specified by Guid, then ASSERT().
674
675 @param[in] Pointer to a 128-bit unique value that designates which namespace
676 to set a value from. If NULL, then the default token space is used.
677 @param[in] The previous PCD token number. If 0, then retrieves the first PCD
678 token number.
679
680 @retval UINTN The next valid token number.
681
682 **/
683 UINTN
684 EFIAPI
685 LibPcdGetNextToken (
686 IN CONST GUID *Guid, OPTIONAL
687 IN UINTN *TokenNumber
688 );
689
690 #endif