OvmfPkg/Csm/CsmSupportLib/LegacyRegion.h

   1 /** @file
   2   Legacy Region Support
   3
   4   Copyright (c) 2008 - 2016, Intel Corporation. All rights reserved.<BR>
   5
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef _LEGACY_REGION_DXE_H_
  11 #define _LEGACY_REGION_DXE_H_
  12
  13 #include <PiDxe.h>
  14
  15 #include <Protocol/LegacyRegion2.h>
  16
  17 #include <IndustryStandard/Pci.h>
  18 #include <IndustryStandard/Q35MchIch9.h>
  19 #include <IndustryStandard/I440FxPiix4.h>
  20
  21 #include <Library/PciLib.h>
  22 #include <Library/PcdLib.h>
  23 #include <Library/DebugLib.h>
  24 #include <Library/MemoryAllocationLib.h>
  25 #include <Library/UefiBootServicesTableLib.h>
  26
  27 #define PAM_BASE_ADDRESS   0xc0000
  28 #define PAM_LIMIT_ADDRESS  BASE_1MB
  29
  30 //
  31 // Describes Legacy Region blocks and status.
  32 //
  33 typedef struct {
  34   UINT32     Start;
  35   UINT32     Length;
  36   BOOLEAN    ReadEnabled;
  37   BOOLEAN    WriteEnabled;
  38 } LEGACY_MEMORY_SECTION_INFO;
  39
  40 //
  41 // Provides a map of the PAM registers and bits used to set Read/Write access.
  42 //
  43 typedef struct {
  44   UINTN    PAMRegPciLibAddress;
  45   UINT8    ReadEnableData;
  46   UINT8    WriteEnableData;
  47 } PAM_REGISTER_VALUE;
  48
  49 /**
  50   Modify the hardware to allow (decode) or disallow (not decode) memory reads in a region.
  51
  52   If the On parameter evaluates to TRUE, this function enables memory reads in the address range
  53   Start to (Start + Length - 1).
  54   If the On parameter evaluates to FALSE, this function disables memory reads in the address range
  55   Start to (Start + Length - 1).
  56
  57   @param  This[in]              Indicates the EFI_LEGACY_REGION_PROTOCOL instance.
  58   @param  Start[in]             The beginning of the physical address of the region whose attributes
  59                                 should be modified.
  60   @param  Length[in]            The number of bytes of memory whose attributes should be modified.
  61                                 The actual number of bytes modified may be greater than the number
  62                                 specified.
  63   @param  Granularity[out]      The number of bytes in the last region affected. This may be less
  64                                 than the total number of bytes affected if the starting address
  65                                 was not aligned to a region's starting address or if the length
  66                                 was greater than the number of bytes in the first region.
  67   @param  On[in]                Decode / Non-Decode flag.
  68
  69   @retval EFI_SUCCESS           The region's attributes were successfully modified.
  70   @retval EFI_INVALID_PARAMETER If Start or Length describe an address not in the Legacy Region.
  71
  72 **/
  73 EFI_STATUS
  74 EFIAPI
  75 LegacyRegion2Decode (
  76   IN  EFI_LEGACY_REGION2_PROTOCOL  *This,
  77   IN  UINT32                       Start,
  78   IN  UINT32                       Length,
  79   OUT UINT32                       *Granularity,
  80   IN  BOOLEAN                      *On
  81   );
  82
  83 /**
  84   Modify the hardware to disallow memory writes in a region.
  85
  86   This function changes the attributes of a memory range to not allow writes.
  87
  88   @param  This[in]              Indicates the EFI_LEGACY_REGION_PROTOCOL instance.
  89   @param  Start[in]             The beginning of the physical address of the region whose
  90                                 attributes should be modified.
  91   @param  Length[in]            The number of bytes of memory whose attributes should be modified.
  92                                 The actual number of bytes modified may be greater than the number
  93                                 specified.
  94   @param  Granularity[out]      The number of bytes in the last region affected. This may be less
  95                                 than the total number of bytes affected if the starting address was
  96                                 not aligned to a region's starting address or if the length was
  97                                 greater than the number of bytes in the first region.
  98
  99   @retval EFI_SUCCESS           The region's attributes were successfully modified.
 100   @retval EFI_INVALID_PARAMETER If Start or Length describe an address not in the Legacy Region.
 101
 102 **/
 103 EFI_STATUS
 104 EFIAPI
 105 LegacyRegion2Lock (
 106   IN  EFI_LEGACY_REGION2_PROTOCOL  *This,
 107   IN  UINT32                       Start,
 108   IN  UINT32                       Length,
 109   OUT UINT32                       *Granularity
 110   );
 111
 112 /**
 113   Modify the hardware to disallow memory attribute changes in a region.
 114
 115   This function makes the attributes of a region read only. Once a region is boot-locked with this
 116   function, the read and write attributes of that region cannot be changed until a power cycle has
 117   reset the boot-lock attribute. Calls to Decode(), Lock() and Unlock() will have no effect.
 118
 119   @param  This[in]              Indicates the EFI_LEGACY_REGION_PROTOCOL instance.
 120   @param  Start[in]             The beginning of the physical address of the region whose
 121                                 attributes should be modified.
 122   @param  Length[in]            The number of bytes of memory whose attributes should be modified.
 123                                 The actual number of bytes modified may be greater than the number
 124                                 specified.
 125   @param  Granularity[out]      The number of bytes in the last region affected. This may be less
 126                                 than the total number of bytes affected if the starting address was
 127                                 not aligned to a region's starting address or if the length was
 128                                 greater than the number of bytes in the first region.
 129
 130   @retval EFI_SUCCESS           The region's attributes were successfully modified.
 131   @retval EFI_INVALID_PARAMETER If Start or Length describe an address not in the Legacy Region.
 132   @retval EFI_UNSUPPORTED       The chipset does not support locking the configuration registers in
 133                                 a way that will not affect memory regions outside the legacy memory
 134                                 region.
 135
 136 **/
 137 EFI_STATUS
 138 EFIAPI
 139 LegacyRegion2BootLock (
 140   IN EFI_LEGACY_REGION2_PROTOCOL  *This,
 141   IN  UINT32                      Start,
 142   IN  UINT32                      Length,
 143   OUT UINT32                      *Granularity
 144   );
 145
 146 /**
 147   Modify the hardware to allow memory writes in a region.
 148
 149   This function changes the attributes of a memory range to allow writes.
 150
 151   @param  This[in]              Indicates the EFI_LEGACY_REGION_PROTOCOL instance.
 152   @param  Start[in]             The beginning of the physical address of the region whose
 153                                 attributes should be modified.
 154   @param  Length[in]            The number of bytes of memory whose attributes should be modified.
 155                                 The actual number of bytes modified may be greater than the number
 156                                 specified.
 157   @param  Granularity[out]      The number of bytes in the last region affected. This may be less
 158                                 than the total number of bytes affected if the starting address was
 159                                 not aligned to a region's starting address or if the length was
 160                                 greater than the number of bytes in the first region.
 161
 162   @retval EFI_SUCCESS           The region's attributes were successfully modified.
 163   @retval EFI_INVALID_PARAMETER If Start or Length describe an address not in the Legacy Region.
 164
 165 **/
 166 EFI_STATUS
 167 EFIAPI
 168 LegacyRegion2Unlock (
 169   IN  EFI_LEGACY_REGION2_PROTOCOL  *This,
 170   IN  UINT32                       Start,
 171   IN  UINT32                       Length,
 172   OUT UINT32                       *Granularity
 173   );
 174
 175 /**
 176   Get region information for the attributes of the Legacy Region.
 177
 178   This function is used to discover the granularity of the attributes for the memory in the legacy
 179   region. Each attribute may have a different granularity and the granularity may not be the same
 180   for all memory ranges in the legacy region.
 181
 182   @param  This[in]              Indicates the EFI_LEGACY_REGION_PROTOCOL instance.
 183   @param  DescriptorCount[out]  The number of region descriptor entries returned in the Descriptor
 184                                 buffer.
 185   @param  Descriptor[out]       A pointer to a pointer used to return a buffer where the legacy
 186                                 region information is deposited. This buffer will contain a list of
 187                                 DescriptorCount number of region descriptors.  This function will
 188                                 provide the memory for the buffer.
 189
 190   @retval EFI_SUCCESS           The region's attributes were successfully modified.
 191   @retval EFI_INVALID_PARAMETER If Start or Length describe an address not in the Legacy Region.
 192
 193 **/
 194 EFI_STATUS
 195 EFIAPI
 196 LegacyRegionGetInfo (
 197   IN  EFI_LEGACY_REGION2_PROTOCOL   *This,
 198   OUT UINT32                        *DescriptorCount,
 199   OUT EFI_LEGACY_REGION_DESCRIPTOR  **Descriptor
 200   );
 201
 202 #endif