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   Worker functons that 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   Worker functon that 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   Worker function that 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   Worker function that 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   Worker function that 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   Worker function that 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   Worker function that 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   Worker function that 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   Worker function that 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   Worker function that 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   Worker function that 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   Worker function that 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   Worker function that 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 InternalSwitchStack (
 321   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
 322   IN      VOID                      *Context1,
 323   IN      VOID                      *Context2,
 324   IN      VOID                      *NewStack
 325   );
 326
 327 //
 328 // Ia32 and x64 specific functions
 329 //
 330
 331 /**
 332   Reads the current Global Descriptor Table Register(GDTR) descriptor.
 333
 334   Reads and returns the current GDTR descriptor and returns it in Gdtr. This
 335   function is only available on IA-32 and X64.
 336
 337   @param  Gdtr  Pointer to a GDTR descriptor.
 338
 339 **/
 340 VOID
 341 EFIAPI
 342 InternalX86ReadGdtr (
 343   OUT     IA32_DESCRIPTOR           *Gdtr
 344   );
 345
 346 /**
 347   Writes the current Global Descriptor Table Register (GDTR) descriptor.
 348
 349   Writes and the current GDTR descriptor specified by Gdtr. This function is
 350   only available on IA-32 and X64.
 351
 352   @param  Gdtr  Pointer to a GDTR descriptor.
 353
 354 **/
 355 VOID
 356 EFIAPI
 357 InternalX86WriteGdtr (
 358   IN      CONST IA32_DESCRIPTOR     *Gdtr
 359   );
 360
 361 /**
 362   Reads the current Interrupt Descriptor Table Register(GDTR) descriptor.
 363
 364   Reads and returns the current IDTR descriptor and returns it in Idtr. This
 365   function is only available on IA-32 and X64.
 366
 367   @param  Idtr  Pointer to a IDTR descriptor.
 368
 369 **/
 370 VOID
 371 EFIAPI
 372 InternalX86ReadIdtr (
 373   OUT     IA32_DESCRIPTOR           *Idtr
 374   );
 375
 376 /**
 377   Writes the current Interrupt Descriptor Table Register(GDTR) descriptor.
 378
 379   Writes the current IDTR descriptor and returns it in Idtr. This function is
 380   only available on IA-32 and X64.
 381
 382   @param  Idtr  Pointer to a IDTR descriptor.
 383
 384 **/
 385 VOID
 386 EFIAPI
 387 InternalX86WriteIdtr (
 388   IN      CONST IA32_DESCRIPTOR     *Idtr
 389   );
 390
 391 /**
 392   Save the current floating point/SSE/SSE2 context to a buffer.
 393
 394   Saves the current floating point/SSE/SSE2 state to the buffer specified by
 395   Buffer. Buffer must be aligned on a 16-byte boundary. This function is only
 396   available on IA-32 and X64.
 397
 398   @param  Buffer  Pointer to a buffer to save the floating point/SSE/SSE2 context.
 399
 400 **/
 401 VOID
 402 EFIAPI
 403 InternalX86FxSave (
 404   OUT     IA32_FX_BUFFER            *Buffer
 405   );
 406
 407 /**
 408   Restores the current floating point/SSE/SSE2 context from a buffer.
 409
 410   Restores the current floating point/SSE/SSE2 state from the buffer specified
 411   by Buffer. Buffer must be aligned on a 16-byte boundary. This function is
 412   only available on IA-32 and X64.
 413
 414   @param  Buffer  Pointer to a buffer to save the floating point/SSE/SSE2 context.
 415
 416 **/
 417 VOID
 418 EFIAPI
 419 InternalX86FxRestore (
 420   IN      CONST IA32_FX_BUFFER      *Buffer
 421   );
 422
 423 /**
 424   Enables the 32-bit paging mode on the CPU.
 425
 426   Enables the 32-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
 427   must be properly initialized prior to calling this service. This function
 428   assumes the current execution mode is 32-bit protected mode. This function is
 429   only available on IA-32. After the 32-bit paging mode is enabled, control is
 430   transferred to the function specified by EntryPoint using the new stack
 431   specified by NewStack and passing in the parameters specified by Context1 and
 432   Context2. Context1 and Context2 are optional and may be NULL. The function
 433   EntryPoint must never return.
 434
 435   There are a number of constraints that must be followed before calling this
 436   function:
 437   1)  Interrupts must be disabled.
 438   2)  The caller must be in 32-bit protected mode with flat descriptors. This
 439       means all descriptors must have a base of 0 and a limit of 4GB.
 440   3)  CR0 and CR4 must be compatible with 32-bit protected mode with flat
 441       descriptors.
 442   4)  CR3 must point to valid page tables that will be used once the transition
 443       is complete, and those page tables must guarantee that the pages for this
 444       function and the stack are identity mapped.
 445
 446   @param  EntryPoint  A pointer to function to call with the new stack after
 447                       paging is enabled.
 448   @param  Context1    A pointer to the context to pass into the EntryPoint
 449                       function as the first parameter after paging is enabled.
 450   @param  Context2    A pointer to the context to pass into the EntryPoint
 451                       function as the second parameter after paging is enabled.
 452   @param  NewStack    A pointer to the new stack to use for the EntryPoint
 453                       function after paging is enabled.
 454
 455 **/
 456 VOID
 457 EFIAPI
 458 InternalX86EnablePaging32 (
 459   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
 460   IN      VOID                      *Context1,  OPTIONAL
 461   IN      VOID                      *Context2,  OPTIONAL
 462   IN      VOID                      *NewStack
 463   );
 464
 465 /**
 466   Disables the 32-bit paging mode on the CPU.
 467
 468   Disables the 32-bit paging mode on the CPU and returns to 32-bit protected
 469   mode. This function assumes the current execution mode is 32-paged protected
 470   mode. This function is only available on IA-32. After the 32-bit paging mode
 471   is disabled, control is transferred to the function specified by EntryPoint
 472   using the new stack specified by NewStack and passing in the parameters
 473   specified by Context1 and Context2. Context1 and Context2 are optional and
 474   may be NULL. The function EntryPoint must never return.
 475
 476   There are a number of constraints that must be followed before calling this
 477   function:
 478   1)  Interrupts must be disabled.
 479   2)  The caller must be in 32-bit paged mode.
 480   3)  CR0, CR3, and CR4 must be compatible with 32-bit paged mode.
 481   4)  CR3 must point to valid page tables that guarantee that the pages for
 482       this function and the stack are identity mapped.
 483
 484   @param  EntryPoint  A pointer to function to call with the new stack after
 485                       paging is disabled.
 486   @param  Context1    A pointer to the context to pass into the EntryPoint
 487                       function as the first parameter after paging is disabled.
 488   @param  Context2    A pointer to the context to pass into the EntryPoint
 489                       function as the second parameter after paging is
 490                       disabled.
 491   @param  NewStack    A pointer to the new stack to use for the EntryPoint
 492                       function after paging is disabled.
 493
 494 **/
 495 VOID
 496 EFIAPI
 497 InternalX86DisablePaging32 (
 498   IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
 499   IN      VOID                      *Context1,  OPTIONAL
 500   IN      VOID                      *Context2,  OPTIONAL
 501   IN      VOID                      *NewStack
 502   );
 503
 504 /**
 505   Enables the 64-bit paging mode on the CPU.
 506
 507   Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
 508   must be properly initialized prior to calling this service. This function
 509   assumes the current execution mode is 32-bit protected mode with flat
 510   descriptors. This function is only available on IA-32. After the 64-bit
 511   paging mode is enabled, control is transferred to the function specified by
 512   EntryPoint using the new stack specified by NewStack and passing in the
 513   parameters specified by Context1 and Context2. Context1 and Context2 are
 514   optional and may be 0. The function EntryPoint must never return.
 515
 516   @param  Cs          The 16-bit selector to load in the CS before EntryPoint
 517                       is called. The descriptor in the GDT that this selector
 518                       references must be setup for long mode.
 519   @param  EntryPoint  The 64-bit virtual address of the function to call with
 520                       the new stack after paging is enabled.
 521   @param  Context1    The 64-bit virtual address of the context to pass into
 522                       the EntryPoint function as the first parameter after
 523                       paging is enabled.
 524   @param  Context2    The 64-bit virtual address of the context to pass into
 525                       the EntryPoint function as the second parameter after
 526                       paging is enabled.
 527   @param  NewStack    The 64-bit virtual address of the new stack to use for
 528                       the EntryPoint function after paging is enabled.
 529
 530 **/
 531 VOID
 532 EFIAPI
 533 InternalX86EnablePaging64 (
 534   IN      UINT16                    Cs,
 535   IN      UINT64                    EntryPoint,
 536   IN      UINT64                    Context1,  OPTIONAL
 537   IN      UINT64                    Context2,  OPTIONAL
 538   IN      UINT64                    NewStack
 539   );
 540
 541 /**
 542   Disables the 64-bit paging mode on the CPU.
 543
 544   Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
 545   mode. This function assumes the current execution mode is 64-paging mode.
 546   This function is only available on X64. After the 64-bit paging mode is
 547   disabled, control is transferred to the function specified by EntryPoint
 548   using the new stack specified by NewStack and passing in the parameters
 549   specified by Context1 and Context2. Context1 and Context2 are optional and
 550   may be 0. The function EntryPoint must never return.
 551
 552   @param  Cs          The 16-bit selector to load in the CS before EntryPoint
 553                       is called. The descriptor in the GDT that this selector
 554                       references must be setup for 32-bit protected mode.
 555   @param  EntryPoint  The 64-bit virtual address of the function to call with
 556                       the new stack after paging is disabled.
 557   @param  Context1    The 64-bit virtual address of the context to pass into
 558                       the EntryPoint function as the first parameter after
 559                       paging is disabled.
 560   @param  Context2    The 64-bit virtual address of the context to pass into
 561                       the EntryPoint function as the second parameter after
 562                       paging is disabled.
 563   @param  NewStack    The 64-bit virtual address of the new stack to use for
 564                       the EntryPoint function after paging is disabled.
 565
 566 **/
 567 VOID
 568 EFIAPI
 569 InternalX86DisablePaging64 (
 570   IN      UINT16                    Cs,
 571   IN      UINT32                    EntryPoint,
 572   IN      UINT32                    Context1,  OPTIONAL
 573   IN      UINT32                    Context2,  OPTIONAL
 574   IN      UINT32                    NewStack
 575   );
 576
 577 #endif