5 Copyright (c) 2012 - 2014, Intel Corporation. All rights reserved
7 SPDX-License-Identifier: BSD-2-Clause-Patent
15 This file defines the EFI SPI Protocol which implements the
16 Intel(R) ICH SPI Host Controller Compatibility Interface.
24 #define EFI_SPI_PROTOCOL_GUID \
26 0x1156efc6, 0xea32, 0x4396, 0xb5, 0xd5, 0x26, 0x93, 0x2e, 0x83, 0xc3, 0x13 \
28 #define EFI_SMM_SPI_PROTOCOL_GUID \
30 0xD9072C35, 0xEB8F, 0x43ad, 0xA2, 0x20, 0x34, 0xD4, 0x0E, 0x2A, 0x82, 0x85 \
32 extern EFI_GUID gEfiSpiProtocolGuid
;
33 extern EFI_GUID gEfiSmmSpiProtocolGuid
;
36 /// Forward reference for ANSI C compatibility
38 typedef struct _EFI_SPI_PROTOCOL EFI_SPI_PROTOCOL
;
41 /// SPI protocol data structures and definitions
44 /// Number of Prefix Opcodes allowed on the SPI interface
46 #define SPI_NUM_PREFIX_OPCODE 2
49 /// Number of Opcodes in the Opcode Menu
51 #define SPI_NUM_OPCODE 8
55 /// EnumSpiOpcodeCommand: Command without address
56 /// EnumSpiOpcodeRead: Read with address
57 /// EnumSpiOpcodeWrite: Write with address
60 EnumSpiOpcodeReadNoAddr
,
61 EnumSpiOpcodeWriteNoAddr
,
70 EnumSpiCycle66MHz
, /// Not supported by VLV
73 } SPI_CYCLE_FREQUENCY
;
79 EnumSpiRegionDescriptor
,
80 EnumSpiRegionPlatformData
,
85 /// Hardware Sequencing required operations (as listed in Valleyview EDS "Hardware
86 /// Sequencing Commands and Opcode Requirements"
89 EnumSpiOperationWriteStatus
,
90 EnumSpiOperationProgramData_1_Byte
,
91 EnumSpiOperationProgramData_64_Byte
,
92 EnumSpiOperationReadData
,
93 EnumSpiOperationWriteDisable
,
94 EnumSpiOperationReadStatus
,
95 EnumSpiOperationWriteEnable
,
96 EnumSpiOperationFastRead
,
97 EnumSpiOperationEnableWriteStatus
,
98 EnumSpiOperationErase_256_Byte
,
99 EnumSpiOperationErase_4K_Byte
,
100 EnumSpiOperationErase_8K_Byte
,
101 EnumSpiOperationErase_64K_Byte
,
102 EnumSpiOperationFullChipErase
,
103 EnumSpiOperationJedecId
,
104 EnumSpiOperationDualOutputFastRead
,
105 EnumSpiOperationDiscoveryParameters
,
106 EnumSpiOperationOther
,
111 /// SPI Command Configuration
112 /// Frequency The expected frequency to be used (value to be programmed to the SSFC
114 /// Operation Which Hardware Sequencing required operation this opcode respoinds to.
115 /// The required operations are listed in EDS Table 5-55: "Hardware
116 /// Sequencing Commands and Opcode Requirements"
117 /// If the opcode does not corresponds to any operation listed, use
118 /// EnumSpiOperationOther, and provides TYPE and Code for it in
119 /// SpecialOpcodeEntry.
121 typedef struct _SPI_OPCODE_MENU_ENTRY
{
122 SPI_OPCODE_TYPE Type
;
124 SPI_CYCLE_FREQUENCY Frequency
;
125 SPI_OPERATION Operation
;
126 } SPI_OPCODE_MENU_ENTRY
;
129 // Initialization data table loaded to the SPI host controller
130 // VendorId Vendor ID of the SPI device
131 // DeviceId0 Device ID0 of the SPI device
132 // DeviceId1 Device ID1 of the SPI device
133 // PrefixOpcode Prefix opcodes which are loaded into the SPI host controller
134 // OpcodeMenu Opcodes which are loaded into the SPI host controller Opcode Menu
135 // BiosStartOffset The offset of the start of the BIOS image relative to the flash device.
136 // Please note this is a Flash Linear Address, NOT a memory space address.
137 // This value is platform specific and depends on the system flash map.
138 // This value is only used on non Descriptor mode.
139 // BiosSize The the BIOS Image size in flash. This value is platform specific
140 // and depends on the system flash map. Please note BIOS Image size may
141 // be smaller than BIOS Region size (in Descriptor Mode) or the flash size
142 // (in Non Descriptor Mode), and in this case, BIOS Image is supposed to be
143 // placed at the top end of the BIOS Region (in Descriptor Mode) or the flash
144 // (in Non Descriptor Mode)
146 typedef struct _SPI_INIT_TABLE
{
150 UINT8 PrefixOpcode
[SPI_NUM_PREFIX_OPCODE
];
151 SPI_OPCODE_MENU_ENTRY OpcodeMenu
[SPI_NUM_OPCODE
];
152 UINTN BiosStartOffset
;
157 // Protocol member functions
161 (EFIAPI
*EFI_SPI_INIT
) (
162 IN EFI_SPI_PROTOCOL
* This
,
163 IN SPI_INIT_TABLE
* InitTable
169 Initializes the host controller to execute SPI commands.
171 @param[in] This Pointer to the EFI_SPI_PROTOCOL instance.
172 @param[in] InitData Pointer to caller-allocated buffer containing the SPI
173 interface initialization table.
175 @retval EFI_SUCCESS Opcode initialization on the SPI host controller completed.
176 @retval EFI_ACCESS_DENIED The SPI configuration interface is locked.
177 @retval EFI_OUT_OF_RESOURCES Not enough resource available to initialize the device.
178 @retval EFI_DEVICE_ERROR Device error, operation failed.
184 (EFIAPI
*EFI_SPI_LOCK
) (
185 IN EFI_SPI_PROTOCOL
* This
190 Initializes the host controller to execute SPI commands.
192 @param[in] This Pointer to the EFI_SPI_PROTOCOL instance.
193 @param[in] InitData Pointer to caller-allocated buffer containing the SPI
194 interface initialization table.
196 @retval EFI_SUCCESS Opcode initialization on the SPI host controller completed.
197 @retval EFI_ACCESS_DENIED The SPI configuration interface is locked.
198 @retval EFI_OUT_OF_RESOURCES Not enough resource available to initialize the device.
199 @retval EFI_DEVICE_ERROR Device error, operation failed.
205 (EFIAPI
*EFI_SPI_EXECUTE
) (
206 IN EFI_SPI_PROTOCOL
* This
,
207 IN UINT8 OpcodeIndex
,
208 IN UINT8 PrefixOpcodeIndex
,
209 IN BOOLEAN DataCycle
,
213 IN UINT32 DataByteCount
,
214 IN OUT UINT8
*Buffer
,
215 IN SPI_REGION_TYPE SpiRegionType
220 Execute SPI commands from the host controller.
222 @param[in] This Pointer to the EFI_SPI_PROTOCOL instance.
223 @param[in] OpcodeIndex Index of the command in the OpCode Menu.
224 @param[in] PrefixOpcodeIndex Index of the first command to run when in an atomic cycle sequence.
225 @param[in] DataCycle TRUE if the SPI cycle contains data
226 @param[in] Atomic TRUE if the SPI cycle is atomic and interleave cycles are not allowed.
227 @param[in] ShiftOut If DataByteCount is not zero, TRUE to shift data out and FALSE to shift data in.
228 @param[in] Address In Descriptor Mode, for Descriptor Region, GbE Region, ME Region and Platform
229 Region, this value specifies the offset from the Region Base; for BIOS Region,
230 this value specifies the offset from the start of the BIOS Image. In Non
231 Descriptor Mode, this value specifies the offset from the start of the BIOS Image.
232 Please note BIOS Image size may be smaller than BIOS Region size (in Descriptor
233 Mode) or the flash size (in Non Descriptor Mode), and in this case, BIOS Image is
234 supposed to be placed at the top end of the BIOS Region (in Descriptor Mode) or
235 the flash (in Non Descriptor Mode)
236 @param[in] DataByteCount Number of bytes in the data portion of the SPI cycle.
237 @param[in] Buffer Pointer to caller-allocated buffer containing the dada received or sent during the SPI cycle.
238 @param[in] SpiRegionType SPI Region type. Values EnumSpiRegionBios, EnumSpiRegionGbE, EnumSpiRegionMe,
239 EnumSpiRegionDescriptor, and EnumSpiRegionPlatformData are only applicable in
240 Descriptor mode. Value EnumSpiRegionAll is applicable to both Descriptor Mode
241 and Non Descriptor Mode, which indicates "SpiRegionOffset" is actually relative
242 to base of the 1st flash device (i.e., it is a Flash Linear Address).
244 @retval EFI_SUCCESS Command succeed.
245 @retval EFI_INVALID_PARAMETER The parameters specified are not valid.
246 @exception EFI_UNSUPPORTED Command not supported.
247 @retval EFI_DEVICE_ERROR Device error, command aborts abnormally.
252 /// Protocol definition
254 struct _EFI_SPI_PROTOCOL
{
257 EFI_SPI_EXECUTE Execute
;