1 /** @file 2 Header file for the PCH SPI Common Driver. 3 4 Copyright (c) 2013-2015 Intel Corporation. 5 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 **/ 15 #ifndef _SPI_COMMON_H_ 16 #define _SPI_COMMON_H_ 17 18 #include "Protocol/Spi.h" 19 #include <Library/PciLib.h> 20 #include <Library/IoLib.h> 21 #include <Library/DebugLib.h> 22 #include <Library/PcdLib.h> 23 #include <Library/BaseMemoryLib.h> 24 #include <Library/IntelQNCLib.h> 25 #include <Library/QNCAccessLib.h> 26 #include <Uefi/UefiBaseType.h> 27 28 // 29 // Maximum time allowed while waiting the SPI cycle to complete 30 // Wait Time = 6 seconds = 6000000 microseconds 31 // Wait Period = 10 microseconds 32 // 33 #define WAIT_TIME 6000000 34 #define WAIT_PERIOD 10 35 // 36 // PCH Required SPI Commands -------- COMMAND SET I ------------ 37 // SPI flash device must support in order to be compatible with PCH 38 // 39 #define PCH_SPI_COMMAND_PROGRAM_BYTE 0x02 40 #define PCH_SPI_COMMAND_READ_DATA 0x03 41 #define PCH_SPI_COMMAND_WRITE_DISABLE 0x04 42 #define PCH_SPI_COMMAND_READ_STATUS 0x05 43 #define PCH_SPI_COMMAND_WRITE_ENABLE 0x06 44 #define PCH_SPI_COMMAND_FAST_READ 0x0B 45 #define PCH_SPI_COMMAND_READ_ID 0x9F 46 #define PCH_SPI_COMMAND_DUAL_FAST_READ 0x3B // Dual Output Fast Read 47 48 // 49 // Need to support at least one of the following two kinds of size of sector for erasing 50 // 51 #define PCH_SPI_COMMAND_4KB_ERASE 0x20 52 #define PCH_SPI_COMMAND_64KB_ERASE 0xD8 53 // 54 // Recommended SPI Commands -------- COMMAND SET II ------------ 55 // SPI flash device best to support 56 // 57 #define PCH_SPI_COMMAND_WRITE_STATUS 0x01 58 #define PCH_SPI_COMMAND_FULL_CHIP_ERASE 0xC7 59 60 // 61 // Private data structure definitions for the driver 62 // 63 #define PCH_SPI_PRIVATE_DATA_SIGNATURE SIGNATURE_32 ('P', 'S', 'P', 'I') 64 65 typedef struct { 66 UINTN Signature; 67 EFI_HANDLE Handle; 68 EFI_SPI_PROTOCOL SpiProtocol; 69 SPI_INIT_TABLE SpiInitTable; 70 UINTN PchRootComplexBar; 71 BOOLEAN InitDone; // Set to TRUE on SpiProtocolInit SUCCESS. 72 SPI_INIT_INFO InitInfo; 73 } SPI_INSTANCE; 74 75 #define SPI_INSTANCE_FROM_SPIPROTOCOL(a) CR (a, SPI_INSTANCE, SpiProtocol, PCH_SPI_PRIVATE_DATA_SIGNATURE) 76 77 // 78 // Function prototypes used by the SPI protocol. 79 // 80 EFI_STATUS 81 SpiProtocolConstructor ( 82 SPI_INSTANCE *SpiInstance 83 ) 84 /*++ 85 86 Routine Description: 87 88 Initialize an SPI protocol instance. 89 The function will assert in debug if PCH RCBA has not been initialized 90 91 Arguments: 92 93 SpiInstance - Pointer to SpiInstance to initialize 94 95 Returns: 96 97 EFI_SUCCESS The protocol instance was properly initialized 98 EFI_UNSUPPORTED The PCH is not supported by this module 99 100 --*/ 101 ; 102 103 EFI_STATUS 104 EFIAPI 105 SpiProtocolInit ( 106 IN EFI_SPI_PROTOCOL *This, 107 IN SPI_INIT_TABLE *InitTable 108 ) 109 /*++ 110 111 Routine Description: 112 113 Initialize the host controller to execute SPI command. 114 115 Arguments: 116 117 This Pointer to the EFI_SPI_PROTOCOL instance. 118 InitTable Initialization data to be programmed into the SPI host controller. 119 120 Returns: 121 122 EFI_SUCCESS Initialization completed. 123 EFI_ACCESS_DENIED The SPI static configuration interface has been locked-down. 124 EFI_INVALID_PARAMETER Bad input parameters. 125 --*/ 126 ; 127 128 EFI_STATUS 129 EFIAPI 130 SpiProtocolLock ( 131 IN EFI_SPI_PROTOCOL *This 132 ) 133 /*++ 134 135 Routine Description: 136 137 Lock the SPI Static Configuration Interface. 138 Once locked, the interface can not be changed and can only be clear by system reset. 139 140 Arguments: 141 142 This Pointer to the EFI_SPI_PROTOCOL instance. 143 144 Returns: 145 146 EFI_SUCCESS Lock operation succeed. 147 EFI_DEVICE_ERROR Device error, operation failed. 148 EFI_ACCESS_DENIED The interface has already been locked. 149 150 --*/ 151 ; 152 153 EFI_STATUS 154 EFIAPI 155 SpiProtocolExecute ( 156 IN EFI_SPI_PROTOCOL *This, 157 IN UINT8 OpcodeIndex, 158 IN UINT8 PrefixOpcodeIndex, 159 IN BOOLEAN DataCycle, 160 IN BOOLEAN Atomic, 161 IN BOOLEAN ShiftOut, 162 IN UINTN Address, 163 IN UINT32 DataByteCount, 164 IN OUT UINT8 *Buffer, 165 IN SPI_REGION_TYPE SpiRegionType 166 ) 167 /*++ 168 169 Routine Description: 170 171 Execute SPI commands from the host controller. 172 173 Arguments: 174 175 This Pointer to the EFI_SPI_PROTOCOL instance. 176 OpcodeIndex Index of the command in the OpCode Menu. 177 PrefixOpcodeIndex Index of the first command to run when in an atomic cycle sequence. 178 DataCycle TRUE if the SPI cycle contains data 179 Atomic TRUE if the SPI cycle is atomic and interleave cycles are not allowed. 180 ShiftOut If DataByteCount is not zero, TRUE to shift data out and FALSE to shift data in. 181 Address In Descriptor Mode, for Descriptor Region, GbE Region, ME Region and Platform 182 Region, this value specifies the offset from the Region Base; for BIOS Region, 183 this value specifies the offset from the start of the BIOS Image. In Non 184 Descriptor Mode, this value specifies the offset from the start of the BIOS Image. 185 Please note BIOS Image size may be smaller than BIOS Region size (in Descriptor 186 Mode) or the flash size (in Non Descriptor Mode), and in this case, BIOS Image is 187 supposed to be placed at the top end of the BIOS Region (in Descriptor Mode) or 188 the flash (in Non Descriptor Mode) 189 DataByteCount Number of bytes in the data portion of the SPI cycle. 190 Buffer Pointer to caller-allocated buffer containing the dada received or sent during the SPI cycle. 191 SpiRegionType SPI Region type. Values EnumSpiRegionBios, EnumSpiRegionGbE, EnumSpiRegionMe, 192 EnumSpiRegionDescriptor, and EnumSpiRegionPlatformData are only applicable in 193 Descriptor mode. Value EnumSpiRegionAll is applicable to both Descriptor Mode 194 and Non Descriptor Mode, which indicates "SpiRegionOffset" is actually relative 195 to base of the 1st flash device (i.e., it is a Flash Linear Address). 196 197 Returns: 198 199 EFI_SUCCESS Command succeed. 200 EFI_INVALID_PARAMETER The parameters specified are not valid. 201 EFI_UNSUPPORTED Command not supported. 202 EFI_DEVICE_ERROR Device error, command aborts abnormally. 203 204 --*/ 205 ; 206 207 EFI_STATUS 208 SendSpiCmd ( 209 IN EFI_SPI_PROTOCOL *This, 210 IN UINT8 OpcodeIndex, 211 IN UINT8 PrefixOpcodeIndex, 212 IN BOOLEAN DataCycle, 213 IN BOOLEAN Atomic, 214 IN BOOLEAN ShiftOut, 215 IN UINTN Address, 216 IN UINT32 DataByteCount, 217 IN OUT UINT8 *Buffer, 218 IN SPI_REGION_TYPE SpiRegionType 219 ) 220 /*++ 221 222 Routine Description: 223 224 This function sends the programmed SPI command to the slave device. 225 226 Arguments: 227 228 OpcodeIndex Index of the command in the OpCode Menu. 229 PrefixOpcodeIndex Index of the first command to run when in an atomic cycle sequence. 230 DataCycle TRUE if the SPI cycle contains data 231 Atomic TRUE if the SPI cycle is atomic and interleave cycles are not allowed. 232 ShiftOut If DataByteCount is not zero, TRUE to shift data out and FALSE to shift data in. 233 Address In Descriptor Mode, for Descriptor Region, GbE Region, ME Region and Platform 234 Region, this value specifies the offset from the Region Base; for BIOS Region, 235 this value specifies the offset from the start of the BIOS Image. In Non 236 Descriptor Mode, this value specifies the offset from the start of the BIOS Image. 237 Please note BIOS Image size may be smaller than BIOS Region size (in Descriptor 238 Mode) or the flash size (in Non Descriptor Mode), and in this case, BIOS Image is 239 supposed to be placed at the top end of the BIOS Region (in Descriptor Mode) or 240 the flash (in Non Descriptor Mode) 241 DataByteCount Number of bytes in the data portion of the SPI cycle. This function may break the 242 data transfer into multiple operations. This function ensures each operation does 243 not cross 256 byte flash address boundary. 244 *NOTE: if there is some SPI chip that has a stricter address boundary requirement 245 (e.g., its write page size is < 256 byte), then the caller cannot rely on this 246 function to cut the data transfer at proper address boundaries, and it's the 247 caller's reponsibility to pass in a properly cut DataByteCount parameter. 248 Buffer Data received or sent during the SPI cycle. 249 SpiRegionType SPI Region type. Values EnumSpiRegionBios, EnumSpiRegionGbE, EnumSpiRegionMe, 250 EnumSpiRegionDescriptor, and EnumSpiRegionPlatformData are only applicable in 251 Descriptor mode. Value EnumSpiRegionAll is applicable to both Descriptor Mode 252 and Non Descriptor Mode, which indicates "SpiRegionOffset" is actually relative 253 to base of the 1st flash device (i.e., it is a Flash Linear Address). 254 255 Returns: 256 257 EFI_SUCCESS SPI command completes successfully. 258 EFI_DEVICE_ERROR Device error, the command aborts abnormally. 259 EFI_ACCESS_DENIED Some unrecognized command encountered in hardware sequencing mode 260 EFI_INVALID_PARAMETER The parameters specified are not valid. 261 262 --*/ 263 ; 264 265 BOOLEAN 266 WaitForSpiCycleComplete ( 267 IN EFI_SPI_PROTOCOL *This, 268 IN BOOLEAN ErrorCheck 269 ) 270 /*++ 271 272 Routine Description: 273 274 Wait execution cycle to complete on the SPI interface. Check both Hardware 275 and Software Sequencing status registers 276 277 Arguments: 278 279 This - The SPI protocol instance 280 UseSoftwareSequence - TRUE if this is a Hardware Sequencing operation 281 ErrorCheck - TRUE if the SpiCycle needs to do the error check 282 283 Returns: 284 285 TRUE SPI cycle completed on the interface. 286 FALSE Time out while waiting the SPI cycle to complete. 287 It's not safe to program the next command on the SPI interface. 288 289 --*/ 290 ; 291 292 EFI_STATUS 293 EFIAPI 294 SpiProtocolInfo ( 295 IN EFI_SPI_PROTOCOL *This, 296 OUT SPI_INIT_INFO **InitInfoPtr 297 ) 298 /*++ 299 300 Routine Description: 301 302 Return info about SPI host controller, to help callers usage of Execute 303 service. 304 305 If 0xff is returned as an opcode index in init info struct 306 then device does not support the operation. 307 308 Arguments: 309 310 This Pointer to the EFI_SPI_PROTOCOL instance. 311 InitInfoPtr Pointer to init info written to this memory location. 312 313 Returns: 314 315 EFI_SUCCESS Information returned. 316 EFI_INVALID_PARAMETER Invalid parameter. 317 EFI_NOT_READY Required resources not setup. 318 Others Unexpected error happened. 319 320 --*/ 321 ; 322 323 #endif 324