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