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   Read data from the flash part.
 122
 123   @param[in] FlashRegionType      The Flash Region type for flash cycle which is listed in the Descriptor.
 124   @param[in] Address              The Flash Linear Address must fall within a region for which BIOS has access permissions.
 125   @param[in] ByteCount            Number of bytes in the data portion of the SPI cycle.
 126   @param[out] Buffer              The Pointer to caller-allocated buffer containing the dada received.
 127                                   It is the caller's responsibility to make sure Buffer is large enough for the total number of bytes read.
 128
 129   @retval EFI_SUCCESS             Command succeed.
 130   @retval EFI_INVALID_PARAMETER   The parameters specified are not valid.
 131   @retval EFI_DEVICE_ERROR        Device error, command aborts abnormally.
 132 **/
 133 EFI_STATUS
 134 EFIAPI
 135 SpiFlashRead (
 136   IN     FLASH_REGION_TYPE  FlashRegionType,
 137   IN     UINT32             Address,
 138   IN     UINT32             ByteCount,
 139   OUT    UINT8              *Buffer
 140   );
 141
 142 /**
 143   Erase some area on the flash part.
 144
 145   @param[in] FlashRegionType      The Flash Region type for flash cycle which is listed in the Descriptor.
 146   @param[in] Address              The Flash Linear Address must fall within a region for which BIOS has access permissions.
 147   @param[in] ByteCount            Number of bytes in the data portion of the SPI cycle.
 148
 149   @retval EFI_SUCCESS             Command succeed.
 150   @retval EFI_INVALID_PARAMETER   The parameters specified are not valid.
 151   @retval EFI_DEVICE_ERROR        Device error, command aborts abnormally.
 152 **/
 153 EFI_STATUS
 154 EFIAPI
 155 SpiFlashErase (
 156   IN     FLASH_REGION_TYPE  FlashRegionType,
 157   IN     UINT32             Address,
 158   IN     UINT32             ByteCount
 159   );
 160
 161 /**
 162   Write data to the flash part.
 163
 164   @param[in] FlashRegionType      The Flash Region type for flash cycle which is listed in the Descriptor.
 165   @param[in] Address              The Flash Linear Address must fall within a region for which BIOS has access permissions.
 166   @param[in] ByteCount            Number of bytes in the data portion of the SPI cycle.
 167   @param[in] Buffer               Pointer to caller-allocated buffer containing the data sent during the SPI cycle.
 168
 169   @retval EFI_SUCCESS             Command succeed.
 170   @retval EFI_INVALID_PARAMETER   The parameters specified are not valid.
 171   @retval EFI_DEVICE_ERROR        Device error, command aborts abnormally.
 172 **/
 173 EFI_STATUS
 174 EFIAPI
 175 SpiFlashWrite (
 176   IN     FLASH_REGION_TYPE  FlashRegionType,
 177   IN     UINT32             Address,
 178   IN     UINT32             ByteCount,
 179   IN     UINT8              *Buffer
 180   );
 181
 182 /**
 183   Initialize an SPI library.
 184
 185   @retval EFI_SUCCESS             The protocol instance was properly initialized
 186   @retval EFI_NOT_FOUND           The expected SPI info could not be found
 187 **/
 188 EFI_STATUS
 189 EFIAPI
 190 SpiConstructor (
 191   VOID
 192   );
 193
 194 /**
 195   Get the SPI region base and size, based on the enum type
 196
 197   @param[in] FlashRegionType      The Flash Region type for for the base address which is listed in the Descriptor.
 198   @param[out] BaseAddress         The Flash Linear Address for the Region 'n' Base
 199   @param[out] RegionSize          The size for the Region 'n'
 200
 201   @retval EFI_SUCCESS             Read success
 202   @retval EFI_INVALID_PARAMETER   Invalid region type given
 203   @retval EFI_DEVICE_ERROR        The region is not used
 204 **/
 205 EFI_STATUS
 206 EFIAPI
 207 SpiGetRegionAddress (
 208   IN     FLASH_REGION_TYPE  FlashRegionType,
 209   OUT    UINT32             *BaseAddress  OPTIONAL,
 210   OUT    UINT32             *RegionSize OPTIONAL
 211   );
 212
 213 #endif