1 /** 2 **/ 3 /** 4 5 Copyright (c) 2012 - 2014, Intel Corporation. All rights reserved 6 7 This program and the accompanying materials are licensed and made available under 8 the terms and conditions of the BSD License that accompanies this distribution. 9 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 @file 18 Spi.h 19 20 @brief 21 This file defines the EFI SPI Protocol which implements the 22 Intel(R) ICH SPI Host Controller Compatibility Interface. 23 24 **/ 25 #ifndef _EFI_SPI_H_ 26 #define _EFI_SPI_H_ 27 28 29 // 30 #define EFI_SPI_PROTOCOL_GUID \ 31 { \ 32 0x1156efc6, 0xea32, 0x4396, 0xb5, 0xd5, 0x26, 0x93, 0x2e, 0x83, 0xc3, 0x13 \ 33 } 34 #define EFI_SMM_SPI_PROTOCOL_GUID \ 35 { \ 36 0xD9072C35, 0xEB8F, 0x43ad, 0xA2, 0x20, 0x34, 0xD4, 0x0E, 0x2A, 0x82, 0x85 \ 37 } 38 extern EFI_GUID gEfiSpiProtocolGuid; 39 extern EFI_GUID gEfiSmmSpiProtocolGuid; 40 41 /// 42 /// Forward reference for ANSI C compatibility 43 /// 44 typedef struct _EFI_SPI_PROTOCOL EFI_SPI_PROTOCOL; 45 46 /// 47 /// SPI protocol data structures and definitions 48 /// 49 /// 50 /// Number of Prefix Opcodes allowed on the SPI interface 51 /// 52 #define SPI_NUM_PREFIX_OPCODE 2 53 54 /// 55 /// Number of Opcodes in the Opcode Menu 56 /// 57 #define SPI_NUM_OPCODE 8 58 59 /// 60 /// Opcode Type 61 /// EnumSpiOpcodeCommand: Command without address 62 /// EnumSpiOpcodeRead: Read with address 63 /// EnumSpiOpcodeWrite: Write with address 64 /// 65 typedef enum { 66 EnumSpiOpcodeReadNoAddr, 67 EnumSpiOpcodeWriteNoAddr, 68 EnumSpiOpcodeRead, 69 EnumSpiOpcodeWrite, 70 EnumSpiOpcodeMax 71 } SPI_OPCODE_TYPE; 72 73 typedef enum { 74 EnumSpiCycle20MHz, 75 EnumSpiCycle33MHz, 76 EnumSpiCycle66MHz, /// Not supported by VLV 77 EnumSpiCycle50MHz, 78 EnumSpiCycleMax 79 } SPI_CYCLE_FREQUENCY; 80 81 typedef enum { 82 EnumSpiRegionAll, 83 EnumSpiRegionBios, 84 EnumSpiRegionSeC, 85 EnumSpiRegionDescriptor, 86 EnumSpiRegionPlatformData, 87 EnumSpiRegionMax 88 } SPI_REGION_TYPE; 89 90 /// 91 /// Hardware Sequencing required operations (as listed in Valleyview EDS "Hardware 92 /// Sequencing Commands and Opcode Requirements" 93 /// 94 typedef enum { 95 EnumSpiOperationWriteStatus, 96 EnumSpiOperationProgramData_1_Byte, 97 EnumSpiOperationProgramData_64_Byte, 98 EnumSpiOperationReadData, 99 EnumSpiOperationWriteDisable, 100 EnumSpiOperationReadStatus, 101 EnumSpiOperationWriteEnable, 102 EnumSpiOperationFastRead, 103 EnumSpiOperationEnableWriteStatus, 104 EnumSpiOperationErase_256_Byte, 105 EnumSpiOperationErase_4K_Byte, 106 EnumSpiOperationErase_8K_Byte, 107 EnumSpiOperationErase_64K_Byte, 108 EnumSpiOperationFullChipErase, 109 EnumSpiOperationJedecId, 110 EnumSpiOperationDualOutputFastRead, 111 EnumSpiOperationDiscoveryParameters, 112 EnumSpiOperationOther, 113 EnumSpiOperationMax 114 } SPI_OPERATION; 115 116 /// 117 /// SPI Command Configuration 118 /// Frequency The expected frequency to be used (value to be programmed to the SSFC 119 /// Register) 120 /// Operation Which Hardware Sequencing required operation this opcode respoinds to. 121 /// The required operations are listed in EDS Table 5-55: "Hardware 122 /// Sequencing Commands and Opcode Requirements" 123 /// If the opcode does not corresponds to any operation listed, use 124 /// EnumSpiOperationOther, and provides TYPE and Code for it in 125 /// SpecialOpcodeEntry. 126 /// 127 typedef struct _SPI_OPCODE_MENU_ENTRY { 128 SPI_OPCODE_TYPE Type; 129 UINT8 Code; 130 SPI_CYCLE_FREQUENCY Frequency; 131 SPI_OPERATION Operation; 132 } SPI_OPCODE_MENU_ENTRY; 133 134 // 135 // Initialization data table loaded to the SPI host controller 136 // VendorId Vendor ID of the SPI device 137 // DeviceId0 Device ID0 of the SPI device 138 // DeviceId1 Device ID1 of the SPI device 139 // PrefixOpcode Prefix opcodes which are loaded into the SPI host controller 140 // OpcodeMenu Opcodes which are loaded into the SPI host controller Opcode Menu 141 // BiosStartOffset The offset of the start of the BIOS image relative to the flash device. 142 // Please note this is a Flash Linear Address, NOT a memory space address. 143 // This value is platform specific and depends on the system flash map. 144 // This value is only used on non Descriptor mode. 145 // BiosSize The the BIOS Image size in flash. This value is platform specific 146 // and depends on the system flash map. Please note BIOS Image size may 147 // be smaller than BIOS Region size (in Descriptor Mode) or the flash size 148 // (in Non Descriptor Mode), and in this case, BIOS Image is supposed to be 149 // placed at the top end of the BIOS Region (in Descriptor Mode) or the flash 150 // (in Non Descriptor Mode) 151 // 152 typedef struct _SPI_INIT_TABLE { 153 UINT8 VendorId; 154 UINT8 DeviceId0; 155 UINT8 DeviceId1; 156 UINT8 PrefixOpcode[SPI_NUM_PREFIX_OPCODE]; 157 SPI_OPCODE_MENU_ENTRY OpcodeMenu[SPI_NUM_OPCODE]; 158 UINTN BiosStartOffset; 159 UINTN BiosSize; 160 } SPI_INIT_TABLE; 161 162 // 163 // Protocol member functions 164 // 165 typedef 166 EFI_STATUS 167 (EFIAPI *EFI_SPI_INIT) ( 168 IN EFI_SPI_PROTOCOL * This, 169 IN SPI_INIT_TABLE * InitTable 170 ); 171 172 /** 173 174 @brief 175 Initializes the host controller to execute SPI commands. 176 177 @param[in] This Pointer to the EFI_SPI_PROTOCOL instance. 178 @param[in] InitData Pointer to caller-allocated buffer containing the SPI 179 interface initialization table. 180 181 @retval EFI_SUCCESS Opcode initialization on the SPI host controller completed. 182 @retval EFI_ACCESS_DENIED The SPI configuration interface is locked. 183 @retval EFI_OUT_OF_RESOURCES Not enough resource available to initialize the device. 184 @retval EFI_DEVICE_ERROR Device error, operation failed. 185 186 **/ 187 188 typedef 189 EFI_STATUS 190 (EFIAPI *EFI_SPI_LOCK) ( 191 IN EFI_SPI_PROTOCOL * This 192 ); 193 /** 194 195 @brief 196 Initializes the host controller to execute SPI commands. 197 198 @param[in] This Pointer to the EFI_SPI_PROTOCOL instance. 199 @param[in] InitData Pointer to caller-allocated buffer containing the SPI 200 interface initialization table. 201 202 @retval EFI_SUCCESS Opcode initialization on the SPI host controller completed. 203 @retval EFI_ACCESS_DENIED The SPI configuration interface is locked. 204 @retval EFI_OUT_OF_RESOURCES Not enough resource available to initialize the device. 205 @retval EFI_DEVICE_ERROR Device error, operation failed. 206 207 **/ 208 209 typedef 210 EFI_STATUS 211 (EFIAPI *EFI_SPI_EXECUTE) ( 212 IN EFI_SPI_PROTOCOL * This, 213 IN UINT8 OpcodeIndex, 214 IN UINT8 PrefixOpcodeIndex, 215 IN BOOLEAN DataCycle, 216 IN BOOLEAN Atomic, 217 IN BOOLEAN ShiftOut, 218 IN UINTN Address, 219 IN UINT32 DataByteCount, 220 IN OUT UINT8 *Buffer, 221 IN SPI_REGION_TYPE SpiRegionType 222 ); 223 /** 224 225 @brief 226 Execute SPI commands from the host controller. 227 228 @param[in] This Pointer to the EFI_SPI_PROTOCOL instance. 229 @param[in] OpcodeIndex Index of the command in the OpCode Menu. 230 @param[in] PrefixOpcodeIndex Index of the first command to run when in an atomic cycle sequence. 231 @param[in] DataCycle TRUE if the SPI cycle contains data 232 @param[in] Atomic TRUE if the SPI cycle is atomic and interleave cycles are not allowed. 233 @param[in] ShiftOut If DataByteCount is not zero, TRUE to shift data out and FALSE to shift data in. 234 @param[in] Address In Descriptor Mode, for Descriptor Region, GbE Region, ME Region and Platform 235 Region, this value specifies the offset from the Region Base; for BIOS Region, 236 this value specifies the offset from the start of the BIOS Image. In Non 237 Descriptor Mode, this value specifies the offset from the start of the BIOS Image. 238 Please note BIOS Image size may be smaller than BIOS Region size (in Descriptor 239 Mode) or the flash size (in Non Descriptor Mode), and in this case, BIOS Image is 240 supposed to be placed at the top end of the BIOS Region (in Descriptor Mode) or 241 the flash (in Non Descriptor Mode) 242 @param[in] DataByteCount Number of bytes in the data portion of the SPI cycle. 243 @param[in] Buffer Pointer to caller-allocated buffer containing the dada received or sent during the SPI cycle. 244 @param[in] SpiRegionType SPI Region type. Values EnumSpiRegionBios, EnumSpiRegionGbE, EnumSpiRegionMe, 245 EnumSpiRegionDescriptor, and EnumSpiRegionPlatformData are only applicable in 246 Descriptor mode. Value EnumSpiRegionAll is applicable to both Descriptor Mode 247 and Non Descriptor Mode, which indicates "SpiRegionOffset" is actually relative 248 to base of the 1st flash device (i.e., it is a Flash Linear Address). 249 250 @retval EFI_SUCCESS Command succeed. 251 @retval EFI_INVALID_PARAMETER The parameters specified are not valid. 252 @exception EFI_UNSUPPORTED Command not supported. 253 @retval EFI_DEVICE_ERROR Device error, command aborts abnormally. 254 255 **/ 256 257 /// 258 /// Protocol definition 259 /// 260 struct _EFI_SPI_PROTOCOL { 261 EFI_SPI_INIT Init; 262 EFI_SPI_LOCK Lock; 263 EFI_SPI_EXECUTE Execute; 264 }; 265 266 #endif 267
