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