UefiPayloadPkg/Library/SpiFlashLib/SpiCommon.h

   1 /** @file
   2   Header file for the SPI flash module.
   3
   4   Copyright (c) 2017 - 2021, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef SPI_COMMON_LIB_H_
  10 #define SPI_COMMON_LIB_H_
  11
  12 #include <PiDxe.h>
  13 #include <Uefi/UefiBaseType.h>
  14 #include <IndustryStandard/Pci30.h>
  15 #include <Library/IoLib.h>
  16 #include <Library/DebugLib.h>
  17 #include <Library/BaseMemoryLib.h>
  18 #include <Library/SpiFlashLib.h>
  19 #include <Library/MemoryAllocationLib.h>
  20 #include <Library/BaseLib.h>
  21 #include <Library/HobLib.h>
  22 #include <Library/TimerLib.h>
  23 #include <Guid/SpiFlashInfoGuid.h>
  24 #include "RegsSpi.h"
  25
  26 ///
  27 /// Maximum time allowed while waiting the SPI cycle to complete
  28 ///  Wait Time = 6 seconds = 6000000 microseconds
  29 ///  Wait Period = 10 microseconds
  30 ///
  31 #define WAIT_TIME   6000000     ///< Wait Time = 6 seconds = 6000000 microseconds
  32 #define WAIT_PERIOD 10          ///< Wait Period = 10 microseconds
  33
  34 ///
  35 /// Flash cycle Type
  36 ///
  37 typedef enum {
  38   FlashCycleRead,
  39   FlashCycleWrite,
  40   FlashCycleErase,
  41   FlashCycleReadSfdp,
  42   FlashCycleReadJedecId,
  43   FlashCycleWriteStatus,
  44   FlashCycleReadStatus,
  45   FlashCycleMax
  46 } FLASH_CYCLE_TYPE;
  47
  48 ///
  49 /// Flash Component Number
  50 ///
  51 typedef enum {
  52   FlashComponent0,
  53   FlashComponent1,
  54   FlashComponentMax
  55 } FLASH_COMPONENT_NUM;
  56
  57 ///
  58 /// Private data structure definitions for the driver
  59 ///
  60 #define SC_SPI_PRIVATE_DATA_SIGNATURE  SIGNATURE_32 ('P', 'S', 'P', 'I')
  61
  62 typedef struct {
  63   UINTN                 Signature;
  64   EFI_HANDLE            Handle;
  65   UINT32                AcpiTmrReg;
  66   UINTN                 PchSpiBase;
  67   UINT16                RegionPermission;
  68   UINT32                SfdpVscc0Value;
  69   UINT32                SfdpVscc1Value;
  70   UINT32                StrapBaseAddress;
  71   UINT8                 NumberOfComponents;
  72   UINT16                Flags;
  73   UINT32                Component1StartAddr;
  74 } SPI_INSTANCE;
  75
  76
  77 /**
  78   Acquire SPI MMIO BAR
  79
  80   @param[in] PchSpiBase           PCH SPI PCI Base Address
  81
  82   @retval                         Return SPI BAR Address
  83
  84 **/
  85 UINT32
  86 AcquireSpiBar0 (
  87   IN  UINTN         PchSpiBase
  88   );
  89
  90
  91 /**
  92   Release SPI MMIO BAR. Do nothing.
  93
  94   @param[in] PchSpiBase           PCH SPI PCI Base Address
  95
  96   @retval None
  97
  98 **/
  99 VOID
 100 ReleaseSpiBar0 (
 101   IN  UINTN         PchSpiBase
 102   );
 103
 104
 105 /**
 106   This function is a hook for Spi to disable BIOS Write Protect
 107
 108   @param[in] PchSpiBase           PCH SPI PCI Base Address
 109   @param[in] CpuSmmBwp            Need to disable CPU SMM Bios write protection or not
 110
 111   @retval EFI_SUCCESS             The protocol instance was properly initialized
 112   @retval EFI_ACCESS_DENIED       The BIOS Region can only be updated in SMM phase
 113
 114 **/
 115 EFI_STATUS
 116 EFIAPI
 117 DisableBiosWriteProtect (
 118   IN  UINTN         PchSpiBase,
 119   IN  UINT8         CpuSmmBwp
 120   );
 121
 122 /**
 123   This function is a hook for Spi to enable BIOS Write Protect
 124
 125   @param[in] PchSpiBase           PCH SPI PCI Base Address
 126   @param[in] CpuSmmBwp            Need to disable CPU SMM Bios write protection or not
 127
 128   @retval None
 129
 130 **/
 131 VOID
 132 EFIAPI
 133 EnableBiosWriteProtect (
 134   IN  UINTN         PchSpiBase,
 135   IN  UINT8         CpuSmmBwp
 136   );
 137
 138
 139 /**
 140   This function disables SPI Prefetching and caching,
 141   and returns previous BIOS Control Register value before disabling.
 142
 143   @param[in] PchSpiBase           PCH SPI PCI Base Address
 144
 145   @retval                         Previous BIOS Control Register value
 146
 147 **/
 148 UINT8
 149 SaveAndDisableSpiPrefetchCache (
 150   IN  UINTN         PchSpiBase
 151   );
 152
 153 /**
 154   This function updates BIOS Control Register with the given value.
 155
 156   @param[in] PchSpiBase           PCH SPI PCI Base Address
 157   @param[in] BiosCtlValue         BIOS Control Register Value to be updated
 158
 159   @retval None
 160
 161 **/
 162 VOID
 163 SetSpiBiosControlRegister (
 164   IN  UINTN         PchSpiBase,
 165   IN  UINT8         BiosCtlValue
 166   );
 167
 168
 169 /**
 170   This function sends the programmed SPI command to the slave device.
 171
 172   @param[in] SpiRegionType        The SPI Region type for flash cycle which is listed in the Descriptor
 173   @param[in] FlashCycleType       The Flash SPI cycle type list in HSFC (Hardware Sequencing Flash Control Register) register
 174   @param[in] Address              The Flash Linear Address must fall within a region for which BIOS has access permissions.
 175   @param[in] ByteCount            Number of bytes in the data portion of the SPI cycle.
 176   @param[in,out] Buffer           Pointer to caller-allocated buffer containing the data received or sent during the SPI cycle.
 177
 178   @retval EFI_SUCCESS             SPI command completes successfully.
 179   @retval EFI_DEVICE_ERROR        Device error, the command aborts abnormally.
 180   @retval EFI_ACCESS_DENIED       Some unrecognized command encountered in hardware sequencing mode
 181   @retval EFI_INVALID_PARAMETER   The parameters specified are not valid.
 182 **/
 183 EFI_STATUS
 184 SendSpiCmd (
 185   IN     FLASH_REGION_TYPE  FlashRegionType,
 186   IN     FLASH_CYCLE_TYPE   FlashCycleType,
 187   IN     UINT32             Address,
 188   IN     UINT32             ByteCount,
 189   IN OUT UINT8              *Buffer
 190   );
 191
 192 /**
 193   Wait execution cycle to complete on the SPI interface.
 194
 195   @param[in] PchSpiBar0           Spi MMIO base address
 196   @param[in] ErrorCheck           TRUE if the SpiCycle needs to do the error check
 197
 198   @retval TRUE                    SPI cycle completed on the interface.
 199   @retval FALSE                   Time out while waiting the SPI cycle to complete.
 200                                   It's not safe to program the next command on the SPI interface.
 201 **/
 202 BOOLEAN
 203 WaitForSpiCycleComplete (
 204   IN     UINT32             PchSpiBar0,
 205   IN     BOOLEAN            ErrorCheck
 206   );
 207
 208 #endif