1.Updated some functions header of BaseLib with new MWG spec
[mirror_edk2.git] / MdePkg / Include / Library / BaseLib.h
CommitLineData
878ddf1f 1/** @file\r
24e25d11 2 Memory-only library functions with no library constructor/destructor\r
878ddf1f 3\r
24e25d11 4 Copyright (c) 2006, Intel Corporation\r
5 All rights reserved. This program and the accompanying materials\r
6 are licensed and made available under the terms and conditions of the BSD License\r
7 which accompanies this distribution. The full text of the license may be found at\r
8 http://opensource.org/licenses/bsd-license.php\r
878ddf1f 9\r
24e25d11 10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
878ddf1f 12\r
24e25d11 13 Module Name: BaseLib.h\r
878ddf1f 14\r
15**/\r
16\r
17#ifndef __BASE_LIB__\r
18#define __BASE_LIB__\r
19\r
20//\r
21// Definitions for architecture specific types\r
22// These include SPIN_LOCK and BASE_LIBRARY_JUMP_BUFFER\r
23//\r
24\r
25//\r
26// SPIN_LOCK\r
27//\r
28typedef UINTN SPIN_LOCK;\r
29\r
30#if defined (MDE_CPU_IA32)\r
31//\r
32// IA32 context buffer used by SetJump() and LongJump()\r
33//\r
34typedef struct {\r
35 UINT32 Ebx;\r
36 UINT32 Esi;\r
37 UINT32 Edi;\r
38 UINT32 Ebp;\r
39 UINT32 Esp;\r
40 UINT32 Eip;\r
41} BASE_LIBRARY_JUMP_BUFFER;\r
42\r
43#elif defined (MDE_CPU_IPF)\r
44//\r
45// IPF context buffer used by SetJump() and LongJump()\r
46//\r
47typedef struct {\r
4cbd2175 48 UINT64 F2[2];\r
49 UINT64 F3[2];\r
50 UINT64 F4[2];\r
51 UINT64 F5[2];\r
52 UINT64 F16[2];\r
53 UINT64 F17[2];\r
54 UINT64 F18[2];\r
55 UINT64 F19[2];\r
56 UINT64 F20[2];\r
57 UINT64 F21[2];\r
58 UINT64 F22[2];\r
59 UINT64 F23[2];\r
60 UINT64 F24[2];\r
61 UINT64 F25[2];\r
62 UINT64 F26[2];\r
63 UINT64 F27[2];\r
64 UINT64 F28[2];\r
65 UINT64 F29[2];\r
66 UINT64 F30[2];\r
67 UINT64 F31[2];\r
878ddf1f 68 UINT64 R4;\r
69 UINT64 R5;\r
70 UINT64 R6;\r
71 UINT64 R7;\r
72 UINT64 SP;\r
878ddf1f 73 UINT64 BR0;\r
74 UINT64 BR1;\r
75 UINT64 BR2;\r
76 UINT64 BR3;\r
77 UINT64 BR4;\r
78 UINT64 BR5;\r
4cbd2175 79 UINT64 InitialUNAT;\r
80 UINT64 AfterSpillUNAT;\r
81 UINT64 PFS;\r
82 UINT64 BSP;\r
83 UINT64 Predicates;\r
84 UINT64 LoopCount;\r
85 UINT64 FPSR;\r
878ddf1f 86} BASE_LIBRARY_JUMP_BUFFER;\r
87\r
88#elif defined (MDE_CPU_X64)\r
89//\r
90// X64 context buffer used by SetJump() and LongJump()\r
91//\r
92typedef struct {\r
93 UINT64 Rbx;\r
94 UINT64 Rsp;\r
95 UINT64 Rbp;\r
96 UINT64 Rdi;\r
97 UINT64 Rsi;\r
98 UINT64 R12;\r
99 UINT64 R13;\r
100 UINT64 R14;\r
101 UINT64 R15;\r
102 UINT64 Rip;\r
103} BASE_LIBRARY_JUMP_BUFFER;\r
104\r
105#elif defined (MDE_CPU_EBC)\r
106//\r
107// EBC context buffer used by SetJump() and LongJump()\r
108//\r
109typedef struct {\r
110 UINT64 R0;\r
111 UINT64 R1;\r
112 UINT64 R2;\r
113 UINT64 R3;\r
114 UINT64 IP;\r
115} BASE_LIBRARY_JUMP_BUFFER;\r
116\r
117#else\r
118#error Unknown Processor Type\r
119#endif\r
120\r
121//\r
122// String Services\r
123//\r
124\r
125/**\r
126 Copies one Null-terminated Unicode string to another Null-terminated Unicode\r
127 string and returns the new Unicode string.\r
128\r
129 This function copies the contents of the Unicode string Source to the Unicode\r
130 string Destination, and returns Destination. If Source and Destination\r
131 overlap, then the results are undefined.\r
132\r
133 If Destination is NULL, then ASSERT().\r
134 If Source is NULL, then ASSERT().\r
135 If Source and Destination overlap, then ASSERT().\r
136 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r
30817eb4 137 PcdMaximumUnicodeStringLength Unicode characters not including the \r
138 Null-terminator, then ASSERT().\r
878ddf1f 139\r
140 @param Destination Pointer to a Null-terminated Unicode string.\r
141 @param Source Pointer to a Null-terminated Unicode string.\r
142\r
143 @return Destiantion\r
144\r
145**/\r
146CHAR16 *\r
147EFIAPI\r
148StrCpy (\r
149 OUT CHAR16 *Destination,\r
150 IN CONST CHAR16 *Source\r
151 );\r
878ddf1f 152/**\r
153 Copies one Null-terminated Unicode string with a maximum length to another\r
154 Null-terminated Unicode string with a maximum length and returns the new\r
155 Unicode string.\r
156\r
157 This function copies the contents of the Unicode string Source to the Unicode\r
158 string Destination, and returns Destination. At most, Length Unicode\r
159 characters are copied from Source to Destination. If Length is 0, then\r
160 Destination is returned unmodified. If Length is greater that the number of\r
161 Unicode characters in Source, then Destination is padded with Null Unicode\r
162 characters. If Source and Destination overlap, then the results are\r
163 undefined.\r
164\r
165 If Destination is NULL, then ASSERT().\r
166 If Source is NULL, then ASSERT().\r
167 If Source and Destination overlap, then ASSERT().\r
168 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r
30817eb4 169 PcdMaximumUnicodeStringLength Unicode characters not including the \r
170 Null-terminator, then ASSERT().\r
878ddf1f 171\r
172 @param Destination Pointer to a Null-terminated Unicode string.\r
173 @param Source Pointer to a Null-terminated Unicode string.\r
174 @param Length Maximum number of Unicode characters to copy.\r
175\r
176 @return Destination\r
177\r
178**/\r
179CHAR16 *\r
180EFIAPI\r
181StrnCpy (\r
182 OUT CHAR16 *Destination,\r
183 IN CONST CHAR16 *Source,\r
184 IN UINTN Length\r
185 );\r
878ddf1f 186/**\r
187 Returns the length of a Null-terminated Unicode string.\r
188\r
189 This function returns the number of Unicode characters in the Null-terminated\r
190 Unicode string specified by String.\r
191\r
192 If String is NULL, then ASSERT().\r
193 If PcdMaximumUnicodeStringLength is not zero, and String contains more than\r
30817eb4 194 PcdMaximumUnicodeStringLength Unicode characters not including the \r
195 Null-terminator, then ASSERT().\r
878ddf1f 196\r
197 @param String Pointer to a Null-terminated Unicode string.\r
198\r
199 @return The length of String.\r
200\r
201**/\r
202UINTN\r
203EFIAPI\r
204StrLen (\r
205 IN CONST CHAR16 *String\r
206 );\r
878ddf1f 207/**\r
208 Returns the size of a Null-terminated Unicode string in bytes, including the\r
209 Null terminator.\r
210\r
211 This function returns the size, in bytes, of the Null-terminated Unicode\r
212 string specified by String.\r
213\r
214 If String is NULL, then ASSERT().\r
215 If PcdMaximumUnicodeStringLength is not zero, and String contains more than\r
30817eb4 216 PcdMaximumUnicodeStringLength Unicode characters not including the \r
217 Null-terminator, then ASSERT().\r
878ddf1f 218\r
219 @param String Pointer to a Null-terminated Unicode string.\r
220\r
221 @return The size of String.\r
222\r
223**/\r
224UINTN\r
225EFIAPI\r
226StrSize (\r
227 IN CONST CHAR16 *String\r
228 );\r
878ddf1f 229/**\r
230 Compares two Null-terminated Unicode strings, and returns the difference\r
231 between the first mismatched Unicode characters.\r
232\r
233 This function compares the Null-terminated Unicode string FirstString to the\r
234 Null-terminated Unicode string SecondString. If FirstString is identical to\r
235 SecondString, then 0 is returned. Otherwise, the value returned is the first\r
236 mismatched Unicode character in SecondString subtracted from the first\r
237 mismatched Unicode character in FirstString.\r
238\r
239 If FirstString is NULL, then ASSERT().\r
240 If SecondString is NULL, then ASSERT().\r
241 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more\r
30817eb4 242 than PcdMaximumUnicodeStringLength Unicode characters not including the \r
243 Null-terminator, then ASSERT().\r
878ddf1f 244 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more\r
30817eb4 245 than PcdMaximumUnicodeStringLength Unicode characters not including the \r
246 Null-terminator, then ASSERT().\r
878ddf1f 247\r
248 @param FirstString Pointer to a Null-terminated Unicode string.\r
249 @param SecondString Pointer to a Null-terminated Unicode string.\r
250\r
251 @retval 0 FirstString is identical to SecondString.\r
252 @retval !=0 FirstString is not identical to SecondString.\r
253\r
254**/\r
255INTN\r
256EFIAPI\r
257StrCmp (\r
258 IN CONST CHAR16 *FirstString,\r
259 IN CONST CHAR16 *SecondString\r
260 );\r
878ddf1f 261/**\r
262 Compares two Null-terminated Unicode strings with maximum lengths, and\r
263 returns the difference between the first mismatched Unicode characters.\r
264\r
265 This function compares the Null-terminated Unicode string FirstString to the\r
266 Null-terminated Unicode string SecondString. At most, Length Unicode\r
267 characters will be compared. If Length is 0, then 0 is returned. If\r
268 FirstString is identical to SecondString, then 0 is returned. Otherwise, the\r
269 value returned is the first mismatched Unicode character in SecondString\r
270 subtracted from the first mismatched Unicode character in FirstString.\r
271\r
272 If FirstString is NULL, then ASSERT().\r
273 If SecondString is NULL, then ASSERT().\r
274 If PcdMaximumUnicodeStringLength is not zero, and FirstString contains more\r
30817eb4 275 than PcdMaximumUnicodeStringLength Unicode characters not including the\r
276 Null-terminator, then ASSERT().\r
878ddf1f 277 If PcdMaximumUnicodeStringLength is not zero, and SecondString contains more\r
30817eb4 278 than PcdMaximumUnicodeStringLength Unicode characters not including the\r
279 Null-terminator, then ASSERT().\r
878ddf1f 280\r
281 @param FirstString Pointer to a Null-terminated Unicode string.\r
282 @param SecondString Pointer to a Null-terminated Unicode string.\r
283 @param Length Maximum number of Unicode characters to compare.\r
284\r
285 @retval 0 FirstString is identical to SecondString.\r
286 @retval !=0 FirstString is not identical to SecondString.\r
287\r
288**/\r
289INTN\r
290EFIAPI\r
291StrnCmp (\r
292 IN CONST CHAR16 *FirstString,\r
293 IN CONST CHAR16 *SecondString,\r
294 IN UINTN Length\r
295 );\r
878ddf1f 296/**\r
297 Concatenates one Null-terminated Unicode string to another Null-terminated\r
298 Unicode string, and returns the concatenated Unicode string.\r
299\r
300 This function concatenates two Null-terminated Unicode strings. The contents\r
301 of Null-terminated Unicode string Source are concatenated to the end of\r
302 Null-terminated Unicode string Destination. The Null-terminated concatenated\r
303 Unicode String is returned. If Source and Destination overlap, then the\r
304 results are undefined.\r
305\r
306 If Destination is NULL, then ASSERT().\r
307 If Source is NULL, then ASSERT().\r
308 If Source and Destination overlap, then ASSERT().\r
309 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more\r
30817eb4 310 than PcdMaximumUnicodeStringLength Unicode characters not including the\r
311 Null-terminator, then ASSERT().\r
878ddf1f 312 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r
30817eb4 313 PcdMaximumUnicodeStringLength Unicode characters not including the\r
314 Null-terminator, then ASSERT().\r
878ddf1f 315 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination\r
316 and Source results in a Unicode string with more than\r
30817eb4 317 PcdMaximumUnicodeStringLength Unicode characters not including the\r
318 Null-terminator, then ASSERT().\r
878ddf1f 319\r
320 @param Destination Pointer to a Null-terminated Unicode string.\r
321 @param Source Pointer to a Null-terminated Unicode string.\r
322\r
323 @return Destination\r
324\r
325**/\r
326CHAR16 *\r
327EFIAPI\r
328StrCat (\r
329 IN OUT CHAR16 *Destination,\r
330 IN CONST CHAR16 *Source\r
331 );\r
878ddf1f 332/**\r
333 Concatenates one Null-terminated Unicode string with a maximum length to the\r
334 end of another Null-terminated Unicode string, and returns the concatenated\r
335 Unicode string.\r
336\r
337 This function concatenates two Null-terminated Unicode strings. The contents\r
338 of Null-terminated Unicode string Source are concatenated to the end of\r
339 Null-terminated Unicode string Destination, and Destination is returned. At\r
340 most, Length Unicode characters are concatenated from Source to the end of\r
341 Destination, and Destination is always Null-terminated. If Length is 0, then\r
342 Destination is returned unmodified. If Source and Destination overlap, then\r
343 the results are undefined.\r
344\r
345 If Destination is NULL, then ASSERT().\r
346 If Source is NULL, then ASSERT().\r
347 If Source and Destination overlap, then ASSERT().\r
348 If PcdMaximumUnicodeStringLength is not zero, and Destination contains more\r
30817eb4 349 than PcdMaximumUnicodeStringLength Unicode characters not including the\r
350 Null-terminator, then ASSERT().\r
878ddf1f 351 If PcdMaximumUnicodeStringLength is not zero, and Source contains more than\r
30817eb4 352 PcdMaximumUnicodeStringLength Unicode characters not including the\r
353 Null-terminator, then ASSERT().\r
878ddf1f 354 If PcdMaximumUnicodeStringLength is not zero, and concatenating Destination\r
355 and Source results in a Unicode string with more than\r
30817eb4 356 PcdMaximumUnicodeStringLength Unicode characters not including the\r
357 Null-terminator, then ASSERT().\r
878ddf1f 358\r
359 @param Destination Pointer to a Null-terminated Unicode string.\r
360 @param Source Pointer to a Null-terminated Unicode string.\r
361 @param Length Maximum number of Unicode characters to concatenate from\r
362 Source.\r
363\r
364 @return Destination\r
365\r
366**/\r
367CHAR16 *\r
368EFIAPI\r
369StrnCat (\r
370 IN OUT CHAR16 *Destination,\r
371 IN CONST CHAR16 *Source,\r
372 IN UINTN Length\r
373 );\r
878ddf1f 374/**\r
375 Copies one Null-terminated ASCII string to another Null-terminated ASCII\r
376 string and returns the new ASCII string.\r
377\r
378 This function copies the contents of the ASCII string Source to the ASCII\r
379 string Destination, and returns Destination. If Source and Destination\r
380 overlap, then the results are undefined.\r
381\r
382 If Destination is NULL, then ASSERT().\r
383 If Source is NULL, then ASSERT().\r
384 If Source and Destination overlap, then ASSERT().\r
385 If PcdMaximumAsciiStringLength is not zero and Source contains more than\r
30817eb4 386 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
387 then ASSERT().\r
878ddf1f 388\r
389 @param Destination Pointer to a Null-terminated ASCII string.\r
390 @param Source Pointer to a Null-terminated ASCII string.\r
391\r
392 @return Destination\r
393\r
394**/\r
395CHAR8 *\r
396EFIAPI\r
397AsciiStrCpy (\r
398 OUT CHAR8 *Destination,\r
399 IN CONST CHAR8 *Source\r
400 );\r
878ddf1f 401/**\r
402 Copies one Null-terminated ASCII string with a maximum length to another\r
403 Null-terminated ASCII string with a maximum length and returns the new ASCII\r
404 string.\r
405\r
406 This function copies the contents of the ASCII string Source to the ASCII\r
407 string Destination, and returns Destination. At most, Length ASCII characters\r
408 are copied from Source to Destination. If Length is 0, then Destination is\r
409 returned unmodified. If Length is greater that the number of ASCII characters\r
410 in Source, then Destination is padded with Null ASCII characters. If Source\r
411 and Destination overlap, then the results are undefined.\r
412\r
413 If Destination is NULL, then ASSERT().\r
414 If Source is NULL, then ASSERT().\r
415 If Source and Destination overlap, then ASSERT().\r
416 If PcdMaximumAsciiStringLength is not zero, and Source contains more than\r
30817eb4 417 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
418 then ASSERT().\r
878ddf1f 419\r
420 @param Destination Pointer to a Null-terminated ASCII string.\r
421 @param Source Pointer to a Null-terminated ASCII string.\r
422 @param Length Maximum number of ASCII characters to copy.\r
423\r
424 @return Destination\r
425\r
426**/\r
427CHAR8 *\r
428EFIAPI\r
429AsciiStrnCpy (\r
430 OUT CHAR8 *Destination,\r
431 IN CONST CHAR8 *Source,\r
432 IN UINTN Length\r
433 );\r
878ddf1f 434/**\r
435 Returns the length of a Null-terminated ASCII string.\r
436\r
437 This function returns the number of ASCII characters in the Null-terminated\r
438 ASCII string specified by String.\r
439\r
440 If String is NULL, then ASSERT().\r
441 If PcdMaximumAsciiStringLength is not zero and String contains more than\r
30817eb4 442 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
443 then ASSERT().\r
878ddf1f 444\r
445 @param String Pointer to a Null-terminated ASCII string.\r
446\r
447 @return The length of String.\r
448\r
449**/\r
450UINTN\r
451EFIAPI\r
452AsciiStrLen (\r
453 IN CONST CHAR8 *String\r
454 );\r
878ddf1f 455/**\r
456 Returns the size of a Null-terminated ASCII string in bytes, including the\r
457 Null terminator.\r
458\r
459 This function returns the size, in bytes, of the Null-terminated ASCII string\r
460 specified by String.\r
461\r
462 If String is NULL, then ASSERT().\r
463 If PcdMaximumAsciiStringLength is not zero and String contains more than\r
30817eb4 464 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
465 then ASSERT().\r
878ddf1f 466\r
467 @param String Pointer to a Null-terminated ASCII string.\r
468\r
469 @return The size of String.\r
470\r
471**/\r
472UINTN\r
473EFIAPI\r
474AsciiStrSize (\r
475 IN CONST CHAR8 *String\r
476 );\r
878ddf1f 477/**\r
478 Compares two Null-terminated ASCII strings, and returns the difference\r
479 between the first mismatched ASCII characters.\r
480\r
481 This function compares the Null-terminated ASCII string FirstString to the\r
482 Null-terminated ASCII string SecondString. If FirstString is identical to\r
483 SecondString, then 0 is returned. Otherwise, the value returned is the first\r
484 mismatched ASCII character in SecondString subtracted from the first\r
485 mismatched ASCII character in FirstString.\r
486\r
487 If FirstString is NULL, then ASSERT().\r
488 If SecondString is NULL, then ASSERT().\r
489 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than\r
30817eb4 490 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
491 then ASSERT().\r
878ddf1f 492 If PcdMaximumAsciiStringLength is not zero and SecondString contains more\r
30817eb4 493 than PcdMaximumAsciiStringLength ASCII characters not including the\r
494 Null-terminator, then ASSERT().\r
878ddf1f 495\r
496 @param FirstString Pointer to a Null-terminated ASCII string.\r
497 @param SecondString Pointer to a Null-terminated ASCII string.\r
498\r
499 @retval 0 FirstString is identical to SecondString.\r
500 @retval !=0 FirstString is not identical to SecondString.\r
501\r
502**/\r
503INTN\r
504EFIAPI\r
505AsciiStrCmp (\r
506 IN CONST CHAR8 *FirstString,\r
507 IN CONST CHAR8 *SecondString\r
508 );\r
878ddf1f 509/**\r
510 Performs a case insensitive comparison of two Null-terminated ASCII strings,\r
511 and returns the difference between the first mismatched ASCII characters.\r
512\r
513 This function performs a case insensitive comparison of the Null-terminated\r
514 ASCII string FirstString to the Null-terminated ASCII string SecondString. If\r
515 FirstString is identical to SecondString, then 0 is returned. Otherwise, the\r
516 value returned is the first mismatched lower case ASCII character in\r
517 SecondString subtracted from the first mismatched lower case ASCII character\r
518 in FirstString.\r
519\r
520 If FirstString is NULL, then ASSERT().\r
521 If SecondString is NULL, then ASSERT().\r
522 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than\r
30817eb4 523 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
524 then ASSERT().\r
878ddf1f 525 If PcdMaximumAsciiStringLength is not zero and SecondString contains more\r
30817eb4 526 than PcdMaximumAsciiStringLength ASCII characters not including the\r
527 Null-terminator, then ASSERT().\r
878ddf1f 528\r
529 @param FirstString Pointer to a Null-terminated ASCII string.\r
530 @param SecondString Pointer to a Null-terminated ASCII string.\r
531\r
532 @retval 0 FirstString is identical to SecondString using case insensitive\r
533 comparisons.\r
534 @retval !=0 FirstString is not identical to SecondString using case\r
535 insensitive comparisons.\r
536\r
537**/\r
538INTN\r
539EFIAPI\r
540AsciiStriCmp (\r
541 IN CONST CHAR8 *FirstString,\r
542 IN CONST CHAR8 *SecondString\r
543 );\r
878ddf1f 544/**\r
545 Compares two Null-terminated ASCII strings with maximum lengths, and returns\r
546 the difference between the first mismatched ASCII characters.\r
547\r
548 This function compares the Null-terminated ASCII string FirstString to the\r
549 Null-terminated ASCII string SecondString. At most, Length ASCII characters\r
550 will be compared. If Length is 0, then 0 is returned. If FirstString is\r
551 identical to SecondString, then 0 is returned. Otherwise, the value returned\r
552 is the first mismatched ASCII character in SecondString subtracted from the\r
553 first mismatched ASCII character in FirstString.\r
554\r
555 If FirstString is NULL, then ASSERT().\r
556 If SecondString is NULL, then ASSERT().\r
557 If PcdMaximumAsciiStringLength is not zero and FirstString contains more than\r
30817eb4 558 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
559 then ASSERT().\r
560 If PcdMaximumAsciiStringLength is not zero and SecondString contains more than\r
561 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
562 then ASSERT().\r
878ddf1f 563\r
564 @param FirstString Pointer to a Null-terminated ASCII string.\r
565 @param SecondString Pointer to a Null-terminated ASCII string.\r
566\r
567 @retval 0 FirstString is identical to SecondString.\r
568 @retval !=0 FirstString is not identical to SecondString.\r
569\r
570**/\r
571INTN\r
572EFIAPI\r
573AsciiStrnCmp (\r
574 IN CONST CHAR8 *FirstString,\r
575 IN CONST CHAR8 *SecondString,\r
576 IN UINTN Length\r
577 );\r
878ddf1f 578/**\r
579 Concatenates one Null-terminated ASCII string to another Null-terminated\r
580 ASCII string, and returns the concatenated ASCII string.\r
581\r
582 This function concatenates two Null-terminated ASCII strings. The contents of\r
583 Null-terminated ASCII string Source are concatenated to the end of Null-\r
584 terminated ASCII string Destination. The Null-terminated concatenated ASCII\r
585 String is returned.\r
586\r
587 If Destination is NULL, then ASSERT().\r
588 If Source is NULL, then ASSERT().\r
589 If PcdMaximumAsciiStringLength is not zero and Destination contains more than\r
30817eb4 590 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
591 then ASSERT().\r
878ddf1f 592 If PcdMaximumAsciiStringLength is not zero and Source contains more than\r
30817eb4 593 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
594 then ASSERT().\r
878ddf1f 595 If PcdMaximumAsciiStringLength is not zero and concatenating Destination and\r
596 Source results in a ASCII string with more than PcdMaximumAsciiStringLength\r
597 ASCII characters, then ASSERT().\r
598\r
599 @param Destination Pointer to a Null-terminated ASCII string.\r
600 @param Source Pointer to a Null-terminated ASCII string.\r
601\r
602 @return Destination\r
603\r
604**/\r
605CHAR8 *\r
606EFIAPI\r
607AsciiStrCat (\r
30817eb4 608 IN OUT CHAR8 *Destination,\r
609 IN CONST CHAR8 *Source\r
878ddf1f 610 );\r
878ddf1f 611/**\r
612 Concatenates one Null-terminated ASCII string with a maximum length to the\r
613 end of another Null-terminated ASCII string, and returns the concatenated\r
614 ASCII string.\r
615\r
616 This function concatenates two Null-terminated ASCII strings. The contents\r
617 of Null-terminated ASCII string Source are concatenated to the end of Null-\r
618 terminated ASCII string Destination, and Destination is returned. At most,\r
619 Length ASCII characters are concatenated from Source to the end of\r
620 Destination, and Destination is always Null-terminated. If Length is 0, then\r
621 Destination is returned unmodified. If Source and Destination overlap, then\r
622 the results are undefined.\r
623\r
624 If Destination is NULL, then ASSERT().\r
625 If Source is NULL, then ASSERT().\r
626 If Source and Destination overlap, then ASSERT().\r
30817eb4 627 If PcdMaximumAsciiStringLength is not zero, and Destination contains more than\r
628 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
629 then ASSERT().\r
878ddf1f 630 If PcdMaximumAsciiStringLength is not zero, and Source contains more than\r
30817eb4 631 PcdMaximumAsciiStringLength ASCII characters not including the Null-terminator,\r
632 then ASSERT().\r
878ddf1f 633 If PcdMaximumAsciiStringLength is not zero, and concatenating Destination and\r
634 Source results in a ASCII string with more than PcdMaximumAsciiStringLength\r
30817eb4 635 ASCII characters not including the Null-terminator, then ASSERT().\r
878ddf1f 636\r
637 @param Destination Pointer to a Null-terminated ASCII string.\r
638 @param Source Pointer to a Null-terminated ASCII string.\r
639 @param Length Maximum number of ASCII characters to concatenate from\r
640 Source.\r
641\r
642 @return Destination\r
643\r
644**/\r
645CHAR8 *\r
646EFIAPI\r
647AsciiStrnCat (\r
648 IN OUT CHAR8 *Destination,\r
649 IN CONST CHAR8 *Source,\r
650 IN UINTN Length\r
651 );\r
dee4740a 652/**\r
653 Converts an 8-bit value to an 8-bit BCD value.\r
654\r
655 Converts the 8-bit value specified by Value to BCD. The BCD value is\r
656 returned.\r
657\r
658 If Value >= 100, then ASSERT().\r
659\r
660 @param Value The 8-bit value to convert to BCD. Range 0..99.\r
661\r
662 @return The BCD value\r
663\r
664**/\r
665UINT8\r
666EFIAPI\r
667DecimalToBcd8 (\r
668 IN UINT8 Value\r
669 );\r
670\r
671/**\r
672 Converts an 8-bit BCD value to an 8-bit value.\r
673\r
674 Converts the 8-bit BCD value specified by Value to an 8-bit value. The 8-bit\r
675 value is returned.\r
676\r
677 If Value >= 0xA0, then ASSERT().\r
678 If (Value & 0x0F) >= 0x0A, then ASSERT().\r
679\r
680 @param Value The 8-bit BCD value to convert to an 8-bit value.\r
681\r
682 @return The 8-bit value is returned.\r
683\r
684**/\r
685UINT8\r
686EFIAPI\r
687BcdToDecimal8 (\r
688 IN UINT8 Value\r
689 );\r
690\r
878ddf1f 691//\r
692// LIST_ENTRY definition\r
693//\r
694typedef struct _LIST_ENTRY LIST_ENTRY;\r
695\r
696struct _LIST_ENTRY {\r
697 LIST_ENTRY *ForwardLink;\r
698 LIST_ENTRY *BackLink;\r
699};\r
700\r
701//\r
702// Linked List Functions and Macros\r
703//\r
704\r
705/**\r
706 Initializes the head node of a doubly linked list that is declared as a\r
707 global variable in a module.\r
708\r
709 Initializes the forward and backward links of a new linked list. After\r
710 initializing a linked list with this macro, the other linked list functions\r
711 may be used to add and remove nodes from the linked list. This macro results\r
712 in smaller executables by initializing the linked list in the data section,\r
713 instead if calling the InitializeListHead() function to perform the\r
714 equivalent operation.\r
715\r
716 @param ListHead The head note of a list to initiailize.\r
717\r
718**/\r
719#define INITIALIZE_LIST_HEAD_VARIABLE(ListHead) {&ListHead, &ListHead}\r
720\r
721/**\r
722 Initializes the head node of a doubly linked list, and returns the pointer to\r
723 the head node of the doubly linked list.\r
724\r
725 Initializes the forward and backward links of a new linked list. After\r
726 initializing a linked list with this function, the other linked list\r
727 functions may be used to add and remove nodes from the linked list. It is up\r
728 to the caller of this function to allocate the memory for ListHead.\r
729\r
730 If ListHead is NULL, then ASSERT().\r
731\r
732 @param ListHead A pointer to the head node of a new doubly linked list.\r
733\r
734 @return ListHead\r
735\r
736**/\r
737LIST_ENTRY *\r
738EFIAPI\r
739InitializeListHead (\r
740 IN LIST_ENTRY *ListHead\r
741 );\r
742\r
743/**\r
744 Adds a node to the beginning of a doubly linked list, and returns the pointer\r
745 to the head node of the doubly linked list.\r
746\r
747 Adds the node Entry at the beginning of the doubly linked list denoted by\r
748 ListHead, and returns ListHead.\r
749\r
750 If ListHead is NULL, then ASSERT().\r
751 If Entry is NULL, then ASSERT().\r
752 If ListHead was not initialized with InitializeListHead(), then ASSERT().\r
30817eb4 753 If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number\r
754 of nodes in ListHead, including the ListHead node, is greater than or \r
755 equal to PcdMaximumLinkedListLength, then ASSERT().\r
878ddf1f 756\r
757 @param ListHead A pointer to the head node of a doubly linked list.\r
758 @param Entry A pointer to a node that is to be inserted at the beginning\r
759 of a doubly linked list.\r
760\r
761 @return ListHead\r
762\r
763**/\r
764LIST_ENTRY *\r
765EFIAPI\r
766InsertHeadList (\r
767 IN LIST_ENTRY *ListHead,\r
768 IN LIST_ENTRY *Entry\r
769 );\r
770\r
771/**\r
772 Adds a node to the end of a doubly linked list, and returns the pointer to\r
773 the head node of the doubly linked list.\r
774\r
775 Adds the node Entry to the end of the doubly linked list denoted by ListHead,\r
776 and returns ListHead.\r
777\r
778 If ListHead is NULL, then ASSERT().\r
779 If Entry is NULL, then ASSERT().\r
780 If ListHead was not initialized with InitializeListHead(), then ASSERT().\r
30817eb4 781 If PcdMaximumLinkedListLenth is not zero, and prior to insertion the number\r
782 of nodes in ListHead, including the ListHead node, is greater than or \r
783 equal to PcdMaximumLinkedListLength, then ASSERT().\r
878ddf1f 784\r
785 @param ListHead A pointer to the head node of a doubly linked list.\r
786 @param Entry A pointer to a node that is to be added at the end of the\r
787 doubly linked list.\r
788\r
789 @return ListHead\r
790\r
791**/\r
792LIST_ENTRY *\r
793EFIAPI\r
794InsertTailList (\r
795 IN LIST_ENTRY *ListHead,\r
796 IN LIST_ENTRY *Entry\r
797 );\r
798\r
799/**\r
800 Retrieves the first node of a doubly linked list.\r
801\r
802 Returns the first node of a doubly linked list. List must have been\r
803 initialized with InitializeListHead(). If List is empty, then NULL is\r
804 returned.\r
805\r
806 If List is NULL, then ASSERT().\r
807 If List was not initialized with InitializeListHead(), then ASSERT().\r
30817eb4 808 If PcdMaximumLinkedListLenth is not zero, and the number of nodes \r
809 in List, including the List node, is greater than or equal to \r
810 PcdMaximumLinkedListLength, then ASSERT().\r
878ddf1f 811\r
812 @param List A pointer to the head node of a doubly linked list.\r
813\r
814 @return The first node of a doubly linked list.\r
815 @retval NULL The list is empty.\r
816\r
817**/\r
818LIST_ENTRY *\r
819EFIAPI\r
820GetFirstNode (\r
821 IN CONST LIST_ENTRY *List\r
822 );\r
823\r
824/**\r
825 Retrieves the next node of a doubly linked list.\r
826\r
827 Returns the node of a doubly linked list that follows Node. List must have\r
828 been initialized with InitializeListHead(). If List is empty, then List is\r
829 returned.\r
830\r
831 If List is NULL, then ASSERT().\r
832 If Node is NULL, then ASSERT().\r
833 If List was not initialized with InitializeListHead(), then ASSERT().\r
834 If PcdMaximumLinkedListLenth is not zero, and List contains more than\r
835 PcdMaximumLinkedListLenth nodes, then ASSERT().\r
836 If Node is not a node in List, then ASSERT().\r
837\r
838 @param List A pointer to the head node of a doubly linked list.\r
839 @param Node A pointer to a node in the doubly linked list.\r
840\r
841 @return Pointer to the next node if one exists. Otherwise a null value which\r
842 is actually List is returned.\r
843\r
844**/\r
845LIST_ENTRY *\r
846EFIAPI\r
847GetNextNode (\r
848 IN CONST LIST_ENTRY *List,\r
849 IN CONST LIST_ENTRY *Node\r
850 );\r
851\r
852/**\r
853 Checks to see if a doubly linked list is empty or not.\r
854\r
855 Checks to see if the doubly linked list is empty. If the linked list contains\r
856 zero nodes, this function returns TRUE. Otherwise, it returns FALSE.\r
857\r
858 If ListHead is NULL, then ASSERT().\r
859 If ListHead was not initialized with InitializeListHead(), then ASSERT().\r
30817eb4 860 If PcdMaximumLinkedListLenth is not zero, and the number of nodes \r
861 in List, including the List node, is greater than or equal to \r
862 PcdMaximumLinkedListLength, then ASSERT().\r
878ddf1f 863\r
864 @param ListHead A pointer to the head node of a doubly linked list.\r
865\r
866 @retval TRUE The linked list is empty.\r
867 @retval FALSE The linked list is not empty.\r
868\r
869**/\r
870BOOLEAN\r
871EFIAPI\r
872IsListEmpty (\r
873 IN CONST LIST_ENTRY *ListHead\r
874 );\r
875\r
876/**\r
877 Determines if a node in a doubly linked list is null.\r
878\r
879 Returns FALSE if Node is one of the nodes in the doubly linked list specified\r
880 by List. Otherwise, TRUE is returned. List must have been initialized with\r
881 InitializeListHead().\r
882\r
883 If List is NULL, then ASSERT().\r
884 If Node is NULL, then ASSERT().\r
885 If List was not initialized with InitializeListHead(), then ASSERT().\r
30817eb4 886 If PcdMaximumLinkedListLenth is not zero, and the number of nodes \r
887 in List, including the List node, is greater than or equal to \r
888 PcdMaximumLinkedListLength, then ASSERT().\r
878ddf1f 889 If Node is not a node in List and Node is not equal to List, then ASSERT().\r
890\r
891 @param List A pointer to the head node of a doubly linked list.\r
24e25d11 892 @param Node A pointer to a node in the doubly linked list.\r
878ddf1f 893\r
894 @retval TRUE Node is one of the nodes in the doubly linked list.\r
895 @retval FALSE Node is not one of the nodes in the doubly linked list.\r
896\r
897**/\r
898BOOLEAN\r
899EFIAPI\r
900IsNull (\r
901 IN CONST LIST_ENTRY *List,\r
902 IN CONST LIST_ENTRY *Node\r
903 );\r
904\r
905/**\r
906 Determines if a node the last node in a doubly linked list.\r
907\r
908 Returns TRUE if Node is the last node in the doubly linked list specified by\r
909 List. Otherwise, FALSE is returned. List must have been initialized with\r
910 InitializeListHead().\r
911\r
912 If List is NULL, then ASSERT().\r
913 If Node is NULL, then ASSERT().\r
914 If List was not initialized with InitializeListHead(), then ASSERT().\r
30817eb4 915 If PcdMaximumLinkedListLenth is not zero, and the number of nodes \r
916 in List, including the List node, is greater than or equal to \r
917 PcdMaximumLinkedListLength, then ASSERT().\r
878ddf1f 918 If Node is not a node in List, then ASSERT().\r
919\r
920 @param List A pointer to the head node of a doubly linked list.\r
24e25d11 921 @param Node A pointer to a node in the doubly linked list.\r
878ddf1f 922\r
923 @retval TRUE Node is the last node in the linked list.\r
924 @retval FALSE Node is not the last node in the linked list.\r
925\r
926**/\r
927BOOLEAN\r
928EFIAPI\r
929IsNodeAtEnd (\r
930 IN CONST LIST_ENTRY *List,\r
931 IN CONST LIST_ENTRY *Node\r
932 );\r
933\r
934/**\r
935 Swaps the location of two nodes in a doubly linked list, and returns the\r
936 first node after the swap.\r
937\r
938 If FirstEntry is identical to SecondEntry, then SecondEntry is returned.\r
939 Otherwise, the location of the FirstEntry node is swapped with the location\r
940 of the SecondEntry node in a doubly linked list. SecondEntry must be in the\r
941 same double linked list as FirstEntry and that double linked list must have\r
942 been initialized with InitializeListHead(). SecondEntry is returned after the\r
943 nodes are swapped.\r
944\r
945 If FirstEntry is NULL, then ASSERT().\r
946 If SecondEntry is NULL, then ASSERT().\r
947 If SecondEntry and FirstEntry are not in the same linked list, then ASSERT().\r
30817eb4 948 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the\r
949 linked list containing the FirstEntry and SecondEntry nodes, including\r
950 the FirstEntry and SecondEntry nodes, is greater than or equal to \r
951 PcdMaximumLinkedListLength, then ASSERT().\r
878ddf1f 952\r
953 @param FirstEntry A pointer to a node in a linked list.\r
954 @param SecondEntry A pointer to another node in the same linked list.\r
955\r
956**/\r
957LIST_ENTRY *\r
958EFIAPI\r
959SwapListEntries (\r
960 IN LIST_ENTRY *FirstEntry,\r
961 IN LIST_ENTRY *SecondEntry\r
962 );\r
963\r
964/**\r
965 Removes a node from a doubly linked list, and returns the node that follows\r
966 the removed node.\r
967\r
968 Removes the node Entry from a doubly linked list. It is up to the caller of\r
969 this function to release the memory used by this node if that is required. On\r
970 exit, the node following Entry in the doubly linked list is returned. If\r
971 Entry is the only node in the linked list, then the head node of the linked\r
972 list is returned.\r
973\r
974 If Entry is NULL, then ASSERT().\r
975 If Entry is the head node of an empty list, then ASSERT().\r
30817eb4 976 If PcdMaximumLinkedListLength is not zero, and the number of nodes in the \r
977 linked list containing Entry, including the Entry node, is greater than \r
978 or equal to PcdMaximumLinkedListLength, then ASSERT().\r
878ddf1f 979\r
980 @param Entry A pointer to a node in a linked list\r
981\r
982 @return Entry\r
983\r
984**/\r
985LIST_ENTRY *\r
986EFIAPI\r
987RemoveEntryList (\r
988 IN CONST LIST_ENTRY *Entry\r
989 );\r
990\r
991//\r
992// Math Services\r
993//\r
994\r
995/**\r
996 Shifts a 64-bit integer left between 0 and 63 bits. The low bits are filled\r
997 with zeros. The shifted value is returned.\r
998\r
999 This function shifts the 64-bit value Operand to the left by Count bits. The\r
1000 low Count bits are set to zero. The shifted value is returned.\r
1001\r
1002 If Count is greater than 63, then ASSERT().\r
1003\r
1004 @param Operand The 64-bit operand to shift left.\r
1005 @param Count The number of bits to shift left.\r
1006\r
1007 @return Operand << Count\r
1008\r
1009**/\r
1010UINT64\r
1011EFIAPI\r
1012LShiftU64 (\r
1013 IN UINT64 Operand,\r
1014 IN UINTN Count\r
1015 );\r
1016\r
1017/**\r
1018 Shifts a 64-bit integer right between 0 and 63 bits. This high bits are\r
1019 filled with zeros. The shifted value is returned.\r
1020\r
1021 This function shifts the 64-bit value Operand to the right by Count bits. The\r
1022 high Count bits are set to zero. The shifted value is returned.\r
1023\r
1024 If Count is greater than 63, then ASSERT().\r
1025\r
1026 @param Operand The 64-bit operand to shift right.\r
1027 @param Count The number of bits to shift right.\r
1028\r
1029 @return Operand >> Count\r
1030\r
1031**/\r
1032UINT64\r
1033EFIAPI\r
1034RShiftU64 (\r
1035 IN UINT64 Operand,\r
1036 IN UINTN Count\r
1037 );\r
1038\r
1039/**\r
1040 Shifts a 64-bit integer right between 0 and 63 bits. The high bits are filled\r
1041 with original integer's bit 63. The shifted value is returned.\r
1042\r
1043 This function shifts the 64-bit value Operand to the right by Count bits. The\r
1044 high Count bits are set to bit 63 of Operand. The shifted value is returned.\r
1045\r
1046 If Count is greater than 63, then ASSERT().\r
1047\r
1048 @param Operand The 64-bit operand to shift right.\r
1049 @param Count The number of bits to shift right.\r
1050\r
1051 @return Operand >> Count\r
1052\r
1053**/\r
1054UINT64\r
1055EFIAPI\r
1056ARShiftU64 (\r
1057 IN UINT64 Operand,\r
1058 IN UINTN Count\r
1059 );\r
1060\r
1061/**\r
1062 Rotates a 32-bit integer left between 0 and 31 bits, filling the low bits\r
1063 with the high bits that were rotated.\r
1064\r
1065 This function rotates the 32-bit value Operand to the left by Count bits. The\r
1066 low Count bits are fill with the high Count bits of Operand. The rotated\r
1067 value is returned.\r
1068\r
1069 If Count is greater than 31, then ASSERT().\r
1070\r
1071 @param Operand The 32-bit operand to rotate left.\r
1072 @param Count The number of bits to rotate left.\r
1073\r
1074 @return Operand <<< Count\r
1075\r
1076**/\r
1077UINT32\r
1078EFIAPI\r
1079LRotU32 (\r
1080 IN UINT32 Operand,\r
1081 IN UINTN Count\r
1082 );\r
1083\r
1084/**\r
1085 Rotates a 32-bit integer right between 0 and 31 bits, filling the high bits\r
1086 with the low bits that were rotated.\r
1087\r
1088 This function rotates the 32-bit value Operand to the right by Count bits.\r
1089 The high Count bits are fill with the low Count bits of Operand. The rotated\r
1090 value is returned.\r
1091\r
1092 If Count is greater than 31, then ASSERT().\r
1093\r
1094 @param Operand The 32-bit operand to rotate right.\r
1095 @param Count The number of bits to rotate right.\r
1096\r
1097 @return Operand >>> Count\r
1098\r
1099**/\r
1100UINT32\r
1101EFIAPI\r
1102RRotU32 (\r
1103 IN UINT32 Operand,\r
1104 IN UINTN Count\r
1105 );\r
1106\r
1107/**\r
1108 Rotates a 64-bit integer left between 0 and 63 bits, filling the low bits\r
1109 with the high bits that were rotated.\r
1110\r
1111 This function rotates the 64-bit value Operand to the left by Count bits. The\r
1112 low Count bits are fill with the high Count bits of Operand. The rotated\r
1113 value is returned.\r
1114\r
1115 If Count is greater than 63, then ASSERT().\r
1116\r
1117 @param Operand The 64-bit operand to rotate left.\r
1118 @param Count The number of bits to rotate left.\r
1119\r
1120 @return Operand <<< Count\r
1121\r
1122**/\r
1123UINT64\r
1124EFIAPI\r
1125LRotU64 (\r
1126 IN UINT64 Operand,\r
1127 IN UINTN Count\r
1128 );\r
1129\r
1130/**\r
1131 Rotates a 64-bit integer right between 0 and 63 bits, filling the high bits\r
1132 with the high low bits that were rotated.\r
1133\r
1134 This function rotates the 64-bit value Operand to the right by Count bits.\r
1135 The high Count bits are fill with the low Count bits of Operand. The rotated\r
1136 value is returned.\r
1137\r
1138 If Count is greater than 63, then ASSERT().\r
1139\r
1140 @param Operand The 64-bit operand to rotate right.\r
1141 @param Count The number of bits to rotate right.\r
1142\r
1143 @return Operand >>> Count\r
1144\r
1145**/\r
1146UINT64\r
1147EFIAPI\r
1148RRotU64 (\r
1149 IN UINT64 Operand,\r
1150 IN UINTN Count\r
1151 );\r
1152\r
1153/**\r
1154 Returns the bit position of the lowest bit set in a 32-bit value.\r
1155\r
1156 This function computes the bit position of the lowest bit set in the 32-bit\r
1157 value specified by Operand. If Operand is zero, then -1 is returned.\r
1158 Otherwise, a value between 0 and 31 is returned.\r
1159\r
1160 @param Operand The 32-bit operand to evaluate.\r
1161\r
1162 @return Position of the lowest bit set in Operand if found.\r
1163 @retval -1 Operand is zero.\r
1164\r
1165**/\r
1166INTN\r
1167EFIAPI\r
1168LowBitSet32 (\r
1169 IN UINT32 Operand\r
1170 );\r
1171\r
1172/**\r
1173 Returns the bit position of the lowest bit set in a 64-bit value.\r
1174\r
1175 This function computes the bit position of the lowest bit set in the 64-bit\r
1176 value specified by Operand. If Operand is zero, then -1 is returned.\r
1177 Otherwise, a value between 0 and 63 is returned.\r
1178\r
1179 @param Operand The 64-bit operand to evaluate.\r
1180\r
1181 @return Position of the lowest bit set in Operand if found.\r
1182 @retval -1 Operand is zero.\r
1183\r
1184**/\r
1185INTN\r
1186EFIAPI\r
1187LowBitSet64 (\r
1188 IN UINT64 Operand\r
1189 );\r
1190\r
1191/**\r
1192 Returns the bit position of the highest bit set in a 32-bit value. Equivalent\r
1193 to log2(x).\r
1194\r
1195 This function computes the bit position of the highest bit set in the 32-bit\r
1196 value specified by Operand. If Operand is zero, then -1 is returned.\r
1197 Otherwise, a value between 0 and 31 is returned.\r
1198\r
1199 @param Operand The 32-bit operand to evaluate.\r
1200\r
1201 @return Position of the highest bit set in Operand if found.\r
1202 @retval -1 Operand is zero.\r
1203\r
1204**/\r
1205INTN\r
1206EFIAPI\r
1207HighBitSet32 (\r
1208 IN UINT32 Operand\r
1209 );\r
1210\r
1211/**\r
1212 Returns the bit position of the highest bit set in a 64-bit value. Equivalent\r
1213 to log2(x).\r
1214\r
1215 This function computes the bit position of the highest bit set in the 64-bit\r
1216 value specified by Operand. If Operand is zero, then -1 is returned.\r
1217 Otherwise, a value between 0 and 63 is returned.\r
1218\r
1219 @param Operand The 64-bit operand to evaluate.\r
1220\r
1221 @return Position of the highest bit set in Operand if found.\r
1222 @retval -1 Operand is zero.\r
1223\r
1224**/\r
1225INTN\r
1226EFIAPI\r
1227HighBitSet64 (\r
1228 IN UINT64 Operand\r
1229 );\r
1230\r
1231/**\r
1232 Returns the value of the highest bit set in a 32-bit value. Equivalent to\r
1233 1 << HighBitSet32(x).\r
1234\r
1235 This function computes the value of the highest bit set in the 32-bit value\r
1236 specified by Operand. If Operand is zero, then zero is returned.\r
1237\r
1238 @param Operand The 32-bit operand to evaluate.\r
1239\r
1240 @return 1 << HighBitSet32(Operand)\r
1241 @retval 0 Operand is zero.\r
1242\r
1243**/\r
1244UINT32\r
1245EFIAPI\r
1246GetPowerOfTwo32 (\r
1247 IN UINT32 Operand\r
1248 );\r
1249\r
1250/**\r
1251 Returns the value of the highest bit set in a 64-bit value. Equivalent to\r
1252 1 << HighBitSet64(x).\r
1253\r
1254 This function computes the value of the highest bit set in the 64-bit value\r
1255 specified by Operand. If Operand is zero, then zero is returned.\r
1256\r
1257 @param Operand The 64-bit operand to evaluate.\r
1258\r
1259 @return 1 << HighBitSet64(Operand)\r
1260 @retval 0 Operand is zero.\r
1261\r
1262**/\r
1263UINT64\r
1264EFIAPI\r
1265GetPowerOfTwo64 (\r
1266 IN UINT64 Operand\r
1267 );\r
1268\r
1269/**\r
1270 Switches the endianess of a 16-bit integer.\r
1271\r
1272 This function swaps the bytes in a 16-bit unsigned value to switch the value\r
1273 from little endian to big endian or vice versa. The byte swapped value is\r
1274 returned.\r
1275\r
1276 @param Operand A 16-bit unsigned value.\r
1277\r
1278 @return The byte swaped Operand.\r
1279\r
1280**/\r
1281UINT16\r
1282EFIAPI\r
1283SwapBytes16 (\r
1284 IN UINT16 Value\r
1285 );\r
1286\r
1287/**\r
1288 Switches the endianess of a 32-bit integer.\r
1289\r
1290 This function swaps the bytes in a 32-bit unsigned value to switch the value\r
1291 from little endian to big endian or vice versa. The byte swapped value is\r
1292 returned.\r
1293\r
1294 @param Operand A 32-bit unsigned value.\r
1295\r
1296 @return The byte swaped Operand.\r
1297\r
1298**/\r
1299UINT32\r
1300EFIAPI\r
1301SwapBytes32 (\r
1302 IN UINT32 Value\r
1303 );\r
1304\r
1305/**\r
1306 Switches the endianess of a 64-bit integer.\r
1307\r
1308 This function swaps the bytes in a 64-bit unsigned value to switch the value\r
1309 from little endian to big endian or vice versa. The byte swapped value is\r
1310 returned.\r
1311\r
1312 @param Operand A 64-bit unsigned value.\r
1313\r
1314 @return The byte swaped Operand.\r
1315\r
1316**/\r
1317UINT64\r
1318EFIAPI\r
1319SwapBytes64 (\r
1320 IN UINT64 Value\r
1321 );\r
1322\r
1323/**\r
1324 Multiples a 64-bit unsigned integer by a 32-bit unsigned integer and\r
1325 generates a 64-bit unsigned result.\r
1326\r
1327 This function multiples the 64-bit unsigned value Multiplicand by the 32-bit\r
1328 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-\r
1329 bit unsigned result is returned.\r
1330\r
1331 If the result overflows, then ASSERT().\r
1332\r
1333 @param Multiplicand A 64-bit unsigned value.\r
1334 @param Multiplier A 32-bit unsigned value.\r
1335\r
1336 @return Multiplicand * Multiplier\r
1337\r
1338**/\r
1339UINT64\r
1340EFIAPI\r
1341MultU64x32 (\r
1342 IN UINT64 Multiplicand,\r
1343 IN UINT32 Multiplier\r
1344 );\r
1345\r
1346/**\r
1347 Multiples a 64-bit unsigned integer by a 64-bit unsigned integer and\r
1348 generates a 64-bit unsigned result.\r
1349\r
1350 This function multiples the 64-bit unsigned value Multiplicand by the 64-bit\r
1351 unsigned value Multiplier and generates a 64-bit unsigned result. This 64-\r
1352 bit unsigned result is returned.\r
1353\r
1354 If the result overflows, then ASSERT().\r
1355\r
1356 @param Multiplicand A 64-bit unsigned value.\r
1357 @param Multiplier A 64-bit unsigned value.\r
1358\r
1359 @return Multiplicand * Multiplier\r
1360\r
1361**/\r
1362UINT64\r
1363EFIAPI\r
1364MultU64x64 (\r
1365 IN UINT64 Multiplicand,\r
1366 IN UINT64 Multiplier\r
1367 );\r
1368\r
1369/**\r
1370 Multiples a 64-bit signed integer by a 64-bit signed integer and generates a\r
1371 64-bit signed result.\r
1372\r
1373 This function multiples the 64-bit signed value Multiplicand by the 64-bit\r
1374 signed value Multiplier and generates a 64-bit signed result. This 64-bit\r
1375 signed result is returned.\r
1376\r
1377 If the result overflows, then ASSERT().\r
1378\r
1379 @param Multiplicand A 64-bit signed value.\r
1380 @param Multiplier A 64-bit signed value.\r
1381\r
1382 @return Multiplicand * Multiplier\r
1383\r
1384**/\r
1385INT64\r
1386EFIAPI\r
1387MultS64x64 (\r
1388 IN INT64 Multiplicand,\r
1389 IN INT64 Multiplier\r
1390 );\r
1391\r
1392/**\r
1393 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates\r
1394 a 64-bit unsigned result.\r
1395\r
1396 This function divides the 64-bit unsigned value Dividend by the 32-bit\r
1397 unsigned value Divisor and generates a 64-bit unsigned quotient. This\r
1398 function returns the 64-bit unsigned quotient.\r
1399\r
1400 If Divisor is 0, then ASSERT().\r
1401\r
1402 @param Dividend A 64-bit unsigned value.\r
1403 @param Divisor A 32-bit unsigned value.\r
1404\r
1405 @return Dividend / Divisor\r
1406\r
1407**/\r
1408UINT64\r
1409EFIAPI\r
1410DivU64x32 (\r
1411 IN UINT64 Dividend,\r
1412 IN UINT32 Divisor\r
1413 );\r
1414\r
1415/**\r
1416 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates\r
1417 a 32-bit unsigned remainder.\r
1418\r
1419 This function divides the 64-bit unsigned value Dividend by the 32-bit\r
1420 unsigned value Divisor and generates a 32-bit remainder. This function\r
1421 returns the 32-bit unsigned remainder.\r
1422\r
1423 If Divisor is 0, then ASSERT().\r
1424\r
1425 @param Dividend A 64-bit unsigned value.\r
1426 @param Divisor A 32-bit unsigned value.\r
1427\r
1428 @return Dividend % Divisor\r
1429\r
1430**/\r
1431UINT32\r
1432EFIAPI\r
1433ModU64x32 (\r
1434 IN UINT64 Dividend,\r
1435 IN UINT32 Divisor\r
1436 );\r
1437\r
1438/**\r
1439 Divides a 64-bit unsigned integer by a 32-bit unsigned integer and generates\r
1440 a 64-bit unsigned result and an optional 32-bit unsigned remainder.\r
1441\r
1442 This function divides the 64-bit unsigned value Dividend by the 32-bit\r
1443 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder\r
1444 is not NULL, then the 32-bit unsigned remainder is returned in Remainder.\r
1445 This function returns the 64-bit unsigned quotient.\r
1446\r
1447 If Divisor is 0, then ASSERT().\r
1448\r
1449 @param Dividend A 64-bit unsigned value.\r
1450 @param Divisor A 32-bit unsigned value.\r
1451 @param Remainder A pointer to a 32-bit unsigned value. This parameter is\r
1452 optional and may be NULL.\r
1453\r
1454 @return Dividend / Divisor\r
1455\r
1456**/\r
1457UINT64\r
1458EFIAPI\r
1459DivU64x32Remainder (\r
1460 IN UINT64 Dividend,\r
1461 IN UINT32 Divisor,\r
1462 OUT UINT32 *Remainder OPTIONAL\r
1463 );\r
1464\r
1465/**\r
1466 Divides a 64-bit unsigned integer by a 64-bit unsigned integer and generates\r
1467 a 64-bit unsigned result and an optional 64-bit unsigned remainder.\r
1468\r
1469 This function divides the 64-bit unsigned value Dividend by the 64-bit\r
1470 unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder\r
1471 is not NULL, then the 64-bit unsigned remainder is returned in Remainder.\r
1472 This function returns the 64-bit unsigned quotient.\r
1473\r
1474 If Divisor is 0, then ASSERT().\r
1475\r
1476 @param Dividend A 64-bit unsigned value.\r
1477 @param Divisor A 64-bit unsigned value.\r
1478 @param Remainder A pointer to a 64-bit unsigned value. This parameter is\r
1479 optional and may be NULL.\r
1480\r
1481 @return Dividend / Divisor\r
1482\r
1483**/\r
1484UINT64\r
1485EFIAPI\r
1486DivU64x64Remainder (\r
1487 IN UINT64 Dividend,\r
1488 IN UINT64 Divisor,\r
1489 OUT UINT64 *Remainder OPTIONAL\r
1490 );\r
1491\r
1492/**\r
1493 Divides a 64-bit signed integer by a 64-bit signed integer and generates a\r
1494 64-bit signed result and a optional 64-bit signed remainder.\r
1495\r
1496 This function divides the 64-bit signed value Dividend by the 64-bit signed\r
1497 value Divisor and generates a 64-bit signed quotient. If Remainder is not\r
1498 NULL, then the 64-bit signed remainder is returned in Remainder. This\r
1499 function returns the 64-bit signed quotient.\r
1500\r
1501 If Divisor is 0, then ASSERT().\r
1502\r
1503 @param Dividend A 64-bit signed value.\r
1504 @param Divisor A 64-bit signed value.\r
1505 @param Remainder A pointer to a 64-bit signed value. This parameter is\r
1506 optional and may be NULL.\r
1507\r
1508 @return Dividend / Divisor\r
1509\r
1510**/\r
1511INT64\r
1512EFIAPI\r
1513DivS64x64Remainder (\r
1514 IN INT64 Dividend,\r
1515 IN INT64 Divisor,\r
1516 OUT INT64 *Remainder OPTIONAL\r
1517 );\r
1518\r
1519/**\r
1520 Reads a 16-bit value from memory that may be unaligned.\r
1521\r
1522 This function returns the 16-bit value pointed to by Buffer. The function\r
1523 guarantees that the read operation does not produce an alignment fault.\r
1524\r
1525 If the Buffer is NULL, then ASSERT().\r
1526\r
1527 @param Buffer Pointer to a 16-bit value that may be unaligned.\r
1528\r
1529 @return *Uint16\r
1530\r
1531**/\r
1532UINT16\r
1533EFIAPI\r
1534ReadUnaligned16 (\r
1535 IN CONST UINT16 *Uint16\r
1536 );\r
1537\r
1538/**\r
1539 Writes a 16-bit value to memory that may be unaligned.\r
1540\r
1541 This function writes the 16-bit value specified by Value to Buffer. Value is\r
1542 returned. The function guarantees that the write operation does not produce\r
1543 an alignment fault.\r
1544\r
1545 If the Buffer is NULL, then ASSERT().\r
1546\r
1547 @param Buffer Pointer to a 16-bit value that may be unaligned.\r
1548 @param Value 16-bit value to write to Buffer.\r
1549\r
1550 @return Value\r
1551\r
1552**/\r
1553UINT16\r
1554EFIAPI\r
1555WriteUnaligned16 (\r
1556 OUT UINT16 *Uint16,\r
1557 IN UINT16 Value\r
1558 );\r
1559\r
1560/**\r
1561 Reads a 24-bit value from memory that may be unaligned.\r
1562\r
1563 This function returns the 24-bit value pointed to by Buffer. The function\r
1564 guarantees that the read operation does not produce an alignment fault.\r
1565\r
1566 If the Buffer is NULL, then ASSERT().\r
1567\r
1568 @param Buffer Pointer to a 24-bit value that may be unaligned.\r
1569\r
1570 @return The value read.\r
1571\r
1572**/\r
1573UINT32\r
1574EFIAPI\r
1575ReadUnaligned24 (\r
1576 IN CONST UINT32 *Buffer\r
1577 );\r
1578\r
1579/**\r
1580 Writes a 24-bit value to memory that may be unaligned.\r
1581\r
1582 This function writes the 24-bit value specified by Value to Buffer. Value is\r
1583 returned. The function guarantees that the write operation does not produce\r
1584 an alignment fault.\r
1585\r
1586 If the Buffer is NULL, then ASSERT().\r
1587\r
1588 @param Buffer Pointer to a 24-bit value that may be unaligned.\r
1589 @param Value 24-bit value to write to Buffer.\r
1590\r
1591 @return The value written.\r
1592\r
1593**/\r
1594UINT32\r
1595EFIAPI\r
1596WriteUnaligned24 (\r
1597 OUT UINT32 *Buffer,\r
1598 IN UINT32 Value\r
1599 );\r
1600\r
1601/**\r
1602 Reads a 32-bit value from memory that may be unaligned.\r
1603\r
1604 This function returns the 32-bit value pointed to by Buffer. The function\r
1605 guarantees that the read operation does not produce an alignment fault.\r
1606\r
1607 If the Buffer is NULL, then ASSERT().\r
1608\r
1609 @param Buffer Pointer to a 32-bit value that may be unaligned.\r
1610\r
1611 @return *Uint32\r
1612\r
1613**/\r
1614UINT32\r
1615EFIAPI\r
1616ReadUnaligned32 (\r
1617 IN CONST UINT32 *Uint32\r
1618 );\r
1619\r
1620/**\r
1621 Writes a 32-bit value to memory that may be unaligned.\r
1622\r
1623 This function writes the 32-bit value specified by Value to Buffer. Value is\r
1624 returned. The function guarantees that the write operation does not produce\r
1625 an alignment fault.\r
1626\r
1627 If the Buffer is NULL, then ASSERT().\r
1628\r
1629 @param Buffer Pointer to a 32-bit value that may be unaligned.\r
1630 @param Value 32-bit value to write to Buffer.\r
1631\r
1632 @return Value\r
1633\r
1634**/\r
1635UINT32\r
1636EFIAPI\r
1637WriteUnaligned32 (\r
1638 OUT UINT32 *Uint32,\r
1639 IN UINT32 Value\r
1640 );\r
1641\r
1642/**\r
1643 Reads a 64-bit value from memory that may be unaligned.\r
1644\r
1645 This function returns the 64-bit value pointed to by Buffer. The function\r
1646 guarantees that the read operation does not produce an alignment fault.\r
1647\r
1648 If the Buffer is NULL, then ASSERT().\r
1649\r
1650 @param Buffer Pointer to a 64-bit value that may be unaligned.\r
1651\r
1652 @return *Uint64\r
1653\r
1654**/\r
1655UINT64\r
1656EFIAPI\r
1657ReadUnaligned64 (\r
1658 IN CONST UINT64 *Uint64\r
1659 );\r
1660\r
1661/**\r
1662 Writes a 64-bit value to memory that may be unaligned.\r
1663\r
1664 This function writes the 64-bit value specified by Value to Buffer. Value is\r
1665 returned. The function guarantees that the write operation does not produce\r
1666 an alignment fault.\r
1667\r
1668 If the Buffer is NULL, then ASSERT().\r
1669\r
1670 @param Buffer Pointer to a 64-bit value that may be unaligned.\r
1671 @param Value 64-bit value to write to Buffer.\r
1672\r
1673 @return Value\r
1674\r
1675**/\r
1676UINT64\r
1677EFIAPI\r
1678WriteUnaligned64 (\r
1679 OUT UINT64 *Uint64,\r
1680 IN UINT64 Value\r
1681 );\r
1682\r
1683//\r
1684// Bit Field Functions\r
1685//\r
1686\r
1687/**\r
1688 Returns a bit field from an 8-bit value.\r
1689\r
1690 Returns the bitfield specified by the StartBit and the EndBit from Operand.\r
1691\r
1692 If 8-bit operations are not supported, then ASSERT().\r
1693 If StartBit is greater than 7, then ASSERT().\r
1694 If EndBit is greater than 7, then ASSERT().\r
0ffa1286 1695 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 1696\r
1697 @param Operand Operand on which to perform the bitfield operation.\r
1698 @param StartBit The ordinal of the least significant bit in the bit field.\r
1699 Range 0..7.\r
1700 @param EndBit The ordinal of the most significant bit in the bit field.\r
1701 Range 0..7.\r
1702\r
1703 @return The bit field read.\r
1704\r
1705**/\r
1706UINT8\r
1707EFIAPI\r
1708BitFieldRead8 (\r
1709 IN UINT8 Operand,\r
1710 IN UINTN StartBit,\r
1711 IN UINTN EndBit\r
1712 );\r
1713\r
1714/**\r
1715 Writes a bit field to an 8-bit value, and returns the result.\r
1716\r
1717 Writes Value to the bit field specified by the StartBit and the EndBit in\r
1718 Operand. All other bits in Operand are preserved. The new 8-bit value is\r
1719 returned.\r
1720\r
1721 If 8-bit operations are not supported, then ASSERT().\r
1722 If StartBit is greater than 7, then ASSERT().\r
1723 If EndBit is greater than 7, then ASSERT().\r
0ffa1286 1724 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 1725\r
1726 @param Operand Operand on which to perform the bitfield operation.\r
1727 @param StartBit The ordinal of the least significant bit in the bit field.\r
1728 Range 0..7.\r
1729 @param EndBit The ordinal of the most significant bit in the bit field.\r
1730 Range 0..7.\r
1731 @param Value New value of the bit field.\r
1732\r
1733 @return The new 8-bit value.\r
1734\r
1735**/\r
1736UINT8\r
1737EFIAPI\r
1738BitFieldWrite8 (\r
1739 IN UINT8 Operand,\r
1740 IN UINTN StartBit,\r
1741 IN UINTN EndBit,\r
1742 IN UINT8 Value\r
1743 );\r
1744\r
1745/**\r
1746 Reads a bit field from an 8-bit value, performs a bitwise OR, and returns the\r
1747 result.\r
1748\r
1749 Performs a bitwise inclusive OR between the bit field specified by StartBit\r
1750 and EndBit in Operand and the value specified by OrData. All other bits in\r
1751 Operand are preserved. The new 8-bit value is returned.\r
1752\r
1753 If 8-bit operations are not supported, then ASSERT().\r
1754 If StartBit is greater than 7, then ASSERT().\r
1755 If EndBit is greater than 7, then ASSERT().\r
0ffa1286 1756 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 1757\r
1758 @param Operand Operand on which to perform the bitfield operation.\r
1759 @param StartBit The ordinal of the least significant bit in the bit field.\r
1760 Range 0..7.\r
1761 @param EndBit The ordinal of the most significant bit in the bit field.\r
1762 Range 0..7.\r
1763 @param OrData The value to OR with the read value from the value\r
1764\r
1765 @return The new 8-bit value.\r
1766\r
1767**/\r
1768UINT8\r
1769EFIAPI\r
1770BitFieldOr8 (\r
1771 IN UINT8 Operand,\r
1772 IN UINTN StartBit,\r
1773 IN UINTN EndBit,\r
1774 IN UINT8 OrData\r
1775 );\r
1776\r
1777/**\r
1778 Reads a bit field from an 8-bit value, performs a bitwise AND, and returns\r
1779 the result.\r
1780\r
1781 Performs a bitwise AND between the bit field specified by StartBit and EndBit\r
1782 in Operand and the value specified by AndData. All other bits in Operand are\r
1783 preserved. The new 8-bit value is returned.\r
1784\r
1785 If 8-bit operations are not supported, then ASSERT().\r
1786 If StartBit is greater than 7, then ASSERT().\r
1787 If EndBit is greater than 7, then ASSERT().\r
0ffa1286 1788 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 1789\r
1790 @param Operand Operand on which to perform the bitfield operation.\r
1791 @param StartBit The ordinal of the least significant bit in the bit field.\r
1792 Range 0..7.\r
1793 @param EndBit The ordinal of the most significant bit in the bit field.\r
1794 Range 0..7.\r
1795 @param AndData The value to AND with the read value from the value.\r
1796\r
1797 @return The new 8-bit value.\r
1798\r
1799**/\r
1800UINT8\r
1801EFIAPI\r
1802BitFieldAnd8 (\r
1803 IN UINT8 Operand,\r
1804 IN UINTN StartBit,\r
1805 IN UINTN EndBit,\r
1806 IN UINT8 AndData\r
1807 );\r
1808\r
1809/**\r
1810 Reads a bit field from an 8-bit value, performs a bitwise AND followed by a\r
1811 bitwise OR, and returns the result.\r
1812\r
1813 Performs a bitwise AND between the bit field specified by StartBit and EndBit\r
1814 in Operand and the value specified by AndData, followed by a bitwise\r
1815 inclusive OR with value specified by OrData. All other bits in Operand are\r
1816 preserved. The new 8-bit value is returned.\r
1817\r
1818 If 8-bit operations are not supported, then ASSERT().\r
1819 If StartBit is greater than 7, then ASSERT().\r
1820 If EndBit is greater than 7, then ASSERT().\r
0ffa1286 1821 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 1822\r
1823 @param Operand Operand on which to perform the bitfield operation.\r
1824 @param StartBit The ordinal of the least significant bit in the bit field.\r
1825 Range 0..7.\r
1826 @param EndBit The ordinal of the most significant bit in the bit field.\r
1827 Range 0..7.\r
1828 @param AndData The value to AND with the read value from the value.\r
1829 @param OrData The value to OR with the result of the AND operation.\r
1830\r
1831 @return The new 8-bit value.\r
1832\r
1833**/\r
1834UINT8\r
1835EFIAPI\r
1836BitFieldAndThenOr8 (\r
1837 IN UINT8 Operand,\r
1838 IN UINTN StartBit,\r
1839 IN UINTN EndBit,\r
1840 IN UINT8 AndData,\r
1841 IN UINT8 OrData\r
1842 );\r
1843\r
1844/**\r
1845 Returns a bit field from a 16-bit value.\r
1846\r
1847 Returns the bitfield specified by the StartBit and the EndBit from Operand.\r
1848\r
1849 If 16-bit operations are not supported, then ASSERT().\r
1850 If StartBit is greater than 15, then ASSERT().\r
1851 If EndBit is greater than 15, then ASSERT().\r
0ffa1286 1852 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 1853\r
1854 @param Operand Operand on which to perform the bitfield operation.\r
1855 @param StartBit The ordinal of the least significant bit in the bit field.\r
1856 Range 0..15.\r
1857 @param EndBit The ordinal of the most significant bit in the bit field.\r
1858 Range 0..15.\r
1859\r
1860 @return The bit field read.\r
1861\r
1862**/\r
1863UINT16\r
1864EFIAPI\r
1865BitFieldRead16 (\r
1866 IN UINT16 Operand,\r
1867 IN UINTN StartBit,\r
1868 IN UINTN EndBit\r
1869 );\r
1870\r
1871/**\r
1872 Writes a bit field to a 16-bit value, and returns the result.\r
1873\r
1874 Writes Value to the bit field specified by the StartBit and the EndBit in\r
1875 Operand. All other bits in Operand are preserved. The new 16-bit value is\r
1876 returned.\r
1877\r
1878 If 16-bit operations are not supported, then ASSERT().\r
1879 If StartBit is greater than 15, then ASSERT().\r
1880 If EndBit is greater than 15, then ASSERT().\r
0ffa1286 1881 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 1882\r
1883 @param Operand Operand on which to perform the bitfield operation.\r
1884 @param StartBit The ordinal of the least significant bit in the bit field.\r
1885 Range 0..15.\r
1886 @param EndBit The ordinal of the most significant bit in the bit field.\r
1887 Range 0..15.\r
1888 @param Value New value of the bit field.\r
1889\r
1890 @return The new 16-bit value.\r
1891\r
1892**/\r
1893UINT16\r
1894EFIAPI\r
1895BitFieldWrite16 (\r
1896 IN UINT16 Operand,\r
1897 IN UINTN StartBit,\r
1898 IN UINTN EndBit,\r
1899 IN UINT16 Value\r
1900 );\r
1901\r
1902/**\r
1903 Reads a bit field from a 16-bit value, performs a bitwise OR, and returns the\r
1904 result.\r
1905\r
1906 Performs a bitwise inclusive OR between the bit field specified by StartBit\r
1907 and EndBit in Operand and the value specified by OrData. All other bits in\r
1908 Operand are preserved. The new 16-bit value is returned.\r
1909\r
1910 If 16-bit operations are not supported, then ASSERT().\r
1911 If StartBit is greater than 15, then ASSERT().\r
1912 If EndBit is greater than 15, then ASSERT().\r
0ffa1286 1913 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 1914\r
1915 @param Operand Operand on which to perform the bitfield operation.\r
1916 @param StartBit The ordinal of the least significant bit in the bit field.\r
1917 Range 0..15.\r
1918 @param EndBit The ordinal of the most significant bit in the bit field.\r
1919 Range 0..15.\r
1920 @param OrData The value to OR with the read value from the value\r
1921\r
1922 @return The new 16-bit value.\r
1923\r
1924**/\r
1925UINT16\r
1926EFIAPI\r
1927BitFieldOr16 (\r
1928 IN UINT16 Operand,\r
1929 IN UINTN StartBit,\r
1930 IN UINTN EndBit,\r
1931 IN UINT16 OrData\r
1932 );\r
1933\r
1934/**\r
1935 Reads a bit field from a 16-bit value, performs a bitwise AND, and returns\r
1936 the result.\r
1937\r
1938 Performs a bitwise AND between the bit field specified by StartBit and EndBit\r
1939 in Operand and the value specified by AndData. All other bits in Operand are\r
1940 preserved. The new 16-bit value is returned.\r
1941\r
1942 If 16-bit operations are not supported, then ASSERT().\r
1943 If StartBit is greater than 15, then ASSERT().\r
1944 If EndBit is greater than 15, then ASSERT().\r
0ffa1286 1945 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 1946\r
1947 @param Operand Operand on which to perform the bitfield operation.\r
1948 @param StartBit The ordinal of the least significant bit in the bit field.\r
1949 Range 0..15.\r
1950 @param EndBit The ordinal of the most significant bit in the bit field.\r
1951 Range 0..15.\r
1952 @param AndData The value to AND with the read value from the value\r
1953\r
1954 @return The new 16-bit value.\r
1955\r
1956**/\r
1957UINT16\r
1958EFIAPI\r
1959BitFieldAnd16 (\r
1960 IN UINT16 Operand,\r
1961 IN UINTN StartBit,\r
1962 IN UINTN EndBit,\r
1963 IN UINT16 AndData\r
1964 );\r
1965\r
1966/**\r
1967 Reads a bit field from a 16-bit value, performs a bitwise AND followed by a\r
1968 bitwise OR, and returns the result.\r
1969\r
1970 Performs a bitwise AND between the bit field specified by StartBit and EndBit\r
1971 in Operand and the value specified by AndData, followed by a bitwise\r
1972 inclusive OR with value specified by OrData. All other bits in Operand are\r
1973 preserved. The new 16-bit value is returned.\r
1974\r
1975 If 16-bit operations are not supported, then ASSERT().\r
1976 If StartBit is greater than 15, then ASSERT().\r
1977 If EndBit is greater than 15, then ASSERT().\r
0ffa1286 1978 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 1979\r
1980 @param Operand Operand on which to perform the bitfield operation.\r
1981 @param StartBit The ordinal of the least significant bit in the bit field.\r
1982 Range 0..15.\r
1983 @param EndBit The ordinal of the most significant bit in the bit field.\r
1984 Range 0..15.\r
1985 @param AndData The value to AND with the read value from the value.\r
1986 @param OrData The value to OR with the result of the AND operation.\r
1987\r
1988 @return The new 16-bit value.\r
1989\r
1990**/\r
1991UINT16\r
1992EFIAPI\r
1993BitFieldAndThenOr16 (\r
1994 IN UINT16 Operand,\r
1995 IN UINTN StartBit,\r
1996 IN UINTN EndBit,\r
1997 IN UINT16 AndData,\r
1998 IN UINT16 OrData\r
1999 );\r
2000\r
2001/**\r
2002 Returns a bit field from a 32-bit value.\r
2003\r
2004 Returns the bitfield specified by the StartBit and the EndBit from Operand.\r
2005\r
2006 If 32-bit operations are not supported, then ASSERT().\r
2007 If StartBit is greater than 31, then ASSERT().\r
2008 If EndBit is greater than 31, then ASSERT().\r
0ffa1286 2009 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 2010\r
2011 @param Operand Operand on which to perform the bitfield operation.\r
2012 @param StartBit The ordinal of the least significant bit in the bit field.\r
2013 Range 0..31.\r
2014 @param EndBit The ordinal of the most significant bit in the bit field.\r
2015 Range 0..31.\r
2016\r
2017 @return The bit field read.\r
2018\r
2019**/\r
2020UINT32\r
2021EFIAPI\r
2022BitFieldRead32 (\r
2023 IN UINT32 Operand,\r
2024 IN UINTN StartBit,\r
2025 IN UINTN EndBit\r
2026 );\r
2027\r
2028/**\r
2029 Writes a bit field to a 32-bit value, and returns the result.\r
2030\r
2031 Writes Value to the bit field specified by the StartBit and the EndBit in\r
2032 Operand. All other bits in Operand are preserved. The new 32-bit value is\r
2033 returned.\r
2034\r
2035 If 32-bit operations are not supported, then ASSERT().\r
2036 If StartBit is greater than 31, then ASSERT().\r
2037 If EndBit is greater than 31, then ASSERT().\r
0ffa1286 2038 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 2039\r
2040 @param Operand Operand on which to perform the bitfield operation.\r
2041 @param StartBit The ordinal of the least significant bit in the bit field.\r
2042 Range 0..31.\r
2043 @param EndBit The ordinal of the most significant bit in the bit field.\r
2044 Range 0..31.\r
2045 @param Value New value of the bit field.\r
2046\r
2047 @return The new 32-bit value.\r
2048\r
2049**/\r
2050UINT32\r
2051EFIAPI\r
2052BitFieldWrite32 (\r
2053 IN UINT32 Operand,\r
2054 IN UINTN StartBit,\r
2055 IN UINTN EndBit,\r
2056 IN UINT32 Value\r
2057 );\r
2058\r
2059/**\r
2060 Reads a bit field from a 32-bit value, performs a bitwise OR, and returns the\r
2061 result.\r
2062\r
2063 Performs a bitwise inclusive OR between the bit field specified by StartBit\r
2064 and EndBit in Operand and the value specified by OrData. All other bits in\r
2065 Operand are preserved. The new 32-bit value is returned.\r
2066\r
2067 If 32-bit operations are not supported, then ASSERT().\r
2068 If StartBit is greater than 31, then ASSERT().\r
2069 If EndBit is greater than 31, then ASSERT().\r
0ffa1286 2070 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 2071\r
2072 @param Operand Operand on which to perform the bitfield operation.\r
2073 @param StartBit The ordinal of the least significant bit in the bit field.\r
2074 Range 0..31.\r
2075 @param EndBit The ordinal of the most significant bit in the bit field.\r
2076 Range 0..31.\r
2077 @param OrData The value to OR with the read value from the value\r
2078\r
2079 @return The new 32-bit value.\r
2080\r
2081**/\r
2082UINT32\r
2083EFIAPI\r
2084BitFieldOr32 (\r
2085 IN UINT32 Operand,\r
2086 IN UINTN StartBit,\r
2087 IN UINTN EndBit,\r
2088 IN UINT32 OrData\r
2089 );\r
2090\r
2091/**\r
2092 Reads a bit field from a 32-bit value, performs a bitwise AND, and returns\r
2093 the result.\r
2094\r
2095 Performs a bitwise AND between the bit field specified by StartBit and EndBit\r
2096 in Operand and the value specified by AndData. All other bits in Operand are\r
2097 preserved. The new 32-bit value is returned.\r
2098\r
2099 If 32-bit operations are not supported, then ASSERT().\r
2100 If StartBit is greater than 31, then ASSERT().\r
2101 If EndBit is greater than 31, then ASSERT().\r
0ffa1286 2102 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 2103\r
2104 @param Operand Operand on which to perform the bitfield operation.\r
2105 @param StartBit The ordinal of the least significant bit in the bit field.\r
2106 Range 0..31.\r
2107 @param EndBit The ordinal of the most significant bit in the bit field.\r
2108 Range 0..31.\r
2109 @param AndData The value to AND with the read value from the value\r
2110\r
2111 @return The new 32-bit value.\r
2112\r
2113**/\r
2114UINT32\r
2115EFIAPI\r
2116BitFieldAnd32 (\r
2117 IN UINT32 Operand,\r
2118 IN UINTN StartBit,\r
2119 IN UINTN EndBit,\r
2120 IN UINT32 AndData\r
2121 );\r
2122\r
2123/**\r
2124 Reads a bit field from a 32-bit value, performs a bitwise AND followed by a\r
2125 bitwise OR, and returns the result.\r
2126\r
2127 Performs a bitwise AND between the bit field specified by StartBit and EndBit\r
2128 in Operand and the value specified by AndData, followed by a bitwise\r
2129 inclusive OR with value specified by OrData. All other bits in Operand are\r
2130 preserved. The new 32-bit value is returned.\r
2131\r
2132 If 32-bit operations are not supported, then ASSERT().\r
2133 If StartBit is greater than 31, then ASSERT().\r
2134 If EndBit is greater than 31, then ASSERT().\r
0ffa1286 2135 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 2136\r
2137 @param Operand Operand on which to perform the bitfield operation.\r
2138 @param StartBit The ordinal of the least significant bit in the bit field.\r
2139 Range 0..31.\r
2140 @param EndBit The ordinal of the most significant bit in the bit field.\r
2141 Range 0..31.\r
2142 @param AndData The value to AND with the read value from the value.\r
2143 @param OrData The value to OR with the result of the AND operation.\r
2144\r
2145 @return The new 32-bit value.\r
2146\r
2147**/\r
2148UINT32\r
2149EFIAPI\r
2150BitFieldAndThenOr32 (\r
2151 IN UINT32 Operand,\r
2152 IN UINTN StartBit,\r
2153 IN UINTN EndBit,\r
2154 IN UINT32 AndData,\r
2155 IN UINT32 OrData\r
2156 );\r
2157\r
2158/**\r
2159 Returns a bit field from a 64-bit value.\r
2160\r
2161 Returns the bitfield specified by the StartBit and the EndBit from Operand.\r
2162\r
2163 If 64-bit operations are not supported, then ASSERT().\r
2164 If StartBit is greater than 63, then ASSERT().\r
2165 If EndBit is greater than 63, then ASSERT().\r
0ffa1286 2166 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 2167\r
2168 @param Operand Operand on which to perform the bitfield operation.\r
2169 @param StartBit The ordinal of the least significant bit in the bit field.\r
2170 Range 0..63.\r
2171 @param EndBit The ordinal of the most significant bit in the bit field.\r
2172 Range 0..63.\r
2173\r
2174 @return The bit field read.\r
2175\r
2176**/\r
2177UINT64\r
2178EFIAPI\r
2179BitFieldRead64 (\r
2180 IN UINT64 Operand,\r
2181 IN UINTN StartBit,\r
2182 IN UINTN EndBit\r
2183 );\r
2184\r
2185/**\r
2186 Writes a bit field to a 64-bit value, and returns the result.\r
2187\r
2188 Writes Value to the bit field specified by the StartBit and the EndBit in\r
2189 Operand. All other bits in Operand are preserved. The new 64-bit value is\r
2190 returned.\r
2191\r
2192 If 64-bit operations are not supported, then ASSERT().\r
2193 If StartBit is greater than 63, then ASSERT().\r
2194 If EndBit is greater than 63, then ASSERT().\r
0ffa1286 2195 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 2196\r
2197 @param Operand Operand on which to perform the bitfield operation.\r
2198 @param StartBit The ordinal of the least significant bit in the bit field.\r
2199 Range 0..63.\r
2200 @param EndBit The ordinal of the most significant bit in the bit field.\r
2201 Range 0..63.\r
2202 @param Value New value of the bit field.\r
2203\r
2204 @return The new 64-bit value.\r
2205\r
2206**/\r
2207UINT64\r
2208EFIAPI\r
2209BitFieldWrite64 (\r
2210 IN UINT64 Operand,\r
2211 IN UINTN StartBit,\r
2212 IN UINTN EndBit,\r
2213 IN UINT64 Value\r
2214 );\r
2215\r
2216/**\r
2217 Reads a bit field from a 64-bit value, performs a bitwise OR, and returns the\r
2218 result.\r
2219\r
2220 Performs a bitwise inclusive OR between the bit field specified by StartBit\r
2221 and EndBit in Operand and the value specified by OrData. All other bits in\r
2222 Operand are preserved. The new 64-bit value is returned.\r
2223\r
2224 If 64-bit operations are not supported, then ASSERT().\r
2225 If StartBit is greater than 63, then ASSERT().\r
2226 If EndBit is greater than 63, then ASSERT().\r
0ffa1286 2227 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 2228\r
2229 @param Operand Operand on which to perform the bitfield operation.\r
2230 @param StartBit The ordinal of the least significant bit in the bit field.\r
2231 Range 0..63.\r
2232 @param EndBit The ordinal of the most significant bit in the bit field.\r
2233 Range 0..63.\r
2234 @param OrData The value to OR with the read value from the value\r
2235\r
2236 @return The new 64-bit value.\r
2237\r
2238**/\r
2239UINT64\r
2240EFIAPI\r
2241BitFieldOr64 (\r
2242 IN UINT64 Operand,\r
2243 IN UINTN StartBit,\r
2244 IN UINTN EndBit,\r
2245 IN UINT64 OrData\r
2246 );\r
2247\r
2248/**\r
2249 Reads a bit field from a 64-bit value, performs a bitwise AND, and returns\r
2250 the result.\r
2251\r
2252 Performs a bitwise AND between the bit field specified by StartBit and EndBit\r
2253 in Operand and the value specified by AndData. All other bits in Operand are\r
2254 preserved. The new 64-bit value is returned.\r
2255\r
2256 If 64-bit operations are not supported, then ASSERT().\r
2257 If StartBit is greater than 63, then ASSERT().\r
2258 If EndBit is greater than 63, then ASSERT().\r
0ffa1286 2259 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 2260\r
2261 @param Operand Operand on which to perform the bitfield operation.\r
2262 @param StartBit The ordinal of the least significant bit in the bit field.\r
2263 Range 0..63.\r
2264 @param EndBit The ordinal of the most significant bit in the bit field.\r
2265 Range 0..63.\r
2266 @param AndData The value to AND with the read value from the value\r
2267\r
2268 @return The new 64-bit value.\r
2269\r
2270**/\r
2271UINT64\r
2272EFIAPI\r
2273BitFieldAnd64 (\r
2274 IN UINT64 Operand,\r
2275 IN UINTN StartBit,\r
2276 IN UINTN EndBit,\r
2277 IN UINT64 AndData\r
2278 );\r
2279\r
2280/**\r
2281 Reads a bit field from a 64-bit value, performs a bitwise AND followed by a\r
2282 bitwise OR, and returns the result.\r
2283\r
2284 Performs a bitwise AND between the bit field specified by StartBit and EndBit\r
2285 in Operand and the value specified by AndData, followed by a bitwise\r
2286 inclusive OR with value specified by OrData. All other bits in Operand are\r
2287 preserved. The new 64-bit value is returned.\r
2288\r
2289 If 64-bit operations are not supported, then ASSERT().\r
2290 If StartBit is greater than 63, then ASSERT().\r
2291 If EndBit is greater than 63, then ASSERT().\r
0ffa1286 2292 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 2293\r
2294 @param Operand Operand on which to perform the bitfield operation.\r
2295 @param StartBit The ordinal of the least significant bit in the bit field.\r
2296 Range 0..63.\r
2297 @param EndBit The ordinal of the most significant bit in the bit field.\r
2298 Range 0..63.\r
2299 @param AndData The value to AND with the read value from the value.\r
2300 @param OrData The value to OR with the result of the AND operation.\r
2301\r
2302 @return The new 64-bit value.\r
2303\r
2304**/\r
2305UINT64\r
2306EFIAPI\r
2307BitFieldAndThenOr64 (\r
2308 IN UINT64 Operand,\r
2309 IN UINTN StartBit,\r
2310 IN UINTN EndBit,\r
2311 IN UINT64 AndData,\r
2312 IN UINT64 OrData\r
2313 );\r
2314\r
2315//\r
2316// Base Library Synchronization Functions\r
2317//\r
2318\r
2319/**\r
2320 Retrieves the architecture specific spin lock alignment requirements for\r
2321 optimal spin lock performance.\r
2322\r
2323 This function retrieves the spin lock alignment requirements for optimal\r
2324 performance on a given CPU architecture. The spin lock alignment must be a\r
2325 power of two and is returned by this function. If there are no alignment\r
2326 requirements, then 1 must be returned. The spin lock synchronization\r
2327 functions must function correctly if the spin lock size and alignment values\r
2328 returned by this function are not used at all. These values are hints to the\r
2329 consumers of the spin lock synchronization functions to obtain optimal spin\r
2330 lock performance.\r
2331\r
2332 @return The architecture specific spin lock alignment.\r
2333\r
2334**/\r
2335UINTN\r
2336EFIAPI\r
2337GetSpinLockProperties (\r
2338 VOID\r
2339 );\r
2340\r
2341/**\r
2342 Initializes a spin lock to the released state and returns the spin lock.\r
2343\r
2344 This function initializes the spin lock specified by SpinLock to the released\r
2345 state, and returns SpinLock. Optimal performance can be achieved by calling\r
2346 GetSpinLockProperties() to determine the size and alignment requirements for\r
2347 SpinLock.\r
2348\r
2349 If SpinLock is NULL, then ASSERT().\r
2350\r
2351 @param SpinLock A pointer to the spin lock to initialize to the released\r
2352 state.\r
2353\r
2354 @return SpinLock\r
2355\r
2356**/\r
2357SPIN_LOCK *\r
2358EFIAPI\r
2359InitializeSpinLock (\r
2360 IN SPIN_LOCK *SpinLock\r
2361 );\r
2362\r
2363/**\r
2364 Waits until a spin lock can be placed in the acquired state.\r
2365\r
2366 This function checks the state of the spin lock specified by SpinLock. If\r
2367 SpinLock is in the released state, then this function places SpinLock in the\r
2368 acquired state and returns SpinLock. Otherwise, this function waits\r
2369 indefinitely for the spin lock to be released, and then places it in the\r
2370 acquired state and returns SpinLock. All state transitions of SpinLock must\r
2371 be performed using MP safe mechanisms.\r
2372\r
2373 If SpinLock is NULL, then ASSERT().\r
2374 If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().\r
2375 If PcdSpinLockTimeout is not zero, and SpinLock is can not be acquired in\r
2376 PcdSpinLockTimeout microseconds, then ASSERT().\r
2377\r
2378 @param SpinLock A pointer to the spin lock to place in the acquired state.\r
2379\r
2380 @return SpinLock\r
2381\r
2382**/\r
2383SPIN_LOCK *\r
2384EFIAPI\r
2385AcquireSpinLock (\r
2386 IN SPIN_LOCK *SpinLock\r
2387 );\r
2388\r
2389/**\r
2390 Attempts to place a spin lock in the acquired state.\r
2391\r
2392 This function checks the state of the spin lock specified by SpinLock. If\r
2393 SpinLock is in the released state, then this function places SpinLock in the\r
2394 acquired state and returns TRUE. Otherwise, FALSE is returned. All state\r
2395 transitions of SpinLock must be performed using MP safe mechanisms.\r
2396\r
2397 If SpinLock is NULL, then ASSERT().\r
2398 If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().\r
2399\r
2400 @param SpinLock A pointer to the spin lock to place in the acquired state.\r
2401\r
2402 @retval TRUE SpinLock was placed in the acquired state.\r
2403 @retval FALSE SpinLock could not be acquired.\r
2404\r
2405**/\r
2406BOOLEAN\r
2407EFIAPI\r
2408AcquireSpinLockOrFail (\r
2409 IN SPIN_LOCK *SpinLock\r
2410 );\r
2411\r
2412/**\r
2413 Releases a spin lock.\r
2414\r
2415 This function places the spin lock specified by SpinLock in the release state\r
2416 and returns SpinLock.\r
2417\r
2418 If SpinLock is NULL, then ASSERT().\r
2419 If SpinLock was not initialized with InitializeSpinLock(), then ASSERT().\r
2420\r
2421 @param SpinLock A pointer to the spin lock to release.\r
2422\r
2423 @return SpinLock\r
2424\r
2425**/\r
2426SPIN_LOCK *\r
2427EFIAPI\r
2428ReleaseSpinLock (\r
2429 IN SPIN_LOCK *SpinLock\r
2430 );\r
2431\r
2432/**\r
2433 Performs an atomic increment of an 32-bit unsigned integer.\r
2434\r
2435 Performs an atomic increment of the 32-bit unsigned integer specified by\r
2436 Value and returns the incremented value. The increment operation must be\r
2437 performed using MP safe mechanisms. The state of the return value is not\r
2438 guaranteed to be MP safe.\r
2439\r
2440 If Value is NULL, then ASSERT().\r
2441\r
2442 @param Value A pointer to the 32-bit value to increment.\r
2443\r
2444 @return The incremented value.\r
2445\r
2446**/\r
2447UINT32\r
2448EFIAPI\r
2449InterlockedIncrement (\r
2450 IN UINT32 *Value\r
2451 );\r
2452\r
2453/**\r
2454 Performs an atomic decrement of an 32-bit unsigned integer.\r
2455\r
2456 Performs an atomic decrement of the 32-bit unsigned integer specified by\r
2457 Value and returns the decremented value. The decrement operation must be\r
2458 performed using MP safe mechanisms. The state of the return value is not\r
2459 guaranteed to be MP safe.\r
2460\r
2461 If Value is NULL, then ASSERT().\r
2462\r
2463 @param Value A pointer to the 32-bit value to decrement.\r
2464\r
2465 @return The decremented value.\r
2466\r
2467**/\r
2468UINT32\r
2469EFIAPI\r
2470InterlockedDecrement (\r
2471 IN UINT32 *Value\r
2472 );\r
2473\r
2474/**\r
2475 Performs an atomic compare exchange operation on a 32-bit unsigned integer.\r
2476\r
2477 @param Value A pointer to the 32-bit value for the compare exchange\r
2478 operation.\r
2479 @param CompareValue 32-bit value used in compare operation.\r
2480 @param ExchangeValue 32-bit value used in exchange operation.\r
2481\r
2482 @return The original *Value before exchange.\r
2483\r
2484**/\r
2485UINT32\r
2486EFIAPI\r
2487InterlockedCompareExchange32 (\r
0ffa1286 2488 IN OUT UINT32 *Value,\r
878ddf1f 2489 IN UINT32 CompareValue,\r
2490 IN UINT32 ExchangeValue\r
2491 );\r
2492\r
2493/**\r
2494 Performs an atomic compare exchange operation on a 64-bit unsigned integer.\r
2495\r
2496 @param Value A pointer to the 64-bit value for the compare exchange\r
2497 operation.\r
2498 @param CompareValue 64-bit value used in compare operation.\r
2499 @param ExchangeValue 64-bit value used in exchange operation.\r
2500\r
2501 @return The original *Value before exchange.\r
2502\r
2503**/\r
2504UINT64\r
2505EFIAPI\r
2506InterlockedCompareExchange64 (\r
0ffa1286 2507 IN OUT UINT64 *Value,\r
878ddf1f 2508 IN UINT64 CompareValue,\r
2509 IN UINT64 ExchangeValue\r
2510 );\r
2511\r
2512/**\r
2513 Performs an atomic compare exchange operation on a pointer value.\r
2514\r
2515 Performs an atomic compare exchange operation on the pointer value specified\r
2516 by Value. If Value is equal to CompareValue, then Value is set to\r
2517 ExchangeValue and CompareValue is returned. If Value is not equal to\r
2518 CompareValue, then Value is returned. The compare exchange operation must be\r
2519 performed using MP safe mechanisms.\r
2520\r
2521 If Value is NULL, then ASSERT().\r
2522\r
2523 @param Value A pointer to the pointer value for the compare exchange\r
2524 operation.\r
2525 @param CompareValue Pointer value used in compare operation.\r
2526 @param ExchangeValue Pointer value used in exchange operation.\r
2527\r
2528**/\r
2529VOID *\r
2530EFIAPI\r
2531InterlockedCompareExchangePointer (\r
0ffa1286 2532 IN OUT VOID **Value,\r
878ddf1f 2533 IN VOID *CompareValue,\r
2534 IN VOID *ExchangeValue\r
2535 );\r
2536\r
2537//\r
2538// Base Library CPU Functions\r
2539//\r
2540typedef\r
2541VOID\r
2542(EFIAPI *SWITCH_STACK_ENTRY_POINT) (\r
2543 IN VOID *Context1, OPTIONAL\r
2544 IN VOID *Context2 OPTIONAL\r
2545 );\r
2546\r
2547/**\r
2548 Used to serialize load and store operations.\r
2549\r
2550 All loads and stores that proceed calls to this function are guaranteed to be\r
2551 globally visible when this function returns.\r
2552\r
2553**/\r
2554VOID\r
2555EFIAPI\r
2556MemoryFence (\r
2557 VOID\r
2558 );\r
2559\r
2560/**\r
2561 Saves the current CPU context that can be restored with a call to LongJump()\r
2562 and returns 0.\r
2563\r
2564 Saves the current CPU context in the buffer specified by JumpBuffer and\r
2565 returns 0. The initial call to SetJump() must always return 0. Subsequent\r
2566 calls to LongJump() cause a non-zero value to be returned by SetJump().\r
2567\r
2568 If JumpBuffer is NULL, then ASSERT().\r
2569\r
2570 @param JumpBuffer A pointer to CPU context buffer.\r
2571\r
2572 @retval 0 Indicates a return from SetJump().\r
2573\r
2574**/\r
2575UINTN\r
2576EFIAPI\r
2577SetJump (\r
2578 OUT BASE_LIBRARY_JUMP_BUFFER *JumpBuffer\r
2579 );\r
2580\r
2581/**\r
2582 Restores the CPU context that was saved with SetJump().\r
2583\r
2584 Restores the CPU context from the buffer specified by JumpBuffer. This\r
2585 function never returns to the caller. Instead is resumes execution based on\r
2586 the state of JumpBuffer.\r
2587\r
2588 If JumpBuffer is NULL, then ASSERT().\r
2589 If Value is 0, then ASSERT().\r
2590\r
2591 @param JumpBuffer A pointer to CPU context buffer.\r
2592 @param Value The value to return when the SetJump() context is\r
2593 restored and must be non-zero.\r
2594\r
2595**/\r
2596VOID\r
2597EFIAPI\r
2598LongJump (\r
2599 IN BASE_LIBRARY_JUMP_BUFFER *JumpBuffer,\r
2600 IN UINTN Value\r
2601 );\r
2602\r
2603/**\r
2604 Enables CPU interrupts.\r
2605\r
2606 Enables CPU interrupts.\r
2607\r
2608**/\r
2609VOID\r
2610EFIAPI\r
2611EnableInterrupts (\r
2612 VOID\r
2613 );\r
2614\r
2615/**\r
2616 Disables CPU interrupts.\r
2617\r
2618 Disables CPU interrupts.\r
2619\r
2620**/\r
2621VOID\r
2622EFIAPI\r
2623DisableInterrupts (\r
2624 VOID\r
2625 );\r
2626\r
2627/**\r
2628 Disables CPU interrupts and returns the interrupt state prior to the disable\r
2629 operation.\r
2630\r
2631 Disables CPU interrupts and returns the interrupt state prior to the disable\r
2632 operation.\r
2633\r
2634 @retval TRUE CPU interrupts were enabled on entry to this call.\r
2635 @retval FALSE CPU interrupts were disabled on entry to this call.\r
2636\r
2637**/\r
2638BOOLEAN\r
2639EFIAPI\r
2640SaveAndDisableInterrupts (\r
2641 VOID\r
2642 );\r
2643\r
2644/**\r
2645 Enables CPU interrupts for the smallest window required to capture any\r
2646 pending interrupts.\r
2647\r
2648 Enables CPU interrupts for the smallest window required to capture any\r
2649 pending interrupts.\r
2650\r
2651**/\r
2652VOID\r
2653EFIAPI\r
2654EnableDisableInterrupts (\r
2655 VOID\r
2656 );\r
2657\r
2658/**\r
2659 Retrieves the current CPU interrupt state.\r
2660\r
2661 Retrieves the current CPU interrupt state. Returns TRUE is interrupts are\r
2662 currently enabled. Otherwise returns FALSE.\r
2663\r
2664 @retval TRUE CPU interrupts are enabled.\r
2665 @retval FALSE CPU interrupts are disabled.\r
2666\r
2667**/\r
2668BOOLEAN\r
2669EFIAPI\r
2670GetInterruptState (\r
2671 VOID\r
2672 );\r
2673\r
2674/**\r
2675 Set the current CPU interrupt state.\r
2676\r
2677 Sets the current CPU interrupt state to the state specified by\r
2678 InterruptState. If InterruptState is TRUE, then interrupts are enabled. If\r
2679 InterruptState is FALSE, then interrupts are disabled. InterruptState is\r
2680 returned.\r
2681\r
2682 @param InterruptState TRUE if interrupts should enabled. FALSE if\r
2683 interrupts should be disabled.\r
2684\r
2685 @return InterruptState\r
2686\r
2687**/\r
2688BOOLEAN\r
2689EFIAPI\r
2690SetInterruptState (\r
2691 IN BOOLEAN InterruptState\r
2692 );\r
2693\r
2694/**\r
2695 Places the CPU in a sleep state until an interrupt is received.\r
2696\r
2697 Places the CPU in a sleep state until an interrupt is received. If interrupts\r
2698 are disabled prior to calling this function, then the CPU will be placed in a\r
2699 sleep state indefinitely.\r
2700\r
2701**/\r
2702VOID\r
2703EFIAPI\r
2704CpuSleep (\r
2705 VOID\r
2706 );\r
2707\r
2708/**\r
2709 Requests CPU to pause for a short period of time.\r
2710\r
2711 Requests CPU to pause for a short period of time. Typically used in MP\r
2712 systems to prevent memory starvation while waiting for a spin lock.\r
2713\r
2714**/\r
2715VOID\r
2716EFIAPI\r
2717CpuPause (\r
2718 VOID\r
2719 );\r
2720\r
2721/**\r
2722 Flushes all the Translation Lookaside Buffers(TLB) entries in a CPU.\r
2723\r
2724 Flushes all the Translation Lookaside Buffers(TLB) entries in a CPU.\r
2725\r
2726**/\r
2727VOID\r
2728EFIAPI\r
2729CpuFlushTlb (\r
2730 VOID\r
2731 );\r
2732\r
2733/**\r
2734 Transfers control to a function starting with a new stack.\r
2735\r
2736 Transfers control to the function specified by EntryPoint using the new stack\r
2737 specified by NewStack and passing in the parameters specified by Context1 and\r
2738 Context2. Context1 and Context2 are optional and may be NULL. The function\r
2739 EntryPoint must never return.\r
2740\r
2741 If EntryPoint is NULL, then ASSERT().\r
2742 If NewStack is NULL, then ASSERT().\r
2743\r
2744 @param EntryPoint A pointer to function to call with the new stack.\r
2745 @param Context1 A pointer to the context to pass into the EntryPoint\r
2746 function.\r
2747 @param Context2 A pointer to the context to pass into the EntryPoint\r
2748 function.\r
2749 @param NewStack A pointer to the new stack to use for the EntryPoint\r
2750 function.\r
2751\r
2752**/\r
2753VOID\r
2754EFIAPI\r
2755SwitchStack (\r
2756 IN SWITCH_STACK_ENTRY_POINT EntryPoint,\r
2757 IN VOID *Context1, OPTIONAL\r
2758 IN VOID *Context2, OPTIONAL\r
2759 IN VOID *NewStack\r
2760 );\r
2761\r
2762/**\r
2763 Generates a breakpoint on the CPU.\r
2764\r
2765 Generates a breakpoint on the CPU. The breakpoint must be implemented such\r
2766 that code can resume normal execution after the breakpoint.\r
2767\r
2768**/\r
2769VOID\r
2770EFIAPI\r
2771CpuBreakpoint (\r
2772 VOID\r
2773 );\r
2774\r
2775/**\r
2776 Executes an infinite loop.\r
2777\r
2778 Forces the CPU to execute an infinite loop. A debugger may be used to skip\r
2779 past the loop and the code that follows the loop must execute properly. This\r
2780 implies that the infinite loop must not cause the code that follow it to be\r
2781 optimized away.\r
2782\r
2783**/\r
2784VOID\r
2785EFIAPI\r
2786CpuDeadLoop (\r
2787 VOID\r
2788 );\r
2789\r
2790//\r
2791// IA32 and X64 Specific Functions\r
2792//\r
2793//\r
2794// Byte packed structure for 16-bit Real Mode EFLAGS\r
2795//\r
2796typedef union {\r
2797 struct {\r
2798 UINT32 CF:1; // Carry Flag\r
2799 UINT32 Reserved_0:1; // Reserved\r
2800 UINT32 PF:1; // Parity Flag\r
2801 UINT32 Reserved_1:1; // Reserved\r
2802 UINT32 AF:1; // Auxiliary Carry Flag\r
2803 UINT32 Reserved_2:1; // Reserved\r
2804 UINT32 ZF:1; // Zero Flag\r
2805 UINT32 SF:1; // Sign Flag\r
2806 UINT32 TF:1; // Trap Flag\r
2807 UINT32 IF:1; // Interrupt Enable Flag\r
2808 UINT32 DF:1; // Direction Flag\r
2809 UINT32 OF:1; // Overflow Flag\r
2810 UINT32 IOPL:2; // I/O Privilege Level\r
2811 UINT32 NT:1; // Nested Task\r
2812 UINT32 Reserved_3:1; // Reserved\r
2813 } Bits;\r
2814 UINT16 Uint16;\r
2815} IA32_FLAGS16;\r
2816\r
2817//\r
2818// Byte packed structure for EFLAGS/RFLAGS\r
2819// 32-bits on IA-32\r
2820// 64-bits on X64. The upper 32-bits on X64 are reserved\r
2821//\r
2822typedef union {\r
2823 struct {\r
2824 UINT32 CF:1; // Carry Flag\r
2825 UINT32 Reserved_0:1; // Reserved\r
2826 UINT32 PF:1; // Parity Flag\r
2827 UINT32 Reserved_1:1; // Reserved\r
2828 UINT32 AF:1; // Auxiliary Carry Flag\r
2829 UINT32 Reserved_2:1; // Reserved\r
2830 UINT32 ZF:1; // Zero Flag\r
2831 UINT32 SF:1; // Sign Flag\r
2832 UINT32 TF:1; // Trap Flag\r
2833 UINT32 IF:1; // Interrupt Enable Flag\r
2834 UINT32 DF:1; // Direction Flag\r
2835 UINT32 OF:1; // Overflow Flag\r
2836 UINT32 IOPL:2; // I/O Privilege Level\r
2837 UINT32 NT:1; // Nested Task\r
2838 UINT32 Reserved_3:1; // Reserved\r
2839 UINT32 RF:1; // Resume Flag\r
2840 UINT32 VM:1; // Virtual 8086 Mode\r
2841 UINT32 AC:1; // Alignment Check\r
2842 UINT32 VIF:1; // Virtual Interrupt Flag\r
2843 UINT32 VIP:1; // Virtual Interrupt Pending\r
2844 UINT32 ID:1; // ID Flag\r
2845 UINT32 Reserved_4:10; // Reserved\r
2846 } Bits;\r
2847 UINTN UintN;\r
2848} IA32_EFLAGS32;\r
2849\r
2850//\r
2851// Byte packed structure for Control Register 0 (CR0)\r
2852// 32-bits on IA-32\r
2853// 64-bits on X64. The upper 32-bits on X64 are reserved\r
2854//\r
2855typedef union {\r
2856 struct {\r
2857 UINT32 PE:1; // Protection Enable\r
2858 UINT32 MP:1; // Monitor Coprocessor\r
2859 UINT32 EM:1; // Emulation\r
2860 UINT32 TS:1; // Task Switched\r
2861 UINT32 ET:1; // Extension Type\r
2862 UINT32 NE:1; // Numeric Error\r
2863 UINT32 Reserved_0:10; // Reserved\r
2864 UINT32 WP:1; // Write Protect\r
2865 UINT32 Reserved_1:1; // Reserved\r
2866 UINT32 AM:1; // Alignment Mask\r
2867 UINT32 Reserved_2:10; // Reserved\r
2868 UINT32 NW:1; // Mot Write-through\r
2869 UINT32 CD:1; // Cache Disable\r
2870 UINT32 PG:1; // Paging\r
2871 } Bits;\r
2872 UINTN UintN;\r
2873} IA32_CR0;\r
2874\r
2875//\r
2876// Byte packed structure for Control Register 4 (CR4)\r
2877// 32-bits on IA-32\r
2878// 64-bits on X64. The upper 32-bits on X64 are reserved\r
2879//\r
2880typedef union {\r
2881 struct {\r
2882 UINT32 VME:1; // Virtual-8086 Mode Extensions\r
2883 UINT32 PVI:1; // Protected-Mode Virtual Interrupts\r
2884 UINT32 TSD:1; // Time Stamp Disable\r
2885 UINT32 DE:1; // Debugging Extensions\r
2886 UINT32 PSE:1; // Page Size Extensions\r
2887 UINT32 PAE:1; // Physical Address Extension\r
2888 UINT32 MCE:1; // Machine Check Enable\r
2889 UINT32 PGE:1; // Page Global Enable\r
2890 UINT32 PCE:1; // Performance Monitoring Counter\r
2891 // Enable\r
2892 UINT32 OSFXSR:1; // Operating System Support for\r
2893 // FXSAVE and FXRSTOR instructions\r
2894 UINT32 OSXMMEXCPT:1; // Operating System Support for\r
2895 // Unmasked SIMD Floating Point\r
2896 // Exceptions\r
2897 UINT32 Reserved_0:2; // Reserved\r
2898 UINT32 VMXE:1; // VMX Enable\r
2899 UINT32 Reserved_1:18; // Reseved\r
2900 } Bits;\r
2901 UINTN UintN;\r
2902} IA32_CR4;\r
2903\r
2904//\r
2905// Byte packed structure for an IDTR, GDTR, LDTR descriptor\r
4cbd2175 2906/// @bug How to make this structure byte-packed in a compiler independent way?\r
878ddf1f 2907//\r
2908typedef struct {\r
2909 UINT16 Limit;\r
2910 UINTN Base;\r
2911} IA32_DESCRIPTOR;\r
2912\r
2913#define IA32_IDT_GATE_TYPE_TASK 0x85\r
2914#define IA32_IDT_GATE_TYPE_INTERRUPT_16 0x86\r
2915#define IA32_IDT_GATE_TYPE_TRAP_16 0x87\r
2916#define IA32_IDT_GATE_TYPE_INTERRUPT_32 0x8E\r
2917#define IA32_IDT_GATE_TYPE_TRAP_32 0x8F\r
2918\r
2919//\r
2920// Byte packed structure for an Interrupt Gate Descriptor\r
2921//\r
2922typedef union {\r
2923 struct {\r
2924 UINT32 OffsetLow:16; // Offset bits 15..0\r
2925 UINT32 Selector:16; // Selector\r
2926 UINT32 Reserved_0:8; // Reserved\r
2927 UINT32 GateType:8; // Gate Type. See #defines above\r
2928 UINT32 OffsetHigh:16; // Offset bits 31..16\r
2929 } Bits;\r
2930 UINT64 Uint64;\r
2931} IA32_IDT_GATE_DESCRIPTOR;\r
2932\r
2933//\r
2934// Byte packed structure for an FP/SSE/SSE2 context\r
2935//\r
2936typedef struct {\r
2937 UINT8 Buffer[512];\r
2938} IA32_FX_BUFFER;\r
2939\r
2940//\r
2941// Structures for the 16-bit real mode thunks\r
2942//\r
2943typedef struct {\r
2944 UINT32 Reserved1;\r
2945 UINT32 Reserved2;\r
2946 UINT32 Reserved3;\r
2947 UINT32 Reserved4;\r
2948 UINT8 BL;\r
2949 UINT8 BH;\r
2950 UINT16 Reserved5;\r
2951 UINT8 DL;\r
2952 UINT8 DH;\r
2953 UINT16 Reserved6;\r
2954 UINT8 CL;\r
2955 UINT8 CH;\r
2956 UINT16 Reserved7;\r
2957 UINT8 AL;\r
2958 UINT8 AH;\r
2959 UINT16 Reserved8;\r
2960} IA32_BYTE_REGS;\r
2961\r
2962typedef struct {\r
2963 UINT16 DI;\r
2964 UINT16 Reserved1;\r
2965 UINT16 SI;\r
2966 UINT16 Reserved2;\r
2967 UINT16 BP;\r
2968 UINT16 Reserved3;\r
2969 UINT16 SP;\r
2970 UINT16 Reserved4;\r
2971 UINT16 BX;\r
2972 UINT16 Reserved5;\r
2973 UINT16 DX;\r
2974 UINT16 Reserved6;\r
2975 UINT16 CX;\r
2976 UINT16 Reserved7;\r
2977 UINT16 AX;\r
2978 UINT16 Reserved8;\r
2979} IA32_WORD_REGS;\r
2980\r
2981typedef struct {\r
2982 UINT32 EDI;\r
2983 UINT32 ESI;\r
2984 UINT32 EBP;\r
2985 UINT32 ESP;\r
2986 UINT32 EBX;\r
2987 UINT32 EDX;\r
2988 UINT32 ECX;\r
2989 UINT32 EAX;\r
2990 UINT16 DS;\r
2991 UINT16 ES;\r
2992 UINT16 FS;\r
2993 UINT16 GS;\r
2994 IA32_EFLAGS32 EFLAGS;\r
2995 UINT32 Eip;\r
2996 UINT16 CS;\r
2997 UINT16 SS;\r
2998} IA32_DWORD_REGS;\r
2999\r
3000typedef union {\r
3001 IA32_DWORD_REGS E;\r
3002 IA32_WORD_REGS X;\r
3003 IA32_BYTE_REGS H;\r
3004} IA32_REGISTER_SET;\r
3005\r
3006//\r
3007// Byte packed structure for an 16-bit real mode thunks\r
3008//\r
3009typedef struct {\r
97d92bda 3010 IA32_REGISTER_SET *RealModeState;\r
878ddf1f 3011 VOID *RealModeBuffer;\r
97d92bda 3012 UINT32 RealModeBufferSize;\r
3013 UINT32 ThunkAttributes;\r
878ddf1f 3014} THUNK_CONTEXT;\r
3015\r
97d92bda 3016#define THUNK_ATTRIBUTE_BIG_REAL_MODE 0x00000001\r
3017#define THUNK_ATTRIBUTE_DISABLE_A20_MASK_INT_15 0x00000002\r
3018#define THUNK_ATTRIBUTE_DISABLE_A20_MASK_KBD_CTRL 0x00000004\r
3019\r
878ddf1f 3020/**\r
3021 Retrieves CPUID information.\r
3022\r
3023 Executes the CPUID instruction with EAX set to the value specified by Index.\r
3024 This function always returns Index.\r
3025 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.\r
3026 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.\r
3027 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.\r
3028 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.\r
3029 This function is only available on IA-32 and X64.\r
3030\r
3031 @param Index The 32-bit value to load into EAX prior to invoking the CPUID\r
3032 instruction.\r
3033 @param Eax Pointer to the 32-bit EAX value returned by the CPUID\r
3034 instruction. This is an optional parameter that may be NULL.\r
3035 @param Ebx Pointer to the 32-bit EBX value returned by the CPUID\r
3036 instruction. This is an optional parameter that may be NULL.\r
3037 @param Ecx Pointer to the 32-bit ECX value returned by the CPUID\r
3038 instruction. This is an optional parameter that may be NULL.\r
3039 @param Edx Pointer to the 32-bit EDX value returned by the CPUID\r
3040 instruction. This is an optional parameter that may be NULL.\r
3041\r
3042 @return Index\r
3043\r
3044**/\r
3045UINT32\r
3046EFIAPI\r
3047AsmCpuid (\r
3048 IN UINT32 Index,\r
3049 OUT UINT32 *Eax, OPTIONAL\r
3050 OUT UINT32 *Ebx, OPTIONAL\r
3051 OUT UINT32 *Ecx, OPTIONAL\r
3052 OUT UINT32 *Edx OPTIONAL\r
3053 );\r
3054\r
dee4740a 3055/**\r
3056 Retrieves CPUID information using an extended leaf identifier.\r
3057\r
3058 Executes the CPUID instruction with EAX set to the value specified by Index\r
3059 and ECX set to the value specified by SubIndex. This function always returns\r
3060 Index. This function is only available on IA-32 and x64.\r
3061\r
3062 If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.\r
3063 If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.\r
3064 If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.\r
3065 If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.\r
3066\r
3067 @param Index The 32-bit value to load into EAX prior to invoking the\r
3068 CPUID instruction.\r
3069 @param SubIndex The 32-bit value to load into ECX prior to invoking the\r
3070 CPUID instruction.\r
3071 @param Eax Pointer to the 32-bit EAX value returned by the CPUID\r
3072 instruction. This is an optional parameter that may be\r
3073 NULL.\r
3074 @param Ebx Pointer to the 32-bit EBX value returned by the CPUID\r
3075 instruction. This is an optional parameter that may be\r
3076 NULL.\r
3077 @param Ecx Pointer to the 32-bit ECX value returned by the CPUID\r
3078 instruction. This is an optional parameter that may be\r
3079 NULL.\r
3080 @param Edx Pointer to the 32-bit EDX value returned by the CPUID\r
3081 instruction. This is an optional parameter that may be\r
3082 NULL.\r
3083\r
3084 @return Index\r
3085\r
3086**/\r
3087UINT32\r
3088EFIAPI\r
3089AsmCpuidEx (\r
3090 IN UINT32 Index,\r
3091 IN UINT32 SubIndex,\r
3092 OUT UINT32 *Eax, OPTIONAL\r
3093 OUT UINT32 *Ebx, OPTIONAL\r
3094 OUT UINT32 *Ecx, OPTIONAL\r
3095 OUT UINT32 *Edx OPTIONAL\r
3096 );\r
3097\r
878ddf1f 3098/**\r
3099 Returns the lower 32-bits of a Machine Specific Register(MSR).\r
3100\r
3101 Reads and returns the lower 32-bits of the MSR specified by Index.\r
3102 No parameter checking is performed on Index, and some Index values may cause\r
3103 CPU exceptions. The caller must either guarantee that Index is valid, or the\r
3104 caller must set up exception handlers to catch the exceptions. This function\r
3105 is only available on IA-32 and X64.\r
3106\r
3107 @param Index The 32-bit MSR index to read.\r
3108\r
3109 @return The lower 32 bits of the MSR identified by Index.\r
3110\r
3111**/\r
3112UINT32\r
3113EFIAPI\r
3114AsmReadMsr32 (\r
3115 IN UINT32 Index\r
3116 );\r
3117\r
3118/**\r
3119 Zero-extend a 32-bit value and writes it to a Machine Specific Register(MSR).\r
3120\r
3121 Writes the 32-bit value specified by Value to the MSR specified by Index. The\r
3122 upper 32-bits of the MSR write are set to zero. The 32-bit value written to\r
3123 the MSR is returned. No parameter checking is performed on Index or Value,\r
3124 and some of these may cause CPU exceptions. The caller must either guarantee\r
3125 that Index and Value are valid, or the caller must establish proper exception\r
3126 handlers. This function is only available on IA-32 and X64.\r
3127\r
3128 @param Index The 32-bit MSR index to write.\r
3129 @param Value The 32-bit value to write to the MSR.\r
3130\r
3131 @return Value\r
3132\r
3133**/\r
3134UINT32\r
3135EFIAPI\r
3136AsmWriteMsr32 (\r
3137 IN UINT32 Index,\r
3138 IN UINT32 Value\r
3139 );\r
3140\r
3141/**\r
3142 Reads a 64-bit MSR, performs a bitwise inclusive OR on the lower 32-bits, and\r
3143 writes the result back to the 64-bit MSR.\r
3144\r
3145 Reads the 64-bit MSR specified by Index, performs a bitwise inclusive OR\r
3146 between the lower 32-bits of the read result and the value specified by\r
3147 OrData, and writes the result to the 64-bit MSR specified by Index. The lower\r
3148 32-bits of the value written to the MSR is returned. No parameter checking is\r
3149 performed on Index or OrData, and some of these may cause CPU exceptions. The\r
3150 caller must either guarantee that Index and OrData are valid, or the caller\r
3151 must establish proper exception handlers. This function is only available on\r
3152 IA-32 and X64.\r
3153\r
3154 @param Index The 32-bit MSR index to write.\r
3155 @param OrData The value to OR with the read value from the MSR.\r
3156\r
3157 @return The lower 32-bit value written to the MSR.\r
3158\r
3159**/\r
3160UINT32\r
3161EFIAPI\r
3162AsmMsrOr32 (\r
3163 IN UINT32 Index,\r
3164 IN UINT32 OrData\r
3165 );\r
3166\r
3167/**\r
3168 Reads a 64-bit MSR, performs a bitwise AND on the lower 32-bits, and writes\r
3169 the result back to the 64-bit MSR.\r
3170\r
3171 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the\r
3172 lower 32-bits of the read result and the value specified by AndData, and\r
3173 writes the result to the 64-bit MSR specified by Index. The lower 32-bits of\r
3174 the value written to the MSR is returned. No parameter checking is performed\r
3175 on Index or AndData, and some of these may cause CPU exceptions. The caller\r
3176 must either guarantee that Index and AndData are valid, or the caller must\r
3177 establish proper exception handlers. This function is only available on IA-32\r
3178 and X64.\r
3179\r
3180 @param Index The 32-bit MSR index to write.\r
3181 @param AndData The value to AND with the read value from the MSR.\r
3182\r
3183 @return The lower 32-bit value written to the MSR.\r
3184\r
3185**/\r
3186UINT32\r
3187EFIAPI\r
3188AsmMsrAnd32 (\r
3189 IN UINT32 Index,\r
3190 IN UINT32 AndData\r
3191 );\r
3192\r
3193/**\r
3194 Reads a 64-bit MSR, performs a bitwise AND followed by a bitwise inclusive OR\r
3195 on the lower 32-bits, and writes the result back to the 64-bit MSR.\r
3196\r
3197 Reads the 64-bit MSR specified by Index, performs a bitwise AND between the\r
3198 lower 32-bits of the read result and the value specified by AndData\r
3199 preserving the upper 32-bits, performs a bitwise inclusive OR between the\r
3200 result of the AND operation and the value specified by OrData, and writes the\r
3201 result to the 64-bit MSR specified by Address. The lower 32-bits of the value\r
3202 written to the MSR is returned. No parameter checking is performed on Index,\r
3203 AndData, or OrData, and some of these may cause CPU exceptions. The caller\r
3204 must either guarantee that Index, AndData, and OrData are valid, or the\r
3205 caller must establish proper exception handlers. This function is only\r
3206 available on IA-32 and X64.\r
3207\r
3208 @param Index The 32-bit MSR index to write.\r
3209 @param AndData The value to AND with the read value from the MSR.\r
3210 @param OrData The value to OR with the result of the AND operation.\r
3211\r
3212 @return The lower 32-bit value written to the MSR.\r
3213\r
3214**/\r
3215UINT32\r
3216EFIAPI\r
3217AsmMsrAndThenOr32 (\r
3218 IN UINT32 Index,\r
3219 IN UINT32 AndData,\r
3220 IN UINT32 OrData\r
3221 );\r
3222\r
3223/**\r
3224 Reads a bit field of an MSR.\r
3225\r
3226 Reads the bit field in the lower 32-bits of a 64-bit MSR. The bit field is\r
3227 specified by the StartBit and the EndBit. The value of the bit field is\r
3228 returned. The caller must either guarantee that Index is valid, or the caller\r
3229 must set up exception handlers to catch the exceptions. This function is only\r
3230 available on IA-32 and X64.\r
3231\r
3232 If StartBit is greater than 31, then ASSERT().\r
3233 If EndBit is greater than 31, then ASSERT().\r
0ffa1286 3234 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 3235\r
3236 @param Index The 32-bit MSR index to read.\r
3237 @param StartBit The ordinal of the least significant bit in the bit field.\r
3238 Range 0..31.\r
3239 @param EndBit The ordinal of the most significant bit in the bit field.\r
3240 Range 0..31.\r
3241\r
3242 @return The bit field read from the MSR.\r
3243\r
3244**/\r
3245UINT32\r
3246EFIAPI\r
3247AsmMsrBitFieldRead32 (\r
3248 IN UINT32 Index,\r
3249 IN UINTN StartBit,\r
3250 IN UINTN EndBit\r
3251 );\r
3252\r
3253/**\r
3254 Writes a bit field to an MSR.\r
3255\r
3256 Writes Value to a bit field in the lower 32-bits of a 64-bit MSR. The bit\r
3257 field is specified by the StartBit and the EndBit. All other bits in the\r
3258 destination MSR are preserved. The lower 32-bits of the MSR written is\r
3259 returned. Extra left bits in Value are stripped. The caller must either\r
3260 guarantee that Index and the data written is valid, or the caller must set up\r
3261 exception handlers to catch the exceptions. This function is only available\r
3262 on IA-32 and X64.\r
3263\r
3264 If StartBit is greater than 31, then ASSERT().\r
3265 If EndBit is greater than 31, then ASSERT().\r
0ffa1286 3266 If EndBit is less than StartBit, then ASSERT().\r
878ddf1f 3267\r
3268 @param Index The 32-bit MSR index to write.\r
3269 @param StartBit The ordinal of the least significant bit in the bit field.\r
3270 Range 0..31.\r
3271 @param EndBit The ordinal of the most significant bit in the bit field.\r
3272 Range 0..31.\r
3273 @param Value New value of the bit field.\r
3274\r
3275 @return The lower 32-bit of the value written to the MSR.\r
3276\r
3277**/\r
3278UINT32\r
3279EFIAPI\r
3280AsmMsrBitFieldWrite32 (\r
3281 IN UINT32 Index,\r
3282 IN UINTN StartBit,\r
3283 IN UINTN EndBit,\r
3284 IN UINT32 Value\r
3285 );\r
3286\r
3287/**\r
3288 Reads a bit field in a 64-bit MSR, performs a bitwise OR, and writes the\r
3289 result back to the bit field in the 64-bit MSR.\r
3290\r
3291 Reads the 64-bit MSR specified by Index, performs a bitwise inclusive OR\r
3292 between the read result and the value specified by OrData, and writes the\r