abea7b6724aed4c741e6e1d987ef76f39e23a076
[mirror_edk2.git] / MdePkg / Include / Library / BaseLib.h
1 /** @file
2 Provides string functions, linked list functions, math functions, synchronization
3 functions, file path functions, and CPU architecture-specific functions.
4
5 Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR>
6 Portions copyright (c) 2008 - 2009, Apple Inc. All rights reserved.<BR>
7 This program and the accompanying materials
8 are licensed and made available under the terms and conditions of the BSD License
9 which accompanies this distribution. The full text of the license may be found at
10 http://opensource.org/licenses/bsd-license.php.
11
12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
14
15 **/
16
17 #ifndef __BASE_LIB__
18 #define __BASE_LIB__
19
20 //
21 // Definitions for architecture-specific types
22 //
23 #if defined (MDE_CPU_IA32)
24 ///
25 /// The IA-32 architecture context buffer used by SetJump() and LongJump().
26 ///
27 typedef struct {
28 UINT32 Ebx;
29 UINT32 Esi;
30 UINT32 Edi;
31 UINT32 Ebp;
32 UINT32 Esp;
33 UINT32 Eip;
34 } BASE_LIBRARY_JUMP_BUFFER;
35
36 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
37
38 #endif // defined (MDE_CPU_IA32)
39
40 #if defined (MDE_CPU_IPF)
41
42 ///
43 /// The Itanium architecture context buffer used by SetJump() and LongJump().
44 ///
45 typedef struct {
46 UINT64 F2[2];
47 UINT64 F3[2];
48 UINT64 F4[2];
49 UINT64 F5[2];
50 UINT64 F16[2];
51 UINT64 F17[2];
52 UINT64 F18[2];
53 UINT64 F19[2];
54 UINT64 F20[2];
55 UINT64 F21[2];
56 UINT64 F22[2];
57 UINT64 F23[2];
58 UINT64 F24[2];
59 UINT64 F25[2];
60 UINT64 F26[2];
61 UINT64 F27[2];
62 UINT64 F28[2];
63 UINT64 F29[2];
64 UINT64 F30[2];
65 UINT64 F31[2];
66 UINT64 R4;
67 UINT64 R5;
68 UINT64 R6;
69 UINT64 R7;
70 UINT64 SP;
71 UINT64 BR0;
72 UINT64 BR1;
73 UINT64 BR2;
74 UINT64 BR3;
75 UINT64 BR4;
76 UINT64 BR5;
77 UINT64 InitialUNAT;
78 UINT64 AfterSpillUNAT;
79 UINT64 PFS;
80 UINT64 BSP;
81 UINT64 Predicates;
82 UINT64 LoopCount;
83 UINT64 FPSR;
84 } BASE_LIBRARY_JUMP_BUFFER;
85
86 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 0x10
87
88 #endif // defined (MDE_CPU_IPF)
89
90 #if defined (MDE_CPU_X64)
91 ///
92 /// The x64 architecture context buffer used by SetJump() and LongJump().
93 ///
94 typedef struct {
95 UINT64 Rbx;
96 UINT64 Rsp;
97 UINT64 Rbp;
98 UINT64 Rdi;
99 UINT64 Rsi;
100 UINT64 R12;
101 UINT64 R13;
102 UINT64 R14;
103 UINT64 R15;
104 UINT64 Rip;
105 UINT64 MxCsr;
106 UINT8 XmmBuffer[160]; ///< XMM6-XMM15.
107 } BASE_LIBRARY_JUMP_BUFFER;
108
109 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
110
111 #endif // defined (MDE_CPU_X64)
112
113 #if defined (MDE_CPU_EBC)
114 ///
115 /// The EBC context buffer used by SetJump() and LongJump().
116 ///
117 typedef struct {
118 UINT64 R0;
119 UINT64 R1;
120 UINT64 R2;
121 UINT64 R3;
122 UINT64 IP;
123 } BASE_LIBRARY_JUMP_BUFFER;
124
125 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
126
127 #endif // defined (MDE_CPU_EBC)
128
129 #if defined (MDE_CPU_ARM)
130
131 typedef struct {
132 UINT32 R3; ///< A copy of R13.
133 UINT32 R4;
134 UINT32 R5;
135 UINT32 R6;
136 UINT32 R7;
137 UINT32 R8;
138 UINT32 R9;
139 UINT32 R10;
140 UINT32 R11;
141 UINT32 R12;
142 UINT32 R14;
143 } BASE_LIBRARY_JUMP_BUFFER;
144
145 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 4
146
147 #endif // defined (MDE_CPU_ARM)
148
149 #if defined (MDE_CPU_AARCH64)
150 typedef struct {
151 // GP regs
152 UINT64 X19;
153 UINT64 X20;
154 UINT64 X21;
155 UINT64 X22;
156 UINT64 X23;
157 UINT64 X24;
158 UINT64 X25;
159 UINT64 X26;
160 UINT64 X27;
161 UINT64 X28;
162 UINT64 FP;
163 UINT64 LR;
164 UINT64 IP0;
165
166 // FP regs
167 UINT64 D8;
168 UINT64 D9;
169 UINT64 D10;
170 UINT64 D11;
171 UINT64 D12;
172 UINT64 D13;
173 UINT64 D14;
174 UINT64 D15;
175 } BASE_LIBRARY_JUMP_BUFFER;
176
177 #define BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT 8
178
179 #endif // defined (MDE_CPU_AARCH64)
180
181
182 //
183 // String Services
184 //
185
186
187 /**
188 Returns the length of a Null-terminated Unicode string.
189
190 This function is similar as strlen_s defined in C11.
191
192 If String is not aligned on a 16-bit boundary, then ASSERT().
193
194 @param String A pointer to a Null-terminated Unicode string.
195 @param MaxSize The maximum number of Destination Unicode
196 char, including terminating null char.
197
198 @retval 0 If String is NULL.
199 @retval MaxSize If there is no null character in the first MaxSize characters of String.
200 @return The number of characters that percede the terminating null character.
201
202 **/
203 UINTN
204 EFIAPI
205 StrnLenS (
206 IN CONST CHAR16 *String,
207 IN UINTN MaxSize
208 );
209
210 /**
211 Returns the size of a Null-terminated Unicode string in bytes, including the
212 Null terminator.
213
214 This function returns the size of the Null-terminated Unicode string
215 specified by String in bytes, including the Null terminator.
216
217 If String is not aligned on a 16-bit boundary, then ASSERT().
218
219 @param String A pointer to a Null-terminated Unicode string.
220 @param MaxSize The maximum number of Destination Unicode
221 char, including the Null terminator.
222
223 @retval 0 If String is NULL.
224 @retval (sizeof (CHAR16) * (MaxSize + 1))
225 If there is no Null terminator in the first MaxSize characters of
226 String.
227 @return The size of the Null-terminated Unicode string in bytes, including
228 the Null terminator.
229
230 **/
231 UINTN
232 EFIAPI
233 StrnSizeS (
234 IN CONST CHAR16 *String,
235 IN UINTN MaxSize
236 );
237
238 /**
239 Copies the string pointed to by Source (including the terminating null char)
240 to the array pointed to by Destination.
241
242 This function is similar as strcpy_s defined in C11.
243
244 If Destination is not aligned on a 16-bit boundary, then ASSERT().
245 If Source is not aligned on a 16-bit boundary, then ASSERT().
246 If an error would be returned, then the function will also ASSERT().
247
248 If an error is returned, then the Destination is unmodified.
249
250 @param Destination A pointer to a Null-terminated Unicode string.
251 @param DestMax The maximum number of Destination Unicode
252 char, including terminating null char.
253 @param Source A pointer to a Null-terminated Unicode string.
254
255 @retval RETURN_SUCCESS String is copied.
256 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
257 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
258 If Source is NULL.
259 If PcdMaximumUnicodeStringLength is not zero,
260 and DestMax is greater than
261 PcdMaximumUnicodeStringLength.
262 If DestMax is 0.
263 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
264 **/
265 RETURN_STATUS
266 EFIAPI
267 StrCpyS (
268 OUT CHAR16 *Destination,
269 IN UINTN DestMax,
270 IN CONST CHAR16 *Source
271 );
272
273 /**
274 Copies not more than Length successive char from the string pointed to by
275 Source to the array pointed to by Destination. If no null char is copied from
276 Source, then Destination[Length] is always set to null.
277
278 This function is similar as strncpy_s defined in C11.
279
280 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
281 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
282 If an error would be returned, then the function will also ASSERT().
283
284 If an error is returned, then the Destination is unmodified.
285
286 @param Destination A pointer to a Null-terminated Unicode string.
287 @param DestMax The maximum number of Destination Unicode
288 char, including terminating null char.
289 @param Source A pointer to a Null-terminated Unicode string.
290 @param Length The maximum number of Unicode characters to copy.
291
292 @retval RETURN_SUCCESS String is copied.
293 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
294 MIN(StrLen(Source), Length).
295 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
296 If Source is NULL.
297 If PcdMaximumUnicodeStringLength is not zero,
298 and DestMax is greater than
299 PcdMaximumUnicodeStringLength.
300 If DestMax is 0.
301 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
302 **/
303 RETURN_STATUS
304 EFIAPI
305 StrnCpyS (
306 OUT CHAR16 *Destination,
307 IN UINTN DestMax,
308 IN CONST CHAR16 *Source,
309 IN UINTN Length
310 );
311
312 /**
313 Appends a copy of the string pointed to by Source (including the terminating
314 null char) to the end of the string pointed to by Destination.
315
316 This function is similar as strcat_s defined in C11.
317
318 If Destination is not aligned on a 16-bit boundary, then ASSERT().
319 If Source is not aligned on a 16-bit boundary, then ASSERT().
320 If an error would be returned, then the function will also ASSERT().
321
322 If an error is returned, then the Destination is unmodified.
323
324 @param Destination A pointer to a Null-terminated Unicode string.
325 @param DestMax The maximum number of Destination Unicode
326 char, including terminating null char.
327 @param Source A pointer to a Null-terminated Unicode string.
328
329 @retval RETURN_SUCCESS String is appended.
330 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
331 StrLen(Destination).
332 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
333 greater than StrLen(Source).
334 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
335 If Source is NULL.
336 If PcdMaximumUnicodeStringLength is not zero,
337 and DestMax is greater than
338 PcdMaximumUnicodeStringLength.
339 If DestMax is 0.
340 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
341 **/
342 RETURN_STATUS
343 EFIAPI
344 StrCatS (
345 IN OUT CHAR16 *Destination,
346 IN UINTN DestMax,
347 IN CONST CHAR16 *Source
348 );
349
350 /**
351 Appends not more than Length successive char from the string pointed to by
352 Source to the end of the string pointed to by Destination. If no null char is
353 copied from Source, then Destination[StrLen(Destination) + Length] is always
354 set to null.
355
356 This function is similar as strncat_s defined in C11.
357
358 If Destination is not aligned on a 16-bit boundary, then ASSERT().
359 If Source is not aligned on a 16-bit boundary, then ASSERT().
360 If an error would be returned, then the function will also ASSERT().
361
362 If an error is returned, then the Destination is unmodified.
363
364 @param Destination A pointer to a Null-terminated Unicode string.
365 @param DestMax The maximum number of Destination Unicode
366 char, including terminating null char.
367 @param Source A pointer to a Null-terminated Unicode string.
368 @param Length The maximum number of Unicode characters to copy.
369
370 @retval RETURN_SUCCESS String is appended.
371 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
372 StrLen(Destination).
373 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
374 greater than MIN(StrLen(Source), Length).
375 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
376 If Source is NULL.
377 If PcdMaximumUnicodeStringLength is not zero,
378 and DestMax is greater than
379 PcdMaximumUnicodeStringLength.
380 If DestMax is 0.
381 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
382 **/
383 RETURN_STATUS
384 EFIAPI
385 StrnCatS (
386 IN OUT CHAR16 *Destination,
387 IN UINTN DestMax,
388 IN CONST CHAR16 *Source,
389 IN UINTN Length
390 );
391
392 /**
393 Convert a Null-terminated Unicode decimal string to a value of type UINTN.
394
395 This function outputs a value of type UINTN by interpreting the contents of
396 the Unicode string specified by String as a decimal number. The format of the
397 input Unicode string String is:
398
399 [spaces] [decimal digits].
400
401 The valid decimal digit character is in the range [0-9]. The function will
402 ignore the pad space, which includes spaces or tab characters, before
403 [decimal digits]. The running zero in the beginning of [decimal digits] will
404 be ignored. Then, the function stops at the first character that is a not a
405 valid decimal character or a Null-terminator, whichever one comes first.
406
407 If String is NULL, then ASSERT().
408 If Data is NULL, then ASSERT().
409 If String is not aligned in a 16-bit boundary, then ASSERT().
410 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
411 PcdMaximumUnicodeStringLength Unicode characters, not including the
412 Null-terminator, then ASSERT().
413
414 If String has no valid decimal digits in the above format, then 0 is stored
415 at the location pointed to by Data.
416 If the number represented by String exceeds the range defined by UINTN, then
417 MAX_UINTN is stored at the location pointed to by Data.
418
419 If EndPointer is not NULL, a pointer to the character that stopped the scan
420 is stored at the location pointed to by EndPointer. If String has no valid
421 decimal digits right after the optional pad spaces, the value of String is
422 stored at the location pointed to by EndPointer.
423
424 @param String Pointer to a Null-terminated Unicode string.
425 @param EndPointer Pointer to character that stops scan.
426 @param Data Pointer to the converted value.
427
428 @retval RETURN_SUCCESS Value is translated from String.
429 @retval RETURN_INVALID_PARAMETER If String is NULL.
430 If Data is NULL.
431 If PcdMaximumUnicodeStringLength is not
432 zero, and String contains more than
433 PcdMaximumUnicodeStringLength Unicode
434 characters, not including the
435 Null-terminator.
436 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
437 the range defined by UINTN.
438
439 **/
440 RETURN_STATUS
441 EFIAPI
442 StrDecimalToUintnS (
443 IN CONST CHAR16 *String,
444 OUT CHAR16 **EndPointer, OPTIONAL
445 OUT UINTN *Data
446 );
447
448 /**
449 Convert a Null-terminated Unicode decimal string to a value of type UINT64.
450
451 This function outputs a value of type UINT64 by interpreting the contents of
452 the Unicode string specified by String as a decimal number. The format of the
453 input Unicode string String is:
454
455 [spaces] [decimal digits].
456
457 The valid decimal digit character is in the range [0-9]. The function will
458 ignore the pad space, which includes spaces or tab characters, before
459 [decimal digits]. The running zero in the beginning of [decimal digits] will
460 be ignored. Then, the function stops at the first character that is a not a
461 valid decimal character or a Null-terminator, whichever one comes first.
462
463 If String is NULL, then ASSERT().
464 If Data is NULL, then ASSERT().
465 If String is not aligned in a 16-bit boundary, then ASSERT().
466 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
467 PcdMaximumUnicodeStringLength Unicode characters, not including the
468 Null-terminator, then ASSERT().
469
470 If String has no valid decimal digits in the above format, then 0 is stored
471 at the location pointed to by Data.
472 If the number represented by String exceeds the range defined by UINT64, then
473 MAX_UINT64 is stored at the location pointed to by Data.
474
475 If EndPointer is not NULL, a pointer to the character that stopped the scan
476 is stored at the location pointed to by EndPointer. If String has no valid
477 decimal digits right after the optional pad spaces, the value of String is
478 stored at the location pointed to by EndPointer.
479
480 @param String Pointer to a Null-terminated Unicode string.
481 @param EndPointer Pointer to character that stops scan.
482 @param Data Pointer to the converted value.
483
484 @retval RETURN_SUCCESS Value is translated from String.
485 @retval RETURN_INVALID_PARAMETER If String is NULL.
486 If Data is NULL.
487 If PcdMaximumUnicodeStringLength is not
488 zero, and String contains more than
489 PcdMaximumUnicodeStringLength Unicode
490 characters, not including the
491 Null-terminator.
492 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
493 the range defined by UINT64.
494
495 **/
496 RETURN_STATUS
497 EFIAPI
498 StrDecimalToUint64S (
499 IN CONST CHAR16 *String,
500 OUT CHAR16 **EndPointer, OPTIONAL
501 OUT UINT64 *Data
502 );
503
504 /**
505 Convert a Null-terminated Unicode hexadecimal string to a value of type
506 UINTN.
507
508 This function outputs a value of type UINTN by interpreting the contents of
509 the Unicode string specified by String as a hexadecimal number. The format of
510 the input Unicode string String is:
511
512 [spaces][zeros][x][hexadecimal digits].
513
514 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
515 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
516 If "x" appears in the input string, it must be prefixed with at least one 0.
517 The function will ignore the pad space, which includes spaces or tab
518 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
519 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
520 after [x] or the first valid hexadecimal digit. Then, the function stops at
521 the first character that is a not a valid hexadecimal character or NULL,
522 whichever one comes first.
523
524 If String is NULL, then ASSERT().
525 If Data is NULL, then ASSERT().
526 If String is not aligned in a 16-bit boundary, then ASSERT().
527 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
528 PcdMaximumUnicodeStringLength Unicode characters, not including the
529 Null-terminator, then ASSERT().
530
531 If String has no valid hexadecimal digits in the above format, then 0 is
532 stored at the location pointed to by Data.
533 If the number represented by String exceeds the range defined by UINTN, then
534 MAX_UINTN is stored at the location pointed to by Data.
535
536 If EndPointer is not NULL, a pointer to the character that stopped the scan
537 is stored at the location pointed to by EndPointer. If String has no valid
538 hexadecimal digits right after the optional pad spaces, the value of String
539 is stored at the location pointed to by EndPointer.
540
541 @param String Pointer to a Null-terminated Unicode string.
542 @param EndPointer Pointer to character that stops scan.
543 @param Data Pointer to the converted value.
544
545 @retval RETURN_SUCCESS Value is translated from String.
546 @retval RETURN_INVALID_PARAMETER If String is NULL.
547 If Data is NULL.
548 If PcdMaximumUnicodeStringLength is not
549 zero, and String contains more than
550 PcdMaximumUnicodeStringLength Unicode
551 characters, not including the
552 Null-terminator.
553 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
554 the range defined by UINTN.
555
556 **/
557 RETURN_STATUS
558 EFIAPI
559 StrHexToUintnS (
560 IN CONST CHAR16 *String,
561 OUT CHAR16 **EndPointer, OPTIONAL
562 OUT UINTN *Data
563 );
564
565 /**
566 Convert a Null-terminated Unicode hexadecimal string to a value of type
567 UINT64.
568
569 This function outputs a value of type UINT64 by interpreting the contents of
570 the Unicode string specified by String as a hexadecimal number. The format of
571 the input Unicode string String is:
572
573 [spaces][zeros][x][hexadecimal digits].
574
575 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
576 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
577 If "x" appears in the input string, it must be prefixed with at least one 0.
578 The function will ignore the pad space, which includes spaces or tab
579 characters, before [zeros], [x] or [hexadecimal digit]. The running zero
580 before [x] or [hexadecimal digit] will be ignored. Then, the decoding starts
581 after [x] or the first valid hexadecimal digit. Then, the function stops at
582 the first character that is a not a valid hexadecimal character or NULL,
583 whichever one comes first.
584
585 If String is NULL, then ASSERT().
586 If Data is NULL, then ASSERT().
587 If String is not aligned in a 16-bit boundary, then ASSERT().
588 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
589 PcdMaximumUnicodeStringLength Unicode characters, not including the
590 Null-terminator, then ASSERT().
591
592 If String has no valid hexadecimal digits in the above format, then 0 is
593 stored at the location pointed to by Data.
594 If the number represented by String exceeds the range defined by UINT64, then
595 MAX_UINT64 is stored at the location pointed to by Data.
596
597 If EndPointer is not NULL, a pointer to the character that stopped the scan
598 is stored at the location pointed to by EndPointer. If String has no valid
599 hexadecimal digits right after the optional pad spaces, the value of String
600 is stored at the location pointed to by EndPointer.
601
602 @param String Pointer to a Null-terminated Unicode string.
603 @param EndPointer Pointer to character that stops scan.
604 @param Data Pointer to the converted value.
605
606 @retval RETURN_SUCCESS Value is translated from String.
607 @retval RETURN_INVALID_PARAMETER If String is NULL.
608 If Data is NULL.
609 If PcdMaximumUnicodeStringLength is not
610 zero, and String contains more than
611 PcdMaximumUnicodeStringLength Unicode
612 characters, not including the
613 Null-terminator.
614 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
615 the range defined by UINT64.
616
617 **/
618 RETURN_STATUS
619 EFIAPI
620 StrHexToUint64S (
621 IN CONST CHAR16 *String,
622 OUT CHAR16 **EndPointer, OPTIONAL
623 OUT UINT64 *Data
624 );
625
626 /**
627 Returns the length of a Null-terminated Ascii string.
628
629 This function is similar as strlen_s defined in C11.
630
631 @param String A pointer to a Null-terminated Ascii string.
632 @param MaxSize The maximum number of Destination Ascii
633 char, including terminating null char.
634
635 @retval 0 If String is NULL.
636 @retval MaxSize If there is no null character in the first MaxSize characters of String.
637 @return The number of characters that percede the terminating null character.
638
639 **/
640 UINTN
641 EFIAPI
642 AsciiStrnLenS (
643 IN CONST CHAR8 *String,
644 IN UINTN MaxSize
645 );
646
647 /**
648 Returns the size of a Null-terminated Ascii string in bytes, including the
649 Null terminator.
650
651 This function returns the size of the Null-terminated Ascii string specified
652 by String in bytes, including the Null terminator.
653
654 @param String A pointer to a Null-terminated Ascii string.
655 @param MaxSize The maximum number of Destination Ascii
656 char, including the Null terminator.
657
658 @retval 0 If String is NULL.
659 @retval (sizeof (CHAR8) * (MaxSize + 1))
660 If there is no Null terminator in the first MaxSize characters of
661 String.
662 @return The size of the Null-terminated Ascii string in bytes, including the
663 Null terminator.
664
665 **/
666 UINTN
667 EFIAPI
668 AsciiStrnSizeS (
669 IN CONST CHAR8 *String,
670 IN UINTN MaxSize
671 );
672
673 /**
674 Copies the string pointed to by Source (including the terminating null char)
675 to the array pointed to by Destination.
676
677 This function is similar as strcpy_s defined in C11.
678
679 If an error would be returned, then the function will also ASSERT().
680
681 If an error is returned, then the Destination is unmodified.
682
683 @param Destination A pointer to a Null-terminated Ascii string.
684 @param DestMax The maximum number of Destination Ascii
685 char, including terminating null char.
686 @param Source A pointer to a Null-terminated Ascii string.
687
688 @retval RETURN_SUCCESS String is copied.
689 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
690 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
691 If Source is NULL.
692 If PcdMaximumAsciiStringLength is not zero,
693 and DestMax is greater than
694 PcdMaximumAsciiStringLength.
695 If DestMax is 0.
696 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
697 **/
698 RETURN_STATUS
699 EFIAPI
700 AsciiStrCpyS (
701 OUT CHAR8 *Destination,
702 IN UINTN DestMax,
703 IN CONST CHAR8 *Source
704 );
705
706 /**
707 Copies not more than Length successive char from the string pointed to by
708 Source to the array pointed to by Destination. If no null char is copied from
709 Source, then Destination[Length] is always set to null.
710
711 This function is similar as strncpy_s defined in C11.
712
713 If an error would be returned, then the function will also ASSERT().
714
715 If an error is returned, then the Destination is unmodified.
716
717 @param Destination A pointer to a Null-terminated Ascii string.
718 @param DestMax The maximum number of Destination Ascii
719 char, including terminating null char.
720 @param Source A pointer to a Null-terminated Ascii string.
721 @param Length The maximum number of Ascii characters to copy.
722
723 @retval RETURN_SUCCESS String is copied.
724 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than
725 MIN(StrLen(Source), Length).
726 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
727 If Source is NULL.
728 If PcdMaximumAsciiStringLength is not zero,
729 and DestMax is greater than
730 PcdMaximumAsciiStringLength.
731 If DestMax is 0.
732 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
733 **/
734 RETURN_STATUS
735 EFIAPI
736 AsciiStrnCpyS (
737 OUT CHAR8 *Destination,
738 IN UINTN DestMax,
739 IN CONST CHAR8 *Source,
740 IN UINTN Length
741 );
742
743 /**
744 Appends a copy of the string pointed to by Source (including the terminating
745 null char) to the end of the string pointed to by Destination.
746
747 This function is similar as strcat_s defined in C11.
748
749 If an error would be returned, then the function will also ASSERT().
750
751 If an error is returned, then the Destination is unmodified.
752
753 @param Destination A pointer to a Null-terminated Ascii string.
754 @param DestMax The maximum number of Destination Ascii
755 char, including terminating null char.
756 @param Source A pointer to a Null-terminated Ascii string.
757
758 @retval RETURN_SUCCESS String is appended.
759 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
760 StrLen(Destination).
761 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
762 greater than StrLen(Source).
763 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
764 If Source is NULL.
765 If PcdMaximumAsciiStringLength is not zero,
766 and DestMax is greater than
767 PcdMaximumAsciiStringLength.
768 If DestMax is 0.
769 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
770 **/
771 RETURN_STATUS
772 EFIAPI
773 AsciiStrCatS (
774 IN OUT CHAR8 *Destination,
775 IN UINTN DestMax,
776 IN CONST CHAR8 *Source
777 );
778
779 /**
780 Appends not more than Length successive char from the string pointed to by
781 Source to the end of the string pointed to by Destination. If no null char is
782 copied from Source, then Destination[StrLen(Destination) + Length] is always
783 set to null.
784
785 This function is similar as strncat_s defined in C11.
786
787 If an error would be returned, then the function will also ASSERT().
788
789 If an error is returned, then the Destination is unmodified.
790
791 @param Destination A pointer to a Null-terminated Ascii string.
792 @param DestMax The maximum number of Destination Ascii
793 char, including terminating null char.
794 @param Source A pointer to a Null-terminated Ascii string.
795 @param Length The maximum number of Ascii characters to copy.
796
797 @retval RETURN_SUCCESS String is appended.
798 @retval RETURN_BAD_BUFFER_SIZE If DestMax is NOT greater than
799 StrLen(Destination).
800 @retval RETURN_BUFFER_TOO_SMALL If (DestMax - StrLen(Destination)) is NOT
801 greater than MIN(StrLen(Source), Length).
802 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
803 If Source is NULL.
804 If PcdMaximumAsciiStringLength is not zero,
805 and DestMax is greater than
806 PcdMaximumAsciiStringLength.
807 If DestMax is 0.
808 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
809 **/
810 RETURN_STATUS
811 EFIAPI
812 AsciiStrnCatS (
813 IN OUT CHAR8 *Destination,
814 IN UINTN DestMax,
815 IN CONST CHAR8 *Source,
816 IN UINTN Length
817 );
818
819 /**
820 Convert a Null-terminated Ascii decimal string to a value of type UINTN.
821
822 This function outputs a value of type UINTN by interpreting the contents of
823 the Ascii string specified by String as a decimal number. The format of the
824 input Ascii string String is:
825
826 [spaces] [decimal digits].
827
828 The valid decimal digit character is in the range [0-9]. The function will
829 ignore the pad space, which includes spaces or tab characters, before
830 [decimal digits]. The running zero in the beginning of [decimal digits] will
831 be ignored. Then, the function stops at the first character that is a not a
832 valid decimal character or a Null-terminator, whichever one comes first.
833
834 If String is NULL, then ASSERT().
835 If Data is NULL, then ASSERT().
836 If PcdMaximumAsciiStringLength is not zero, and String contains more than
837 PcdMaximumAsciiStringLength Ascii characters, not including the
838 Null-terminator, then ASSERT().
839
840 If String has no valid decimal digits in the above format, then 0 is stored
841 at the location pointed to by Data.
842 If the number represented by String exceeds the range defined by UINTN, then
843 MAX_UINTN is stored at the location pointed to by Data.
844
845 If EndPointer is not NULL, a pointer to the character that stopped the scan
846 is stored at the location pointed to by EndPointer. If String has no valid
847 decimal digits right after the optional pad spaces, the value of String is
848 stored at the location pointed to by EndPointer.
849
850 @param String Pointer to a Null-terminated Ascii string.
851 @param EndPointer Pointer to character that stops scan.
852 @param Data Pointer to the converted value.
853
854 @retval RETURN_SUCCESS Value is translated from String.
855 @retval RETURN_INVALID_PARAMETER If String is NULL.
856 If Data is NULL.
857 If PcdMaximumAsciiStringLength is not zero,
858 and String contains more than
859 PcdMaximumAsciiStringLength Ascii
860 characters, not including the
861 Null-terminator.
862 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
863 the range defined by UINTN.
864
865 **/
866 RETURN_STATUS
867 EFIAPI
868 AsciiStrDecimalToUintnS (
869 IN CONST CHAR8 *String,
870 OUT CHAR8 **EndPointer, OPTIONAL
871 OUT UINTN *Data
872 );
873
874 /**
875 Convert a Null-terminated Ascii decimal string to a value of type UINT64.
876
877 This function outputs a value of type UINT64 by interpreting the contents of
878 the Ascii string specified by String as a decimal number. The format of the
879 input Ascii string String is:
880
881 [spaces] [decimal digits].
882
883 The valid decimal digit character is in the range [0-9]. The function will
884 ignore the pad space, which includes spaces or tab characters, before
885 [decimal digits]. The running zero in the beginning of [decimal digits] will
886 be ignored. Then, the function stops at the first character that is a not a
887 valid decimal character or a Null-terminator, whichever one comes first.
888
889 If String is NULL, then ASSERT().
890 If Data is NULL, then ASSERT().
891 If PcdMaximumAsciiStringLength is not zero, and String contains more than
892 PcdMaximumAsciiStringLength Ascii characters, not including the
893 Null-terminator, then ASSERT().
894
895 If String has no valid decimal digits in the above format, then 0 is stored
896 at the location pointed to by Data.
897 If the number represented by String exceeds the range defined by UINT64, then
898 MAX_UINT64 is stored at the location pointed to by Data.
899
900 If EndPointer is not NULL, a pointer to the character that stopped the scan
901 is stored at the location pointed to by EndPointer. If String has no valid
902 decimal digits right after the optional pad spaces, the value of String is
903 stored at the location pointed to by EndPointer.
904
905 @param String Pointer to a Null-terminated Ascii string.
906 @param EndPointer Pointer to character that stops scan.
907 @param Data Pointer to the converted value.
908
909 @retval RETURN_SUCCESS Value is translated from String.
910 @retval RETURN_INVALID_PARAMETER If String is NULL.
911 If Data is NULL.
912 If PcdMaximumAsciiStringLength is not zero,
913 and String contains more than
914 PcdMaximumAsciiStringLength Ascii
915 characters, not including the
916 Null-terminator.
917 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
918 the range defined by UINT64.
919
920 **/
921 RETURN_STATUS
922 EFIAPI
923 AsciiStrDecimalToUint64S (
924 IN CONST CHAR8 *String,
925 OUT CHAR8 **EndPointer, OPTIONAL
926 OUT UINT64 *Data
927 );
928
929 /**
930 Convert a Null-terminated Ascii hexadecimal string to a value of type UINTN.
931
932 This function outputs a value of type UINTN by interpreting the contents of
933 the Ascii string specified by String as a hexadecimal number. The format of
934 the input Ascii string String is:
935
936 [spaces][zeros][x][hexadecimal digits].
937
938 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
939 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
940 "x" appears in the input string, it must be prefixed with at least one 0. The
941 function will ignore the pad space, which includes spaces or tab characters,
942 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
943 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
944 the first valid hexadecimal digit. Then, the function stops at the first
945 character that is a not a valid hexadecimal character or Null-terminator,
946 whichever on comes first.
947
948 If String is NULL, then ASSERT().
949 If Data is NULL, then ASSERT().
950 If PcdMaximumAsciiStringLength is not zero, and String contains more than
951 PcdMaximumAsciiStringLength Ascii characters, not including the
952 Null-terminator, then ASSERT().
953
954 If String has no valid hexadecimal digits in the above format, then 0 is
955 stored at the location pointed to by Data.
956 If the number represented by String exceeds the range defined by UINTN, then
957 MAX_UINTN is stored at the location pointed to by Data.
958
959 If EndPointer is not NULL, a pointer to the character that stopped the scan
960 is stored at the location pointed to by EndPointer. If String has no valid
961 hexadecimal digits right after the optional pad spaces, the value of String
962 is stored at the location pointed to by EndPointer.
963
964 @param String Pointer to a Null-terminated Ascii string.
965 @param EndPointer Pointer to character that stops scan.
966 @param Data Pointer to the converted value.
967
968 @retval RETURN_SUCCESS Value is translated from String.
969 @retval RETURN_INVALID_PARAMETER If String is NULL.
970 If Data is NULL.
971 If PcdMaximumAsciiStringLength is not zero,
972 and String contains more than
973 PcdMaximumAsciiStringLength Ascii
974 characters, not including the
975 Null-terminator.
976 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
977 the range defined by UINTN.
978
979 **/
980 RETURN_STATUS
981 EFIAPI
982 AsciiStrHexToUintnS (
983 IN CONST CHAR8 *String,
984 OUT CHAR8 **EndPointer, OPTIONAL
985 OUT UINTN *Data
986 );
987
988 /**
989 Convert a Null-terminated Ascii hexadecimal string to a value of type UINT64.
990
991 This function outputs a value of type UINT64 by interpreting the contents of
992 the Ascii string specified by String as a hexadecimal number. The format of
993 the input Ascii string String is:
994
995 [spaces][zeros][x][hexadecimal digits].
996
997 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
998 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If
999 "x" appears in the input string, it must be prefixed with at least one 0. The
1000 function will ignore the pad space, which includes spaces or tab characters,
1001 before [zeros], [x] or [hexadecimal digits]. The running zero before [x] or
1002 [hexadecimal digits] will be ignored. Then, the decoding starts after [x] or
1003 the first valid hexadecimal digit. Then, the function stops at the first
1004 character that is a not a valid hexadecimal character or Null-terminator,
1005 whichever on comes first.
1006
1007 If String is NULL, then ASSERT().
1008 If Data is NULL, then ASSERT().
1009 If PcdMaximumAsciiStringLength is not zero, and String contains more than
1010 PcdMaximumAsciiStringLength Ascii characters, not including the
1011 Null-terminator, then ASSERT().
1012
1013 If String has no valid hexadecimal digits in the above format, then 0 is
1014 stored at the location pointed to by Data.
1015 If the number represented by String exceeds the range defined by UINT64, then
1016 MAX_UINT64 is stored at the location pointed to by Data.
1017
1018 If EndPointer is not NULL, a pointer to the character that stopped the scan
1019 is stored at the location pointed to by EndPointer. If String has no valid
1020 hexadecimal digits right after the optional pad spaces, the value of String
1021 is stored at the location pointed to by EndPointer.
1022
1023 @param String Pointer to a Null-terminated Ascii string.
1024 @param EndPointer Pointer to character that stops scan.
1025 @param Data Pointer to the converted value.
1026
1027 @retval RETURN_SUCCESS Value is translated from String.
1028 @retval RETURN_INVALID_PARAMETER If String is NULL.
1029 If Data is NULL.
1030 If PcdMaximumAsciiStringLength is not zero,
1031 and String contains more than
1032 PcdMaximumAsciiStringLength Ascii
1033 characters, not including the
1034 Null-terminator.
1035 @retval RETURN_UNSUPPORTED If the number represented by String exceeds
1036 the range defined by UINT64.
1037
1038 **/
1039 RETURN_STATUS
1040 EFIAPI
1041 AsciiStrHexToUint64S (
1042 IN CONST CHAR8 *String,
1043 OUT CHAR8 **EndPointer, OPTIONAL
1044 OUT UINT64 *Data
1045 );
1046
1047
1048 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1049
1050 /**
1051 [ATTENTION] This function is deprecated for security reason.
1052
1053 Copies one Null-terminated Unicode string to another Null-terminated Unicode
1054 string and returns the new Unicode string.
1055
1056 This function copies the contents of the Unicode string Source to the Unicode
1057 string Destination, and returns Destination. If Source and Destination
1058 overlap, then the results are undefined.
1059
1060 If Destination is NULL, then ASSERT().
1061 If Destination is not aligned on a 16-bit boundary, then ASSERT().
1062 If Source is NULL, then ASSERT().
1063 If Source is not aligned on a 16-bit boundary, then ASSERT().
1064 If Source and Destination overlap, then ASSERT().
1065 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1066 PcdMaximumUnicodeStringLength Unicode characters not including the
1067 Null-terminator, then ASSERT().
1068
1069 @param Destination The pointer to a Null-terminated Unicode string.
1070 @param Source The pointer to a Null-terminated Unicode string.
1071
1072 @return Destination.
1073
1074 **/
1075 CHAR16 *
1076 EFIAPI
1077 StrCpy (
1078 OUT CHAR16 *Destination,
1079 IN CONST CHAR16 *Source
1080 );
1081
1082
1083 /**
1084 [ATTENTION] This function is deprecated for security reason.
1085
1086 Copies up to a specified length from one Null-terminated Unicode string to
1087 another Null-terminated Unicode string and returns the new Unicode string.
1088
1089 This function copies the contents of the Unicode string Source to the Unicode
1090 string Destination, and returns Destination. At most, Length Unicode
1091 characters are copied from Source to Destination. If Length is 0, then
1092 Destination is returned unmodified. If Length is greater that the number of
1093 Unicode characters in Source, then Destination is padded with Null Unicode
1094 characters. If Source and Destination overlap, then the results are
1095 undefined.
1096
1097 If Length > 0 and Destination is NULL, then ASSERT().
1098 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
1099 If Length > 0 and Source is NULL, then ASSERT().
1100 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
1101 If Source and Destination overlap, then ASSERT().
1102 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1103 PcdMaximumUnicodeStringLength, then ASSERT().
1104 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1105 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1106 then ASSERT().
1107
1108 @param Destination The pointer to a Null-terminated Unicode string.
1109 @param Source The pointer to a Null-terminated Unicode string.
1110 @param Length The maximum number of Unicode characters to copy.
1111
1112 @return Destination.
1113
1114 **/
1115 CHAR16 *
1116 EFIAPI
1117 StrnCpy (
1118 OUT CHAR16 *Destination,
1119 IN CONST CHAR16 *Source,
1120 IN UINTN Length
1121 );
1122 #endif
1123
1124 /**
1125 Returns the length of a Null-terminated Unicode string.
1126
1127 This function returns the number of Unicode characters in the Null-terminated
1128 Unicode string specified by String.
1129
1130 If String is NULL, then ASSERT().
1131 If String is not aligned on a 16-bit boundary, then ASSERT().
1132 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1133 PcdMaximumUnicodeStringLength Unicode characters not including the
1134 Null-terminator, then ASSERT().
1135
1136 @param String Pointer to a Null-terminated Unicode string.
1137
1138 @return The length of String.
1139
1140 **/
1141 UINTN
1142 EFIAPI
1143 StrLen (
1144 IN CONST CHAR16 *String
1145 );
1146
1147
1148 /**
1149 Returns the size of a Null-terminated Unicode string in bytes, including the
1150 Null terminator.
1151
1152 This function returns the size, in bytes, of the Null-terminated Unicode string
1153 specified by String.
1154
1155 If String is NULL, then ASSERT().
1156 If String is not aligned on a 16-bit boundary, then ASSERT().
1157 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1158 PcdMaximumUnicodeStringLength Unicode characters not including the
1159 Null-terminator, then ASSERT().
1160
1161 @param String The pointer to a Null-terminated Unicode string.
1162
1163 @return The size of String.
1164
1165 **/
1166 UINTN
1167 EFIAPI
1168 StrSize (
1169 IN CONST CHAR16 *String
1170 );
1171
1172
1173 /**
1174 Compares two Null-terminated Unicode strings, and returns the difference
1175 between the first mismatched Unicode characters.
1176
1177 This function compares the Null-terminated Unicode string FirstString to the
1178 Null-terminated Unicode string SecondString. If FirstString is identical to
1179 SecondString, then 0 is returned. Otherwise, the value returned is the first
1180 mismatched Unicode character in SecondString subtracted from the first
1181 mismatched Unicode character in FirstString.
1182
1183 If FirstString is NULL, then ASSERT().
1184 If FirstString is not aligned on a 16-bit boundary, then ASSERT().
1185 If SecondString is NULL, then ASSERT().
1186 If SecondString is not aligned on a 16-bit boundary, then ASSERT().
1187 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more
1188 than PcdMaximumUnicodeStringLength Unicode characters not including the
1189 Null-terminator, then ASSERT().
1190 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more
1191 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1192 Null-terminator, then ASSERT().
1193
1194 @param FirstString The pointer to a Null-terminated Unicode string.
1195 @param SecondString The pointer to a Null-terminated Unicode string.
1196
1197 @retval 0 FirstString is identical to SecondString.
1198 @return others FirstString is not identical to SecondString.
1199
1200 **/
1201 INTN
1202 EFIAPI
1203 StrCmp (
1204 IN CONST CHAR16 *FirstString,
1205 IN CONST CHAR16 *SecondString
1206 );
1207
1208
1209 /**
1210 Compares up to a specified length the contents of two Null-terminated Unicode strings,
1211 and returns the difference between the first mismatched Unicode characters.
1212
1213 This function compares the Null-terminated Unicode string FirstString to the
1214 Null-terminated Unicode string SecondString. At most, Length Unicode
1215 characters will be compared. If Length is 0, then 0 is returned. If
1216 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1217 value returned is the first mismatched Unicode character in SecondString
1218 subtracted from the first mismatched Unicode character in FirstString.
1219
1220 If Length > 0 and FirstString is NULL, then ASSERT().
1221 If Length > 0 and FirstString is not aligned on a 16-bit boundary, then ASSERT().
1222 If Length > 0 and SecondString is NULL, then ASSERT().
1223 If Length > 0 and SecondString is not aligned on a 16-bit boundary, then ASSERT().
1224 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1225 PcdMaximumUnicodeStringLength, then ASSERT().
1226 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more than
1227 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1228 then ASSERT().
1229 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more than
1230 PcdMaximumUnicodeStringLength Unicode characters, not including the Null-terminator,
1231 then ASSERT().
1232
1233 @param FirstString The pointer to a Null-terminated Unicode string.
1234 @param SecondString The pointer to a Null-terminated Unicode string.
1235 @param Length The maximum number of Unicode characters to compare.
1236
1237 @retval 0 FirstString is identical to SecondString.
1238 @return others FirstString is not identical to SecondString.
1239
1240 **/
1241 INTN
1242 EFIAPI
1243 StrnCmp (
1244 IN CONST CHAR16 *FirstString,
1245 IN CONST CHAR16 *SecondString,
1246 IN UINTN Length
1247 );
1248
1249
1250 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1251
1252 /**
1253 [ATTENTION] This function is deprecated for security reason.
1254
1255 Concatenates one Null-terminated Unicode string to another Null-terminated
1256 Unicode string, and returns the concatenated Unicode string.
1257
1258 This function concatenates two Null-terminated Unicode strings. The contents
1259 of Null-terminated Unicode string Source are concatenated to the end of
1260 Null-terminated Unicode string Destination. The Null-terminated concatenated
1261 Unicode String is returned. If Source and Destination overlap, then the
1262 results are undefined.
1263
1264 If Destination is NULL, then ASSERT().
1265 If Destination is not aligned on a 16-bit boundary, then ASSERT().
1266 If Source is NULL, then ASSERT().
1267 If Source is not aligned on a 16-bit boundary, then ASSERT().
1268 If Source and Destination overlap, then ASSERT().
1269 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
1270 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1271 Null-terminator, then ASSERT().
1272 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1273 PcdMaximumUnicodeStringLength Unicode characters, not including the
1274 Null-terminator, then ASSERT().
1275 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
1276 and Source results in a Unicode string with more than
1277 PcdMaximumUnicodeStringLength Unicode characters, not including the
1278 Null-terminator, then ASSERT().
1279
1280 @param Destination The pointer to a Null-terminated Unicode string.
1281 @param Source The pointer to a Null-terminated Unicode string.
1282
1283 @return Destination.
1284
1285 **/
1286 CHAR16 *
1287 EFIAPI
1288 StrCat (
1289 IN OUT CHAR16 *Destination,
1290 IN CONST CHAR16 *Source
1291 );
1292
1293
1294 /**
1295 [ATTENTION] This function is deprecated for security reason.
1296
1297 Concatenates up to a specified length one Null-terminated Unicode to the end
1298 of another Null-terminated Unicode string, and returns the concatenated
1299 Unicode string.
1300
1301 This function concatenates two Null-terminated Unicode strings. The contents
1302 of Null-terminated Unicode string Source are concatenated to the end of
1303 Null-terminated Unicode string Destination, and Destination is returned. At
1304 most, Length Unicode characters are concatenated from Source to the end of
1305 Destination, and Destination is always Null-terminated. If Length is 0, then
1306 Destination is returned unmodified. If Source and Destination overlap, then
1307 the results are undefined.
1308
1309 If Destination is NULL, then ASSERT().
1310 If Length > 0 and Destination is not aligned on a 16-bit boundary, then ASSERT().
1311 If Length > 0 and Source is NULL, then ASSERT().
1312 If Length > 0 and Source is not aligned on a 16-bit boundary, then ASSERT().
1313 If Source and Destination overlap, then ASSERT().
1314 If PcdMaximumUnicodeStringLength is not zero, and Length is greater than
1315 PcdMaximumUnicodeStringLength, then ASSERT().
1316 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more
1317 than PcdMaximumUnicodeStringLength Unicode characters, not including the
1318 Null-terminator, then ASSERT().
1319 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
1320 PcdMaximumUnicodeStringLength Unicode characters, not including the
1321 Null-terminator, then ASSERT().
1322 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination
1323 and Source results in a Unicode string with more than PcdMaximumUnicodeStringLength
1324 Unicode characters, not including the Null-terminator, then ASSERT().
1325
1326 @param Destination The pointer to a Null-terminated Unicode string.
1327 @param Source The pointer to a Null-terminated Unicode string.
1328 @param Length The maximum number of Unicode characters to concatenate from
1329 Source.
1330
1331 @return Destination.
1332
1333 **/
1334 CHAR16 *
1335 EFIAPI
1336 StrnCat (
1337 IN OUT CHAR16 *Destination,
1338 IN CONST CHAR16 *Source,
1339 IN UINTN Length
1340 );
1341 #endif
1342
1343 /**
1344 Returns the first occurrence of a Null-terminated Unicode sub-string
1345 in a Null-terminated Unicode string.
1346
1347 This function scans the contents of the Null-terminated Unicode string
1348 specified by String and returns the first occurrence of SearchString.
1349 If SearchString is not found in String, then NULL is returned. If
1350 the length of SearchString is zero, then String is returned.
1351
1352 If String is NULL, then ASSERT().
1353 If String is not aligned on a 16-bit boundary, then ASSERT().
1354 If SearchString is NULL, then ASSERT().
1355 If SearchString is not aligned on a 16-bit boundary, then ASSERT().
1356
1357 If PcdMaximumUnicodeStringLength is not zero, and SearchString
1358 or String contains more than PcdMaximumUnicodeStringLength Unicode
1359 characters, not including the Null-terminator, then ASSERT().
1360
1361 @param String The pointer to a Null-terminated Unicode string.
1362 @param SearchString The pointer to a Null-terminated Unicode string to search for.
1363
1364 @retval NULL If the SearchString does not appear in String.
1365 @return others If there is a match.
1366
1367 **/
1368 CHAR16 *
1369 EFIAPI
1370 StrStr (
1371 IN CONST CHAR16 *String,
1372 IN CONST CHAR16 *SearchString
1373 );
1374
1375 /**
1376 Convert a Null-terminated Unicode decimal string to a value of
1377 type UINTN.
1378
1379 This function returns a value of type UINTN by interpreting the contents
1380 of the Unicode string specified by String as a decimal number. The format
1381 of the input Unicode string String is:
1382
1383 [spaces] [decimal digits].
1384
1385 The valid decimal digit character is in the range [0-9]. The
1386 function will ignore the pad space, which includes spaces or
1387 tab characters, before [decimal digits]. The running zero in the
1388 beginning of [decimal digits] will be ignored. Then, the function
1389 stops at the first character that is a not a valid decimal character
1390 or a Null-terminator, whichever one comes first.
1391
1392 If String is NULL, then ASSERT().
1393 If String is not aligned in a 16-bit boundary, then ASSERT().
1394 If String has only pad spaces, then 0 is returned.
1395 If String has no pad spaces or valid decimal digits,
1396 then 0 is returned.
1397 If the number represented by String overflows according
1398 to the range defined by UINTN, then MAX_UINTN is returned.
1399
1400 If PcdMaximumUnicodeStringLength is not zero, and String contains
1401 more than PcdMaximumUnicodeStringLength Unicode characters not including
1402 the Null-terminator, then ASSERT().
1403
1404 @param String The pointer to a Null-terminated Unicode string.
1405
1406 @retval Value translated from String.
1407
1408 **/
1409 UINTN
1410 EFIAPI
1411 StrDecimalToUintn (
1412 IN CONST CHAR16 *String
1413 );
1414
1415 /**
1416 Convert a Null-terminated Unicode decimal string to a value of
1417 type UINT64.
1418
1419 This function returns a value of type UINT64 by interpreting the contents
1420 of the Unicode string specified by String as a decimal number. The format
1421 of the input Unicode string String is:
1422
1423 [spaces] [decimal digits].
1424
1425 The valid decimal digit character is in the range [0-9]. The
1426 function will ignore the pad space, which includes spaces or
1427 tab characters, before [decimal digits]. The running zero in the
1428 beginning of [decimal digits] will be ignored. Then, the function
1429 stops at the first character that is a not a valid decimal character
1430 or a Null-terminator, whichever one comes first.
1431
1432 If String is NULL, then ASSERT().
1433 If String is not aligned in a 16-bit boundary, then ASSERT().
1434 If String has only pad spaces, then 0 is returned.
1435 If String has no pad spaces or valid decimal digits,
1436 then 0 is returned.
1437 If the number represented by String overflows according
1438 to the range defined by UINT64, then MAX_UINT64 is returned.
1439
1440 If PcdMaximumUnicodeStringLength is not zero, and String contains
1441 more than PcdMaximumUnicodeStringLength Unicode characters not including
1442 the Null-terminator, then ASSERT().
1443
1444 @param String The pointer to a Null-terminated Unicode string.
1445
1446 @retval Value translated from String.
1447
1448 **/
1449 UINT64
1450 EFIAPI
1451 StrDecimalToUint64 (
1452 IN CONST CHAR16 *String
1453 );
1454
1455
1456 /**
1457 Convert a Null-terminated Unicode hexadecimal string to a value of type UINTN.
1458
1459 This function returns a value of type UINTN by interpreting the contents
1460 of the Unicode string specified by String as a hexadecimal number.
1461 The format of the input Unicode string String is:
1462
1463 [spaces][zeros][x][hexadecimal digits].
1464
1465 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1466 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1467 If "x" appears in the input string, it must be prefixed with at least one 0.
1468 The function will ignore the pad space, which includes spaces or tab characters,
1469 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1470 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1471 first valid hexadecimal digit. Then, the function stops at the first character
1472 that is a not a valid hexadecimal character or NULL, whichever one comes first.
1473
1474 If String is NULL, then ASSERT().
1475 If String is not aligned in a 16-bit boundary, then ASSERT().
1476 If String has only pad spaces, then zero is returned.
1477 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1478 then zero is returned.
1479 If the number represented by String overflows according to the range defined by
1480 UINTN, then MAX_UINTN is returned.
1481
1482 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1483 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1484 then ASSERT().
1485
1486 @param String The pointer to a Null-terminated Unicode string.
1487
1488 @retval Value translated from String.
1489
1490 **/
1491 UINTN
1492 EFIAPI
1493 StrHexToUintn (
1494 IN CONST CHAR16 *String
1495 );
1496
1497
1498 /**
1499 Convert a Null-terminated Unicode hexadecimal string to a value of type UINT64.
1500
1501 This function returns a value of type UINT64 by interpreting the contents
1502 of the Unicode string specified by String as a hexadecimal number.
1503 The format of the input Unicode string String is
1504
1505 [spaces][zeros][x][hexadecimal digits].
1506
1507 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
1508 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix.
1509 If "x" appears in the input string, it must be prefixed with at least one 0.
1510 The function will ignore the pad space, which includes spaces or tab characters,
1511 before [zeros], [x] or [hexadecimal digit]. The running zero before [x] or
1512 [hexadecimal digit] will be ignored. Then, the decoding starts after [x] or the
1513 first valid hexadecimal digit. Then, the function stops at the first character that is
1514 a not a valid hexadecimal character or NULL, whichever one comes first.
1515
1516 If String is NULL, then ASSERT().
1517 If String is not aligned in a 16-bit boundary, then ASSERT().
1518 If String has only pad spaces, then zero is returned.
1519 If String has no leading pad spaces, leading zeros or valid hexadecimal digits,
1520 then zero is returned.
1521 If the number represented by String overflows according to the range defined by
1522 UINT64, then MAX_UINT64 is returned.
1523
1524 If PcdMaximumUnicodeStringLength is not zero, and String contains more than
1525 PcdMaximumUnicodeStringLength Unicode characters not including the Null-terminator,
1526 then ASSERT().
1527
1528 @param String The pointer to a Null-terminated Unicode string.
1529
1530 @retval Value translated from String.
1531
1532 **/
1533 UINT64
1534 EFIAPI
1535 StrHexToUint64 (
1536 IN CONST CHAR16 *String
1537 );
1538
1539 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1540
1541 /**
1542 [ATTENTION] This function is deprecated for security reason.
1543
1544 Convert a Null-terminated Unicode string to a Null-terminated
1545 ASCII string and returns the ASCII string.
1546
1547 This function converts the content of the Unicode string Source
1548 to the ASCII string Destination by copying the lower 8 bits of
1549 each Unicode character. It returns Destination.
1550
1551 The caller is responsible to make sure Destination points to a buffer with size
1552 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1553
1554 If any Unicode characters in Source contain non-zero value in
1555 the upper 8 bits, then ASSERT().
1556
1557 If Destination is NULL, then ASSERT().
1558 If Source is NULL, then ASSERT().
1559 If Source is not aligned on a 16-bit boundary, then ASSERT().
1560 If Source and Destination overlap, then ASSERT().
1561
1562 If PcdMaximumUnicodeStringLength is not zero, and Source contains
1563 more than PcdMaximumUnicodeStringLength Unicode characters not including
1564 the Null-terminator, then ASSERT().
1565
1566 If PcdMaximumAsciiStringLength is not zero, and Source contains more
1567 than PcdMaximumAsciiStringLength Unicode characters not including the
1568 Null-terminator, then ASSERT().
1569
1570 @param Source The pointer to a Null-terminated Unicode string.
1571 @param Destination The pointer to a Null-terminated ASCII string.
1572
1573 @return Destination.
1574
1575 **/
1576 CHAR8 *
1577 EFIAPI
1578 UnicodeStrToAsciiStr (
1579 IN CONST CHAR16 *Source,
1580 OUT CHAR8 *Destination
1581 );
1582
1583 #endif
1584
1585 /**
1586 Convert a Null-terminated Unicode string to a Null-terminated
1587 ASCII string.
1588
1589 This function is similar to AsciiStrCpyS.
1590
1591 This function converts the content of the Unicode string Source
1592 to the ASCII string Destination by copying the lower 8 bits of
1593 each Unicode character. The function terminates the ASCII string
1594 Destination by appending a Null-terminator character at the end.
1595
1596 The caller is responsible to make sure Destination points to a buffer with size
1597 equal or greater than ((StrLen (Source) + 1) * sizeof (CHAR8)) in bytes.
1598
1599 If any Unicode characters in Source contain non-zero value in
1600 the upper 8 bits, then ASSERT().
1601
1602 If Source is not aligned on a 16-bit boundary, then ASSERT().
1603 If an error would be returned, then the function will also ASSERT().
1604
1605 If an error is returned, then the Destination is unmodified.
1606
1607 @param Source The pointer to a Null-terminated Unicode string.
1608 @param Destination The pointer to a Null-terminated ASCII string.
1609 @param DestMax The maximum number of Destination Ascii
1610 char, including terminating null char.
1611
1612 @retval RETURN_SUCCESS String is converted.
1613 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
1614 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
1615 If Source is NULL.
1616 If PcdMaximumAsciiStringLength is not zero,
1617 and DestMax is greater than
1618 PcdMaximumAsciiStringLength.
1619 If PcdMaximumUnicodeStringLength is not zero,
1620 and DestMax is greater than
1621 PcdMaximumUnicodeStringLength.
1622 If DestMax is 0.
1623 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
1624
1625 **/
1626 RETURN_STATUS
1627 EFIAPI
1628 UnicodeStrToAsciiStrS (
1629 IN CONST CHAR16 *Source,
1630 OUT CHAR8 *Destination,
1631 IN UINTN DestMax
1632 );
1633
1634 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1635
1636 /**
1637 [ATTENTION] This function is deprecated for security reason.
1638
1639 Copies one Null-terminated ASCII string to another Null-terminated ASCII
1640 string and returns the new ASCII string.
1641
1642 This function copies the contents of the ASCII string Source to the ASCII
1643 string Destination, and returns Destination. If Source and Destination
1644 overlap, then the results are undefined.
1645
1646 If Destination is NULL, then ASSERT().
1647 If Source is NULL, then ASSERT().
1648 If Source and Destination overlap, then ASSERT().
1649 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1650 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1651 then ASSERT().
1652
1653 @param Destination The pointer to a Null-terminated ASCII string.
1654 @param Source The pointer to a Null-terminated ASCII string.
1655
1656 @return Destination
1657
1658 **/
1659 CHAR8 *
1660 EFIAPI
1661 AsciiStrCpy (
1662 OUT CHAR8 *Destination,
1663 IN CONST CHAR8 *Source
1664 );
1665
1666
1667 /**
1668 [ATTENTION] This function is deprecated for security reason.
1669
1670 Copies up to a specified length one Null-terminated ASCII string to another
1671 Null-terminated ASCII string and returns the new ASCII string.
1672
1673 This function copies the contents of the ASCII string Source to the ASCII
1674 string Destination, and returns Destination. At most, Length ASCII characters
1675 are copied from Source to Destination. If Length is 0, then Destination is
1676 returned unmodified. If Length is greater that the number of ASCII characters
1677 in Source, then Destination is padded with Null ASCII characters. If Source
1678 and Destination overlap, then the results are undefined.
1679
1680 If Destination is NULL, then ASSERT().
1681 If Source is NULL, then ASSERT().
1682 If Source and Destination overlap, then ASSERT().
1683 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1684 PcdMaximumAsciiStringLength, then ASSERT().
1685 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1686 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1687 then ASSERT().
1688
1689 @param Destination The pointer to a Null-terminated ASCII string.
1690 @param Source The pointer to a Null-terminated ASCII string.
1691 @param Length The maximum number of ASCII characters to copy.
1692
1693 @return Destination
1694
1695 **/
1696 CHAR8 *
1697 EFIAPI
1698 AsciiStrnCpy (
1699 OUT CHAR8 *Destination,
1700 IN CONST CHAR8 *Source,
1701 IN UINTN Length
1702 );
1703 #endif
1704
1705 /**
1706 Returns the length of a Null-terminated ASCII string.
1707
1708 This function returns the number of ASCII characters in the Null-terminated
1709 ASCII string specified by String.
1710
1711 If Length > 0 and Destination is NULL, then ASSERT().
1712 If Length > 0 and Source is NULL, then ASSERT().
1713 If PcdMaximumAsciiStringLength is not zero and String contains more than
1714 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1715 then ASSERT().
1716
1717 @param String The pointer to a Null-terminated ASCII string.
1718
1719 @return The length of String.
1720
1721 **/
1722 UINTN
1723 EFIAPI
1724 AsciiStrLen (
1725 IN CONST CHAR8 *String
1726 );
1727
1728
1729 /**
1730 Returns the size of a Null-terminated ASCII string in bytes, including the
1731 Null terminator.
1732
1733 This function returns the size, in bytes, of the Null-terminated ASCII string
1734 specified by String.
1735
1736 If String is NULL, then ASSERT().
1737 If PcdMaximumAsciiStringLength is not zero and String contains more than
1738 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1739 then ASSERT().
1740
1741 @param String The pointer to a Null-terminated ASCII string.
1742
1743 @return The size of String.
1744
1745 **/
1746 UINTN
1747 EFIAPI
1748 AsciiStrSize (
1749 IN CONST CHAR8 *String
1750 );
1751
1752
1753 /**
1754 Compares two Null-terminated ASCII strings, and returns the difference
1755 between the first mismatched ASCII characters.
1756
1757 This function compares the Null-terminated ASCII string FirstString to the
1758 Null-terminated ASCII string SecondString. If FirstString is identical to
1759 SecondString, then 0 is returned. Otherwise, the value returned is the first
1760 mismatched ASCII character in SecondString subtracted from the first
1761 mismatched ASCII character in FirstString.
1762
1763 If FirstString is NULL, then ASSERT().
1764 If SecondString is NULL, then ASSERT().
1765 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1766 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1767 then ASSERT().
1768 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1769 than PcdMaximumAsciiStringLength ASCII characters not including the
1770 Null-terminator, then ASSERT().
1771
1772 @param FirstString The pointer to a Null-terminated ASCII string.
1773 @param SecondString The pointer to a Null-terminated ASCII string.
1774
1775 @retval ==0 FirstString is identical to SecondString.
1776 @retval !=0 FirstString is not identical to SecondString.
1777
1778 **/
1779 INTN
1780 EFIAPI
1781 AsciiStrCmp (
1782 IN CONST CHAR8 *FirstString,
1783 IN CONST CHAR8 *SecondString
1784 );
1785
1786
1787 /**
1788 Performs a case insensitive comparison of two Null-terminated ASCII strings,
1789 and returns the difference between the first mismatched ASCII characters.
1790
1791 This function performs a case insensitive comparison of the Null-terminated
1792 ASCII string FirstString to the Null-terminated ASCII string SecondString. If
1793 FirstString is identical to SecondString, then 0 is returned. Otherwise, the
1794 value returned is the first mismatched lower case ASCII character in
1795 SecondString subtracted from the first mismatched lower case ASCII character
1796 in FirstString.
1797
1798 If FirstString is NULL, then ASSERT().
1799 If SecondString is NULL, then ASSERT().
1800 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than
1801 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1802 then ASSERT().
1803 If PcdMaximumAsciiStringLength is not zero and SecondString contains more
1804 than PcdMaximumAsciiStringLength ASCII characters not including the
1805 Null-terminator, then ASSERT().
1806
1807 @param FirstString The pointer to a Null-terminated ASCII string.
1808 @param SecondString The pointer to a Null-terminated ASCII string.
1809
1810 @retval ==0 FirstString is identical to SecondString using case insensitive
1811 comparisons.
1812 @retval !=0 FirstString is not identical to SecondString using case
1813 insensitive comparisons.
1814
1815 **/
1816 INTN
1817 EFIAPI
1818 AsciiStriCmp (
1819 IN CONST CHAR8 *FirstString,
1820 IN CONST CHAR8 *SecondString
1821 );
1822
1823
1824 /**
1825 Compares two Null-terminated ASCII strings with maximum lengths, and returns
1826 the difference between the first mismatched ASCII characters.
1827
1828 This function compares the Null-terminated ASCII string FirstString to the
1829 Null-terminated ASCII string SecondString. At most, Length ASCII characters
1830 will be compared. If Length is 0, then 0 is returned. If FirstString is
1831 identical to SecondString, then 0 is returned. Otherwise, the value returned
1832 is the first mismatched ASCII character in SecondString subtracted from the
1833 first mismatched ASCII character in FirstString.
1834
1835 If Length > 0 and FirstString is NULL, then ASSERT().
1836 If Length > 0 and SecondString is NULL, then ASSERT().
1837 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1838 PcdMaximumAsciiStringLength, then ASSERT().
1839 If PcdMaximumAsciiStringLength is not zero, and FirstString contains more than
1840 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1841 then ASSERT().
1842 If PcdMaximumAsciiStringLength is not zero, and SecondString contains more than
1843 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1844 then ASSERT().
1845
1846 @param FirstString The pointer to a Null-terminated ASCII string.
1847 @param SecondString The pointer to a Null-terminated ASCII string.
1848 @param Length The maximum number of ASCII characters for compare.
1849
1850 @retval ==0 FirstString is identical to SecondString.
1851 @retval !=0 FirstString is not identical to SecondString.
1852
1853 **/
1854 INTN
1855 EFIAPI
1856 AsciiStrnCmp (
1857 IN CONST CHAR8 *FirstString,
1858 IN CONST CHAR8 *SecondString,
1859 IN UINTN Length
1860 );
1861
1862
1863 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
1864
1865 /**
1866 [ATTENTION] This function is deprecated for security reason.
1867
1868 Concatenates one Null-terminated ASCII string to another Null-terminated
1869 ASCII string, and returns the concatenated ASCII string.
1870
1871 This function concatenates two Null-terminated ASCII strings. The contents of
1872 Null-terminated ASCII string Source are concatenated to the end of Null-
1873 terminated ASCII string Destination. The Null-terminated concatenated ASCII
1874 String is returned.
1875
1876 If Destination is NULL, then ASSERT().
1877 If Source is NULL, then ASSERT().
1878 If PcdMaximumAsciiStringLength is not zero and Destination contains more than
1879 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1880 then ASSERT().
1881 If PcdMaximumAsciiStringLength is not zero and Source contains more than
1882 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
1883 then ASSERT().
1884 If PcdMaximumAsciiStringLength is not zero and concatenating Destination and
1885 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1886 ASCII characters, then ASSERT().
1887
1888 @param Destination The pointer to a Null-terminated ASCII string.
1889 @param Source The pointer to a Null-terminated ASCII string.
1890
1891 @return Destination
1892
1893 **/
1894 CHAR8 *
1895 EFIAPI
1896 AsciiStrCat (
1897 IN OUT CHAR8 *Destination,
1898 IN CONST CHAR8 *Source
1899 );
1900
1901
1902 /**
1903 [ATTENTION] This function is deprecated for security reason.
1904
1905 Concatenates up to a specified length one Null-terminated ASCII string to
1906 the end of another Null-terminated ASCII string, and returns the
1907 concatenated ASCII string.
1908
1909 This function concatenates two Null-terminated ASCII strings. The contents
1910 of Null-terminated ASCII string Source are concatenated to the end of Null-
1911 terminated ASCII string Destination, and Destination is returned. At most,
1912 Length ASCII characters are concatenated from Source to the end of
1913 Destination, and Destination is always Null-terminated. If Length is 0, then
1914 Destination is returned unmodified. If Source and Destination overlap, then
1915 the results are undefined.
1916
1917 If Length > 0 and Destination is NULL, then ASSERT().
1918 If Length > 0 and Source is NULL, then ASSERT().
1919 If Source and Destination overlap, then ASSERT().
1920 If PcdMaximumAsciiStringLength is not zero, and Length is greater than
1921 PcdMaximumAsciiStringLength, then ASSERT().
1922 If PcdMaximumAsciiStringLength is not zero, and Destination contains more than
1923 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1924 then ASSERT().
1925 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
1926 PcdMaximumAsciiStringLength ASCII characters, not including the Null-terminator,
1927 then ASSERT().
1928 If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and
1929 Source results in a ASCII string with more than PcdMaximumAsciiStringLength
1930 ASCII characters, not including the Null-terminator, then ASSERT().
1931
1932 @param Destination The pointer to a Null-terminated ASCII string.
1933 @param Source The pointer to a Null-terminated ASCII string.
1934 @param Length The maximum number of ASCII characters to concatenate from
1935 Source.
1936
1937 @return Destination
1938
1939 **/
1940 CHAR8 *
1941 EFIAPI
1942 AsciiStrnCat (
1943 IN OUT CHAR8 *Destination,
1944 IN CONST CHAR8 *Source,
1945 IN UINTN Length
1946 );
1947 #endif
1948
1949 /**
1950 Returns the first occurrence of a Null-terminated ASCII sub-string
1951 in a Null-terminated ASCII string.
1952
1953 This function scans the contents of the ASCII string specified by String
1954 and returns the first occurrence of SearchString. If SearchString is not
1955 found in String, then NULL is returned. If the length of SearchString is zero,
1956 then String is returned.
1957
1958 If String is NULL, then ASSERT().
1959 If SearchString is NULL, then ASSERT().
1960
1961 If PcdMaximumAsciiStringLength is not zero, and SearchString or
1962 String contains more than PcdMaximumAsciiStringLength Unicode characters
1963 not including the Null-terminator, then ASSERT().
1964
1965 @param String The pointer to a Null-terminated ASCII string.
1966 @param SearchString The pointer to a Null-terminated ASCII string to search for.
1967
1968 @retval NULL If the SearchString does not appear in String.
1969 @retval others If there is a match return the first occurrence of SearchingString.
1970 If the length of SearchString is zero,return String.
1971
1972 **/
1973 CHAR8 *
1974 EFIAPI
1975 AsciiStrStr (
1976 IN CONST CHAR8 *String,
1977 IN CONST CHAR8 *SearchString
1978 );
1979
1980
1981 /**
1982 Convert a Null-terminated ASCII decimal string to a value of type
1983 UINTN.
1984
1985 This function returns a value of type UINTN by interpreting the contents
1986 of the ASCII string String as a decimal number. The format of the input
1987 ASCII string String is:
1988
1989 [spaces] [decimal digits].
1990
1991 The valid decimal digit character is in the range [0-9]. The function will
1992 ignore the pad space, which includes spaces or tab characters, before the digits.
1993 The running zero in the beginning of [decimal digits] will be ignored. Then, the
1994 function stops at the first character that is a not a valid decimal character or
1995 Null-terminator, whichever on comes first.
1996
1997 If String has only pad spaces, then 0 is returned.
1998 If String has no pad spaces or valid decimal digits, then 0 is returned.
1999 If the number represented by String overflows according to the range defined by
2000 UINTN, then MAX_UINTN is returned.
2001 If String is NULL, then ASSERT().
2002 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2003 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2004 then ASSERT().
2005
2006 @param String The pointer to a Null-terminated ASCII string.
2007
2008 @retval The value translated from String.
2009
2010 **/
2011 UINTN
2012 EFIAPI
2013 AsciiStrDecimalToUintn (
2014 IN CONST CHAR8 *String
2015 );
2016
2017
2018 /**
2019 Convert a Null-terminated ASCII decimal string to a value of type
2020 UINT64.
2021
2022 This function returns a value of type UINT64 by interpreting the contents
2023 of the ASCII string String as a decimal number. The format of the input
2024 ASCII string String is:
2025
2026 [spaces] [decimal digits].
2027
2028 The valid decimal digit character is in the range [0-9]. The function will
2029 ignore the pad space, which includes spaces or tab characters, before the digits.
2030 The running zero in the beginning of [decimal digits] will be ignored. Then, the
2031 function stops at the first character that is a not a valid decimal character or
2032 Null-terminator, whichever on comes first.
2033
2034 If String has only pad spaces, then 0 is returned.
2035 If String has no pad spaces or valid decimal digits, then 0 is returned.
2036 If the number represented by String overflows according to the range defined by
2037 UINT64, then MAX_UINT64 is returned.
2038 If String is NULL, then ASSERT().
2039 If PcdMaximumAsciiStringLength is not zero, and String contains more than
2040 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2041 then ASSERT().
2042
2043 @param String The pointer to a Null-terminated ASCII string.
2044
2045 @retval Value translated from String.
2046
2047 **/
2048 UINT64
2049 EFIAPI
2050 AsciiStrDecimalToUint64 (
2051 IN CONST CHAR8 *String
2052 );
2053
2054
2055 /**
2056 Convert a Null-terminated ASCII hexadecimal string to a value of type UINTN.
2057
2058 This function returns a value of type UINTN by interpreting the contents of
2059 the ASCII string String as a hexadecimal number. The format of the input ASCII
2060 string String is:
2061
2062 [spaces][zeros][x][hexadecimal digits].
2063
2064 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2065 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
2066 appears in the input string, it must be prefixed with at least one 0. The function
2067 will ignore the pad space, which includes spaces or tab characters, before [zeros],
2068 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
2069 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
2070 digit. Then, the function stops at the first character that is a not a valid
2071 hexadecimal character or Null-terminator, whichever on comes first.
2072
2073 If String has only pad spaces, then 0 is returned.
2074 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
2075 0 is returned.
2076
2077 If the number represented by String overflows according to the range defined by UINTN,
2078 then MAX_UINTN is returned.
2079 If String is NULL, then ASSERT().
2080 If PcdMaximumAsciiStringLength is not zero,
2081 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
2082 the Null-terminator, then ASSERT().
2083
2084 @param String The pointer to a Null-terminated ASCII string.
2085
2086 @retval Value translated from String.
2087
2088 **/
2089 UINTN
2090 EFIAPI
2091 AsciiStrHexToUintn (
2092 IN CONST CHAR8 *String
2093 );
2094
2095
2096 /**
2097 Convert a Null-terminated ASCII hexadecimal string to a value of type UINT64.
2098
2099 This function returns a value of type UINT64 by interpreting the contents of
2100 the ASCII string String as a hexadecimal number. The format of the input ASCII
2101 string String is:
2102
2103 [spaces][zeros][x][hexadecimal digits].
2104
2105 The valid hexadecimal digit character is in the range [0-9], [a-f] and [A-F].
2106 The prefix "0x" is optional. Both "x" and "X" is allowed in "0x" prefix. If "x"
2107 appears in the input string, it must be prefixed with at least one 0. The function
2108 will ignore the pad space, which includes spaces or tab characters, before [zeros],
2109 [x] or [hexadecimal digits]. The running zero before [x] or [hexadecimal digits]
2110 will be ignored. Then, the decoding starts after [x] or the first valid hexadecimal
2111 digit. Then, the function stops at the first character that is a not a valid
2112 hexadecimal character or Null-terminator, whichever on comes first.
2113
2114 If String has only pad spaces, then 0 is returned.
2115 If String has no leading pad spaces, leading zeros or valid hexadecimal digits, then
2116 0 is returned.
2117
2118 If the number represented by String overflows according to the range defined by UINT64,
2119 then MAX_UINT64 is returned.
2120 If String is NULL, then ASSERT().
2121 If PcdMaximumAsciiStringLength is not zero,
2122 and String contains more than PcdMaximumAsciiStringLength ASCII characters not including
2123 the Null-terminator, then ASSERT().
2124
2125 @param String The pointer to a Null-terminated ASCII string.
2126
2127 @retval Value translated from String.
2128
2129 **/
2130 UINT64
2131 EFIAPI
2132 AsciiStrHexToUint64 (
2133 IN CONST CHAR8 *String
2134 );
2135
2136 #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
2137
2138 /**
2139 [ATTENTION] This function is deprecated for security reason.
2140
2141 Convert one Null-terminated ASCII string to a Null-terminated
2142 Unicode string and returns the Unicode string.
2143
2144 This function converts the contents of the ASCII string Source to the Unicode
2145 string Destination, and returns Destination. The function terminates the
2146 Unicode string Destination by appending a Null-terminator character at the end.
2147 The caller is responsible to make sure Destination points to a buffer with size
2148 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2149
2150 If Destination is NULL, then ASSERT().
2151 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2152 If Source is NULL, then ASSERT().
2153 If Source and Destination overlap, then ASSERT().
2154 If PcdMaximumAsciiStringLength is not zero, and Source contains more than
2155 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,
2156 then ASSERT().
2157 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than
2158 PcdMaximumUnicodeStringLength ASCII characters not including the
2159 Null-terminator, then ASSERT().
2160
2161 @param Source The pointer to a Null-terminated ASCII string.
2162 @param Destination The pointer to a Null-terminated Unicode string.
2163
2164 @return Destination.
2165
2166 **/
2167 CHAR16 *
2168 EFIAPI
2169 AsciiStrToUnicodeStr (
2170 IN CONST CHAR8 *Source,
2171 OUT CHAR16 *Destination
2172 );
2173
2174 #endif
2175
2176 /**
2177 Convert one Null-terminated ASCII string to a Null-terminated
2178 Unicode string.
2179
2180 This function is similar to StrCpyS.
2181
2182 This function converts the contents of the ASCII string Source to the Unicode
2183 string Destination. The function terminates the Unicode string Destination by
2184 appending a Null-terminator character at the end.
2185
2186 The caller is responsible to make sure Destination points to a buffer with size
2187 equal or greater than ((AsciiStrLen (Source) + 1) * sizeof (CHAR16)) in bytes.
2188
2189 If Destination is not aligned on a 16-bit boundary, then ASSERT().
2190 If an error would be returned, then the function will also ASSERT().
2191
2192 If an error is returned, then the Destination is unmodified.
2193
2194 @param Source The pointer to a Null-terminated ASCII string.
2195 @param Destination The pointer to a Null-terminated Unicode string.
2196 @param DestMax The maximum number of Destination Unicode
2197 char, including terminating null char.
2198
2199 @retval RETURN_SUCCESS String is converted.
2200 @retval RETURN_BUFFER_TOO_SMALL If DestMax is NOT greater than StrLen(Source).
2201 @retval RETURN_INVALID_PARAMETER If Destination is NULL.
2202 If Source is NULL.
2203 If PcdMaximumUnicodeStringLength is not zero,
2204 and DestMax is greater than
2205 PcdMaximumUnicodeStringLength.
2206 If PcdMaximumAsciiStringLength is not zero,
2207 and DestMax is greater than
2208 PcdMaximumAsciiStringLength.
2209 If DestMax is 0.
2210 @retval RETURN_ACCESS_DENIED If Source and Destination overlap.
2211
2212 **/
2213 RETURN_STATUS
2214 EFIAPI
2215 AsciiStrToUnicodeStrS (
2216 IN CONST CHAR8 *Source,
2217 OUT CHAR16 *Destination,
2218 IN UINTN DestMax
2219 );
2220
2221 /**
2222 Converts an 8-bit value to an 8-bit BCD value.
2223
2224 Converts the 8-bit value specified by Value to BCD. The BCD value is
2225 returned.
2226
2227 If Value >= 100, then ASSERT().
2228
2229 @param Value The 8-bit value to convert to BCD. Range 0..99.
2230
2231 @return The BCD value.
2232
2233 **/
2234 UINT8
2235 EFIAPI
2236 DecimalToBcd8 (
2237 IN UINT8 Value
2238 );
2239
2240
2241 /**
2242 Converts an 8-bit BCD value to an 8-bit value.
2243
2244 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit
2245 value is returned.
2246
2247 If Value >= 0xA0, then ASSERT().
2248 If (Value & 0x0F) >= 0x0A, then ASSERT().
2249
2250 @param Value The 8-bit BCD value to convert to an 8-bit value.
2251
2252 @return The 8-bit value is returned.
2253
2254 **/
2255 UINT8
2256 EFIAPI
2257 BcdToDecimal8 (
2258 IN UINT8 Value
2259 );
2260
2261 //
2262 // File Path Manipulation Functions
2263 //
2264
2265 /**
2266 Removes the last directory or file entry in a path.
2267
2268 @param[in, out] Path The pointer to the path to modify.
2269
2270 @retval FALSE Nothing was found to remove.
2271 @retval TRUE A directory or file was removed.
2272 **/
2273 BOOLEAN
2274 EFIAPI
2275 PathRemoveLastItem(
2276 IN OUT CHAR16 *Path
2277 );
2278
2279 /**
2280 Function to clean up paths.
2281 - Single periods in the path are removed.
2282 - Double periods in the path are removed along with a single parent directory.
2283 - Forward slashes L'/' are converted to backward slashes L'\'.
2284
2285 This will be done inline and the existing buffer may be larger than required
2286 upon completion.
2287
2288 @param[in] Path The pointer to the string containing the path.
2289
2290 @return Returns Path, otherwise returns NULL to indicate that an error has occurred.
2291 **/
2292 CHAR16*
2293 EFIAPI
2294 PathCleanUpDirectories(
2295 IN CHAR16 *Path
2296 );
2297
2298 //
2299 // Linked List Functions and Macros
2300 //
2301
2302 /**
2303 Initializes the head node of a doubly linked list that is declared as a
2304 global variable in a module.
2305
2306 Initializes the forward and backward links of a new linked list. After
2307 initializing a linked list with this macro, the other linked list functions
2308 may be used to add and remove nodes from the linked list. This macro results
2309 in smaller executables by initializing the linked list in the data section,
2310 instead if calling the InitializeListHead() function to perform the
2311 equivalent operation.
2312
2313 @param ListHead The head note of a list to initialize.
2314
2315 **/
2316 #define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&(ListHead), &(ListHead)}
2317
2318
2319 /**
2320 Initializes the head node of a doubly linked list, and returns the pointer to
2321 the head node of the doubly linked list.
2322
2323 Initializes the forward and backward links of a new linked list. After
2324 initializing a linked list with this function, the other linked list
2325 functions may be used to add and remove nodes from the linked list. It is up
2326 to the caller of this function to allocate the memory for ListHead.
2327
2328 If ListHead is NULL, then ASSERT().
2329
2330 @param ListHead A pointer to the head node of a new doubly linked list.
2331
2332 @return ListHead
2333
2334 **/
2335 LIST_ENTRY *
2336 EFIAPI
2337 InitializeListHead (
2338 IN OUT LIST_ENTRY *ListHead
2339 );
2340
2341
2342 /**
2343 Adds a node to the beginning of a doubly linked list, and returns the pointer
2344 to the head node of the doubly linked list.
2345
2346 Adds the node Entry at the beginning of the doubly linked list denoted by
2347 ListHead, and returns ListHead.
2348
2349 If ListHead is NULL, then ASSERT().
2350 If Entry is NULL, then ASSERT().
2351 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2352 InitializeListHead(), then ASSERT().
2353 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2354 of nodes in ListHead, including the ListHead node, is greater than or
2355 equal to PcdMaximumLinkedListLength, then ASSERT().
2356
2357 @param ListHead A pointer to the head node of a doubly linked list.
2358 @param Entry A pointer to a node that is to be inserted at the beginning
2359 of a doubly linked list.
2360
2361 @return ListHead
2362
2363 **/
2364 LIST_ENTRY *
2365 EFIAPI
2366 InsertHeadList (
2367 IN OUT LIST_ENTRY *ListHead,
2368 IN OUT LIST_ENTRY *Entry
2369 );
2370
2371
2372 /**
2373 Adds a node to the end of a doubly linked list, and returns the pointer to
2374 the head node of the doubly linked list.
2375
2376 Adds the node Entry to the end of the doubly linked list denoted by ListHead,
2377 and returns ListHead.
2378
2379 If ListHead is NULL, then ASSERT().
2380 If Entry is NULL, then ASSERT().
2381 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2382 InitializeListHead(), then ASSERT().
2383 If PcdMaximumLinkedListLength is not zero, and prior to insertion the number
2384 of nodes in ListHead, including the ListHead node, is greater than or
2385 equal to PcdMaximumLinkedListLength, then ASSERT().
2386
2387 @param ListHead A pointer to the head node of a doubly linked list.
2388 @param Entry A pointer to a node that is to be added at the end of the
2389 doubly linked list.
2390
2391 @return ListHead
2392
2393 **/
2394 LIST_ENTRY *
2395 EFIAPI
2396 InsertTailList (
2397 IN OUT LIST_ENTRY *ListHead,
2398 IN OUT LIST_ENTRY *Entry
2399 );
2400
2401
2402 /**
2403 Retrieves the first node of a doubly linked list.
2404
2405 Returns the first node of a doubly linked list. List must have been
2406 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2407 If List is empty, then List is returned.
2408
2409 If List is NULL, then ASSERT().
2410 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2411 InitializeListHead(), then ASSERT().
2412 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2413 in List, including the List node, is greater than or equal to
2414 PcdMaximumLinkedListLength, then ASSERT().
2415
2416 @param List A pointer to the head node of a doubly linked list.
2417
2418 @return The first node of a doubly linked list.
2419 @retval List The list is empty.
2420
2421 **/
2422 LIST_ENTRY *
2423 EFIAPI
2424 GetFirstNode (
2425 IN CONST LIST_ENTRY *List
2426 );
2427
2428
2429 /**
2430 Retrieves the next node of a doubly linked list.
2431
2432 Returns the node of a doubly linked list that follows Node.
2433 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
2434 or InitializeListHead(). If List is empty, then List is returned.
2435
2436 If List is NULL, then ASSERT().
2437 If Node is NULL, then ASSERT().
2438 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2439 InitializeListHead(), then ASSERT().
2440 If PcdMaximumLinkedListLength is not zero, and List contains more than
2441 PcdMaximumLinkedListLength nodes, then ASSERT().
2442 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2443
2444 @param List A pointer to the head node of a doubly linked list.
2445 @param Node A pointer to a node in the doubly linked list.
2446
2447 @return The pointer to the next node if one exists. Otherwise List is returned.
2448
2449 **/
2450 LIST_ENTRY *
2451 EFIAPI
2452 GetNextNode (
2453 IN CONST LIST_ENTRY *List,
2454 IN CONST LIST_ENTRY *Node
2455 );
2456
2457
2458 /**
2459 Retrieves the previous node of a doubly linked list.
2460
2461 Returns the node of a doubly linked list that precedes Node.
2462 List must have been initialized with INTIALIZE_LIST_HEAD_VARIABLE()
2463 or InitializeListHead(). If List is empty, then List is returned.
2464
2465 If List is NULL, then ASSERT().
2466 If Node is NULL, then ASSERT().
2467 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2468 InitializeListHead(), then ASSERT().
2469 If PcdMaximumLinkedListLength is not zero, and List contains more than
2470 PcdMaximumLinkedListLength nodes, then ASSERT().
2471 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2472
2473 @param List A pointer to the head node of a doubly linked list.
2474 @param Node A pointer to a node in the doubly linked list.
2475
2476 @return The pointer to the previous node if one exists. Otherwise List is returned.
2477
2478 **/
2479 LIST_ENTRY *
2480 EFIAPI
2481 GetPreviousNode (
2482 IN CONST LIST_ENTRY *List,
2483 IN CONST LIST_ENTRY *Node
2484 );
2485
2486
2487 /**
2488 Checks to see if a doubly linked list is empty or not.
2489
2490 Checks to see if the doubly linked list is empty. If the linked list contains
2491 zero nodes, this function returns TRUE. Otherwise, it returns FALSE.
2492
2493 If ListHead is NULL, then ASSERT().
2494 If ListHead was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2495 InitializeListHead(), then ASSERT().
2496 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2497 in List, including the List node, is greater than or equal to
2498 PcdMaximumLinkedListLength, then ASSERT().
2499
2500 @param ListHead A pointer to the head node of a doubly linked list.
2501
2502 @retval TRUE The linked list is empty.
2503 @retval FALSE The linked list is not empty.
2504
2505 **/
2506 BOOLEAN
2507 EFIAPI
2508 IsListEmpty (
2509 IN CONST LIST_ENTRY *ListHead
2510 );
2511
2512
2513 /**
2514 Determines if a node in a doubly linked list is the head node of a the same
2515 doubly linked list. This function is typically used to terminate a loop that
2516 traverses all the nodes in a doubly linked list starting with the head node.
2517
2518 Returns TRUE if Node is equal to List. Returns FALSE if Node is one of the
2519 nodes in the doubly linked list specified by List. List must have been
2520 initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2521
2522 If List is NULL, then ASSERT().
2523 If Node is NULL, then ASSERT().
2524 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead(),
2525 then ASSERT().
2526 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2527 in List, including the List node, is greater than or equal to
2528 PcdMaximumLinkedListLength, then ASSERT().
2529 If PcdVerifyNodeInList is TRUE and Node is not a node in List the and Node is not equal
2530 to List, then ASSERT().
2531
2532 @param List A pointer to the head node of a doubly linked list.
2533 @param Node A pointer to a node in the doubly linked list.
2534
2535 @retval TRUE Node is the head of the doubly-linked list pointed by List.
2536 @retval FALSE Node is not the head of the doubly-linked list pointed by List.
2537
2538 **/
2539 BOOLEAN
2540 EFIAPI
2541 IsNull (
2542 IN CONST LIST_ENTRY *List,
2543 IN CONST LIST_ENTRY *Node
2544 );
2545
2546
2547 /**
2548 Determines if a node the last node in a doubly linked list.
2549
2550 Returns TRUE if Node is the last node in the doubly linked list specified by
2551 List. Otherwise, FALSE is returned. List must have been initialized with
2552 INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2553
2554 If List is NULL, then ASSERT().
2555 If Node is NULL, then ASSERT().
2556 If List was not initialized with INTIALIZE_LIST_HEAD_VARIABLE() or
2557 InitializeListHead(), then ASSERT().
2558 If PcdMaximumLinkedListLength is not zero, and the number of nodes
2559 in List, including the List node, is greater than or equal to
2560 PcdMaximumLinkedListLength, then ASSERT().
2561 If PcdVerifyNodeInList is TRUE and Node is not a node in List, then ASSERT().
2562
2563 @param List A pointer to the head node of a doubly linked list.
2564 @param Node A pointer to a node in the doubly linked list.
2565
2566 @retval TRUE Node is the last node in the linked list.
2567 @retval FALSE Node is not the last node in the linked list.
2568
2569 **/
2570 BOOLEAN
2571 EFIAPI
2572 IsNodeAtEnd (
2573 IN CONST LIST_ENTRY *List,
2574 IN CONST LIST_ENTRY *Node
2575 );
2576
2577
2578 /**
2579 Swaps the location of two nodes in a doubly linked list, and returns the
2580 first node after the swap.
2581
2582 If FirstEntry is identical to SecondEntry, then SecondEntry is returned.
2583 Otherwise, the location of the FirstEntry node is swapped with the location
2584 of the SecondEntry node in a doubly linked list. SecondEntry must be in the
2585 same double linked list as FirstEntry and that double linked list must have
2586 been initialized with INTIALIZE_LIST_HEAD_VARIABLE() or InitializeListHead().
2587 SecondEntry is returned after the nodes are swapped.
2588
2589 If FirstEntry is NULL, then ASSERT().
2590 If SecondEntry is NULL, then ASSERT().
2591 If PcdVerifyNodeInList is TRUE and SecondEntry and FirstEntry are not in the
2592 same linked list, then ASSERT().
2593 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
2594 linked list containing the FirstEntry and SecondEntry nodes, including
2595 the FirstEntry and SecondEntry nodes, is greater than or equal to
2596 PcdMaximumLinkedListLength, then ASSERT().
2597
2598 @param FirstEntry A pointer to a node in a linked list.
2599 @param SecondEntry A pointer to another node in the same linked list.
2600
2601 @return SecondEntry.
2602
2603 **/
2604 LIST_ENTRY *
2605 EFIAPI
2606 SwapListEntries (
2607 IN OUT LIST_ENTRY *FirstEntry,
2608 IN OUT LIST_ENTRY *SecondEntry
2609 );
2610
2611
2612 /**
2613 Removes a node from a doubly linked list, and returns the node that follows
2614 the removed node.
2615
2616 Removes the node Entry from a doubly linked list. It is up to the caller of
2617 this function to release the memory used by this node if that is required. On
2618 exit, the node following Entry in the doubly linked list is returned. If
2619 Entry is the only node in the linked list, then the head node of the linked
2620 list is returned.
2621
2622 If Entry is NULL, then ASSERT().
2623 If Entry is the head node of an empty list, then ASSERT().
2624 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the
2625 linked list containing Entry, including the Entry node, is greater than
2626 or equal to PcdMaximumLinkedListLength, then ASSERT().
2627
2628 @param Entry A pointer to a node in a linked list.
2629
2630 @return Entry.
2631
2632 **/
2633 LIST_ENTRY *
2634 EFIAPI
2635 RemoveEntryList (
2636 IN CONST LIST_ENTRY *Entry
2637 );
2638
2639 //
2640 // Math Services
2641 //
2642
2643 /**
2644 Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled
2645 with zeros. The shifted value is returned.
2646
2647 This function shifts the 64-bit value Operand to the left by Count bits. The
2648 low Count bits are set to zero. The shifted value is returned.
2649
2650 If Count is greater than 63, then ASSERT().
2651
2652 @param Operand The 64-bit operand to shift left.
2653 @param Count The number of bits to shift left.
2654
2655 @return Operand << Count.
2656
2657 **/
2658 UINT64
2659 EFIAPI
2660 LShiftU64 (
2661 IN UINT64 Operand,
2662 IN UINTN Count
2663 );
2664
2665
2666 /**
2667 Shifts a 64-bit integer right between 0 and 63 bits. This high bits are
2668 filled with zeros. The shifted value is returned.
2669
2670 This function shifts the 64-bit value Operand to the right by Count bits. The
2671 high Count bits are set to zero. The shifted value is returned.
2672
2673 If Count is greater than 63, then ASSERT().
2674
2675 @param Operand The 64-bit operand to shift right.
2676 @param Count The number of bits to shift right.
2677
2678 @return Operand >> Count
2679
2680 **/
2681 UINT64
2682 EFIAPI
2683 RShiftU64 (
2684 IN UINT64 Operand,
2685 IN UINTN Count
2686 );
2687
2688
2689 /**
2690 Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled
2691 with original integer's bit 63. The shifted value is returned.
2692
2693 This function shifts the 64-bit value Operand to the right by Count bits. The
2694 high Count bits are set to bit 63 of Operand. The shifted value is returned.
2695
2696 If Count is greater than 63, then ASSERT().
2697
2698 @param Operand The 64-bit operand to shift right.
2699 @param Count The number of bits to shift right.
2700
2701 @return Operand >> Count
2702
2703 **/
2704 UINT64
2705 EFIAPI
2706 ARShiftU64 (
2707 IN UINT64 Operand,
2708 IN UINTN Count
2709 );
2710
2711
2712 /**
2713 Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits
2714 with the high bits that were rotated.
2715
2716 This function rotates the 32-bit value Operand to the left by Count bits. The
2717 low Count bits are fill with the high Count bits of Operand. The rotated
2718 value is returned.
2719
2720 If Count is greater than 31, then ASSERT().
2721
2722 @param Operand The 32-bit operand to rotate left.
2723 @param Count The number of bits to rotate left.
2724
2725 @return Operand << Count
2726
2727 **/
2728 UINT32
2729 EFIAPI
2730 LRotU32 (
2731 IN UINT32 Operand,
2732 IN UINTN Count
2733 );
2734
2735
2736 /**
2737 Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits
2738 with the low bits that were rotated.
2739
2740 This function rotates the 32-bit value Operand to the right by Count bits.
2741 The high Count bits are fill with the low Count bits of Operand. The rotated
2742 value is returned.
2743
2744 If Count is greater than 31, then ASSERT().
2745
2746 @param Operand The 32-bit operand to rotate right.
2747 @param Count The number of bits to rotate right.
2748
2749 @return Operand >> Count
2750
2751 **/
2752 UINT32
2753 EFIAPI
2754 RRotU32 (
2755 IN UINT32 Operand,
2756 IN UINTN Count
2757 );
2758
2759
2760 /**
2761 Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits
2762 with the high bits that were rotated.
2763
2764 This function rotates the 64-bit value Operand to the left by Count bits. The
2765 low Count bits are fill with the high Count bits of Operand. The rotated
2766 value is returned.
2767
2768 If Count is greater than 63, then ASSERT().
2769
2770 @param Operand The 64-bit operand to rotate left.
2771 @param Count The number of bits to rotate left.
2772
2773 @return Operand << Count
2774
2775 **/
2776 UINT64
2777 EFIAPI
2778 LRotU64 (
2779 IN UINT64 Operand,
2780 IN UINTN Count
2781 );
2782
2783
2784 /**
2785 Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits
2786 with the high low bits that were rotated.
2787
2788 This function rotates the 64-bit value Operand to the right by Count bits.
2789 The high Count bits are fill with the low Count bits of Operand. The rotated
2790 value is returned.
2791
2792 If Count is greater than 63, then ASSERT().
2793
2794 @param Operand The 64-bit operand to rotate right.
2795 @param Count The number of bits to rotate right.
2796
2797 @return Operand >> Count
2798
2799 **/
2800 UINT64
2801 EFIAPI
2802 RRotU64 (
2803 IN UINT64 Operand,
2804 IN UINTN Count
2805 );
2806
2807
2808 /**
2809 Returns the bit position of the lowest bit set in a 32-bit value.
2810
2811 This function computes the bit position of the lowest bit set in the 32-bit
2812 value specified by Operand. If Operand is zero, then -1 is returned.
2813 Otherwise, a value between 0 and 31 is returned.
2814
2815 @param Operand The 32-bit operand to evaluate.
2816
2817 @retval 0..31 The lowest bit set in Operand was found.
2818 @retval -1 Operand is zero.
2819
2820 **/
2821 INTN
2822 EFIAPI
2823 LowBitSet32 (
2824 IN UINT32 Operand
2825 );
2826
2827
2828 /**
2829 Returns the bit position of the lowest bit set in a 64-bit value.
2830
2831 This function computes the bit position of the lowest bit set in the 64-bit
2832 value specified by Operand. If Operand is zero, then -1 is returned.
2833 Otherwise, a value between 0 and 63 is returned.
2834
2835 @param Operand The 64-bit operand to evaluate.
2836
2837 @retval 0..63 The lowest bit set in Operand was found.
2838 @retval -1 Operand is zero.
2839
2840
2841 **/
2842 INTN
2843 EFIAPI
2844 LowBitSet64 (
2845 IN UINT64 Operand
2846 );
2847
2848
2849 /**
2850 Returns the bit position of the highest bit set in a 32-bit value. Equivalent
2851 to log2(x).
2852
2853 This function computes the bit position of the highest bit set in the 32-bit
2854 value specified by Operand. If Operand is zero, then -1 is returned.
2855 Otherwise, a value between 0 and 31 is returned.
2856
2857 @param Operand The 32-bit operand to evaluate.
2858
2859 @retval 0..31 Position of the highest bit set in Operand if found.
2860 @retval -1 Operand is zero.
2861
2862 **/
2863 INTN
2864 EFIAPI
2865 HighBitSet32 (
2866 IN UINT32 Operand
2867 );
2868
2869
2870 /**
2871 Returns the bit position of the highest bit set in a 64-bit value. Equivalent
2872 to log2(x).
2873
2874 This function computes the bit position of the highest bit set in the 64-bit
2875 value specified by Operand. If Operand is zero, then -1 is returned.
2876 Otherwise, a value between 0 and 63 is returned.
2877
2878 @param Operand The 64-bit operand to evaluate.
2879
2880 @retval 0..63 Position of the highest bit set in Operand if found.
2881 @retval -1 Operand is zero.
2882
2883 **/
2884 INTN
2885 EFIAPI
2886 HighBitSet64 (
2887 IN UINT64 Operand
2888 );
2889
2890
2891 /**
2892 Returns the value of the highest bit set in a 32-bit value. Equivalent to
2893 1 << log2(x).
2894
2895 This function computes the value of the highest bit set in the 32-bit value
2896 specified by Operand. If Operand is zero, then zero is returned.
2897
2898 @param Operand The 32-bit operand to evaluate.
2899
2900 @return 1 << HighBitSet32(Operand)
2901 @retval 0 Operand is zero.
2902
2903 **/
2904 UINT32
2905 EFIAPI
2906 GetPowerOfTwo32 (
2907 IN UINT32 Operand
2908 );
2909
2910
2911 /**
2912 Returns the value of the highest bit set in a 64-bit value. Equivalent to
2913 1 << log2(x).
2914
2915 This function computes the value of the highest bit set in the 64-bit value
2916 specified by Operand. If Operand is zero, then zero is returned.
2917
2918 @param Operand The 64-bit operand to evaluate.
2919
2920 @return 1 << HighBitSet64(Operand)
2921 @retval 0 Operand is zero.
2922
2923 **/
2924 UINT64
2925 EFIAPI
2926 GetPowerOfTwo64 (
2927 IN UINT64 Operand
2928 );
2929
2930
2931 /**
2932 Switches the endianness of a 16-bit integer.
2933
2934 This function swaps the bytes in a 16-bit unsigned value to switch the value
2935 from little endian to big endian or vice versa. The byte swapped value is
2936 returned.
2937
2938 @param Value A 16-bit unsigned value.
2939
2940 @return The byte swapped Value.
2941
2942 **/
2943 UINT16
2944 EFIAPI
2945 SwapBytes16 (
2946 IN UINT16 Value
2947 );
2948
2949
2950 /**
2951 Switches the endianness of a 32-bit integer.
2952
2953 This function swaps the bytes in a 32-bit unsigned value to switch the value
2954 from little endian to big endian or vice versa. The byte swapped value is
2955 returned.
2956
2957 @param Value A 32-bit unsigned value.
2958
2959 @return The byte swapped Value.
2960
2961 **/
2962 UINT32
2963 EFIAPI
2964 SwapBytes32 (
2965 IN UINT32 Value
2966 );
2967
2968
2969 /**
2970 Switches the endianness of a 64-bit integer.
2971
2972 This function swaps the bytes in a 64-bit unsigned value to switch the value
2973 from little endian to big endian or vice versa. The byte swapped value is
2974 returned.
2975
2976 @param Value A 64-bit unsigned value.
2977
2978 @return The byte swapped Value.
2979
2980 **/
2981 UINT64
2982 EFIAPI
2983 SwapBytes64 (
2984 IN UINT64 Value
2985 );
2986
2987
2988 /**
2989 Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and
2990 generates a 64-bit unsigned result.
2991
2992 This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
2993 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
2994 bit unsigned result is returned.
2995
2996 @param Multiplicand A 64-bit unsigned value.
2997 @param Multiplier A 32-bit unsigned value.
2998
2999 @return Multiplicand * Multiplier
3000
3001 **/
3002 UINT64
3003 EFIAPI
3004 MultU64x32 (
3005 IN UINT64 Multiplicand,
3006 IN UINT32 Multiplier
3007 );
3008
3009
3010 /**
3011 Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and
3012 generates a 64-bit unsigned result.
3013
3014 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
3015 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
3016 bit unsigned result is returned.
3017
3018 @param Multiplicand A 64-bit unsigned value.
3019 @param Multiplier A 64-bit unsigned value.
3020
3021 @return Multiplicand * Multiplier.
3022
3023 **/
3024 UINT64
3025 EFIAPI
3026 MultU64x64 (
3027 IN UINT64 Multiplicand,
3028 IN UINT64 Multiplier
3029 );
3030
3031
3032 /**
3033 Multiples a 64-bit signed integer by a 64-bit signed integer and generates a
3034 64-bit signed result.
3035
3036 This function multiples the 64-bit signed value Multiplicand by the 64-bit
3037 signed value Multiplier and generates a 64-bit signed result. This 64-bit
3038 signed result is returned.
3039
3040 @param Multiplicand A 64-bit signed value.
3041 @param Multiplier A 64-bit signed value.
3042
3043 @return Multiplicand * Multiplier
3044
3045 **/
3046 INT64
3047 EFIAPI
3048 MultS64x64 (
3049 IN INT64 Multiplicand,
3050 IN INT64 Multiplier
3051 );
3052
3053
3054 /**
3055 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3056 a 64-bit unsigned result.
3057
3058 This function divides the 64-bit unsigned value Dividend by the 32-bit
3059 unsigned value Divisor and generates a 64-bit unsigned quotient. This
3060 function returns the 64-bit unsigned quotient.
3061
3062 If Divisor is 0, then ASSERT().
3063
3064 @param Dividend A 64-bit unsigned value.
3065 @param Divisor A 32-bit unsigned value.
3066
3067 @return Dividend / Divisor.
3068
3069 **/
3070 UINT64
3071 EFIAPI
3072 DivU64x32 (
3073 IN UINT64 Dividend,
3074 IN UINT32 Divisor
3075 );
3076
3077
3078 /**
3079 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3080 a 32-bit unsigned remainder.
3081
3082 This function divides the 64-bit unsigned value Dividend by the 32-bit
3083 unsigned value Divisor and generates a 32-bit remainder. This function
3084 returns the 32-bit unsigned remainder.
3085
3086 If Divisor is 0, then ASSERT().
3087
3088 @param Dividend A 64-bit unsigned value.
3089 @param Divisor A 32-bit unsigned value.
3090
3091 @return Dividend % Divisor.
3092
3093 **/
3094 UINT32
3095 EFIAPI
3096 ModU64x32 (
3097 IN UINT64 Dividend,
3098 IN UINT32 Divisor
3099 );
3100
3101
3102 /**
3103 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates
3104 a 64-bit unsigned result and an optional 32-bit unsigned remainder.
3105
3106 This function divides the 64-bit unsigned value Dividend by the 32-bit
3107 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3108 is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
3109 This function returns the 64-bit unsigned quotient.
3110
3111 If Divisor is 0, then ASSERT().
3112
3113 @param Dividend A 64-bit unsigned value.
3114 @param Divisor A 32-bit unsigned value.
3115 @param Remainder A pointer to a 32-bit unsigned value. This parameter is
3116 optional and may be NULL.
3117
3118 @return Dividend / Divisor.
3119
3120 **/
3121 UINT64
3122 EFIAPI
3123 DivU64x32Remainder (
3124 IN UINT64 Dividend,
3125 IN UINT32 Divisor,
3126 OUT UINT32 *Remainder OPTIONAL
3127 );
3128
3129
3130 /**
3131 Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates
3132 a 64-bit unsigned result and an optional 64-bit unsigned remainder.
3133
3134 This function divides the 64-bit unsigned value Dividend by the 64-bit
3135 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
3136 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
3137 This function returns the 64-bit unsigned quotient.
3138
3139 If Divisor is 0, then ASSERT().
3140
3141 @param Dividend A 64-bit unsigned value.
3142 @param Divisor A 64-bit unsigned value.
3143 @param Remainder A pointer to a 64-bit unsigned value. This parameter is
3144 optional and may be NULL.
3145
3146 @return Dividend / Divisor.
3147
3148 **/
3149 UINT64
3150 EFIAPI
3151 DivU64x64Remainder (
3152 IN UINT64 Dividend,
3153 IN UINT64 Divisor,
3154 OUT UINT64 *Remainder OPTIONAL
3155 );
3156
3157
3158 /**
3159 Divides a 64-bit signed integer by a 64-bit signed integer and generates a
3160 64-bit signed result and a optional 64-bit signed remainder.
3161
3162 This function divides the 64-bit signed value Dividend by the 64-bit signed
3163 value Divisor and generates a 64-bit signed quotient. If Remainder is not
3164 NULL, then the 64-bit signed remainder is returned in Remainder. This
3165 function returns the 64-bit signed quotient.
3166
3167 It is the caller's responsibility to not call this function with a Divisor of 0.
3168 If Divisor is 0, then the quotient and remainder should be assumed to be
3169 the largest negative integer.
3170
3171 If Divisor is 0, then ASSERT().
3172
3173 @param Dividend A 64-bit signed value.
3174 @param Divisor A 64-bit signed value.
3175 @param Remainder A pointer to a 64-bit signed value. This parameter is
3176 optional and may be NULL.
3177
3178 @return Dividend / Divisor.
3179
3180 **/
3181 INT64
3182 EFIAPI
3183 DivS64x64Remainder (
3184 IN INT64 Dividend,
3185 IN INT64 Divisor,
3186 OUT INT64 *Remainder OPTIONAL
3187 );
3188
3189
3190 /**
3191 Reads a 16-bit value from memory that may be unaligned.
3192
3193 This function returns the 16-bit value pointed to by Buffer. The function
3194 guarantees that the read operation does not produce an alignment fault.
3195
3196 If the Buffer is NULL, then ASSERT().
3197
3198 @param Buffer The pointer to a 16-bit value that may be unaligned.
3199
3200 @return The 16-bit value read from Buffer.
3201
3202 **/
3203 UINT16
3204 EFIAPI
3205 ReadUnaligned16 (
3206 IN CONST UINT16 *Buffer
3207 );
3208
3209
3210 /**
3211 Writes a 16-bit value to memory that may be unaligned.
3212
3213 This function writes the 16-bit value specified by Value to Buffer. Value is
3214 returned. The function guarantees that the write operation does not produce
3215 an alignment fault.
3216
3217 If the Buffer is NULL, then ASSERT().
3218
3219 @param Buffer The pointer to a 16-bit value that may be unaligned.
3220 @param Value 16-bit value to write to Buffer.
3221
3222 @return The 16-bit value to write to Buffer.
3223
3224 **/
3225 UINT16
3226 EFIAPI
3227 WriteUnaligned16 (
3228 OUT UINT16 *Buffer,
3229 IN UINT16 Value
3230 );
3231
3232
3233 /**
3234 Reads a 24-bit value from memory that may be unaligned.
3235
3236 This function returns the 24-bit value pointed to by Buffer. The function
3237 guarantees that the read operation does not produce an alignment fault.
3238
3239 If the Buffer is NULL, then ASSERT().
3240
3241 @param Buffer The pointer to a 24-bit value that may be unaligned.
3242
3243 @return The 24-bit value read from Buffer.
3244
3245 **/
3246 UINT32
3247 EFIAPI
3248 ReadUnaligned24 (
3249 IN CONST UINT32 *Buffer
3250 );
3251
3252
3253 /**
3254 Writes a 24-bit value to memory that may be unaligned.
3255
3256 This function writes the 24-bit value specified by Value to Buffer. Value is
3257 returned. The function guarantees that the write operation does not produce
3258 an alignment fault.
3259
3260 If the Buffer is NULL, then ASSERT().
3261
3262 @param Buffer The pointer to a 24-bit value that may be unaligned.
3263 @param Value 24-bit value to write to Buffer.
3264
3265 @return The 24-bit value to write to Buffer.
3266
3267 **/
3268 UINT32
3269 EFIAPI
3270 WriteUnaligned24 (
3271 OUT UINT32 *Buffer,
3272 IN UINT32 Value
3273 );
3274
3275
3276 /**
3277 Reads a 32-bit value from memory that may be unaligned.
3278
3279 This function returns the 32-bit value pointed to by Buffer. The function
3280 guarantees that the read operation does not produce an alignment fault.
3281
3282 If the Buffer is NULL, then ASSERT().
3283
3284 @param Buffer The pointer to a 32-bit value that may be unaligned.
3285
3286 @return The 32-bit value read from Buffer.
3287
3288 **/
3289 UINT32
3290 EFIAPI
3291 ReadUnaligned32 (
3292 IN CONST UINT32 *Buffer
3293 );
3294
3295
3296 /**
3297 Writes a 32-bit value to memory that may be unaligned.
3298
3299 This function writes the 32-bit value specified by Value to Buffer. Value is
3300 returned. The function guarantees that the write operation does not produce
3301 an alignment fault.
3302
3303 If the Buffer is NULL, then ASSERT().
3304
3305 @param Buffer The pointer to a 32-bit value that may be unaligned.
3306 @param Value 32-bit value to write to Buffer.
3307
3308 @return The 32-bit value to write to Buffer.
3309
3310 **/
3311 UINT32
3312 EFIAPI
3313 WriteUnaligned32 (
3314 OUT UINT32 *Buffer,
3315 IN UINT32 Value
3316 );
3317
3318
3319 /**
3320 Reads a 64-bit value from memory that may be unaligned.
3321
3322 This function returns the 64-bit value pointed to by Buffer. The function
3323 guarantees that the read operation does not produce an alignment fault.
3324
3325 If the Buffer is NULL, then ASSERT().
3326
3327 @param Buffer The pointer to a 64-bit value that may be unaligned.
3328
3329 @return The 64-bit value read from Buffer.
3330
3331 **/
3332 UINT64
3333 EFIAPI
3334 ReadUnaligned64 (
3335 IN CONST UINT64 *Buffer
3336 );
3337
3338
3339 /**
3340 Writes a 64-bit value to memory that may be unaligned.
3341
3342 This function writes the 64-bit value specified by Value to Buffer. Value is
3343 returned. The function guarantees that the write operation does not produce
3344 an alignment fault.
3345
3346 If the Buffer is NULL, then ASSERT().
3347
3348 @param Buffer The pointer to a 64-bit value that may be unaligned.
3349 @param Value 64-bit value to write to Buffer.
3350
3351 @return The 64-bit value to write to Buffer.
3352
3353 **/
3354 UINT64
3355 EFIAPI
3356 WriteUnaligned64 (
3357 OUT UINT64 *Buffer,
3358 IN UINT64 Value
3359 );
3360
3361
3362 //
3363 // Bit Field Functions
3364 //
3365
3366 /**
3367 Returns a bit field from an 8-bit value.
3368
3369 Returns the bitfield specified by the StartBit and the EndBit from Operand.
3370
3371 If 8-bit operations are not supported, then ASSERT().
3372 If StartBit is greater than 7, then ASSERT().
3373 If EndBit is greater than 7, then ASSERT().
3374 If EndBit is less than StartBit, then ASSERT().
3375
3376 @param Operand Operand on which to perform the bitfield operation.
3377 @param StartBit The ordinal of the least significant bit in the bit field.
3378 Range 0..7.
3379 @param EndBit The ordinal of the most significant bit in the bit field.
3380 Range 0..7.
3381
3382 @return The bit field read.
3383
3384 **/
3385 UINT8
3386 EFIAPI
3387 BitFieldRead8 (
3388 IN UINT8 Operand,
3389 IN UINTN StartBit,
3390 IN UINTN EndBit
3391 );
3392
3393
3394 /**
3395 Writes a bit field to an 8-bit value, and returns the result.
3396
3397 Writes Value to the bit field specified by the StartBit and the EndBit in
3398 Operand. All other bits in Operand are preserved. The new 8-bit value is
3399 returned.
3400
3401 If 8-bit operations are not supported, then ASSERT().
3402 If StartBit is greater than 7, then ASSERT().
3403 If EndBit is greater than 7, then ASSERT().
3404 If EndBit is less than StartBit, then ASSERT().
3405 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3406
3407 @param Operand Operand on which to perform the bitfield operation.
3408 @param StartBit The ordinal of the least significant bit in the bit field.
3409 Range 0..7.
3410 @param EndBit The ordinal of the most significant bit in the bit field.
3411 Range 0..7.
3412 @param Value New value of the bit field.
3413
3414 @return The new 8-bit value.
3415
3416 **/
3417 UINT8
3418 EFIAPI
3419 BitFieldWrite8 (
3420 IN UINT8 Operand,
3421 IN UINTN StartBit,
3422 IN UINTN EndBit,
3423 IN UINT8 Value
3424 );
3425
3426
3427 /**
3428 Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the
3429 result.
3430
3431 Performs a bitwise OR between the bit field specified by StartBit
3432 and EndBit in Operand and the value specified by OrData. All other bits in
3433 Operand are preserved. The new 8-bit value is returned.
3434
3435 If 8-bit operations are not supported, then ASSERT().
3436 If StartBit is greater than 7, then ASSERT().
3437 If EndBit is greater than 7, then ASSERT().
3438 If EndBit is less than StartBit, then ASSERT().
3439 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3440
3441 @param Operand Operand on which to perform the bitfield operation.
3442 @param StartBit The ordinal of the least significant bit in the bit field.
3443 Range 0..7.
3444 @param EndBit The ordinal of the most significant bit in the bit field.
3445 Range 0..7.
3446 @param OrData The value to OR with the read value from the value
3447
3448 @return The new 8-bit value.
3449
3450 **/
3451 UINT8
3452 EFIAPI
3453 BitFieldOr8 (
3454 IN UINT8 Operand,
3455 IN UINTN StartBit,
3456 IN UINTN EndBit,
3457 IN UINT8 OrData
3458 );
3459
3460
3461 /**
3462 Reads a bit field from an 8-bit value, performs a bitwise AND, and returns
3463 the result.
3464
3465 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3466 in Operand and the value specified by AndData. All other bits in Operand are
3467 preserved. The new 8-bit value is returned.
3468
3469 If 8-bit operations are not supported, then ASSERT().
3470 If StartBit is greater than 7, then ASSERT().
3471 If EndBit is greater than 7, then ASSERT().
3472 If EndBit is less than StartBit, then ASSERT().
3473 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3474
3475 @param Operand Operand on which to perform the bitfield operation.
3476 @param StartBit The ordinal of the least significant bit in the bit field.
3477 Range 0..7.
3478 @param EndBit The ordinal of the most significant bit in the bit field.
3479 Range 0..7.
3480 @param AndData The value to AND with the read value from the value.
3481
3482 @return The new 8-bit value.
3483
3484 **/
3485 UINT8
3486 EFIAPI
3487 BitFieldAnd8 (
3488 IN UINT8 Operand,
3489 IN UINTN StartBit,
3490 IN UINTN EndBit,
3491 IN UINT8 AndData
3492 );
3493
3494
3495 /**
3496 Reads a bit field from an 8-bit value, performs a bitwise AND followed by a
3497 bitwise OR, and returns the result.
3498
3499 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3500 in Operand and the value specified by AndData, followed by a bitwise
3501 OR with value specified by OrData. All other bits in Operand are
3502 preserved. The new 8-bit value is returned.
3503
3504 If 8-bit operations are not supported, then ASSERT().
3505 If StartBit is greater than 7, then ASSERT().
3506 If EndBit is greater than 7, then ASSERT().
3507 If EndBit is less than StartBit, then ASSERT().
3508 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3509 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3510
3511 @param Operand Operand on which to perform the bitfield operation.
3512 @param StartBit The ordinal of the least significant bit in the bit field.
3513 Range 0..7.
3514 @param EndBit The ordinal of the most significant bit in the bit field.
3515 Range 0..7.
3516 @param AndData The value to AND with the read value from the value.
3517 @param OrData The value to OR with the result of the AND operation.
3518
3519 @return The new 8-bit value.
3520
3521 **/
3522 UINT8
3523 EFIAPI
3524 BitFieldAndThenOr8 (
3525 IN UINT8 Operand,
3526 IN UINTN StartBit,
3527 IN UINTN EndBit,
3528 IN UINT8 AndData,
3529 IN UINT8 OrData
3530 );
3531
3532
3533 /**
3534 Returns a bit field from a 16-bit value.
3535
3536 Returns the bitfield specified by the StartBit and the EndBit from Operand.
3537
3538 If 16-bit operations are not supported, then ASSERT().
3539 If StartBit is greater than 15, then ASSERT().
3540 If EndBit is greater than 15, then ASSERT().
3541 If EndBit is less than StartBit, then ASSERT().
3542
3543 @param Operand Operand on which to perform the bitfield operation.
3544 @param StartBit The ordinal of the least significant bit in the bit field.
3545 Range 0..15.
3546 @param EndBit The ordinal of the most significant bit in the bit field.
3547 Range 0..15.
3548
3549 @return The bit field read.
3550
3551 **/
3552 UINT16
3553 EFIAPI
3554 BitFieldRead16 (
3555 IN UINT16 Operand,
3556 IN UINTN StartBit,
3557 IN UINTN EndBit
3558 );
3559
3560
3561 /**
3562 Writes a bit field to a 16-bit value, and returns the result.
3563
3564 Writes Value to the bit field specified by the StartBit and the EndBit in
3565 Operand. All other bits in Operand are preserved. The new 16-bit value is
3566 returned.
3567
3568 If 16-bit operations are not supported, then ASSERT().
3569 If StartBit is greater than 15, then ASSERT().
3570 If EndBit is greater than 15, then ASSERT().
3571 If EndBit is less than StartBit, then ASSERT().
3572 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3573
3574 @param Operand Operand on which to perform the bitfield operation.
3575 @param StartBit The ordinal of the least significant bit in the bit field.
3576 Range 0..15.
3577 @param EndBit The ordinal of the most significant bit in the bit field.
3578 Range 0..15.
3579 @param Value New value of the bit field.
3580
3581 @return The new 16-bit value.
3582
3583 **/
3584 UINT16
3585 EFIAPI
3586 BitFieldWrite16 (
3587 IN UINT16 Operand,
3588 IN UINTN StartBit,
3589 IN UINTN EndBit,
3590 IN UINT16 Value
3591 );
3592
3593
3594 /**
3595 Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the
3596 result.
3597
3598 Performs a bitwise OR between the bit field specified by StartBit
3599 and EndBit in Operand and the value specified by OrData. All other bits in
3600 Operand are preserved. The new 16-bit value is returned.
3601
3602 If 16-bit operations are not supported, then ASSERT().
3603 If StartBit is greater than 15, then ASSERT().
3604 If EndBit is greater than 15, then ASSERT().
3605 If EndBit is less than StartBit, then ASSERT().
3606 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3607
3608 @param Operand Operand on which to perform the bitfield operation.
3609 @param StartBit The ordinal of the least significant bit in the bit field.
3610 Range 0..15.
3611 @param EndBit The ordinal of the most significant bit in the bit field.
3612 Range 0..15.
3613 @param OrData The value to OR with the read value from the value
3614
3615 @return The new 16-bit value.
3616
3617 **/
3618 UINT16
3619 EFIAPI
3620 BitFieldOr16 (
3621 IN UINT16 Operand,
3622 IN UINTN StartBit,
3623 IN UINTN EndBit,
3624 IN UINT16 OrData
3625 );
3626
3627
3628 /**
3629 Reads a bit field from a 16-bit value, performs a bitwise AND, and returns
3630 the result.
3631
3632 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3633 in Operand and the value specified by AndData. All other bits in Operand are
3634 preserved. The new 16-bit value is returned.
3635
3636 If 16-bit operations are not supported, then ASSERT().
3637 If StartBit is greater than 15, then ASSERT().
3638 If EndBit is greater than 15, then ASSERT().
3639 If EndBit is less than StartBit, then ASSERT().
3640 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3641
3642 @param Operand Operand on which to perform the bitfield operation.
3643 @param StartBit The ordinal of the least significant bit in the bit field.
3644 Range 0..15.
3645 @param EndBit The ordinal of the most significant bit in the bit field.
3646 Range 0..15.
3647 @param AndData The value to AND with the read value from the value
3648
3649 @return The new 16-bit value.
3650
3651 **/
3652 UINT16
3653 EFIAPI
3654 BitFieldAnd16 (
3655 IN UINT16 Operand,
3656 IN UINTN StartBit,
3657 IN UINTN EndBit,
3658 IN UINT16 AndData
3659 );
3660
3661
3662 /**
3663 Reads a bit field from a 16-bit value, performs a bitwise AND followed by a
3664 bitwise OR, and returns the result.
3665
3666 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3667 in Operand and the value specified by AndData, followed by a bitwise
3668 OR with value specified by OrData. All other bits in Operand are
3669 preserved. The new 16-bit value is returned.
3670
3671 If 16-bit operations are not supported, then ASSERT().
3672 If StartBit is greater than 15, then ASSERT().
3673 If EndBit is greater than 15, then ASSERT().
3674 If EndBit is less than StartBit, then ASSERT().
3675 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3676 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3677
3678 @param Operand Operand on which to perform the bitfield operation.
3679 @param StartBit The ordinal of the least significant bit in the bit field.
3680 Range 0..15.
3681 @param EndBit The ordinal of the most significant bit in the bit field.
3682 Range 0..15.
3683 @param AndData The value to AND with the read value from the value.
3684 @param OrData The value to OR with the result of the AND operation.
3685
3686 @return The new 16-bit value.
3687
3688 **/
3689 UINT16
3690 EFIAPI
3691 BitFieldAndThenOr16 (
3692 IN UINT16 Operand,
3693 IN UINTN StartBit,
3694 IN UINTN EndBit,
3695 IN UINT16 AndData,
3696 IN UINT16 OrData
3697 );
3698
3699
3700 /**
3701 Returns a bit field from a 32-bit value.
3702
3703 Returns the bitfield specified by the StartBit and the EndBit from Operand.
3704
3705 If 32-bit operations are not supported, then ASSERT().
3706 If StartBit is greater than 31, then ASSERT().
3707 If EndBit is greater than 31, then ASSERT().
3708 If EndBit is less than StartBit, then ASSERT().
3709
3710 @param Operand Operand on which to perform the bitfield operation.
3711 @param StartBit The ordinal of the least significant bit in the bit field.
3712 Range 0..31.
3713 @param EndBit The ordinal of the most significant bit in the bit field.
3714 Range 0..31.
3715
3716 @return The bit field read.
3717
3718 **/
3719 UINT32
3720 EFIAPI
3721 BitFieldRead32 (
3722 IN UINT32 Operand,
3723 IN UINTN StartBit,
3724 IN UINTN EndBit
3725 );
3726
3727
3728 /**
3729 Writes a bit field to a 32-bit value, and returns the result.
3730
3731 Writes Value to the bit field specified by the StartBit and the EndBit in
3732 Operand. All other bits in Operand are preserved. The new 32-bit value is
3733 returned.
3734
3735 If 32-bit operations are not supported, then ASSERT().
3736 If StartBit is greater than 31, then ASSERT().
3737 If EndBit is greater than 31, then ASSERT().
3738 If EndBit is less than StartBit, then ASSERT().
3739 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3740
3741 @param Operand Operand on which to perform the bitfield operation.
3742 @param StartBit The ordinal of the least significant bit in the bit field.
3743 Range 0..31.
3744 @param EndBit The ordinal of the most significant bit in the bit field.
3745 Range 0..31.
3746 @param Value New value of the bit field.
3747
3748 @return The new 32-bit value.
3749
3750 **/
3751 UINT32
3752 EFIAPI
3753 BitFieldWrite32 (
3754 IN UINT32 Operand,
3755 IN UINTN StartBit,
3756 IN UINTN EndBit,
3757 IN UINT32 Value
3758 );
3759
3760
3761 /**
3762 Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the
3763 result.
3764
3765 Performs a bitwise OR between the bit field specified by StartBit
3766 and EndBit in Operand and the value specified by OrData. All other bits in
3767 Operand are preserved. The new 32-bit value is returned.
3768
3769 If 32-bit operations are not supported, then ASSERT().
3770 If StartBit is greater than 31, then ASSERT().
3771 If EndBit is greater than 31, then ASSERT().
3772 If EndBit is less than StartBit, then ASSERT().
3773 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3774
3775 @param Operand Operand on which to perform the bitfield operation.
3776 @param StartBit The ordinal of the least significant bit in the bit field.
3777 Range 0..31.
3778 @param EndBit The ordinal of the most significant bit in the bit field.
3779 Range 0..31.
3780 @param OrData The value to OR with the read value from the value.
3781
3782 @return The new 32-bit value.
3783
3784 **/
3785 UINT32
3786 EFIAPI
3787 BitFieldOr32 (
3788 IN UINT32 Operand,
3789 IN UINTN StartBit,
3790 IN UINTN EndBit,
3791 IN UINT32 OrData
3792 );
3793
3794
3795 /**
3796 Reads a bit field from a 32-bit value, performs a bitwise AND, and returns
3797 the result.
3798
3799 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3800 in Operand and the value specified by AndData. All other bits in Operand are
3801 preserved. The new 32-bit value is returned.
3802
3803 If 32-bit operations are not supported, then ASSERT().
3804 If StartBit is greater than 31, then ASSERT().
3805 If EndBit is greater than 31, then ASSERT().
3806 If EndBit is less than StartBit, then ASSERT().
3807 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3808
3809 @param Operand Operand on which to perform the bitfield operation.
3810 @param StartBit The ordinal of the least significant bit in the bit field.
3811 Range 0..31.
3812 @param EndBit The ordinal of the most significant bit in the bit field.
3813 Range 0..31.
3814 @param AndData The value to AND with the read value from the value
3815
3816 @return The new 32-bit value.
3817
3818 **/
3819 UINT32
3820 EFIAPI
3821 BitFieldAnd32 (
3822 IN UINT32 Operand,
3823 IN UINTN StartBit,
3824 IN UINTN EndBit,
3825 IN UINT32 AndData
3826 );
3827
3828
3829 /**
3830 Reads a bit field from a 32-bit value, performs a bitwise AND followed by a
3831 bitwise OR, and returns the result.
3832
3833 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3834 in Operand and the value specified by AndData, followed by a bitwise
3835 OR with value specified by OrData. All other bits in Operand are
3836 preserved. The new 32-bit value is returned.
3837
3838 If 32-bit operations are not supported, then ASSERT().
3839 If StartBit is greater than 31, then ASSERT().
3840 If EndBit is greater than 31, then ASSERT().
3841 If EndBit is less than StartBit, then ASSERT().
3842 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3843 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3844
3845 @param Operand Operand on which to perform the bitfield operation.
3846 @param StartBit The ordinal of the least significant bit in the bit field.
3847 Range 0..31.
3848 @param EndBit The ordinal of the most significant bit in the bit field.
3849 Range 0..31.
3850 @param AndData The value to AND with the read value from the value.
3851 @param OrData The value to OR with the result of the AND operation.
3852
3853 @return The new 32-bit value.
3854
3855 **/
3856 UINT32
3857 EFIAPI
3858 BitFieldAndThenOr32 (
3859 IN UINT32 Operand,
3860 IN UINTN StartBit,
3861 IN UINTN EndBit,
3862 IN UINT32 AndData,
3863 IN UINT32 OrData
3864 );
3865
3866
3867 /**
3868 Returns a bit field from a 64-bit value.
3869
3870 Returns the bitfield specified by the StartBit and the EndBit from Operand.
3871
3872 If 64-bit operations are not supported, then ASSERT().
3873 If StartBit is greater than 63, then ASSERT().
3874 If EndBit is greater than 63, then ASSERT().
3875 If EndBit is less than StartBit, then ASSERT().
3876
3877 @param Operand Operand on which to perform the bitfield operation.
3878 @param StartBit The ordinal of the least significant bit in the bit field.
3879 Range 0..63.
3880 @param EndBit The ordinal of the most significant bit in the bit field.
3881 Range 0..63.
3882
3883 @return The bit field read.
3884
3885 **/
3886 UINT64
3887 EFIAPI
3888 BitFieldRead64 (
3889 IN UINT64 Operand,
3890 IN UINTN StartBit,
3891 IN UINTN EndBit
3892 );
3893
3894
3895 /**
3896 Writes a bit field to a 64-bit value, and returns the result.
3897
3898 Writes Value to the bit field specified by the StartBit and the EndBit in
3899 Operand. All other bits in Operand are preserved. The new 64-bit value is
3900 returned.
3901
3902 If 64-bit operations are not supported, then ASSERT().
3903 If StartBit is greater than 63, then ASSERT().
3904 If EndBit is greater than 63, then ASSERT().
3905 If EndBit is less than StartBit, then ASSERT().
3906 If Value is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3907
3908 @param Operand Operand on which to perform the bitfield operation.
3909 @param StartBit The ordinal of the least significant bit in the bit field.
3910 Range 0..63.
3911 @param EndBit The ordinal of the most significant bit in the bit field.
3912 Range 0..63.
3913 @param Value New value of the bit field.
3914
3915 @return The new 64-bit value.
3916
3917 **/
3918 UINT64
3919 EFIAPI
3920 BitFieldWrite64 (
3921 IN UINT64 Operand,
3922 IN UINTN StartBit,
3923 IN UINTN EndBit,
3924 IN UINT64 Value
3925 );
3926
3927
3928 /**
3929 Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the
3930 result.
3931
3932 Performs a bitwise OR between the bit field specified by StartBit
3933 and EndBit in Operand and the value specified by OrData. All other bits in
3934 Operand are preserved. The new 64-bit value is returned.
3935
3936 If 64-bit operations are not supported, then ASSERT().
3937 If StartBit is greater than 63, then ASSERT().
3938 If EndBit is greater than 63, then ASSERT().
3939 If EndBit is less than StartBit, then ASSERT().
3940 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3941
3942 @param Operand Operand on which to perform the bitfield operation.
3943 @param StartBit The ordinal of the least significant bit in the bit field.
3944 Range 0..63.
3945 @param EndBit The ordinal of the most significant bit in the bit field.
3946 Range 0..63.
3947 @param OrData The value to OR with the read value from the value
3948
3949 @return The new 64-bit value.
3950
3951 **/
3952 UINT64
3953 EFIAPI
3954 BitFieldOr64 (
3955 IN UINT64 Operand,
3956 IN UINTN StartBit,
3957 IN UINTN EndBit,
3958 IN UINT64 OrData
3959 );
3960
3961
3962 /**
3963 Reads a bit field from a 64-bit value, performs a bitwise AND, and returns
3964 the result.
3965
3966 Performs a bitwise AND between the bit field specified by StartBit and EndBit
3967 in Operand and the value specified by AndData. All other bits in Operand are
3968 preserved. The new 64-bit value is returned.
3969
3970 If 64-bit operations are not supported, then ASSERT().
3971 If StartBit is greater than 63, then ASSERT().
3972 If EndBit is greater than 63, then ASSERT().
3973 If EndBit is less than StartBit, then ASSERT().
3974 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
3975
3976 @param Operand Operand on which to perform the bitfield operation.
3977 @param StartBit The ordinal of the least significant bit in the bit field.
3978 Range 0..63.
3979 @param EndBit The ordinal of the most significant bit in the bit field.
3980 Range 0..63.
3981 @param AndData The value to AND with the read value from the value
3982
3983 @return The new 64-bit value.
3984
3985 **/
3986 UINT64
3987 EFIAPI
3988 BitFieldAnd64 (
3989 IN UINT64 Operand,
3990 IN UINTN StartBit,
3991 IN UINTN EndBit,
3992 IN UINT64 AndData
3993 );
3994
3995
3996 /**
3997 Reads a bit field from a 64-bit value, performs a bitwise AND followed by a
3998 bitwise OR, and returns the result.
3999
4000 Performs a bitwise AND between the bit field specified by StartBit and EndBit
4001 in Operand and the value specified by AndData, followed by a bitwise
4002 OR with value specified by OrData. All other bits in Operand are
4003 preserved. The new 64-bit value is returned.
4004
4005 If 64-bit operations are not supported, then ASSERT().
4006 If StartBit is greater than 63, then ASSERT().
4007 If EndBit is greater than 63, then ASSERT().
4008 If EndBit is less than StartBit, then ASSERT().
4009 If AndData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4010 If OrData is larger than the bitmask value range specified by StartBit and EndBit, then ASSERT().
4011
4012 @param Operand Operand on which to perform the bitfield operation.
4013 @param StartBit The ordinal of the least significant bit in the bit field.
4014 Range 0..63.
4015 @param EndBit The ordinal of the most significant bit in the bit field.
4016 Range 0..63.
4017 @param AndData The value to AND with the read value from the value.
4018 @param OrData The value to OR with the result of the AND operation.
4019
4020 @return The new 64-bit value.
4021
4022 **/
4023 UINT64
4024 EFIAPI
4025 BitFieldAndThenOr64 (
4026 IN UINT64 Operand,
4027 IN UINTN StartBit,
4028 IN UINTN EndBit,
4029 IN UINT64 AndData,
4030 IN UINT64 OrData
4031 );
4032
4033 //
4034 // Base Library Checksum Functions
4035 //
4036
4037 /**
4038 Returns the sum of all elements in a buffer in unit of UINT8.
4039 During calculation, the carry bits are dropped.
4040
4041 This function calculates the sum of all elements in a buffer
4042 in unit of UINT8. The carry bits in result of addition are dropped.
4043 The result is returned as UINT8. If Length is Zero, then Zero is
4044 returned.
4045
4046 If Buffer is NULL, then ASSERT().
4047 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4048
4049 @param Buffer The pointer to the buffer to carry out the sum operation.
4050 @param Length The size, in bytes, of Buffer.
4051
4052 @return Sum The sum of Buffer with carry bits dropped during additions.
4053
4054 **/
4055 UINT8
4056 EFIAPI
4057 CalculateSum8 (
4058 IN CONST UINT8 *Buffer,
4059 IN UINTN Length
4060 );
4061
4062
4063 /**
4064 Returns the two's complement checksum of all elements in a buffer
4065 of 8-bit values.
4066
4067 This function first calculates the sum of the 8-bit values in the
4068 buffer specified by Buffer and Length. The carry bits in the result
4069 of addition are dropped. Then, the two's complement of the sum is
4070 returned. If Length is 0, then 0 is returned.
4071
4072 If Buffer is NULL, then ASSERT().
4073 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4074
4075 @param Buffer The pointer to the buffer to carry out the checksum operation.
4076 @param Length The size, in bytes, of Buffer.
4077
4078 @return Checksum The two's complement checksum of Buffer.
4079
4080 **/
4081 UINT8
4082 EFIAPI
4083 CalculateCheckSum8 (
4084 IN CONST UINT8 *Buffer,
4085 IN UINTN Length
4086 );
4087
4088
4089 /**
4090 Returns the sum of all elements in a buffer of 16-bit values. During
4091 calculation, the carry bits are dropped.
4092
4093 This function calculates the sum of the 16-bit values in the buffer
4094 specified by Buffer and Length. The carry bits in result of addition are dropped.
4095 The 16-bit result is returned. If Length is 0, then 0 is returned.
4096
4097 If Buffer is NULL, then ASSERT().
4098 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4099 If Length is not aligned on a 16-bit boundary, then ASSERT().
4100 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4101
4102 @param Buffer The pointer to the buffer to carry out the sum operation.
4103 @param Length The size, in bytes, of Buffer.
4104
4105 @return Sum The sum of Buffer with carry bits dropped during additions.
4106
4107 **/
4108 UINT16
4109 EFIAPI
4110 CalculateSum16 (
4111 IN CONST UINT16 *Buffer,
4112 IN UINTN Length
4113 );
4114
4115
4116 /**
4117 Returns the two's complement checksum of all elements in a buffer of
4118 16-bit values.
4119
4120 This function first calculates the sum of the 16-bit values in the buffer
4121 specified by Buffer and Length. The carry bits in the result of addition
4122 are dropped. Then, the two's complement of the sum is returned. If Length
4123 is 0, then 0 is returned.
4124
4125 If Buffer is NULL, then ASSERT().
4126 If Buffer is not aligned on a 16-bit boundary, then ASSERT().
4127 If Length is not aligned on a 16-bit boundary, then ASSERT().
4128 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4129
4130 @param Buffer The pointer to the buffer to carry out the checksum operation.
4131 @param Length The size, in bytes, of Buffer.
4132
4133 @return Checksum The two's complement checksum of Buffer.
4134
4135 **/
4136 UINT16
4137 EFIAPI
4138 CalculateCheckSum16 (
4139 IN CONST UINT16 *Buffer,
4140 IN UINTN Length
4141 );
4142
4143
4144 /**
4145 Returns the sum of all elements in a buffer of 32-bit values. During
4146 calculation, the carry bits are dropped.
4147
4148 This function calculates the sum of the 32-bit values in the buffer
4149 specified by Buffer and Length. The carry bits in result of addition are dropped.
4150 The 32-bit result is returned. If Length is 0, then 0 is returned.
4151
4152 If Buffer is NULL, then ASSERT().
4153 If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4154 If Length is not aligned on a 32-bit boundary, then ASSERT().
4155 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4156
4157 @param Buffer The pointer to the buffer to carry out the sum operation.
4158 @param Length The size, in bytes, of Buffer.
4159
4160 @return Sum The sum of Buffer with carry bits dropped during additions.
4161
4162 **/
4163 UINT32
4164 EFIAPI
4165 CalculateSum32 (
4166 IN CONST UINT32 *Buffer,
4167 IN UINTN Length
4168 );
4169
4170
4171 /**
4172 Returns the two's complement checksum of all elements in a buffer of
4173 32-bit values.
4174
4175 This function first calculates the sum of the 32-bit values in the buffer
4176 specified by Buffer and Length. The carry bits in the result of addition
4177 are dropped. Then, the two's complement of the sum is returned. If Length
4178 is 0, then 0 is returned.
4179
4180 If Buffer is NULL, then ASSERT().
4181 If Buffer is not aligned on a 32-bit boundary, then ASSERT().
4182 If Length is not aligned on a 32-bit boundary, then ASSERT().
4183 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4184
4185 @param Buffer The pointer to the buffer to carry out the checksum operation.
4186 @param Length The size, in bytes, of Buffer.
4187
4188 @return Checksum The two's complement checksum of Buffer.
4189
4190 **/
4191 UINT32
4192 EFIAPI
4193 CalculateCheckSum32 (
4194 IN CONST UINT32 *Buffer,
4195 IN UINTN Length
4196 );
4197
4198
4199 /**
4200 Returns the sum of all elements in a buffer of 64-bit values. During
4201 calculation, the carry bits are dropped.
4202
4203 This function calculates the sum of the 64-bit values in the buffer
4204 specified by Buffer and Length. The carry bits in result of addition are dropped.
4205 The 64-bit result is returned. If Length is 0, then 0 is returned.
4206
4207 If Buffer is NULL, then ASSERT().
4208 If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4209 If Length is not aligned on a 64-bit boundary, then ASSERT().
4210 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4211
4212 @param Buffer The pointer to the buffer to carry out the sum operation.
4213 @param Length The size, in bytes, of Buffer.
4214
4215 @return Sum The sum of Buffer with carry bits dropped during additions.
4216
4217 **/
4218 UINT64
4219 EFIAPI
4220 CalculateSum64 (
4221 IN CONST UINT64 *Buffer,
4222 IN UINTN Length
4223 );
4224
4225
4226 /**
4227 Returns the two's complement checksum of all elements in a buffer of
4228 64-bit values.
4229
4230 This function first calculates the sum of the 64-bit values in the buffer
4231 specified by Buffer and Length. The carry bits in the result of addition
4232 are dropped. Then, the two's complement of the sum is returned. If Length
4233 is 0, then 0 is returned.
4234
4235 If Buffer is NULL, then ASSERT().
4236 If Buffer is not aligned on a 64-bit boundary, then ASSERT().
4237 If Length is not aligned on a 64-bit boundary, then ASSERT().
4238 If Length is greater than (MAX_ADDRESS - Buffer + 1), then ASSERT().
4239
4240 @param Buffer The pointer to the buffer to carry out the checksum operation.
4241 @param Length The size, in bytes, of Buffer.
4242
4243 @return Checksum The two's complement checksum of Buffer.
4244
4245 **/
4246 UINT64
4247 EFIAPI
4248 CalculateCheckSum64 (
4249 IN CONST UINT64 *Buffer,
4250 IN UINTN Length
4251 );
4252
4253
4254 //
4255 // Base Library CPU Functions
4256 //
4257
4258 /**
4259 Function entry point used when a stack switch is requested with SwitchStack()
4260
4261 @param Context1 Context1 parameter passed into SwitchStack().
4262 @param Context2 Context2 parameter passed into SwitchStack().
4263
4264 **/
4265 typedef
4266 VOID
4267 (EFIAPI *SWITCH_STACK_ENTRY_POINT)(
4268 IN VOID *Context1, OPTIONAL
4269 IN VOID *Context2 OPTIONAL
4270 );
4271
4272
4273 /**
4274 Used to serialize load and store operations.
4275
4276 All loads and stores that proceed calls to this function are guaranteed to be
4277 globally visible when this function returns.
4278
4279 **/
4280 VOID
4281 EFIAPI
4282 MemoryFence (
4283 VOID
4284 );
4285
4286
4287 /**
4288 Saves the current CPU context that can be restored with a call to LongJump()
4289 and returns 0.
4290
4291 Saves the current CPU context in the buffer specified by JumpBuffer and
4292 returns 0. The initial call to SetJump() must always return 0. Subsequent
4293 calls to LongJump() cause a non-zero value to be returned by SetJump().
4294
4295 If JumpBuffer is NULL, then ASSERT().
4296 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
4297
4298 NOTE: The structure BASE_LIBRARY_JUMP_BUFFER is CPU architecture specific.
4299 The same structure must never be used for more than one CPU architecture context.
4300 For example, a BASE_LIBRARY_JUMP_BUFFER allocated by an IA-32 module must never be used from an x64 module.
4301 SetJump()/LongJump() is not currently supported for the EBC processor type.
4302
4303 @param JumpBuffer A pointer to CPU context buffer.
4304
4305 @retval 0 Indicates a return from SetJump().
4306
4307 **/
4308 UINTN
4309 EFIAPI
4310 SetJump (
4311 OUT BASE_LIBRARY_JUMP_BUFFER *JumpBuffer
4312 );
4313
4314
4315 /**
4316 Restores the CPU context that was saved with SetJump().
4317
4318 Restores the CPU context from the buffer specified by JumpBuffer. This
4319 function never returns to the caller. Instead is resumes execution based on
4320 the state of JumpBuffer.
4321
4322 If JumpBuffer is NULL, then ASSERT().
4323 For Itanium processors, if JumpBuffer is not aligned on a 16-byte boundary, then ASSERT().
4324 If Value is 0, then ASSERT().
4325
4326 @param JumpBuffer A pointer to CPU context buffer.
4327 @param Value The value to return when the SetJump() context is
4328 restored and must be non-zero.
4329
4330 **/
4331 VOID
4332 EFIAPI
4333 LongJump (
4334 IN BASE_LIBRARY_JUMP_BUFFER *JumpBuffer,
4335 IN UINTN Value
4336 );
4337
4338
4339 /**
4340 Enables CPU interrupts.
4341
4342 **/
4343 VOID
4344 EFIAPI
4345 EnableInterrupts