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

   1 /**
   2 **/
   3 /**
   4
   5 Copyright (c) 2012  - 2014, Intel Corporation. All rights reserved
   6
   7   This program and the accompanying materials are licensed and made available under
   8   the terms and conditions of the BSD License that accompanies this distribution.
   9   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   @file
  18   Spi.h
  19
  20   @brief
  21   This file defines the EFI SPI Protocol which implements the
  22   Intel(R) ICH SPI Host Controller Compatibility Interface.
  23
  24 **/
  25 #ifndef _EFI_SPI_H_
  26 #define _EFI_SPI_H_
  27
  28
  29 //
  30 #define EFI_SPI_PROTOCOL_GUID \
  31   { \
  32     0x1156efc6, 0xea32, 0x4396, 0xb5, 0xd5, 0x26, 0x93, 0x2e, 0x83, 0xc3, 0x13 \
  33   }
  34 #define EFI_SMM_SPI_PROTOCOL_GUID \
  35   { \
  36     0xD9072C35, 0xEB8F, 0x43ad, 0xA2, 0x20, 0x34, 0xD4, 0x0E, 0x2A, 0x82, 0x85 \
  37   }
  38 extern EFI_GUID                   gEfiSpiProtocolGuid;
  39 extern EFI_GUID                   gEfiSmmSpiProtocolGuid;
  40
  41 ///
  42 /// Forward reference for ANSI C compatibility
  43 ///
  44 typedef struct _EFI_SPI_PROTOCOL  EFI_SPI_PROTOCOL;
  45
  46 ///
  47 /// SPI protocol data structures and definitions
  48 ///
  49 ///
  50 /// Number of Prefix Opcodes allowed on the SPI interface
  51 ///
  52 #define SPI_NUM_PREFIX_OPCODE 2
  53
  54 ///
  55 /// Number of Opcodes in the Opcode Menu
  56 ///
  57 #define SPI_NUM_OPCODE  8
  58
  59 ///
  60 /// Opcode Type
  61 ///    EnumSpiOpcodeCommand: Command without address
  62 ///    EnumSpiOpcodeRead: Read with address
  63 ///    EnumSpiOpcodeWrite: Write with address
  64 ///
  65 typedef enum {
  66   EnumSpiOpcodeReadNoAddr,
  67   EnumSpiOpcodeWriteNoAddr,
  68   EnumSpiOpcodeRead,
  69   EnumSpiOpcodeWrite,
  70   EnumSpiOpcodeMax
  71 } SPI_OPCODE_TYPE;
  72
  73 typedef enum {
  74   EnumSpiCycle20MHz,
  75   EnumSpiCycle33MHz,
  76   EnumSpiCycle66MHz,  /// Not supported by VLV
  77   EnumSpiCycle50MHz,
  78   EnumSpiCycleMax
  79 } SPI_CYCLE_FREQUENCY;
  80
  81 typedef enum {
  82   EnumSpiRegionAll,
  83   EnumSpiRegionBios,
  84   EnumSpiRegionSeC,
  85   EnumSpiRegionDescriptor,
  86   EnumSpiRegionPlatformData,
  87   EnumSpiRegionMax
  88 } SPI_REGION_TYPE;
  89
  90 ///
  91 /// Hardware Sequencing required operations (as listed in Valleyview EDS "Hardware
  92 /// Sequencing Commands and Opcode Requirements"
  93 ///
  94 typedef enum {
  95   EnumSpiOperationWriteStatus,
  96   EnumSpiOperationProgramData_1_Byte,
  97   EnumSpiOperationProgramData_64_Byte,
  98   EnumSpiOperationReadData,
  99   EnumSpiOperationWriteDisable,
 100   EnumSpiOperationReadStatus,
 101   EnumSpiOperationWriteEnable,
 102   EnumSpiOperationFastRead,
 103   EnumSpiOperationEnableWriteStatus,
 104   EnumSpiOperationErase_256_Byte,
 105   EnumSpiOperationErase_4K_Byte,
 106   EnumSpiOperationErase_8K_Byte,
 107   EnumSpiOperationErase_64K_Byte,
 108   EnumSpiOperationFullChipErase,
 109   EnumSpiOperationJedecId,
 110   EnumSpiOperationDualOutputFastRead,
 111   EnumSpiOperationDiscoveryParameters,
 112   EnumSpiOperationOther,
 113   EnumSpiOperationMax
 114 } SPI_OPERATION;
 115
 116 ///
 117 /// SPI Command Configuration
 118 ///   Frequency       The expected frequency to be used (value to be programmed to the SSFC
 119 ///                   Register)
 120 ///   Operation       Which Hardware Sequencing required operation this opcode respoinds to.
 121 ///                   The required operations are listed in EDS Table 5-55: "Hardware
 122 ///                   Sequencing Commands and Opcode Requirements"
 123 ///                   If the opcode does not corresponds to any operation listed, use
 124 ///                   EnumSpiOperationOther, and provides TYPE and Code for it in
 125 ///                   SpecialOpcodeEntry.
 126 ///
 127 typedef struct _SPI_OPCODE_MENU_ENTRY {
 128   SPI_OPCODE_TYPE     Type;
 129   UINT8               Code;
 130   SPI_CYCLE_FREQUENCY Frequency;
 131   SPI_OPERATION       Operation;
 132 } SPI_OPCODE_MENU_ENTRY;
 133
 134 //
 135 // Initialization data table loaded to the SPI host controller
 136 //    VendorId        Vendor ID of the SPI device
 137 //    DeviceId0       Device ID0 of the SPI device
 138 //    DeviceId1       Device ID1 of the SPI device
 139 //    PrefixOpcode    Prefix opcodes which are loaded into the SPI host controller
 140 //    OpcodeMenu      Opcodes which are loaded into the SPI host controller Opcode Menu
 141 //    BiosStartOffset The offset of the start of the BIOS image relative to the flash device.
 142 //                    Please note this is a Flash Linear Address, NOT a memory space address.
 143 //                    This value is platform specific and depends on the system flash map.
 144 //                    This value is only used on non Descriptor mode.
 145 //    BiosSize        The the BIOS Image size in flash. This value is platform specific
 146 //                    and depends on the system flash map. Please note BIOS Image size may
 147 //                    be smaller than BIOS Region size (in Descriptor Mode) or the flash size
 148 //                    (in Non Descriptor Mode), and in this case, BIOS Image is supposed to be
 149 //                    placed at the top end of the BIOS Region (in Descriptor Mode) or the flash
 150 //                    (in Non Descriptor Mode)
 151 //
 152 typedef struct _SPI_INIT_TABLE {
 153   UINT8                 VendorId;
 154   UINT8                 DeviceId0;
 155   UINT8                 DeviceId1;
 156   UINT8                 PrefixOpcode[SPI_NUM_PREFIX_OPCODE];
 157   SPI_OPCODE_MENU_ENTRY OpcodeMenu[SPI_NUM_OPCODE];
 158   UINTN                 BiosStartOffset;
 159   UINTN                 BiosSize;
 160 } SPI_INIT_TABLE;
 161
 162 //
 163 // Protocol member functions
 164 //
 165 typedef
 166 EFI_STATUS
 167 (EFIAPI *EFI_SPI_INIT) (
 168   IN EFI_SPI_PROTOCOL     * This,
 169   IN SPI_INIT_TABLE       * InitTable
 170   );
 171
 172 /**
 173
 174   @brief
 175   Initializes the host controller to execute SPI commands.
 176
 177   @param[in] This                 Pointer to the EFI_SPI_PROTOCOL instance.
 178   @param[in] InitData             Pointer to caller-allocated buffer containing the SPI
 179                                   interface initialization table.
 180
 181   @retval EFI_SUCCESS             Opcode initialization on the SPI host controller completed.
 182   @retval EFI_ACCESS_DENIED       The SPI configuration interface is locked.
 183   @retval EFI_OUT_OF_RESOURCES    Not enough resource available to initialize the device.
 184   @retval EFI_DEVICE_ERROR        Device error, operation failed.
 185
 186 **/
 187
 188 typedef
 189 EFI_STATUS
 190 (EFIAPI *EFI_SPI_LOCK) (
 191   IN EFI_SPI_PROTOCOL     * This
 192   );
 193 /**
 194
 195   @brief
 196   Initializes the host controller to execute SPI commands.
 197
 198   @param[in] This                 Pointer to the EFI_SPI_PROTOCOL instance.
 199   @param[in] InitData             Pointer to caller-allocated buffer containing the SPI
 200                                   interface initialization table.
 201
 202   @retval EFI_SUCCESS             Opcode initialization on the SPI host controller completed.
 203   @retval EFI_ACCESS_DENIED       The SPI configuration interface is locked.
 204   @retval EFI_OUT_OF_RESOURCES    Not enough resource available to initialize the device.
 205   @retval EFI_DEVICE_ERROR        Device error, operation failed.
 206
 207 **/
 208
 209 typedef
 210 EFI_STATUS
 211 (EFIAPI *EFI_SPI_EXECUTE) (
 212   IN     EFI_SPI_PROTOCOL   * This,
 213   IN     UINT8              OpcodeIndex,
 214   IN     UINT8              PrefixOpcodeIndex,
 215   IN     BOOLEAN            DataCycle,
 216   IN     BOOLEAN            Atomic,
 217   IN     BOOLEAN            ShiftOut,
 218   IN     UINTN              Address,
 219   IN     UINT32             DataByteCount,
 220   IN OUT UINT8              *Buffer,
 221   IN     SPI_REGION_TYPE    SpiRegionType
 222   );
 223 /**
 224
 225   @brief
 226   Execute SPI commands from the host controller.
 227
 228   @param[in] This                 Pointer to the EFI_SPI_PROTOCOL instance.
 229   @param[in] OpcodeIndex          Index of the command in the OpCode Menu.
 230   @param[in] PrefixOpcodeIndex    Index of the first command to run when in an atomic cycle sequence.
 231   @param[in] DataCycle            TRUE if the SPI cycle contains data
 232   @param[in] Atomic               TRUE if the SPI cycle is atomic and interleave cycles are not allowed.
 233   @param[in] ShiftOut             If DataByteCount is not zero, TRUE to shift data out and FALSE to shift data in.
 234   @param[in] Address              In Descriptor Mode, for Descriptor Region, GbE Region, ME Region and Platform
 235                                   Region, this value specifies the offset from the Region Base; for BIOS Region,
 236                                   this value specifies the offset from the start of the BIOS Image. In Non
 237                                   Descriptor Mode, this value specifies the offset from the start of the BIOS Image.
 238                                   Please note BIOS Image size may be smaller than BIOS Region size (in Descriptor
 239                                   Mode) or the flash size (in Non Descriptor Mode), and in this case, BIOS Image is
 240                                   supposed to be placed at the top end of the BIOS Region (in Descriptor Mode) or
 241                                   the flash (in Non Descriptor Mode)
 242   @param[in] DataByteCount        Number of bytes in the data portion of the SPI cycle.
 243   @param[in] Buffer               Pointer to caller-allocated buffer containing the dada received or sent during the SPI cycle.
 244   @param[in] SpiRegionType        SPI Region type. Values EnumSpiRegionBios, EnumSpiRegionGbE, EnumSpiRegionMe,
 245                                   EnumSpiRegionDescriptor, and EnumSpiRegionPlatformData are only applicable in
 246                                   Descriptor mode. Value EnumSpiRegionAll is applicable to both Descriptor Mode
 247                                   and Non Descriptor Mode, which indicates "SpiRegionOffset" is actually relative
 248                                   to base of the 1st flash device (i.e., it is a Flash Linear Address).
 249
 250   @retval EFI_SUCCESS             Command succeed.
 251   @retval EFI_INVALID_PARAMETER   The parameters specified are not valid.
 252   @exception EFI_UNSUPPORTED      Command not supported.
 253   @retval EFI_DEVICE_ERROR        Device error, command aborts abnormally.
 254
 255 **/
 256
 257 ///
 258 /// Protocol definition
 259 ///
 260 struct _EFI_SPI_PROTOCOL {
 261   EFI_SPI_INIT    Init;
 262   EFI_SPI_LOCK    Lock;
 263   EFI_SPI_EXECUTE Execute;
 264 };
 265
 266 #endif