QuarkSocPkg/QuarkNorthCluster/Include/Protocol/Spi.h

   1 /** @file
   2 This file defines the EFI SPI Protocol which implements the
   3 Intel(R) ICH SPI Host Controller Compatibility Interface.
   4
   5 Copyright (c) 2013-2015 Intel Corporation.
   6
   7 SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9
  10 **/
  11 #ifndef _SPI_H_
  12 #define _SPI_H_
  13
  14 //
  15 // Define the SPI protocol GUID
  16 //
  17 // EDK and EDKII have different GUID formats
  18 //
  19 #if !defined(EDK_RELEASE_VERSION) || (EDK_RELEASE_VERSION < 0x00020000)
  20 #define EFI_SPI_PROTOCOL_GUID \
  21   { \
  22     0x1156efc6, 0xea32, 0x4396, 0xb5, 0xd5, 0x26, 0x93, 0x2e, 0x83, 0xc3, 0x13 \
  23   }
  24 #define EFI_SMM_SPI_PROTOCOL_GUID \
  25   { \
  26     0xD9072C35, 0xEB8F, 0x43ad, 0xA2, 0x20, 0x34, 0xD4, 0x0E, 0x2A, 0x82, 0x85 \
  27   }
  28 #else
  29 #define EFI_SPI_PROTOCOL_GUID \
  30   { \
  31     0x1156efc6, 0xea32, 0x4396, \
  32     { \
  33       0xb5, 0xd5, 0x26, 0x93, 0x2e, 0x83, 0xc3, 0x13 \
  34     } \
  35   }
  36 #define EFI_SMM_SPI_PROTOCOL_GUID \
  37   { \
  38     0xD9072C35, 0xEB8F, 0x43ad, \
  39     { \
  40       0xA2, 0x20, 0x34, 0xD4, 0x0E, 0x2A, 0x82, 0x85 \
  41     } \
  42   }
  43 #endif
  44 //
  45 // Extern the GUID for protocol users.
  46 //
  47 extern EFI_GUID                   gEfiSpiProtocolGuid;
  48 extern EFI_GUID                   gEfiSmmSpiProtocolGuid;
  49
  50 //
  51 // Forward reference for ANSI C compatibility
  52 //
  53 typedef struct _EFI_SPI_PROTOCOL  EFI_SPI_PROTOCOL;
  54
  55 //
  56 // SPI protocol data structures and definitions
  57 //
  58 //
  59 // Number of Prefix Opcodes allowed on the SPI interface
  60 //
  61 #define SPI_NUM_PREFIX_OPCODE 2
  62
  63 //
  64 // Number of Opcodes in the Opcode Menu
  65 //
  66 #define SPI_NUM_OPCODE  8
  67
  68 #ifdef SERVER_BIOS_FLAG
  69 //
  70 // SPI default opcode slots
  71 //
  72 #define SPI_OPCODE_JEDEC_ID_INDEX        0
  73 #endif // SERVER_BIOS_FLAG
  74
  75 //
  76 // Opcode Type
  77 //    EnumSpiOpcodeCommand: Command without address
  78 //    EnumSpiOpcodeRead: Read with address
  79 //    EnumSpiOpcodeWrite: Write with address
  80 //
  81 typedef enum {
  82   EnumSpiOpcodeReadNoAddr,
  83   EnumSpiOpcodeWriteNoAddr,
  84   EnumSpiOpcodeRead,
  85   EnumSpiOpcodeWrite,
  86   EnumSpiOpcodeMax
  87 } SPI_OPCODE_TYPE;
  88
  89 typedef enum {
  90   EnumSpiCycle20MHz,
  91   EnumSpiCycle33MHz,
  92   EnumSpiCycle66MHz,  // not supported by PCH
  93   EnumSpiCycle50MHz,
  94   EnumSpiCycleMax
  95 } SPI_CYCLE_FREQUENCY;
  96
  97 typedef enum {
  98   EnumSpiRegionAll,
  99   EnumSpiRegionBios,
 100   EnumSpiRegionMe,
 101   EnumSpiRegionGbE,
 102   EnumSpiRegionDescriptor,
 103   EnumSpiRegionPlatformData,
 104   EnumSpiRegionMax
 105 } SPI_REGION_TYPE;
 106
 107 //
 108 // Hardware Sequencing required operations (as listed in CougarPoint EDS Table 5-55: "Hardware
 109 // Sequencing Commands and Opcode Requirements"
 110 //
 111 typedef enum {
 112   EnumSpiOperationWriteStatus,
 113   EnumSpiOperationProgramData_1_Byte,
 114   EnumSpiOperationProgramData_64_Byte,
 115   EnumSpiOperationReadData,
 116   EnumSpiOperationWriteDisable,
 117   EnumSpiOperationReadStatus,
 118   EnumSpiOperationWriteEnable,
 119   EnumSpiOperationFastRead,
 120   EnumSpiOperationEnableWriteStatus,
 121   EnumSpiOperationErase_256_Byte,
 122   EnumSpiOperationErase_4K_Byte,
 123   EnumSpiOperationErase_8K_Byte,
 124   EnumSpiOperationErase_64K_Byte,
 125   EnumSpiOperationFullChipErase,
 126   EnumSpiOperationJedecId,
 127   EnumSpiOperationDualOutputFastRead,
 128   EnumSpiOperationDiscoveryParameters,
 129   EnumSpiOperationOther,
 130   EnumSpiOperationMax
 131 } SPI_OPERATION;
 132
 133 //
 134 // Opcode menu entries
 135 //   Type            Operation Type (value to be programmed to the OPTYPE register)
 136 //   Code            The opcode (value to be programmed to the OPMENU register)
 137 //   Frequency       The expected frequency to be used (value to be programmed to the SSFC
 138 //                   Register)
 139 //   Operation       Which Hardware Sequencing required operation this opcode respoinds to.
 140 //                   The required operations are listed in EDS Table 5-55: "Hardware
 141 //                   Sequencing Commands and Opcode Requirements"
 142 //                   If the opcode does not corresponds to any operation listed, use
 143 //                   EnumSpiOperationOther
 144 //
 145 typedef struct _SPI_OPCODE_MENU_ENTRY {
 146   SPI_OPCODE_TYPE     Type;
 147   UINT8               Code;
 148   SPI_CYCLE_FREQUENCY Frequency;
 149   SPI_OPERATION       Operation;
 150 } SPI_OPCODE_MENU_ENTRY;
 151
 152 //
 153 // Initialization data table loaded to the SPI host controller
 154 //    VendorId        Vendor ID of the SPI device
 155 //    DeviceId0       Device ID0 of the SPI device
 156 //    DeviceId1       Device ID1 of the SPI device
 157 //    PrefixOpcode    Prefix opcodes which are loaded into the SPI host controller
 158 //    OpcodeMenu      Opcodes which are loaded into the SPI host controller Opcode Menu
 159 //    BiosStartOffset The offset of the start of the BIOS image relative to the flash device.
 160 //                    Please note this is a Flash Linear Address, NOT a memory space address.
 161 //                    This value is platform specific and depends on the system flash map.
 162 //                    This value is only used on non Descriptor mode.
 163 //    BiosSize        The the BIOS Image size in flash. This value is platform specific
 164 //                    and depends on the system flash map. Please note BIOS Image size may
 165 //                    be smaller than BIOS Region size (in Descriptor Mode) or the flash size
 166 //                    (in Non Descriptor Mode), and in this case, BIOS Image is supposed to be
 167 //                    placed at the top end of the BIOS Region (in Descriptor Mode) or the flash
 168 //                    (in Non Descriptor Mode)
 169 //
 170 typedef struct _SPI_INIT_TABLE {
 171   UINT8                 VendorId;
 172   UINT8                 DeviceId0;
 173   UINT8                 DeviceId1;
 174   UINT8                 PrefixOpcode[SPI_NUM_PREFIX_OPCODE];
 175   SPI_OPCODE_MENU_ENTRY OpcodeMenu[SPI_NUM_OPCODE];
 176   UINTN                 BiosStartOffset;
 177   UINTN                 BiosSize;
 178 } SPI_INIT_TABLE;
 179
 180 //
 181 // Public Info struct to show current initialized state of the spi interface.
 182 // OpcodeIndex must be less then SPI_NUM_OPCODE for operation to be supported.
 183 //
 184 typedef struct _SPI_INIT_INFO {
 185   SPI_INIT_TABLE        *InitTable;
 186   UINT8                 JedecIdOpcodeIndex;
 187   UINT8                 OtherOpcodeIndex;
 188   UINT8                 WriteStatusOpcodeIndex;
 189   UINT8                 ProgramOpcodeIndex;
 190   UINT8                 ReadOpcodeIndex;
 191   UINT8                 EraseOpcodeIndex;
 192   UINT8                 ReadStatusOpcodeIndex;
 193   UINT8                 FullChipEraseOpcodeIndex;
 194 } SPI_INIT_INFO;
 195
 196 //
 197 // Protocol member functions
 198 //
 199
 200 typedef
 201 EFI_STATUS
 202 (EFIAPI *EFI_SPI_INIT) (
 203   IN EFI_SPI_PROTOCOL     * This,
 204   IN SPI_INIT_TABLE       * InitTable
 205   );
 206 /*++
 207
 208 Routine Description:
 209
 210   Initializes the host controller to execute SPI commands.
 211
 212 Arguments:
 213
 214   This                    Pointer to the EFI_SPI_PROTOCOL instance.
 215   InitTable               Pointer to caller-allocated buffer containing the SPI
 216                           interface initialization table.
 217
 218 Returns:
 219
 220   EFI_SUCCESS             Opcode initialization on the SPI host controller completed.
 221   EFI_ACCESS_DENIED       The SPI configuration interface is locked.
 222   EFI_OUT_OF_RESOURCES    Not enough resource available to initialize the device.
 223   EFI_DEVICE_ERROR        Device error, operation failed.
 224
 225 --*/
 226
 227 typedef
 228 EFI_STATUS
 229 (EFIAPI *EFI_SPI_LOCK) (
 230   IN EFI_SPI_PROTOCOL     * This
 231   );
 232 /*++
 233
 234 Routine Description:
 235
 236   Lock the SPI Static Configuration Interface.
 237   Once locked, the interface is no longer open for configuration changes.
 238   The lock state automatically clears on next system reset.
 239
 240 Arguments:
 241
 242   This      Pointer to the EFI_SPI_PROTOCOL instance.
 243
 244 Returns:
 245
 246   EFI_SUCCESS             Lock operation succeed.
 247   EFI_DEVICE_ERROR        Device error, operation failed.
 248   EFI_ACCESS_DENIED       The interface has already been locked.
 249
 250 --*/
 251
 252 typedef
 253 EFI_STATUS
 254 (EFIAPI *EFI_SPI_EXECUTE) (
 255   IN     EFI_SPI_PROTOCOL   * This,
 256   IN     UINT8              OpcodeIndex,
 257   IN     UINT8              PrefixOpcodeIndex,
 258   IN     BOOLEAN            DataCycle,
 259   IN     BOOLEAN            Atomic,
 260   IN     BOOLEAN            ShiftOut,
 261   IN     UINTN              Address,
 262   IN     UINT32             DataByteCount,
 263   IN OUT UINT8              *Buffer,
 264   IN     SPI_REGION_TYPE    SpiRegionType
 265   );
 266 /*++
 267
 268 Routine Description:
 269
 270   Execute SPI commands from the host controller.
 271
 272 Arguments:
 273
 274   This                    Pointer to the EFI_SPI_PROTOCOL instance.
 275   OpcodeIndex             Index of the command in the OpCode Menu.
 276   PrefixOpcodeIndex       Index of the first command to run when in an atomic cycle sequence.
 277   DataCycle               TRUE if the SPI cycle contains data
 278   Atomic                  TRUE if the SPI cycle is atomic and interleave cycles are not allowed.
 279   ShiftOut                If DataByteCount is not zero, TRUE to shift data out and FALSE to shift data in.
 280   Address                 In Descriptor Mode, for Descriptor Region, GbE Region, ME Region and Platform
 281                           Region, this value specifies the offset from the Region Base; for BIOS Region,
 282                           this value specifies the offset from the start of the BIOS Image. In Non
 283                           Descriptor Mode, this value specifies the offset from the start of the BIOS Image.
 284                           Please note BIOS Image size may be smaller than BIOS Region size (in Descriptor
 285                           Mode) or the flash size (in Non Descriptor Mode), and in this case, BIOS Image is
 286                           supposed to be placed at the top end of the BIOS Region (in Descriptor Mode) or
 287                           the flash (in Non Descriptor Mode)
 288   DataByteCount           Number of bytes in the data portion of the SPI cycle.
 289   Buffer                  Pointer to caller-allocated buffer containing the dada received or sent during the SPI cycle.
 290   SpiRegionType           SPI Region type. Values EnumSpiRegionBios, EnumSpiRegionGbE, EnumSpiRegionMe,
 291                           EnumSpiRegionDescriptor, and EnumSpiRegionPlatformData are only applicable in
 292                           Descriptor mode. Value EnumSpiRegionAll is applicable to both Descriptor Mode
 293                           and Non Descriptor Mode, which indicates "SpiRegionOffset" is actually relative
 294                           to base of the 1st flash device (i.e., it is a Flash Linear Address).
 295
 296 Returns:
 297
 298   EFI_SUCCESS             Command succeed.
 299   EFI_INVALID_PARAMETER   The parameters specified are not valid.
 300   EFI_UNSUPPORTED         Command not supported.
 301   EFI_DEVICE_ERROR        Device error, command aborts abnormally.
 302
 303 --*/
 304
 305 typedef
 306 EFI_STATUS
 307 (EFIAPI *EFI_SPI_INFO) (
 308   IN EFI_SPI_PROTOCOL     *This,
 309   OUT SPI_INIT_INFO      **InitInfoPtr
 310   );
 311 /*++
 312
 313 Routine Description:
 314
 315   Return info about SPI host controller, to help callers usage of Execute
 316   service.
 317
 318   If 0xff is returned as an opcode index in init info struct
 319   then device does not support the operation.
 320
 321 Arguments:
 322
 323   This                    Pointer to the EFI_SPI_PROTOCOL instance.
 324   InitInfoPtr             Pointer to init info written to this memory location.
 325
 326 Returns:
 327
 328   EFI_SUCCESS             Information returned.
 329   EFI_INVALID_PARAMETER   Invalid parameter.
 330   EFI_NOT_READY           Required resources not setup.
 331   Others                  Unexpected error happened.
 332
 333 --*/
 334
 335 //
 336 // Protocol definition
 337 //
 338 struct _EFI_SPI_PROTOCOL {
 339   EFI_SPI_INIT    Init;
 340   EFI_SPI_LOCK    Lock;
 341   EFI_SPI_EXECUTE Execute;
 342   EFI_SPI_INFO    Info;
 343 };
 344
 345 #endif