MdePkg/Library/BaseLib/BaseLibInternals.h

   1 /** @file
   2   Declaration of internal functions in BaseLib.
   3
   4   Copyright (c) 2006, Intel Corporation<BR>
   5   All rights reserved. This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13   Module Name:  BaseLibInternals.h
  14
  15 **/
  16
  17 #ifndef __BASE_LIB_INTERNALS__
  18 #define __BASE_LIB_INTERNALS__
  19
  20 //
  21 // Math functions
  22 //
  23
  24 /**
  25   Shifts a 64-bit integer left between 0 and 63 bits. The low bits
  26   are filled with zeros. The shifted value is returned.
  27
  28   This function shifts the 64-bit value Operand to the left by Count bits. The
  29   low Count bits are set to zero. The shifted value is returned.
  30
  31   @param  Operand The 64-bit operand to shift left.
  32   @param  Count   The number of bits to shift left.
  33
  34   @return Operand << Count
  35
  36 **/
  37 UINT64
  38 EFIAPI
  39 InternalMathLShiftU64 (
  40   IN      UINT64                    Operand,
  41   IN      UINTN                     Count
  42   );
  43
  44 /**
  45   Shifts a 64-bit integer right between 0 and 63 bits. This high bits
  46   are filled with zeros. The shifted value is returned.
  47
  48   This function shifts the 64-bit value Operand to the right by Count bits. The
  49   high Count bits are set to zero. The shifted value is returned.
  50
  51   @param  Operand The 64-bit operand to shift right.
  52   @param  Count   The number of bits to shift right.
  53
  54   @return Operand >> Count
  55
  56 **/
  57 UINT64
  58 EFIAPI
  59 InternalMathRShiftU64 (
  60   IN      UINT64                    Operand,
  61   IN      UINTN                     Count
  62   );
  63
  64 /**
  65   Shifts a 64-bit integer right between 0 and 63 bits. The high bits
  66   are filled with original integer's bit 63. The shifted value is returned.
  67
  68   This function shifts the 64-bit value Operand to the right by Count bits. The
  69   high Count bits are set to bit 63 of Operand.  The shifted value is returned.
  70
  71   @param  Operand The 64-bit operand to shift right.
  72   @param  Count   The number of bits to shift right.
  73
  74   @return Operand arithmetically shifted right by Count
  75
  76 **/
  77 UINT64
  78 EFIAPI
  79 InternalMathARShiftU64 (
  80   IN      UINT64                    Operand,
  81   IN      UINTN                     Count
  82   );
  83
  84 /**
  85   Rotates a 64-bit integer left between 0 and 63 bits, filling
  86   the low bits with the high bits that were rotated.
  87
  88   This function rotates the 64-bit value Operand to the left by Count bits. The
  89   low Count bits are fill with the high Count bits of Operand. The rotated
  90   value is returned.
  91
  92   @param  Operand The 64-bit operand to rotate left.
  93   @param  Count   The number of bits to rotate left.
  94
  95   @return Operand <<< Count
  96
  97 **/
  98 UINT64
  99 EFIAPI
 100 InternalMathLRotU64 (
 101   IN      UINT64                    Operand,
 102   IN      UINTN                     Count
 103   );
 104
 105 /**
 106   Rotates a 64-bit integer right between 0 and 63 bits, filling
 107   the high bits with the high low bits that were rotated.
 108
 109   This function rotates the 64-bit value Operand to the right by Count bits.
 110   The high Count bits are fill with the low Count bits of Operand. The rotated
 111   value is returned.
 112
 113   @param  Operand The 64-bit operand to rotate right.
 114   @param  Count   The number of bits to rotate right.
 115
 116   @return Operand >>> Count
 117
 118 **/
 119 UINT64
 120 EFIAPI
 121 InternalMathRRotU64 (
 122   IN      UINT64                    Operand,
 123   IN      UINTN                     Count
 124   );
 125
 126 /**
 127   Switches the endianess of a 64-bit integer.
 128
 129   This function swaps the bytes in a 64-bit unsigned value to switch the value
 130   from little endian to big endian or vice versa. The byte swapped value is
 131   returned.
 132
 133   @param  Operand A 64-bit unsigned value.
 134
 135   @return The byte swaped Operand.
 136
 137 **/
 138 UINT64
 139 EFIAPI
 140 InternalMathSwapBytes64 (
 141   IN      UINT64                    Operand
 142   );
 143
 144 /**
 145   Multiples a 64-bit unsigned integer by a 32-bit unsigned integer
 146   and generates a 64-bit unsigned result.
 147
 148   This function multiples the 64-bit unsigned value Multiplicand by the 32-bit
 149   unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
 150   bit unsigned result is returned.
 151
 152   @param  Multiplicand  A 64-bit unsigned value.
 153   @param  Multiplier    A 32-bit unsigned value.
 154
 155   @return Multiplicand * Multiplier
 156
 157 **/
 158 UINT64
 159 EFIAPI
 160 InternalMathMultU64x32 (
 161   IN      UINT64                    Multiplicand,
 162   IN      UINT32                    Multiplier
 163   );
 164
 165 /**
 166   Multiples a 64-bit unsigned integer by a 64-bit unsigned integer
 167   and generates a 64-bit unsigned result.
 168
 169   This function multiples the 64-bit unsigned value Multiplicand by the 64-bit
 170   unsigned value Multiplier and generates a 64-bit unsigned result. This 64-
 171   bit unsigned result is returned.
 172
 173   @param  Multiplicand  A 64-bit unsigned value.
 174   @param  Multiplier    A 64-bit unsigned value.
 175
 176   @return Multiplicand * Multiplier
 177
 178 **/
 179 UINT64
 180 EFIAPI
 181 InternalMathMultU64x64 (
 182   IN      UINT64                    Multiplicand,
 183   IN      UINT64                    Multiplier
 184   );
 185
 186 /**
 187   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
 188   generates a 64-bit unsigned result.
 189
 190   This function divides the 64-bit unsigned value Dividend by the 32-bit
 191   unsigned value Divisor and generates a 64-bit unsigned quotient. This
 192   function returns the 64-bit unsigned quotient.
 193
 194    @param  Dividend  A 64-bit unsigned value.
 195   @param  Divisor   A 32-bit unsigned value.
 196
 197   @return Dividend / Divisor
 198
 199 **/
 200 UINT64
 201 EFIAPI
 202 InternalMathDivU64x32 (
 203   IN      UINT64                    Dividend,
 204   IN      UINT32                    Divisor
 205   );
 206
 207 /**
 208   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
 209   generates a 32-bit unsigned remainder.
 210
 211   This function divides the 64-bit unsigned value Dividend by the 32-bit
 212   unsigned value Divisor and generates a 32-bit remainder. This function
 213   returns the 32-bit unsigned remainder.
 214
 215   @param  Dividend  A 64-bit unsigned value.
 216   @param  Divisor   A 32-bit unsigned value.
 217
 218   @return Dividend % Divisor
 219
 220 **/
 221 UINT32
 222 EFIAPI
 223 InternalMathModU64x32 (
 224   IN      UINT64                    Dividend,
 225   IN      UINT32                    Divisor
 226   );
 227
 228 /**
 229   Divides a 64-bit unsigned integer by a 32-bit unsigned integer and
 230   generates a 64-bit unsigned result and an optional 32-bit unsigned remainder.
 231
 232   This function divides the 64-bit unsigned value Dividend by the 32-bit
 233   unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
 234   is not NULL, then the 32-bit unsigned remainder is returned in Remainder.
 235   This function returns the 64-bit unsigned quotient.
 236
 237   @param  Dividend  A 64-bit unsigned value.
 238   @param  Divisor   A 32-bit unsigned value.
 239   @param  Remainder A pointer to a 32-bit unsigned value. This parameter is
 240                     optional and may be NULL.
 241
 242   @return Dividend / Divisor
 243
 244 **/
 245 UINT64
 246 EFIAPI
 247 InternalMathDivRemU64x32 (
 248   IN      UINT64                    Dividend,
 249   IN      UINT32                    Divisor,
 250   OUT     UINT32                    *Remainder
 251   );
 252
 253 /**
 254   Divides a 64-bit unsigned integer by a 64-bit unsigned integer and
 255   generates a 64-bit unsigned result and an optional 64-bit unsigned remainder.
 256
 257   This function divides the 64-bit unsigned value Dividend by the 64-bit
 258   unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
 259   is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
 260   This function returns the 64-bit unsigned quotient.
 261
 262   @param  Dividend  A 64-bit unsigned value.
 263   @param  Divisor   A 64-bit unsigned value.
 264   @param  Remainder A pointer to a 64-bit unsigned value. This parameter is
 265                     optional and may be NULL.
 266
 267   @return Dividend / Divisor
 268
 269 **/
 270 UINT64
 271 EFIAPI
 272 InternalMathDivRemU64x64 (
 273   IN      UINT64                    Dividend,
 274   IN      UINT64                    Divisor,
 275   OUT     UINT64                    *Remainder
 276   );
 277
 278 /**
 279   Divides a 64-bit signed integer by a 64-bit signed integer and
 280   generates a  64-bit signed result and a optional 64-bit signed remainder.
 281
 282   This function divides the 64-bit unsigned value Dividend by the 64-bit
 283   unsigned value Divisor and generates a 64-bit unsigned quotient. If Remainder
 284   is not NULL, then the 64-bit unsigned remainder is returned in Remainder.
 285   This function returns the 64-bit unsigned quotient.
 286
 287   @param  Dividend  A 64-bit signed value.
 288   @param  Divisor   A 64-bit signed value.
 289   @param  Remainder A pointer to a 64-bit signed value. This parameter is
 290                     optional and may be NULL.
 291
 292   @return Dividend / Divisor
 293
 294 **/
 295 INT64
 296 InternalMathDivRemS64x64 (
 297   IN      INT64                     Dividend,
 298   IN      INT64                     Divisor,
 299   OUT     INT64                     *Remainder  OPTIONAL
 300  );
 301
 302 /**
 303   Transfers control to a function starting with a new stack.
 304
 305   Transfers control to the function specified by EntryPoint using the new stack
 306   specified by NewStack and passing in the parameters specified by Context1 and
 307   Context2. Context1 and Context2 are optional and may be NULL. The function
 308   EntryPoint must never return.
 309
 310   @param  EntryPoint  A pointer to function to call with the new stack.
 311   @param  Context1    A pointer to the context to pass into the EntryPoint
 312                       function.
 313   @param  Context2    A pointer to the context to pass into the EntryPoint
 314                       function.
 315   @param  NewStack    A pointer to the new stack to use for the EntryPoint
 316                       function.
 317
 318 **/
 319 VOID
 320 EFIAPI
 321 InternalSwitchStack (
 322   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
 323   IN      VOID                      *Context1,
 324   IN      VOID                      *Context2,
 325   IN      VOID                      *NewStack
 326   );
 327
 328 //
 329 // Ia32 and x64 specific functions
 330 //
 331
 332 /**
 333   Reads the current Global Descriptor Table Register(GDTR) descriptor.
 334
 335   Reads and returns the current GDTR descriptor and returns it in Gdtr. This
 336   function is only available on IA-32 and X64.
 337
 338   @param  Gdtr  Pointer to a GDTR descriptor.
 339
 340 **/
 341 VOID
 342 EFIAPI
 343 InternalX86ReadGdtr (
 344   OUT     IA32_DESCRIPTOR           *Gdtr
 345   );
 346
 347 /**
 348   Writes the current Global Descriptor Table Register (GDTR) descriptor.
 349
 350   Writes and the current GDTR descriptor specified by Gdtr. This function is
 351   only available on IA-32 and X64.
 352
 353   @param  Gdtr  Pointer to a GDTR descriptor.
 354
 355 **/
 356 VOID
 357 EFIAPI
 358 InternalX86WriteGdtr (
 359   IN      CONST IA32_DESCRIPTOR     *Gdtr
 360   );
 361
 362 /**
 363   Reads the current Interrupt Descriptor Table Register(GDTR) descriptor.
 364
 365   Reads and returns the current IDTR descriptor and returns it in Idtr. This
 366   function is only available on IA-32 and X64.
 367
 368   @param  Idtr  Pointer to a IDTR descriptor.
 369
 370 **/
 371 VOID
 372 EFIAPI
 373 InternalX86ReadIdtr (
 374   OUT     IA32_DESCRIPTOR           *Idtr
 375   );
 376
 377 /**
 378   Writes the current Interrupt Descriptor Table Register(GDTR) descriptor.
 379
 380   Writes the current IDTR descriptor and returns it in Idtr. This function is
 381   only available on IA-32 and X64.
 382
 383   @param  Idtr  Pointer to a IDTR descriptor.
 384
 385 **/
 386 VOID
 387 EFIAPI
 388 InternalX86WriteIdtr (
 389   IN      CONST IA32_DESCRIPTOR     *Idtr
 390   );
 391
 392 /**
 393   Save the current floating point/SSE/SSE2 context to a buffer.
 394
 395   Saves the current floating point/SSE/SSE2 state to the buffer specified by
 396   Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
 397   available on IA-32 and X64.
 398
 399   @param  Buffer  Pointer to a buffer to save the floating point/SSE/SSE2 context.
 400
 401 **/
 402 VOID
 403 EFIAPI
 404 InternalX86FxSave (
 405   OUT     IA32_FX_BUFFER            *Buffer
 406   );
 407
 408 /**
 409   Restores the current floating point/SSE/SSE2 context from a buffer.
 410
 411   Restores the current floating point/SSE/SSE2 state from the buffer specified
 412   by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
 413   only available on IA-32 and X64.
 414
 415   @param  Buffer  Pointer to a buffer to save the floating point/SSE/SSE2 context.
 416
 417 **/
 418 VOID
 419 EFIAPI
 420 InternalX86FxRestore (
 421   IN      CONST IA32_FX_BUFFER      *Buffer
 422   );
 423
 424 /**
 425   Enables the 32-bit paging mode on the CPU.
 426
 427   Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
 428   must be properly initialized prior to calling this service. This function
 429   assumes the current execution mode is 32-bit protected mode. This function is
 430   only available on IA-32. After the 32-bit paging mode is enabled, control is
 431   transferred to the function specified by EntryPoint using the new stack
 432   specified by NewStack and passing in the parameters specified by Context1 and
 433   Context2. Context1 and Context2 are optional and may be NULL. The function
 434   EntryPoint must never return.
 435
 436   There are a number of constraints that must be followed before calling this
 437   function:
 438   1)  Interrupts must be disabled.
 439   2)  The caller must be in 32-bit protected mode with flat descriptors. This
 440       means all descriptors must have a base of 0 and a limit of 4GB.
 441   3)  CR0 and CR4 must be compatible with 32-bit protected mode with flat
 442       descriptors.
 443   4)  CR3 must point to valid page tables that will be used once the transition
 444       is complete, and those page tables must guarantee that the pages for this
 445       function and the stack are identity mapped.
 446
 447   @param  EntryPoint  A pointer to function to call with the new stack after
 448                       paging is enabled.
 449   @param  Context1    A pointer to the context to pass into the EntryPoint
 450                       function as the first parameter after paging is enabled.
 451   @param  Context2    A pointer to the context to pass into the EntryPoint
 452                       function as the second parameter after paging is enabled.
 453   @param  NewStack    A pointer to the new stack to use for the EntryPoint
 454                       function after paging is enabled.
 455
 456 **/
 457 VOID
 458 EFIAPI
 459 InternalX86EnablePaging32 (
 460   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
 461   IN      VOID                      *Context1,  OPTIONAL
 462   IN      VOID                      *Context2,  OPTIONAL
 463   IN      VOID                      *NewStack
 464   );
 465
 466 /**
 467   Disables the 32-bit paging mode on the CPU.
 468
 469   Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
 470   mode. This function assumes the current execution mode is 32-paged protected
 471   mode. This function is only available on IA-32. After the 32-bit paging mode
 472   is disabled, control is transferred to the function specified by EntryPoint
 473   using the new stack specified by NewStack and passing in the parameters
 474   specified by Context1 and Context2. Context1 and Context2 are optional and
 475   may be NULL. The function EntryPoint must never return.
 476
 477   There are a number of constraints that must be followed before calling this
 478   function:
 479   1)  Interrupts must be disabled.
 480   2)  The caller must be in 32-bit paged mode.
 481   3)  CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
 482   4)  CR3 must point to valid page tables that guarantee that the pages for
 483       this function and the stack are identity mapped.
 484
 485   @param  EntryPoint  A pointer to function to call with the new stack after
 486                       paging is disabled.
 487   @param  Context1    A pointer to the context to pass into the EntryPoint
 488                       function as the first parameter after paging is disabled.
 489   @param  Context2    A pointer to the context to pass into the EntryPoint
 490                       function as the second parameter after paging is
 491                       disabled.
 492   @param  NewStack    A pointer to the new stack to use for the EntryPoint
 493                       function after paging is disabled.
 494
 495 **/
 496 VOID
 497 EFIAPI
 498 InternalX86DisablePaging32 (
 499   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
 500   IN      VOID                      *Context1,  OPTIONAL
 501   IN      VOID                      *Context2,  OPTIONAL
 502   IN      VOID                      *NewStack
 503   );
 504
 505 /**
 506   Enables the 64-bit paging mode on the CPU.
 507
 508   Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
 509   must be properly initialized prior to calling this service. This function
 510   assumes the current execution mode is 32-bit protected mode with flat
 511   descriptors. This function is only available on IA-32. After the 64-bit
 512   paging mode is enabled, control is transferred to the function specified by
 513   EntryPoint using the new stack specified by NewStack and passing in the
 514   parameters specified by Context1 and Context2. Context1 and Context2 are
 515   optional and may be 0. The function EntryPoint must never return.
 516
 517   @param  Cs          The 16-bit selector to load in the CS before EntryPoint
 518                       is called. The descriptor in the GDT that this selector
 519                       references must be setup for long mode.
 520   @param  EntryPoint  The 64-bit virtual address of the function to call with
 521                       the new stack after paging is enabled.
 522   @param  Context1    The 64-bit virtual address of the context to pass into
 523                       the EntryPoint function as the first parameter after
 524                       paging is enabled.
 525   @param  Context2    The 64-bit virtual address of the context to pass into
 526                       the EntryPoint function as the second parameter after
 527                       paging is enabled.
 528   @param  NewStack    The 64-bit virtual address of the new stack to use for
 529                       the EntryPoint function after paging is enabled.
 530
 531 **/
 532 VOID
 533 EFIAPI
 534 InternalX86EnablePaging64 (
 535   IN      UINT16                    Cs,
 536   IN      UINT64                    EntryPoint,
 537   IN      UINT64                    Context1,  OPTIONAL
 538   IN      UINT64                    Context2,  OPTIONAL
 539   IN      UINT64                    NewStack
 540   );
 541
 542 /**
 543   Disables the 64-bit paging mode on the CPU.
 544
 545   Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
 546   mode. This function assumes the current execution mode is 64-paging mode.
 547   This function is only available on X64. After the 64-bit paging mode is
 548   disabled, control is transferred to the function specified by EntryPoint
 549   using the new stack specified by NewStack and passing in the parameters
 550   specified by Context1 and Context2. Context1 and Context2 are optional and
 551   may be 0. The function EntryPoint must never return.
 552
 553   @param  Cs          The 16-bit selector to load in the CS before EntryPoint
 554                       is called. The descriptor in the GDT that this selector
 555                       references must be setup for 32-bit protected mode.
 556   @param  EntryPoint  The 64-bit virtual address of the function to call with
 557                       the new stack after paging is disabled.
 558   @param  Context1    The 64-bit virtual address of the context to pass into
 559                       the EntryPoint function as the first parameter after
 560                       paging is disabled.
 561   @param  Context2    The 64-bit virtual address of the context to pass into
 562                       the EntryPoint function as the second parameter after
 563                       paging is disabled.
 564   @param  NewStack    The 64-bit virtual address of the new stack to use for
 565                       the EntryPoint function after paging is disabled.
 566
 567 **/
 568 VOID
 569 EFIAPI
 570 InternalX86DisablePaging64 (
 571   IN      UINT16                    Cs,
 572   IN      UINT32                    EntryPoint,
 573   IN      UINT32                    Context1,  OPTIONAL
 574   IN      UINT32                    Context2,  OPTIONAL
 575   IN      UINT32                    NewStack
 576   );
 577
 578 #endif