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