MdePkg/Include/Protocol/LegacyRegion2.h

   1 /** @file
   2   The Legacy Region Protocol controls the read, write and boot-lock attributes for
   3   the region 0xC0000 to 0xFFFFF.
   4
   5   Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR>
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8   @par Revision Reference:
   9   This Protocol is defined in UEFI Platform Initialization Specification 1.2
  10   Volume 5: Standards
  11
  12 **/
  13
  14 #ifndef __LEGACY_REGION2_H__
  15 #define __LEGACY_REGION2_H__
  16
  17 #define EFI_LEGACY_REGION2_PROTOCOL_GUID \
  18 { \
  19   0x70101eaf, 0x85, 0x440c, {0xb3, 0x56, 0x8e, 0xe3, 0x6f, 0xef, 0x24, 0xf0 } \
  20 }
  21
  22 typedef struct _EFI_LEGACY_REGION2_PROTOCOL EFI_LEGACY_REGION2_PROTOCOL;
  23
  24 /**
  25   Modify the hardware to allow (decode) or disallow (not decode) memory reads in a region.
  26
  27   If the On parameter evaluates to TRUE, this function enables memory reads in the address range
  28   Start to (Start + Length - 1).
  29   If the On parameter evaluates to FALSE, this function disables memory reads in the address range
  30   Start to (Start + Length - 1).
  31
  32   @param  This[in]              Indicates the EFI_LEGACY_REGION2_PROTOCOL instance.
  33   @param  Start[in]             The beginning of the physical address of the region whose attributes
  34                                 should be modified.
  35   @param  Length[in]            The number of bytes of memory whose attributes should be modified.
  36                                 The actual number of bytes modified may be greater than the number
  37                                 specified.
  38   @param  Granularity[out]      The number of bytes in the last region affected. This may be less
  39                                 than the total number of bytes affected if the starting address
  40                                 was not aligned to a region's starting address or if the length
  41                                 was greater than the number of bytes in the first region.
  42   @param  On[in]                Decode / Non-Decode flag.
  43
  44   @retval EFI_SUCCESS           The region's attributes were successfully modified.
  45   @retval EFI_INVALID_PARAMETER If Start or Length describe an address not in the Legacy Region.
  46
  47 **/
  48 typedef
  49 EFI_STATUS
  50 (EFIAPI *EFI_LEGACY_REGION2_DECODE)(
  51   IN  EFI_LEGACY_REGION2_PROTOCOL  *This,
  52   IN  UINT32                       Start,
  53   IN  UINT32                       Length,
  54   OUT UINT32                       *Granularity,
  55   IN  BOOLEAN                      *On
  56   );
  57
  58 /**
  59   Modify the hardware to disallow memory writes in a region.
  60
  61   This function changes the attributes of a memory range to not allow writes.
  62
  63   @param  This[in]              Indicates the EFI_LEGACY_REGION2_PROTOCOL instance.
  64   @param  Start[in]             The beginning of the physical address of the region whose
  65                                 attributes should be modified.
  66   @param  Length[in]            The number of bytes of memory whose attributes should be modified.
  67                                 The actual number of bytes modified may be greater than the number
  68                                 specified.
  69   @param  Granularity[out]      The number of bytes in the last region affected. This may be less
  70                                 than the total number of bytes affected if the starting address was
  71                                 not aligned to a region's starting address or if the length was
  72                                 greater than the number of bytes in the first region.
  73
  74   @retval EFI_SUCCESS           The region's attributes were successfully modified.
  75   @retval EFI_INVALID_PARAMETER If Start or Length describe an address not in the Legacy Region.
  76
  77 **/
  78 typedef
  79 EFI_STATUS
  80 (EFIAPI *EFI_LEGACY_REGION2_LOCK)(
  81   IN  EFI_LEGACY_REGION2_PROTOCOL   *This,
  82   IN  UINT32                        Start,
  83   IN  UINT32                        Length,
  84   OUT UINT32                        *Granularity
  85   );
  86
  87 /**
  88   Modify the hardware to disallow memory attribute changes in a region.
  89
  90   This function makes the attributes of a region read only. Once a region is boot-locked with this
  91   function, the read and write attributes of that region cannot be changed until a power cycle has
  92   reset the boot-lock attribute. Calls to Decode(), Lock() and Unlock() will have no effect.
  93
  94   @param  This[in]              Indicates the EFI_LEGACY_REGION2_PROTOCOL instance.
  95   @param  Start[in]             The beginning of the physical address of the region whose
  96                                 attributes should be modified.
  97   @param  Length[in]            The number of bytes of memory whose attributes should be modified.
  98                                 The actual number of bytes modified may be greater than the number
  99                                 specified.
 100   @param  Granularity[out]      The number of bytes in the last region affected. This may be less
 101                                 than the total number of bytes affected if the starting address was
 102                                 not aligned to a region's starting address or if the length was
 103                                 greater than the number of bytes in the first region.
 104
 105   @retval EFI_SUCCESS           The region's attributes were successfully modified.
 106   @retval EFI_INVALID_PARAMETER If Start or Length describe an address not in the Legacy Region.
 107   @retval EFI_UNSUPPORTED       The chipset does not support locking the configuration registers in
 108                                 a way that will not affect memory regions outside the legacy memory
 109                                 region.
 110
 111 **/
 112 typedef
 113 EFI_STATUS
 114 (EFIAPI *EFI_LEGACY_REGION2_BOOT_LOCK)(
 115   IN  EFI_LEGACY_REGION2_PROTOCOL         *This,
 116   IN  UINT32                              Start,
 117   IN  UINT32                              Length,
 118   OUT UINT32                              *Granularity OPTIONAL
 119   );
 120
 121 /**
 122   Modify the hardware to allow memory writes in a region.
 123
 124   This function changes the attributes of a memory range to allow writes.
 125
 126   @param  This[in]              Indicates the EFI_LEGACY_REGION2_PROTOCOL instance.
 127   @param  Start[in]             The beginning of the physical address of the region whose
 128                                 attributes should be modified.
 129   @param  Length[in]            The number of bytes of memory whose attributes should be modified.
 130                                 The actual number of bytes modified may be greater than the number
 131                                 specified.
 132   @param  Granularity[out]      The number of bytes in the last region affected. This may be less
 133                                 than the total number of bytes affected if the starting address was
 134                                 not aligned to a region's starting address or if the length was
 135                                 greater than the number of bytes in the first region.
 136
 137   @retval EFI_SUCCESS           The region's attributes were successfully modified.
 138   @retval EFI_INVALID_PARAMETER If Start or Length describe an address not in the Legacy Region.
 139
 140 **/
 141 typedef
 142 EFI_STATUS
 143 (EFIAPI *EFI_LEGACY_REGION2_UNLOCK)(
 144   IN  EFI_LEGACY_REGION2_PROTOCOL  *This,
 145   IN  UINT32                       Start,
 146   IN  UINT32                       Length,
 147   OUT UINT32                       *Granularity
 148   );
 149
 150 typedef enum {
 151   LegacyRegionDecoded,         ///< This region is currently set to allow reads.
 152   LegacyRegionNotDecoded,      ///< This region is currently set to not allow reads.
 153   LegacyRegionWriteEnabled,    ///< This region is currently set to allow writes.
 154   LegacyRegionWriteDisabled,   ///< This region is currently set to write protected.
 155   LegacyRegionBootLocked,      ///< This region's attributes are locked, cannot be modified until
 156                                ///< after a power cycle.
 157   LegacyRegionNotLocked        ///< This region's attributes are not locked.
 158 } EFI_LEGACY_REGION_ATTRIBUTE;
 159
 160 typedef struct {
 161   ///
 162   /// The beginning of the physical address of this
 163   /// region.
 164   ///
 165   UINT32                         Start;
 166   ///
 167   /// The number of bytes in this region.
 168   ///
 169   UINT32                         Length;
 170   ///
 171   /// Attribute of the Legacy Region Descriptor that
 172   /// describes the capabilities for that memory region.
 173   ///
 174   EFI_LEGACY_REGION_ATTRIBUTE    Attribute;
 175   ///
 176   /// Describes the byte length programmability
 177   /// associated with the Start address and the specified
 178   /// Attribute setting.
 179   UINT32                         Granularity;
 180 } EFI_LEGACY_REGION_DESCRIPTOR;
 181
 182 /**
 183   Get region information for the attributes of the Legacy Region.
 184
 185   This function is used to discover the granularity of the attributes for the memory in the legacy
 186   region. Each attribute may have a different granularity and the granularity may not be the same
 187   for all memory ranges in the legacy region.
 188
 189   @param  This[in]              Indicates the EFI_LEGACY_REGION2_PROTOCOL instance.
 190   @param  DescriptorCount[out]  The number of region descriptor entries returned in the Descriptor
 191                                 buffer.
 192   @param  Descriptor[out]       A pointer to a pointer used to return a buffer where the legacy
 193                                 region information is deposited. This buffer will contain a list of
 194                                 DescriptorCount number of region descriptors.  This function will
 195                                 provide the memory for the buffer.
 196
 197   @retval EFI_SUCCESS           The information structure was returned.
 198   @retval EFI_UNSUPPORTED       This function is not supported.
 199
 200 **/
 201 typedef
 202 EFI_STATUS
 203 (EFIAPI *EFI_LEGACY_REGION_GET_INFO)(
 204   IN  EFI_LEGACY_REGION2_PROTOCOL   *This,
 205   OUT UINT32                        *DescriptorCount,
 206   OUT EFI_LEGACY_REGION_DESCRIPTOR  **Descriptor
 207   );
 208
 209 ///
 210 /// The EFI_LEGACY_REGION2_PROTOCOL is used to abstract the hardware control of the memory
 211 /// attributes of the Option ROM shadowing region, 0xC0000 to 0xFFFFF.
 212 /// There are three memory attributes that can be modified through this protocol: read, write and
 213 /// boot-lock. These protocols may be set in any combination.
 214 ///
 215 struct _EFI_LEGACY_REGION2_PROTOCOL {
 216   EFI_LEGACY_REGION2_DECODE       Decode;
 217   EFI_LEGACY_REGION2_LOCK         Lock;
 218   EFI_LEGACY_REGION2_BOOT_LOCK    BootLock;
 219   EFI_LEGACY_REGION2_UNLOCK       UnLock;
 220   EFI_LEGACY_REGION_GET_INFO      GetInfo;
 221 };
 222
 223 extern EFI_GUID  gEfiLegacyRegion2ProtocolGuid;
 224
 225 #endif