QuarkSocPkg/QuarkNorthCluster/Spi/Common/SpiCommon.h

   1 /** @file
   2 Header file for the PCH SPI Common Driver.
   3
   4 Copyright (c) 2013-2015 Intel Corporation.
   5
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9 #ifndef _SPI_COMMON_H_
  10 #define _SPI_COMMON_H_
  11
  12 #include "Protocol/Spi.h"
  13 #include <Library/PciLib.h>
  14 #include <Library/IoLib.h>
  15 #include <Library/DebugLib.h>
  16 #include <Library/PcdLib.h>
  17 #include <Library/BaseMemoryLib.h>
  18 #include <Library/IntelQNCLib.h>
  19 #include <Library/QNCAccessLib.h>
  20 #include <Uefi/UefiBaseType.h>
  21
  22 //
  23 // Maximum time allowed while waiting the SPI cycle to complete
  24 //  Wait Time = 6 seconds = 6000000 microseconds
  25 //  Wait Period = 10 microseconds
  26 //
  27 #define WAIT_TIME   6000000
  28 #define WAIT_PERIOD 10
  29 //
  30 // PCH Required SPI Commands -------- COMMAND SET I ------------
  31 // SPI flash device must support in order to be compatible with PCH
  32 //
  33 #define PCH_SPI_COMMAND_PROGRAM_BYTE          0x02
  34 #define PCH_SPI_COMMAND_READ_DATA             0x03
  35 #define PCH_SPI_COMMAND_WRITE_DISABLE         0x04
  36 #define PCH_SPI_COMMAND_READ_STATUS           0x05
  37 #define PCH_SPI_COMMAND_WRITE_ENABLE          0x06
  38 #define PCH_SPI_COMMAND_FAST_READ             0x0B
  39 #define PCH_SPI_COMMAND_READ_ID               0x9F
  40 #define PCH_SPI_COMMAND_DUAL_FAST_READ        0x3B  // Dual Output Fast Read
  41
  42 //
  43 // Need to support at least one of the following two kinds of size of sector for erasing
  44 //
  45 #define PCH_SPI_COMMAND_4KB_ERASE   0x20
  46 #define PCH_SPI_COMMAND_64KB_ERASE  0xD8
  47 //
  48 // Recommended SPI Commands -------- COMMAND SET II ------------
  49 // SPI flash device best to support
  50 //
  51 #define PCH_SPI_COMMAND_WRITE_STATUS    0x01
  52 #define PCH_SPI_COMMAND_FULL_CHIP_ERASE 0xC7
  53
  54 //
  55 // Private data structure definitions for the driver
  56 //
  57 #define PCH_SPI_PRIVATE_DATA_SIGNATURE  SIGNATURE_32 ('P', 'S', 'P', 'I')
  58
  59 typedef struct {
  60   UINTN             Signature;
  61   EFI_HANDLE        Handle;
  62   EFI_SPI_PROTOCOL  SpiProtocol;
  63   SPI_INIT_TABLE    SpiInitTable;
  64   UINTN             PchRootComplexBar;
  65   BOOLEAN           InitDone; // Set to TRUE on SpiProtocolInit SUCCESS.
  66   SPI_INIT_INFO     InitInfo;
  67 } SPI_INSTANCE;
  68
  69 #define SPI_INSTANCE_FROM_SPIPROTOCOL(a)  CR (a, SPI_INSTANCE, SpiProtocol, PCH_SPI_PRIVATE_DATA_SIGNATURE)
  70
  71 //
  72 // Function prototypes used by the SPI protocol.
  73 //
  74 EFI_STATUS
  75 SpiProtocolConstructor (
  76   SPI_INSTANCE          *SpiInstance
  77   )
  78 /*++
  79
  80 Routine Description:
  81
  82   Initialize an SPI protocol instance.
  83   The function will assert in debug if PCH RCBA has not been initialized
  84
  85 Arguments:
  86
  87   SpiInstance   - Pointer to SpiInstance to initialize
  88
  89 Returns:
  90
  91   EFI_SUCCESS     The protocol instance was properly initialized
  92   EFI_UNSUPPORTED The PCH is not supported by this module
  93
  94 --*/
  95 ;
  96
  97 EFI_STATUS
  98 EFIAPI
  99 SpiProtocolInit (
 100   IN EFI_SPI_PROTOCOL       *This,
 101   IN SPI_INIT_TABLE         *InitTable
 102   )
 103 /*++
 104
 105 Routine Description:
 106
 107   Initialize the host controller to execute SPI command.
 108
 109 Arguments:
 110
 111   This                    Pointer to the EFI_SPI_PROTOCOL instance.
 112   InitTable               Initialization data to be programmed into the SPI host controller.
 113
 114 Returns:
 115
 116   EFI_SUCCESS             Initialization completed.
 117   EFI_ACCESS_DENIED       The SPI static configuration interface has been locked-down.
 118   EFI_INVALID_PARAMETER   Bad input parameters.
 119 --*/
 120 ;
 121
 122 EFI_STATUS
 123 EFIAPI
 124 SpiProtocolLock (
 125   IN EFI_SPI_PROTOCOL       *This
 126   )
 127 /*++
 128
 129 Routine Description:
 130
 131   Lock the SPI Static Configuration Interface.
 132   Once locked, the interface can not be changed and can only be clear by system reset.
 133
 134 Arguments:
 135
 136   This      Pointer to the EFI_SPI_PROTOCOL instance.
 137
 138 Returns:
 139
 140   EFI_SUCCESS             Lock operation succeed.
 141   EFI_DEVICE_ERROR        Device error, operation failed.
 142   EFI_ACCESS_DENIED       The interface has already been locked.
 143
 144 --*/
 145 ;
 146
 147 EFI_STATUS
 148 EFIAPI
 149 SpiProtocolExecute (
 150   IN     EFI_SPI_PROTOCOL   *This,
 151   IN     UINT8              OpcodeIndex,
 152   IN     UINT8              PrefixOpcodeIndex,
 153   IN     BOOLEAN            DataCycle,
 154   IN     BOOLEAN            Atomic,
 155   IN     BOOLEAN            ShiftOut,
 156   IN     UINTN              Address,
 157   IN     UINT32             DataByteCount,
 158   IN OUT UINT8              *Buffer,
 159   IN     SPI_REGION_TYPE    SpiRegionType
 160   )
 161 /*++
 162
 163 Routine Description:
 164
 165   Execute SPI commands from the host controller.
 166
 167 Arguments:
 168
 169   This                    Pointer to the EFI_SPI_PROTOCOL instance.
 170   OpcodeIndex             Index of the command in the OpCode Menu.
 171   PrefixOpcodeIndex       Index of the first command to run when in an atomic cycle sequence.
 172   DataCycle               TRUE if the SPI cycle contains data
 173   Atomic                  TRUE if the SPI cycle is atomic and interleave cycles are not allowed.
 174   ShiftOut                If DataByteCount is not zero, TRUE to shift data out and FALSE to shift data in.
 175   Address                 In Descriptor Mode, for Descriptor Region, GbE Region, ME Region and Platform
 176                           Region, this value specifies the offset from the Region Base; for BIOS Region,
 177                           this value specifies the offset from the start of the BIOS Image. In Non
 178                           Descriptor Mode, this value specifies the offset from the start of the BIOS Image.
 179                           Please note BIOS Image size may be smaller than BIOS Region size (in Descriptor
 180                           Mode) or the flash size (in Non Descriptor Mode), and in this case, BIOS Image is
 181                           supposed to be placed at the top end of the BIOS Region (in Descriptor Mode) or
 182                           the flash (in Non Descriptor Mode)
 183   DataByteCount           Number of bytes in the data portion of the SPI cycle.
 184   Buffer                  Pointer to caller-allocated buffer containing the dada received or sent during the SPI cycle.
 185   SpiRegionType           SPI Region type. Values EnumSpiRegionBios, EnumSpiRegionGbE, EnumSpiRegionMe,
 186                           EnumSpiRegionDescriptor, and EnumSpiRegionPlatformData are only applicable in
 187                           Descriptor mode. Value EnumSpiRegionAll is applicable to both Descriptor Mode
 188                           and Non Descriptor Mode, which indicates "SpiRegionOffset" is actually relative
 189                           to base of the 1st flash device (i.e., it is a Flash Linear Address).
 190
 191 Returns:
 192
 193   EFI_SUCCESS             Command succeed.
 194   EFI_INVALID_PARAMETER   The parameters specified are not valid.
 195   EFI_UNSUPPORTED         Command not supported.
 196   EFI_DEVICE_ERROR        Device error, command aborts abnormally.
 197
 198 --*/
 199 ;
 200
 201 EFI_STATUS
 202 SendSpiCmd (
 203   IN     EFI_SPI_PROTOCOL   *This,
 204   IN     UINT8              OpcodeIndex,
 205   IN     UINT8              PrefixOpcodeIndex,
 206   IN     BOOLEAN            DataCycle,
 207   IN     BOOLEAN            Atomic,
 208   IN     BOOLEAN            ShiftOut,
 209   IN     UINTN              Address,
 210   IN     UINT32             DataByteCount,
 211   IN OUT UINT8              *Buffer,
 212   IN     SPI_REGION_TYPE    SpiRegionType
 213   )
 214 /*++
 215
 216 Routine Description:
 217
 218   This function sends the programmed SPI command to the slave device.
 219
 220 Arguments:
 221
 222   OpcodeIndex       Index of the command in the OpCode Menu.
 223   PrefixOpcodeIndex Index of the first command to run when in an atomic cycle sequence.
 224   DataCycle         TRUE if the SPI cycle contains data
 225   Atomic            TRUE if the SPI cycle is atomic and interleave cycles are not allowed.
 226   ShiftOut          If DataByteCount is not zero, TRUE to shift data out and FALSE to shift data in.
 227   Address           In Descriptor Mode, for Descriptor Region, GbE Region, ME Region and Platform
 228                     Region, this value specifies the offset from the Region Base; for BIOS Region,
 229                     this value specifies the offset from the start of the BIOS Image. In Non
 230                     Descriptor Mode, this value specifies the offset from the start of the BIOS Image.
 231                     Please note BIOS Image size may be smaller than BIOS Region size (in Descriptor
 232                     Mode) or the flash size (in Non Descriptor Mode), and in this case, BIOS Image is
 233                     supposed to be placed at the top end of the BIOS Region (in Descriptor Mode) or
 234                     the flash (in Non Descriptor Mode)
 235   DataByteCount     Number of bytes in the data portion of the SPI cycle. This function may break the
 236                     data transfer into multiple operations. This function ensures each operation does
 237                     not cross 256 byte flash address boundary.
 238                     *NOTE: if there is some SPI chip that has a stricter address boundary requirement
 239                     (e.g., its write page size is < 256 byte), then the caller cannot rely on this
 240                     function to cut the data transfer at proper address boundaries, and it's the
 241                     caller's reponsibility to pass in a properly cut DataByteCount parameter.
 242   Buffer            Data received or sent during the SPI cycle.
 243   SpiRegionType     SPI Region type. Values EnumSpiRegionBios, EnumSpiRegionGbE, EnumSpiRegionMe,
 244                     EnumSpiRegionDescriptor, and EnumSpiRegionPlatformData are only applicable in
 245                     Descriptor mode. Value EnumSpiRegionAll is applicable to both Descriptor Mode
 246                     and Non Descriptor Mode, which indicates "SpiRegionOffset" is actually relative
 247                     to base of the 1st flash device (i.e., it is a Flash Linear Address).
 248
 249 Returns:
 250
 251   EFI_SUCCESS             SPI command completes successfully.
 252   EFI_DEVICE_ERROR        Device error, the command aborts abnormally.
 253   EFI_ACCESS_DENIED       Some unrecognized command encountered in hardware sequencing mode
 254   EFI_INVALID_PARAMETER   The parameters specified are not valid.
 255
 256 --*/
 257 ;
 258
 259 BOOLEAN
 260 WaitForSpiCycleComplete (
 261   IN     EFI_SPI_PROTOCOL   *This,
 262   IN     BOOLEAN            ErrorCheck
 263   )
 264 /*++
 265
 266 Routine Description:
 267
 268   Wait execution cycle to complete on the SPI interface. Check both Hardware
 269   and Software Sequencing status registers
 270
 271 Arguments:
 272
 273   This                - The SPI protocol instance
 274   UseSoftwareSequence - TRUE if this is a Hardware Sequencing operation
 275   ErrorCheck          - TRUE if the SpiCycle needs to do the error check
 276
 277 Returns:
 278
 279   TRUE       SPI cycle completed on the interface.
 280   FALSE      Time out while waiting the SPI cycle to complete.
 281              It's not safe to program the next command on the SPI interface.
 282
 283 --*/
 284 ;
 285
 286 EFI_STATUS
 287 EFIAPI
 288 SpiProtocolInfo (
 289   IN EFI_SPI_PROTOCOL     *This,
 290   OUT SPI_INIT_INFO      **InitInfoPtr
 291   )
 292 /*++
 293
 294 Routine Description:
 295
 296   Return info about SPI host controller, to help callers usage of Execute
 297   service.
 298
 299   If 0xff is returned as an opcode index in init info struct
 300   then device does not support the operation.
 301
 302 Arguments:
 303
 304   This                    Pointer to the EFI_SPI_PROTOCOL instance.
 305   InitInfoPtr             Pointer to init info written to this memory location.
 306
 307 Returns:
 308
 309   EFI_SUCCESS             Information returned.
 310   EFI_INVALID_PARAMETER   Invalid parameter.
 311   EFI_NOT_READY           Required resources not setup.
 312   Others                  Unexpected error happened.
 313
 314 --*/
 315 ;
 316
 317 #endif