Vlv2DeviceRefCodePkg/ValleyView2Soc/SouthCluster/Include/Protocol/Spi.h

   1 /**
   2 **/
   3 /**
   4
   5 Copyright (c) 2012  - 2014, Intel Corporation. All rights reserved
   6
   7   SPDX-License-Identifier: BSD-2-Clause-Patent
   8
   9
  10
  11   @file
  12   Spi.h
  13
  14   @brief
  15   This file defines the EFI SPI Protocol which implements the
  16   Intel(R) ICH SPI Host Controller Compatibility Interface.
  17
  18 **/
  19 #ifndef _EFI_SPI_H_
  20 #define _EFI_SPI_H_
  21
  22
  23 //
  24 #define EFI_SPI_PROTOCOL_GUID \
  25   { \
  26     0x1156efc6, 0xea32, 0x4396, 0xb5, 0xd5, 0x26, 0x93, 0x2e, 0x83, 0xc3, 0x13 \
  27   }
  28 #define EFI_SMM_SPI_PROTOCOL_GUID \
  29   { \
  30     0xD9072C35, 0xEB8F, 0x43ad, 0xA2, 0x20, 0x34, 0xD4, 0x0E, 0x2A, 0x82, 0x85 \
  31   }
  32 extern EFI_GUID                   gEfiSpiProtocolGuid;
  33 extern EFI_GUID                   gEfiSmmSpiProtocolGuid;
  34
  35 ///
  36 /// Forward reference for ANSI C compatibility
  37 ///
  38 typedef struct _EFI_SPI_PROTOCOL  EFI_SPI_PROTOCOL;
  39
  40 ///
  41 /// SPI protocol data structures and definitions
  42 ///
  43 ///
  44 /// Number of Prefix Opcodes allowed on the SPI interface
  45 ///
  46 #define SPI_NUM_PREFIX_OPCODE 2
  47
  48 ///
  49 /// Number of Opcodes in the Opcode Menu
  50 ///
  51 #define SPI_NUM_OPCODE  8
  52
  53 ///
  54 /// Opcode Type
  55 ///    EnumSpiOpcodeCommand: Command without address
  56 ///    EnumSpiOpcodeRead: Read with address
  57 ///    EnumSpiOpcodeWrite: Write with address
  58 ///
  59 typedef enum {
  60   EnumSpiOpcodeReadNoAddr,
  61   EnumSpiOpcodeWriteNoAddr,
  62   EnumSpiOpcodeRead,
  63   EnumSpiOpcodeWrite,
  64   EnumSpiOpcodeMax
  65 } SPI_OPCODE_TYPE;
  66
  67 typedef enum {
  68   EnumSpiCycle20MHz,
  69   EnumSpiCycle33MHz,
  70   EnumSpiCycle66MHz,  /// Not supported by VLV
  71   EnumSpiCycle50MHz,
  72   EnumSpiCycleMax
  73 } SPI_CYCLE_FREQUENCY;
  74
  75 typedef enum {
  76   EnumSpiRegionAll,
  77   EnumSpiRegionBios,
  78   EnumSpiRegionSeC,
  79   EnumSpiRegionDescriptor,
  80   EnumSpiRegionPlatformData,
  81   EnumSpiRegionMax
  82 } SPI_REGION_TYPE;
  83
  84 ///
  85 /// Hardware Sequencing required operations (as listed in Valleyview EDS "Hardware
  86 /// Sequencing Commands and Opcode Requirements"
  87 ///
  88 typedef enum {
  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,
 107   EnumSpiOperationMax
 108 } SPI_OPERATION;
 109
 110 ///
 111 /// SPI Command Configuration
 112 ///   Frequency       The expected frequency to be used (value to be programmed to the SSFC
 113 ///                   Register)
 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.
 120 ///
 121 typedef struct _SPI_OPCODE_MENU_ENTRY {
 122   SPI_OPCODE_TYPE     Type;
 123   UINT8               Code;
 124   SPI_CYCLE_FREQUENCY Frequency;
 125   SPI_OPERATION       Operation;
 126 } SPI_OPCODE_MENU_ENTRY;
 127
 128 //
 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)
 145 //
 146 typedef struct _SPI_INIT_TABLE {
 147   UINT8                 VendorId;
 148   UINT8                 DeviceId0;
 149   UINT8                 DeviceId1;
 150   UINT8                 PrefixOpcode[SPI_NUM_PREFIX_OPCODE];
 151   SPI_OPCODE_MENU_ENTRY OpcodeMenu[SPI_NUM_OPCODE];
 152   UINTN                 BiosStartOffset;
 153   UINTN                 BiosSize;
 154 } SPI_INIT_TABLE;
 155
 156 //
 157 // Protocol member functions
 158 //
 159 typedef
 160 EFI_STATUS
 161 (EFIAPI *EFI_SPI_INIT) (
 162   IN EFI_SPI_PROTOCOL     * This,
 163   IN SPI_INIT_TABLE       * InitTable
 164   );
 165
 166 /**
 167
 168   @brief
 169   Initializes the host controller to execute SPI commands.
 170
 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.
 174
 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.
 179
 180 **/
 181
 182 typedef
 183 EFI_STATUS
 184 (EFIAPI *EFI_SPI_LOCK) (
 185   IN EFI_SPI_PROTOCOL     * This
 186   );
 187 /**
 188
 189   @brief
 190   Initializes the host controller to execute SPI commands.
 191
 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.
 195
 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.
 200
 201 **/
 202
 203 typedef
 204 EFI_STATUS
 205 (EFIAPI *EFI_SPI_EXECUTE) (
 206   IN     EFI_SPI_PROTOCOL   * This,
 207   IN     UINT8              OpcodeIndex,
 208   IN     UINT8              PrefixOpcodeIndex,
 209   IN     BOOLEAN            DataCycle,
 210   IN     BOOLEAN            Atomic,
 211   IN     BOOLEAN            ShiftOut,
 212   IN     UINTN              Address,
 213   IN     UINT32             DataByteCount,
 214   IN OUT UINT8              *Buffer,
 215   IN     SPI_REGION_TYPE    SpiRegionType
 216   );
 217 /**
 218
 219   @brief
 220   Execute SPI commands from the host controller.
 221
 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).
 243
 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.
 248
 249 **/
 250
 251 ///
 252 /// Protocol definition
 253 ///
 254 struct _EFI_SPI_PROTOCOL {
 255   EFI_SPI_INIT    Init;
 256   EFI_SPI_LOCK    Lock;
 257   EFI_SPI_EXECUTE Execute;
 258 };
 259
 260 #endif