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