path: root/MdePkg/Test/UnitTest/Include/Library/UnitTestHostBaseLib.h

/** @file
  Unit Test Host BaseLib hooks.

  Copyright (c) 2020, Intel Corporation. All rights reserved.<BR>
  SPDX-License-Identifier: BSD-2-Clause-Patent

**/

#ifndef __UNIT_TEST_HOST_BASE_LIB_H__
#define __UNIT_TEST_HOST_BASE_LIB_H__

/**
  Prototype of service with no parameters and no return value.
**/
typedef
VOID
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_VOID)(
  VOID
  );

/**
  Prototype of service that reads and returns a BOOLEAN value.

  @return The value read.
**/
typedef
BOOLEAN
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_READ_BOOLEAN)(
  VOID
  );

/**
  Prototype of service that reads and returns a UINT16 value.

  @return The value read.
**/
typedef
UINT16
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_READ_UINT16)(
  VOID
  );

/**
  Prototype of service that reads and returns a UINTN value.

  @return The value read.
**/
typedef
UINTN
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_READ_UINTN)(
  VOID
  );

/**
  Prototype of service that writes and returns a UINT16 value.

  @param[in]  Value  The value to write.

  @return The value written.
**/
typedef
VOID
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_WRITE_UINT16)(
  IN UINT16  Value
  );

/**
  Prototype of service that writes and returns a UINTN value.

  @param[in]  Value  The value to write.

  @return The value written.
**/
typedef
UINTN
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_WRITE_UINTN)(
  IN UINTN  Value
  );

/**
  Prototype of service that reads and returns an IA32_DESCRIPTOR.

  @param[out]  Ia32Descriptor  Pointer to the descriptor read.
**/
typedef
VOID
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_ASM_READ_IA32_DESCRIPTOR)(
  OUT IA32_DESCRIPTOR           *Ia32Descriptor
  );

/**
  Prototype of service that writes an IA32_DESCRIPTOR.

  @param[in]  Ia32Descriptor  Pointer to the descriptor to write.
**/
typedef
VOID
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_ASM_WRITE_IA32_DESCRIPTOR)(
  IN CONST IA32_DESCRIPTOR     *Ia32Descriptor
  );

/**
  Retrieves CPUID information.

  Executes the CPUID instruction with EAX set to the value specified by Index.
  This function always returns Index.
  If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
  If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
  If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
  If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.
  This function is only available on IA-32 and x64.

  @param  Index The 32-bit value to load into EAX prior to invoking the CPUID
                instruction.
  @param  Eax   The pointer to the 32-bit EAX value returned by the CPUID
                instruction. This is an optional parameter that may be NULL.
  @param  Ebx   The pointer to the 32-bit EBX value returned by the CPUID
                instruction. This is an optional parameter that may be NULL.
  @param  Ecx   The pointer to the 32-bit ECX value returned by the CPUID
                instruction. This is an optional parameter that may be NULL.
  @param  Edx   The pointer to the 32-bit EDX value returned by the CPUID
                instruction. This is an optional parameter that may be NULL.

  @return Index.

**/
typedef
UINT32
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_ASM_CPUID)(
  IN      UINT32                    Index,
  OUT     UINT32                    *Eax,  OPTIONAL
  OUT     UINT32                    *Ebx,  OPTIONAL
  OUT     UINT32                    *Ecx,  OPTIONAL
  OUT     UINT32                    *Edx   OPTIONAL
  );

/**
  Retrieves CPUID information using an extended leaf identifier.

  Executes the CPUID instruction with EAX set to the value specified by Index
  and ECX set to the value specified by SubIndex. This function always returns
  Index. This function is only available on IA-32 and x64.

  If Eax is not NULL, then the value of EAX after CPUID is returned in Eax.
  If Ebx is not NULL, then the value of EBX after CPUID is returned in Ebx.
  If Ecx is not NULL, then the value of ECX after CPUID is returned in Ecx.
  If Edx is not NULL, then the value of EDX after CPUID is returned in Edx.

  @param  Index     The 32-bit value to load into EAX prior to invoking the
                    CPUID instruction.
  @param  SubIndex  The 32-bit value to load into ECX prior to invoking the
                    CPUID instruction.
  @param  Eax       The pointer to the 32-bit EAX value returned by the CPUID
                    instruction. This is an optional parameter that may be
                    NULL.
  @param  Ebx       The pointer to the 32-bit EBX value returned by the CPUID
                    instruction. This is an optional parameter that may be
                    NULL.
  @param  Ecx       The pointer to the 32-bit ECX value returned by the CPUID
                    instruction. This is an optional parameter that may be
                    NULL.
  @param  Edx       The pointer to the 32-bit EDX value returned by the CPUID
                    instruction. This is an optional parameter that may be
                    NULL.

  @return Index.

**/
typedef
UINT32
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_ASM_CPUID_EX)(
  IN      UINT32                    Index,
  IN      UINT32                    SubIndex,
  OUT     UINT32                    *Eax,  OPTIONAL
  OUT     UINT32                    *Ebx,  OPTIONAL
  OUT     UINT32                    *Ecx,  OPTIONAL
  OUT     UINT32                    *Edx   OPTIONAL
  );

/**
  Returns a 64-bit Machine Specific Register(MSR).

  Reads and returns the 64-bit MSR specified by Index. No parameter checking is
  performed on Index, and some Index values may cause CPU exceptions. The
  caller must either guarantee that Index is valid, or the caller must set up
  exception handlers to catch the exceptions. This function is only available
  on IA-32 and x64.

  @param  Index The 32-bit MSR index to read.

  @return The value of the MSR identified by Index.

**/
typedef
UINT64
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_ASM_READ_MSR_64)(
  IN      UINT32                    Index
  );

/**
  Writes a 64-bit value to a Machine Specific Register(MSR), and returns the
  value.

  Writes the 64-bit value specified by Value to the MSR specified by Index. The
  64-bit value written to the MSR is returned. No parameter checking is
  performed on Index or Value, and some of these may cause CPU exceptions. The
  caller must either guarantee that Index and Value are valid, or the caller
  must establish proper exception handlers. This function is only available on
  IA-32 and x64.

  @param  Index The 32-bit MSR index to write.
  @param  Value The 64-bit value to write to the MSR.

  @return Value

**/
typedef
UINT64
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_ASM_WRITE_MSR_64)(
  IN      UINT32                    Index,
  IN      UINT64                    Value
  );

/**
  Reads the current value of a Performance Counter (PMC).

  Reads and returns the current value of performance counter specified by
  Index. This function is only available on IA-32 and x64.

  @param  Index The 32-bit Performance Counter index to read.

  @return The value of the PMC specified by Index.

**/
typedef
UINT64
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_ASM_READ_PMC)(
  IN      UINT32                    Index
  );

/**
  Sets up a monitor buffer that is used by AsmMwait().

  Executes a MONITOR instruction with the register state specified by Eax, Ecx
  and Edx. Returns Eax. This function is only available on IA-32 and x64.

  @param  Eax The value to load into EAX or RAX before executing the MONITOR
              instruction.
  @param  Ecx The value to load into ECX or RCX before executing the MONITOR
              instruction.
  @param  Edx The value to load into EDX or RDX before executing the MONITOR
              instruction.

  @return Eax

**/
typedef
UINTN
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_ASM_MONITOR)(
  IN      UINTN                     Eax,
  IN      UINTN                     Ecx,
  IN      UINTN                     Edx
  );

/**
  Executes an MWAIT instruction.

  Executes an MWAIT instruction with the register state specified by Eax and
  Ecx. Returns Eax. This function is only available on IA-32 and x64.

  @param  Eax The value to load into EAX or RAX before executing the MONITOR
              instruction.
  @param  Ecx The value to load into ECX or RCX before executing the MONITOR
              instruction.

  @return Eax

**/
typedef
UINTN
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_ASM_MWAIT)(
  IN      UINTN                     Eax,
  IN      UINTN                     Ecx
  );

/**
  Flushes a cache line from all the instruction and data caches within the
  coherency domain of the CPU.

  Flushed the cache line specified by LinearAddress, and returns LinearAddress.
  This function is only available on IA-32 and x64.

  @param  LinearAddress The address of the cache line to flush. If the CPU is
                        in a physical addressing mode, then LinearAddress is a
                        physical address. If the CPU is in a virtual
                        addressing mode, then LinearAddress is a virtual
                        address.

  @return LinearAddress.
**/
typedef
VOID *
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_ASM_FLUSH_CACHE_LINE)(
  IN      VOID                      *LinearAddress
  );

/**
  Prototype of service that enables ot disables 32-bit paging modes.

  @param  EntryPoint  A pointer to function to call with the new stack after
                      paging is enabled.
  @param  Context1    A pointer to the context to pass into the EntryPoint
                      function as the first parameter after paging is enabled.
  @param  Context2    A pointer to the context to pass into the EntryPoint
                      function as the second parameter after paging is enabled.
  @param  NewStack    A pointer to the new stack to use for the EntryPoint
                      function after paging is enabled.

**/
typedef
VOID
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_ASM_PAGING_32)(
  IN      SWITCH_STACK_ENTRY_POINT  EntryPoint,
  IN      VOID                      *Context1,  OPTIONAL
  IN      VOID                      *Context2,  OPTIONAL
  IN      VOID                      *NewStack
  );

/**
  Enables the 64-bit paging mode on the CPU.

  Enables the 64-bit paging mode on the CPU. CR0, CR3, CR4, and the page tables
  must be properly initialized prior to calling this service. This function
  assumes the current execution mode is 32-bit protected mode with flat
  descriptors. This function is only available on IA-32. After the 64-bit
  paging mode is enabled, control is transferred to the function specified by
  EntryPoint using the new stack specified by NewStack and passing in the
  parameters specified by Context1 and Context2. Context1 and Context2 are
  optional and may be 0. The function EntryPoint must never return.

  If the current execution mode is not 32-bit protected mode with flat
  descriptors, then ASSERT().
  If EntryPoint is 0, then ASSERT().
  If NewStack is 0, then ASSERT().

  @param  Cs          The 16-bit selector to load in the CS before EntryPoint
                      is called. The descriptor in the GDT that this selector
                      references must be setup for long mode.
  @param  EntryPoint  The 64-bit virtual address of the function to call with
                      the new stack after paging is enabled.
  @param  Context1    The 64-bit virtual address of the context to pass into
                      the EntryPoint function as the first parameter after
                      paging is enabled.
  @param  Context2    The 64-bit virtual address of the context to pass into
                      the EntryPoint function as the second parameter after
                      paging is enabled.
  @param  NewStack    The 64-bit virtual address of the new stack to use for
                      the EntryPoint function after paging is enabled.

**/
typedef
VOID
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_ASM_ENABLE_PAGING_64)(
  IN      UINT16                    Cs,
  IN      UINT64                    EntryPoint,
  IN      UINT64                    Context1,  OPTIONAL
  IN      UINT64                    Context2,  OPTIONAL
  IN      UINT64                    NewStack
  );

/**
  Disables the 64-bit paging mode on the CPU.

  Disables the 64-bit paging mode on the CPU and returns to 32-bit protected
  mode. This function assumes the current execution mode is 64-paging mode.
  This function is only available on x64. After the 64-bit paging mode is
  disabled, control is transferred to the function specified by EntryPoint
  using the new stack specified by NewStack and passing in the parameters
  specified by Context1 and Context2. Context1 and Context2 are optional and
  may be 0. The function EntryPoint must never return.

  If the current execution mode is not 64-bit paged mode, then ASSERT().
  If EntryPoint is 0, then ASSERT().
  If NewStack is 0, then ASSERT().

  @param  Cs          The 16-bit selector to load in the CS before EntryPoint
                      is called. The descriptor in the GDT that this selector
                      references must be setup for 32-bit protected mode.
  @param  EntryPoint  The 64-bit virtual address of the function to call with
                      the new stack after paging is disabled.
  @param  Context1    The 64-bit virtual address of the context to pass into
                      the EntryPoint function as the first parameter after
                      paging is disabled.
  @param  Context2    The 64-bit virtual address of the context to pass into
                      the EntryPoint function as the second parameter after
                      paging is disabled.
  @param  NewStack    The 64-bit virtual address of the new stack to use for
                      the EntryPoint function after paging is disabled.

**/
typedef
VOID
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_ASM_DISABLE_PAGING_64)(
  IN      UINT16                    Cs,
  IN      UINT32                    EntryPoint,
  IN      UINT32                    Context1,  OPTIONAL
  IN      UINT32                    Context2,  OPTIONAL
  IN      UINT32                    NewStack
  );

/**
  Retrieves the properties for 16-bit thunk functions.

  Computes the size of the buffer and stack below 1MB required to use the
  AsmPrepareThunk16(), AsmThunk16() and AsmPrepareAndThunk16() functions. This
  buffer size is returned in RealModeBufferSize, and the stack size is returned
  in ExtraStackSize. If parameters are passed to the 16-bit real mode code,
  then the actual minimum stack size is ExtraStackSize plus the maximum number
  of bytes that need to be passed to the 16-bit real mode code.

  If RealModeBufferSize is NULL, then ASSERT().
  If ExtraStackSize is NULL, then ASSERT().

  @param  RealModeBufferSize  A pointer to the size of the buffer below 1MB
                              required to use the 16-bit thunk functions.
  @param  ExtraStackSize      A pointer to the extra size of stack below 1MB
                              that the 16-bit thunk functions require for
                              temporary storage in the transition to and from
                              16-bit real mode.

**/
typedef
VOID
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_ASM_GET_THUNK_16_PROPERTIES)(
  OUT     UINT32                    *RealModeBufferSize,
  OUT     UINT32                    *ExtraStackSize
  );

/**
  Prototype of services that operates on a THUNK_CONTEXT structure.

  @param  ThunkContext  A pointer to the context structure that describes the
                        16-bit real mode code to call.

**/
typedef
VOID
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_ASM_THUNK_16)(
  IN OUT  THUNK_CONTEXT             *ThunkContext
  );

/**
  Patch the immediate operand of an IA32 or X64 instruction such that the byte,
  word, dword or qword operand is encoded at the end of the instruction's
  binary representation.

  This function should be used to update object code that was compiled with
  NASM from assembly source code. Example:

  NASM source code:

        mov     eax, strict dword 0 ; the imm32 zero operand will be patched
    ASM_PFX(gPatchCr3):
        mov     cr3, eax

  C source code:

    X86_ASSEMBLY_PATCH_LABEL gPatchCr3;
    PatchInstructionX86 (gPatchCr3, AsmReadCr3 (), 4);

  @param[out] InstructionEnd  Pointer right past the instruction to patch. The
                              immediate operand to patch is expected to
                              comprise the trailing bytes of the instruction.
                              If InstructionEnd is closer to address 0 than
                              ValueSize permits, then ASSERT().

  @param[in] PatchValue       The constant to write to the immediate operand.
                              The caller is responsible for ensuring that
                              PatchValue can be represented in the byte, word,
                              dword or qword operand (as indicated through
                              ValueSize); otherwise ASSERT().

  @param[in] ValueSize        The size of the operand in bytes; must be 1, 2,
                              4, or 8. ASSERT() otherwise.
**/
typedef
VOID
(EFIAPI *UNIT_TEST_HOST_BASE_LIB_ASM_PATCH_INSTRUCTION_X86)(
  OUT X86_ASSEMBLY_PATCH_LABEL *InstructionEnd,
  IN  UINT64                   PatchValue,
  IN  UINTN                    ValueSize
  );

///
/// Common services
///
typedef struct {
  UNIT_TEST_HOST_BASE_LIB_VOID          EnableInterrupts;
  UNIT_TEST_HOST_BASE_LIB_VOID          DisableInterrupts;
  UNIT_TEST_HOST_BASE_LIB_VOID          EnableDisableInterrupts;
  UNIT_TEST_HOST_BASE_LIB_READ_BOOLEAN  GetInterruptState;
} UNIT_TEST_HOST_BASE_LIB_COMMON;

///
/// IA32/X64 services
///
typedef struct {
  UNIT_TEST_HOST_BASE_LIB_ASM_CPUID                    AsmCpuid;
  UNIT_TEST_HOST_BASE_LIB_ASM_CPUID_EX                 AsmCpuidEx;
  UNIT_TEST_HOST_BASE_LIB_VOID                         AsmDisableCache;
  UNIT_TEST_HOST_BASE_LIB_VOID                         AsmEnableCache;
  UNIT_TEST_HOST_BASE_LIB_ASM_READ_MSR_64              AsmReadMsr64;
  UNIT_TEST_HOST_BASE_LIB_ASM_WRITE_MSR_64             AsmWriteMsr64;
  UNIT_TEST_HOST_BASE_LIB_READ_UINTN                   AsmReadCr0;
  UNIT_TEST_HOST_BASE_LIB_READ_UINTN                   AsmReadCr2;
  UNIT_TEST_HOST_BASE_LIB_READ_UINTN                   AsmReadCr3;
  UNIT_TEST_HOST_BASE_LIB_READ_UINTN                   AsmReadCr4;
  UNIT_TEST_HOST_BASE_LIB_WRITE_UINTN                  AsmWriteCr0;
  UNIT_TEST_HOST_BASE_LIB_WRITE_UINTN                  AsmWriteCr2;
  UNIT_TEST_HOST_BASE_LIB_WRITE_UINTN                  AsmWriteCr3;
  UNIT_TEST_HOST_BASE_LIB_WRITE_UINTN                  AsmWriteCr4;
  UNIT_TEST_HOST_BASE_LIB_READ_UINTN                   AsmReadDr0;
  UNIT_TEST_HOST_BASE_LIB_READ_UINTN                   AsmReadDr1;
  UNIT_TEST_HOST_BASE_LIB_READ_UINTN                   AsmReadDr2;
  UNIT_TEST_HOST_BASE_LIB_READ_UINTN                   AsmReadDr3;
  UNIT_TEST_HOST_BASE_LIB_READ_UINTN                   AsmReadDr4;
  UNIT_TEST_HOST_BASE_LIB_READ_UINTN                   AsmReadDr5;
  UNIT_TEST_HOST_BASE_LIB_READ_UINTN                   AsmReadDr6;
  UNIT_TEST_HOST_BASE_LIB_READ_UINTN                   AsmReadDr7;
  UNIT_TEST_HOST_BASE_LIB_WRITE_UINTN                  AsmWriteDr0;
  UNIT_TEST_HOST_BASE_LIB_WRITE_UINTN                  AsmWriteDr1;
  UNIT_TEST_HOST_BASE_LIB_WRITE_UINTN                  AsmWriteDr2;
  UNIT_TEST_HOST_BASE_LIB_WRITE_UINTN                  AsmWriteDr3;
  UNIT_TEST_HOST_BASE_LIB_WRITE_UINTN                  AsmWriteDr4;
  UNIT_TEST_HOST_BASE_LIB_WRITE_UINTN                  AsmWriteDr5;
  UNIT_TEST_HOST_BASE_LIB_WRITE_UINTN                  AsmWriteDr6;
  UNIT_TEST_HOST_BASE_LIB_WRITE_UINTN                  AsmWriteDr7;
  UNIT_TEST_HOST_BASE_LIB_READ_UINT16                  AsmReadCs;
  UNIT_TEST_HOST_BASE_LIB_READ_UINT16                  AsmReadDs;
  UNIT_TEST_HOST_BASE_LIB_READ_UINT16                  AsmReadEs;
  UNIT_TEST_HOST_BASE_LIB_READ_UINT16                  AsmReadFs;
  UNIT_TEST_HOST_BASE_LIB_READ_UINT16                  AsmReadGs;
  UNIT_TEST_HOST_BASE_LIB_READ_UINT16                  AsmReadSs;
  UNIT_TEST_HOST_BASE_LIB_READ_UINT16                  AsmReadTr;
  UNIT_TEST_HOST_BASE_LIB_ASM_READ_IA32_DESCRIPTOR     AsmReadGdtr;
  UNIT_TEST_HOST_BASE_LIB_ASM_WRITE_IA32_DESCRIPTOR    AsmWriteGdtr;
  UNIT_TEST_HOST_BASE_LIB_ASM_READ_IA32_DESCRIPTOR     AsmReadIdtr;
  UNIT_TEST_HOST_BASE_LIB_ASM_WRITE_IA32_DESCRIPTOR    AsmWriteIdtr;
  UNIT_TEST_HOST_BASE_LIB_READ_UINT16                  AsmReadLdtr;
  UNIT_TEST_HOST_BASE_LIB_WRITE_UINT16                 AsmWriteLdtr;
  UNIT_TEST_HOST_BASE_LIB_ASM_READ_PMC                 AsmReadPmc;
  UNIT_TEST_HOST_BASE_LIB_ASM_MONITOR                  AsmMonitor;
  UNIT_TEST_HOST_BASE_LIB_ASM_MWAIT                    AsmMwait;
  UNIT_TEST_HOST_BASE_LIB_VOID                         AsmWbinvd;
  UNIT_TEST_HOST_BASE_LIB_VOID                         AsmInvd;
  UNIT_TEST_HOST_BASE_LIB_ASM_FLUSH_CACHE_LINE         AsmFlushCacheLine;
  UNIT_TEST_HOST_BASE_LIB_ASM_PAGING_32                AsmEnablePaging32;
  UNIT_TEST_HOST_BASE_LIB_ASM_PAGING_32                AsmDisablePaging32;
  UNIT_TEST_HOST_BASE_LIB_ASM_ENABLE_PAGING_64         AsmEnablePaging64;
  UNIT_TEST_HOST_BASE_LIB_ASM_DISABLE_PAGING_64        AsmDisablePaging64;
  UNIT_TEST_HOST_BASE_LIB_ASM_GET_THUNK_16_PROPERTIES  AsmGetThunk16Properties;
  UNIT_TEST_HOST_BASE_LIB_ASM_THUNK_16                 AsmPrepareThunk16;
  UNIT_TEST_HOST_BASE_LIB_ASM_THUNK_16                 AsmThunk16;
  UNIT_TEST_HOST_BASE_LIB_ASM_THUNK_16                 AsmPrepareAndThunk16;
  UNIT_TEST_HOST_BASE_LIB_WRITE_UINT16                 AsmWriteTr;
  UNIT_TEST_HOST_BASE_LIB_VOID                         AsmLfence;
  UNIT_TEST_HOST_BASE_LIB_ASM_PATCH_INSTRUCTION_X86    PatchInstructionX86;
} UNIT_TEST_HOST_BASE_LIB_X86;

///
/// Data structure that contains pointers structures of common services and CPU
/// architctuire specific services.  Support for additional CPU architectures
/// can be added to the end of this structure.
///
typedef struct {
  UNIT_TEST_HOST_BASE_LIB_COMMON  *Common;
  UNIT_TEST_HOST_BASE_LIB_X86     *X86;
} UNIT_TEST_HOST_BASE_LIB;

extern UNIT_TEST_HOST_BASE_LIB  gUnitTestHostBaseLib;

#endif