/** @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