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