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 240