1/** @file
2This file defines the EFI SPI Protocol which implements the
3Intel(R) ICH SPI Host Controller Compatibility Interface.
4
5Copyright (c) 2013-2015 Intel Corporation.
6
7This program and the accompanying materials
8are licensed and made available under the terms and conditions of the BSD License
9which accompanies this distribution.  The full text of the license may be found at
10http://opensource.org/licenses/bsd-license.php
11
12THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
13WITHOUT 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//
53extern EFI_GUID                   gEfiSpiProtocolGuid;
54extern EFI_GUID                   gEfiSmmSpiProtocolGuid;
55
56//
57// Forward reference for ANSI C compatibility
58//
59typedef 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//
87typedef enum {
88  EnumSpiOpcodeReadNoAddr,
89  EnumSpiOpcodeWriteNoAddr,
90  EnumSpiOpcodeRead,
91  EnumSpiOpcodeWrite,
92  EnumSpiOpcodeMax
93} SPI_OPCODE_TYPE;
94
95typedef enum {
96  EnumSpiCycle20MHz,
97  EnumSpiCycle33MHz,
98  EnumSpiCycle66MHz,  // not supported by PCH
99  EnumSpiCycle50MHz,
100  EnumSpiCycleMax
101} SPI_CYCLE_FREQUENCY;
102
103typedef 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//
117typedef 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//
151typedef 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//
176typedef 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//
190typedef 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
206typedef
207EFI_STATUS
208(EFIAPI *EFI_SPI_INIT) (
209  IN EFI_SPI_PROTOCOL     * This,
210  IN SPI_INIT_TABLE       * InitTable
211  );
212/*++
213
214Routine Description:
215
216  Initializes the host controller to execute SPI commands.
217
218Arguments:
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
224Returns:
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
233typedef
234EFI_STATUS
235(EFIAPI *EFI_SPI_LOCK) (
236  IN EFI_SPI_PROTOCOL     * This
237  );
238/*++
239
240Routine 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
246Arguments:
247
248  This      Pointer to the EFI_SPI_PROTOCOL instance.
249
250Returns:
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
258typedef
259EFI_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
274Routine Description:
275
276  Execute SPI commands from the host controller.
277
278Arguments:
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
302Returns:
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
311typedef
312EFI_STATUS
313(EFIAPI *EFI_SPI_INFO) (
314  IN EFI_SPI_PROTOCOL     *This,
315  OUT SPI_INIT_INFO      **InitInfoPtr
316  );
317/*++
318
319Routine 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
327Arguments:
328
329  This                    Pointer to the EFI_SPI_PROTOCOL instance.
330  InitInfoPtr             Pointer to init info written to this memory location.
331
332Returns:
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//
344struct _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