1 /** @file 2 This file defines the EFI SPI Protocol which implements the 3 Intel(R) ICH SPI Host Controller Compatibility Interface. 4 5 Copyright (c) 2013-2015 Intel Corporation. 6 7 This program and the accompanying materials 8 are licensed and made available under the terms and conditions of the BSD License 9 which accompanies this distribution. The full text of the license may be found at 10 http://opensource.org/licenses/bsd-license.php 11 12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 14 15 16 **/ 17 #ifndef _SPI_H_ 18 #define _SPI_H_ 19 20 // 21 // Define the SPI protocol GUID 22 // 23 // EDK and EDKII have different GUID formats 24 // 25 #if !defined(EDK_RELEASE_VERSION) || (EDK_RELEASE_VERSION < 0x00020000) 26 #define EFI_SPI_PROTOCOL_GUID \ 27 { \ 28 0x1156efc6, 0xea32, 0x4396, 0xb5, 0xd5, 0x26, 0x93, 0x2e, 0x83, 0xc3, 0x13 \ 29 } 30 #define EFI_SMM_SPI_PROTOCOL_GUID \ 31 { \ 32 0xD9072C35, 0xEB8F, 0x43ad, 0xA2, 0x20, 0x34, 0xD4, 0x0E, 0x2A, 0x82, 0x85 \ 33 } 34 #else 35 #define EFI_SPI_PROTOCOL_GUID \ 36 { \ 37 0x1156efc6, 0xea32, 0x4396, \ 38 { \ 39 0xb5, 0xd5, 0x26, 0x93, 0x2e, 0x83, 0xc3, 0x13 \ 40 } \ 41 } 42 #define EFI_SMM_SPI_PROTOCOL_GUID \ 43 { \ 44 0xD9072C35, 0xEB8F, 0x43ad, \ 45 { \ 46 0xA2, 0x20, 0x34, 0xD4, 0x0E, 0x2A, 0x82, 0x85 \ 47 } \ 48 } 49 #endif 50 // 51 // Extern the GUID for protocol users. 52 // 53 extern EFI_GUID gEfiSpiProtocolGuid; 54 extern EFI_GUID gEfiSmmSpiProtocolGuid; 55 56 // 57 // Forward reference for ANSI C compatibility 58 // 59 typedef struct _EFI_SPI_PROTOCOL EFI_SPI_PROTOCOL; 60 61 // 62 // SPI protocol data structures and definitions 63 // 64 // 65 // Number of Prefix Opcodes allowed on the SPI interface 66 // 67 #define SPI_NUM_PREFIX_OPCODE 2 68 69 // 70 // Number of Opcodes in the Opcode Menu 71 // 72 #define SPI_NUM_OPCODE 8 73 74 #ifdef SERVER_BIOS_FLAG 75 // 76 // SPI default opcode slots 77 // 78 #define SPI_OPCODE_JEDEC_ID_INDEX 0 79 #endif // SERVER_BIOS_FLAG 80 81 // 82 // Opcode Type 83 // EnumSpiOpcodeCommand: Command without address 84 // EnumSpiOpcodeRead: Read with address 85 // EnumSpiOpcodeWrite: Write with address 86 // 87 typedef enum { 88 EnumSpiOpcodeReadNoAddr, 89 EnumSpiOpcodeWriteNoAddr, 90 EnumSpiOpcodeRead, 91 EnumSpiOpcodeWrite, 92 EnumSpiOpcodeMax 93 } SPI_OPCODE_TYPE; 94 95 typedef enum { 96 EnumSpiCycle20MHz, 97 EnumSpiCycle33MHz, 98 EnumSpiCycle66MHz, // not supported by PCH 99 EnumSpiCycle50MHz, 100 EnumSpiCycleMax 101 } SPI_CYCLE_FREQUENCY; 102 103 typedef enum { 104 EnumSpiRegionAll, 105 EnumSpiRegionBios, 106 EnumSpiRegionMe, 107 EnumSpiRegionGbE, 108 EnumSpiRegionDescriptor, 109 EnumSpiRegionPlatformData, 110 EnumSpiRegionMax 111 } SPI_REGION_TYPE; 112 113 // 114 // Hardware Sequencing required operations (as listed in CougarPoint EDS Table 5-55: "Hardware 115 // Sequencing Commands and Opcode Requirements" 116 // 117 typedef enum { 118 EnumSpiOperationWriteStatus, 119 EnumSpiOperationProgramData_1_Byte, 120 EnumSpiOperationProgramData_64_Byte, 121 EnumSpiOperationReadData, 122 EnumSpiOperationWriteDisable, 123 EnumSpiOperationReadStatus, 124 EnumSpiOperationWriteEnable, 125 EnumSpiOperationFastRead, 126 EnumSpiOperationEnableWriteStatus, 127 EnumSpiOperationErase_256_Byte, 128 EnumSpiOperationErase_4K_Byte, 129 EnumSpiOperationErase_8K_Byte, 130 EnumSpiOperationErase_64K_Byte, 131 EnumSpiOperationFullChipErase, 132 EnumSpiOperationJedecId, 133 EnumSpiOperationDualOutputFastRead, 134 EnumSpiOperationDiscoveryParameters, 135 EnumSpiOperationOther, 136 EnumSpiOperationMax 137 } SPI_OPERATION; 138 139 // 140 // Opcode menu entries 141 // Type Operation Type (value to be programmed to the OPTYPE register) 142 // Code The opcode (value to be programmed to the OPMENU register) 143 // Frequency The expected frequency to be used (value to be programmed to the SSFC 144 // Register) 145 // Operation Which Hardware Sequencing required operation this opcode respoinds to. 146 // The required operations are listed in EDS Table 5-55: "Hardware 147 // Sequencing Commands and Opcode Requirements" 148 // If the opcode does not corresponds to any operation listed, use 149 // EnumSpiOperationOther 150 // 151 typedef struct _SPI_OPCODE_MENU_ENTRY { 152 SPI_OPCODE_TYPE Type; 153 UINT8 Code; 154 SPI_CYCLE_FREQUENCY Frequency; 155 SPI_OPERATION Operation; 156 } SPI_OPCODE_MENU_ENTRY; 157 158 // 159 // Initialization data table loaded to the SPI host controller 160 // VendorId Vendor ID of the SPI device 161 // DeviceId0 Device ID0 of the SPI device 162 // DeviceId1 Device ID1 of the SPI device 163 // PrefixOpcode Prefix opcodes which are loaded into the SPI host controller 164 // OpcodeMenu Opcodes which are loaded into the SPI host controller Opcode Menu 165 // BiosStartOffset The offset of the start of the BIOS image relative to the flash device. 166 // Please note this is a Flash Linear Address, NOT a memory space address. 167 // This value is platform specific and depends on the system flash map. 168 // This value is only used on non Descriptor mode. 169 // BiosSize The the BIOS Image size in flash. This value is platform specific 170 // and depends on the system flash map. Please note BIOS Image size may 171 // be smaller than BIOS Region size (in Descriptor Mode) or the flash size 172 // (in Non Descriptor Mode), and in this case, BIOS Image is supposed to be 173 // placed at the top end of the BIOS Region (in Descriptor Mode) or the flash 174 // (in Non Descriptor Mode) 175 // 176 typedef struct _SPI_INIT_TABLE { 177 UINT8 VendorId; 178 UINT8 DeviceId0; 179 UINT8 DeviceId1; 180 UINT8 PrefixOpcode[SPI_NUM_PREFIX_OPCODE]; 181 SPI_OPCODE_MENU_ENTRY OpcodeMenu[SPI_NUM_OPCODE]; 182 UINTN BiosStartOffset; 183 UINTN BiosSize; 184 } SPI_INIT_TABLE; 185 186 // 187 // Public Info struct to show current initialized state of the spi interface. 188 // OpcodeIndex must be less then SPI_NUM_OPCODE for operation to be supported. 189 // 190 typedef struct _SPI_INIT_INFO { 191 SPI_INIT_TABLE *InitTable; 192 UINT8 JedecIdOpcodeIndex; 193 UINT8 OtherOpcodeIndex; 194 UINT8 WriteStatusOpcodeIndex; 195 UINT8 ProgramOpcodeIndex; 196 UINT8 ReadOpcodeIndex; 197 UINT8 EraseOpcodeIndex; 198 UINT8 ReadStatusOpcodeIndex; 199 UINT8 FullChipEraseOpcodeIndex; 200 } SPI_INIT_INFO; 201 202 // 203 // Protocol member functions 204 // 205 206 typedef 207 EFI_STATUS 208 (EFIAPI *EFI_SPI_INIT) ( 209 IN EFI_SPI_PROTOCOL * This, 210 IN SPI_INIT_TABLE * InitTable 211 ); 212 /*++ 213 214 Routine Description: 215 216 Initializes the host controller to execute SPI commands. 217 218 Arguments: 219 220 This Pointer to the EFI_SPI_PROTOCOL instance. 221 InitTable Pointer to caller-allocated buffer containing the SPI 222 interface initialization table. 223 224 Returns: 225 226 EFI_SUCCESS Opcode initialization on the SPI host controller completed. 227 EFI_ACCESS_DENIED The SPI configuration interface is locked. 228 EFI_OUT_OF_RESOURCES Not enough resource available to initialize the device. 229 EFI_DEVICE_ERROR Device error, operation failed. 230 231 --*/ 232 233 typedef 234 EFI_STATUS 235 (EFIAPI *EFI_SPI_LOCK) ( 236 IN EFI_SPI_PROTOCOL * This 237 ); 238 /*++ 239 240 Routine Description: 241 242 Lock the SPI Static Configuration Interface. 243 Once locked, the interface is no longer open for configuration changes. 244 The lock state automatically clears on next system reset. 245 246 Arguments: 247 248 This Pointer to the EFI_SPI_PROTOCOL instance. 249 250 Returns: 251 252 EFI_SUCCESS Lock operation succeed. 253 EFI_DEVICE_ERROR Device error, operation failed. 254 EFI_ACCESS_DENIED The interface has already been locked. 255 256 --*/ 257 258 typedef 259 EFI_STATUS 260 (EFIAPI *EFI_SPI_EXECUTE) ( 261 IN EFI_SPI_PROTOCOL * This, 262 IN UINT8 OpcodeIndex, 263 IN UINT8 PrefixOpcodeIndex, 264 IN BOOLEAN DataCycle, 265 IN BOOLEAN Atomic, 266 IN BOOLEAN ShiftOut, 267 IN UINTN Address, 268 IN UINT32 DataByteCount, 269 IN OUT UINT8 *Buffer, 270 IN SPI_REGION_TYPE SpiRegionType 271 ); 272 /*++ 273 274 Routine Description: 275 276 Execute SPI commands from the host controller. 277 278 Arguments: 279 280 This Pointer to the EFI_SPI_PROTOCOL instance. 281 OpcodeIndex Index of the command in the OpCode Menu. 282 PrefixOpcodeIndex Index of the first command to run when in an atomic cycle sequence. 283 DataCycle TRUE if the SPI cycle contains data 284 Atomic TRUE if the SPI cycle is atomic and interleave cycles are not allowed. 285 ShiftOut If DataByteCount is not zero, TRUE to shift data out and FALSE to shift data in. 286 Address In Descriptor Mode, for Descriptor Region, GbE Region, ME Region and Platform 287 Region, this value specifies the offset from the Region Base; for BIOS Region, 288 this value specifies the offset from the start of the BIOS Image. In Non 289 Descriptor Mode, this value specifies the offset from the start of the BIOS Image. 290 Please note BIOS Image size may be smaller than BIOS Region size (in Descriptor 291 Mode) or the flash size (in Non Descriptor Mode), and in this case, BIOS Image is 292 supposed to be placed at the top end of the BIOS Region (in Descriptor Mode) or 293 the flash (in Non Descriptor Mode) 294 DataByteCount Number of bytes in the data portion of the SPI cycle. 295 Buffer Pointer to caller-allocated buffer containing the dada received or sent during the SPI cycle. 296 SpiRegionType SPI Region type. Values EnumSpiRegionBios, EnumSpiRegionGbE, EnumSpiRegionMe, 297 EnumSpiRegionDescriptor, and EnumSpiRegionPlatformData are only applicable in 298 Descriptor mode. Value EnumSpiRegionAll is applicable to both Descriptor Mode 299 and Non Descriptor Mode, which indicates "SpiRegionOffset" is actually relative 300 to base of the 1st flash device (i.e., it is a Flash Linear Address). 301 302 Returns: 303 304 EFI_SUCCESS Command succeed. 305 EFI_INVALID_PARAMETER The parameters specified are not valid. 306 EFI_UNSUPPORTED Command not supported. 307 EFI_DEVICE_ERROR Device error, command aborts abnormally. 308 309 --*/ 310 311 typedef 312 EFI_STATUS 313 (EFIAPI *EFI_SPI_INFO) ( 314 IN EFI_SPI_PROTOCOL *This, 315 OUT SPI_INIT_INFO **InitInfoPtr 316 ); 317 /*++ 318 319 Routine Description: 320 321 Return info about SPI host controller, to help callers usage of Execute 322 service. 323 324 If 0xff is returned as an opcode index in init info struct 325 then device does not support the operation. 326 327 Arguments: 328 329 This Pointer to the EFI_SPI_PROTOCOL instance. 330 InitInfoPtr Pointer to init info written to this memory location. 331 332 Returns: 333 334 EFI_SUCCESS Information returned. 335 EFI_INVALID_PARAMETER Invalid parameter. 336 EFI_NOT_READY Required resources not setup. 337 Others Unexpected error happened. 338 339 --*/ 340 341 // 342 // Protocol definition 343 // 344 struct _EFI_SPI_PROTOCOL { 345 EFI_SPI_INIT Init; 346 EFI_SPI_LOCK Lock; 347 EFI_SPI_EXECUTE Execute; 348 EFI_SPI_INFO Info; 349 }; 350 351 #endif 352