UefiPayloadPkg/Include/Library/SpiFlashLib.h

   1 /** @file
   2   PCH SPI Common Driver implements the SPI Host Controller Compatibility Interface.
   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_FLASH_LIB_H_
  10 #define SPI_FLASH_LIB_H_
  11
  12 /**
  13   Flash Region Type
  14 **/
  15 typedef enum {
  16   FlashRegionDescriptor,
  17   FlashRegionBios,
  18   FlashRegionMe,
  19   FlashRegionGbE,
  20   FlashRegionPlatformData,
  21   FlashRegionDer,
  22   FlashRegionAll,
  23   FlashRegionMax
  24 } FLASH_REGION_TYPE;
  25
  26 /**
  27   Read SFDP data from the flash part.
  28
  29   @param[in] ComponentNumber      The Component Number for chip select
  30   @param[in] ByteCount            Number of bytes in SFDP data portion of the SPI cycle, the max number is 64
  31   @param[out] SfdpData            The Pointer to caller-allocated buffer containing the SFDP data received
  32                                   It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
  33
  34   @retval EFI_SUCCESS             Command succeed.
  35   @retval EFI_INVALID_PARAMETER   The parameters specified are not valid.
  36   @retval EFI_DEVICE_ERROR        Device error, command aborts abnormally.
  37 **/
  38 EFI_STATUS
  39 EFIAPI
  40 SpiFlashReadSfdp (
  41   IN     UINT8              ComponentNumber,
  42   IN     UINT32             ByteCount,
  43   OUT    UINT8              *SfdpData
  44   );
  45
  46 /**
  47   Read Jedec Id from the flash part.
  48
  49   @param[in] ComponentNumber      The Component Number for chip select
  50   @param[in] ByteCount            Number of bytes in JedecId data portion of the SPI cycle, the data size is 3 typically
  51   @param[out] JedecId             The Pointer to caller-allocated buffer containing JEDEC ID received
  52                                   It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
  53
  54   @retval EFI_SUCCESS             Command succeed.
  55   @retval EFI_INVALID_PARAMETER   The parameters specified are not valid.
  56   @retval EFI_DEVICE_ERROR        Device error, command aborts abnormally.
  57 **/
  58 EFI_STATUS
  59 EFIAPI
  60 SpiFlashReadJedecId (
  61   IN     UINT8              ComponentNumber,
  62   IN     UINT32             ByteCount,
  63   OUT    UINT8              *JedecId
  64   );
  65
  66 /**
  67   Write the status register in the flash part.
  68
  69   @param[in] ByteCount            Number of bytes in Status data portion of the SPI cycle, the data size is 1 typically
  70   @param[in] StatusValue          The Pointer to caller-allocated buffer containing the value of Status register writing
  71
  72   @retval EFI_SUCCESS             Command succeed.
  73   @retval EFI_INVALID_PARAMETER   The parameters specified are not valid.
  74   @retval EFI_DEVICE_ERROR        Device error, command aborts abnormally.
  75 **/
  76 EFI_STATUS
  77 EFIAPI
  78 SpiFlashWriteStatus (
  79   IN     UINT32             ByteCount,
  80   IN     UINT8              *StatusValue
  81   );
  82
  83 /**
  84   Read status register in the flash part.
  85
  86   @param[in] ByteCount            Number of bytes in Status data portion of the SPI cycle, the data size is 1 typically
  87   @param[out] StatusValue         The Pointer to caller-allocated buffer containing the value of Status register received.
  88
  89   @retval EFI_SUCCESS             Command succeed.
  90   @retval EFI_INVALID_PARAMETER   The parameters specified are not valid.
  91   @retval EFI_DEVICE_ERROR        Device error, command aborts abnormally.
  92 **/
  93 EFI_STATUS
  94 EFIAPI
  95 SpiFlashReadStatus (
  96   IN     UINT32             ByteCount,
  97   OUT    UINT8              *StatusValue
  98   );
  99
 100 /**
 101   Read SC Soft Strap Values
 102
 103   @param[in] SoftStrapAddr        SC Soft Strap address offset from FPSBA.
 104   @param[in] ByteCount            Number of bytes in SoftStrap data portion of the SPI cycle
 105   @param[out] SoftStrapValue      The Pointer to caller-allocated buffer containing SC Soft Strap Value.
 106                                   It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
 107
 108   @retval EFI_SUCCESS             Command succeed.
 109   @retval EFI_INVALID_PARAMETER   The parameters specified are not valid.
 110   @retval EFI_DEVICE_ERROR        Device error, command aborts abnormally.
 111 **/
 112 EFI_STATUS
 113 EFIAPI
 114 SpiReadPchSoftStrap (
 115   IN     UINT32             SoftStrapAddr,
 116   IN     UINT32             ByteCount,
 117   OUT    UINT8              *SoftStrapValue
 118   );
 119
 120
 121 /**
 122   Read data from the flash part.
 123
 124   @param[in] FlashRegionType      The Flash Region type for flash cycle which is listed in the Descriptor.
 125   @param[in] Address              The Flash Linear Address must fall within a region for which BIOS has access permissions.
 126   @param[in] ByteCount            Number of bytes in the data portion of the SPI cycle.
 127   @param[out] Buffer              The Pointer to caller-allocated buffer containing the dada received.
 128                                   It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
 129
 130   @retval EFI_SUCCESS             Command succeed.
 131   @retval EFI_INVALID_PARAMETER   The parameters specified are not valid.
 132   @retval EFI_DEVICE_ERROR        Device error, command aborts abnormally.
 133 **/
 134 EFI_STATUS
 135 EFIAPI
 136 SpiFlashRead (
 137   IN     FLASH_REGION_TYPE  FlashRegionType,
 138   IN     UINT32             Address,
 139   IN     UINT32             ByteCount,
 140   OUT    UINT8              *Buffer
 141   );
 142
 143 /**
 144   Erase some area on the flash part.
 145
 146   @param[in] FlashRegionType      The Flash Region type for flash cycle which is listed in the Descriptor.
 147   @param[in] Address              The Flash Linear Address must fall within a region for which BIOS has access permissions.
 148   @param[in] ByteCount            Number of bytes in the data portion of the SPI cycle.
 149
 150   @retval EFI_SUCCESS             Command succeed.
 151   @retval EFI_INVALID_PARAMETER   The parameters specified are not valid.
 152   @retval EFI_DEVICE_ERROR        Device error, command aborts abnormally.
 153 **/
 154 EFI_STATUS
 155 EFIAPI
 156 SpiFlashErase (
 157   IN     FLASH_REGION_TYPE  FlashRegionType,
 158   IN     UINT32             Address,
 159   IN     UINT32             ByteCount
 160   );
 161
 162 /**
 163   Write data to the flash part.
 164
 165   @param[in] FlashRegionType      The Flash Region type for flash cycle which is listed in the Descriptor.
 166   @param[in] Address              The Flash Linear Address must fall within a region for which BIOS has access permissions.
 167   @param[in] ByteCount            Number of bytes in the data portion of the SPI cycle.
 168   @param[in] Buffer               Pointer to caller-allocated buffer containing the data sent during the SPI cycle.
 169
 170   @retval EFI_SUCCESS             Command succeed.
 171   @retval EFI_INVALID_PARAMETER   The parameters specified are not valid.
 172   @retval EFI_DEVICE_ERROR        Device error, command aborts abnormally.
 173 **/
 174 EFI_STATUS
 175 EFIAPI
 176 SpiFlashWrite (
 177   IN     FLASH_REGION_TYPE  FlashRegionType,
 178   IN     UINT32             Address,
 179   IN     UINT32             ByteCount,
 180   IN     UINT8              *Buffer
 181   );
 182
 183 /**
 184   Initialize an SPI library.
 185
 186   @retval EFI_SUCCESS             The protocol instance was properly initialized
 187   @retval EFI_NOT_FOUND           The expected SPI info could not be found
 188 **/
 189 EFI_STATUS
 190 EFIAPI
 191 SpiConstructor (
 192   VOID
 193   );
 194
 195 /**
 196   Get the SPI region base and size, based on the enum type
 197
 198   @param[in] FlashRegionType      The Flash Region type for for the base address which is listed in the Descriptor.
 199   @param[out] BaseAddress         The Flash Linear Address for the Region 'n' Base
 200   @param[out] RegionSize          The size for the Region 'n'
 201
 202   @retval EFI_SUCCESS             Read success
 203   @retval EFI_INVALID_PARAMETER   Invalid region type given
 204   @retval EFI_DEVICE_ERROR        The region is not used
 205 **/
 206 EFI_STATUS
 207 EFIAPI
 208 SpiGetRegionAddress (
 209   IN     FLASH_REGION_TYPE  FlashRegionType,
 210   OUT    UINT32             *BaseAddress, OPTIONAL
 211   OUT    UINT32             *RegionSize OPTIONAL
 212   );
 213
 214 #endif
 215