MdePkg/Include/Protocol/SpiNorFlash.h

   1 /** @file
   2   This file defines the SPI NOR Flash Protocol.
   3
   4   Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7   @par Revision Reference:
   8     This Protocol was introduced in UEFI PI Specification 1.6.
   9
  10 **/
  11
  12 #ifndef __SPI_NOR_FLASH_PROTOCOL_H__
  13 #define __SPI_NOR_FLASH_PROTOCOL_H__
  14
  15 #include <Protocol/SpiConfiguration.h>
  16
  17 ///
  18 /// Global ID for the SPI NOR Flash Protocol
  19 ///
  20 #define EFI_SPI_NOR_FLASH_PROTOCOL_GUID  \
  21   { 0xb57ec3fe, 0xf833, 0x4ba6,          \
  22     { 0x85, 0x78, 0x2a, 0x7d, 0x6a, 0x87, 0x44, 0x4b }}
  23
  24 typedef struct _EFI_SPI_NOR_FLASH_PROTOCOL EFI_SPI_NOR_FLASH_PROTOCOL;
  25
  26 /**
  27   Read the 3 byte manufacture and device ID from the SPI flash.
  28
  29   This routine must be called at or below TPL_NOTIFY.
  30   This routine reads the 3 byte manufacture and device ID from the flash part
  31   filling the buffer provided.
  32
  33   @param[in]  This    Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data structure.
  34   @param[out] Buffer  Pointer to a 3 byte buffer to receive the manufacture and
  35                       device ID.
  36
  37
  38
  39   @retval EFI_SUCCESS            The manufacture and device ID was read
  40                                  successfully.
  41   @retval EFI_INVALID_PARAMETER  Buffer is NULL
  42   @retval EFI_DEVICE_ERROR       Invalid data received from SPI flash part.
  43
  44 **/
  45 typedef
  46 EFI_STATUS
  47 (EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_GET_FLASH_ID) (
  48   IN  CONST EFI_SPI_NOR_FLASH_PROTOCOL  *This,
  49   OUT UINT8                             *Buffer
  50   );
  51
  52 /**
  53   Read data from the SPI flash.
  54
  55   This routine must be called at or below TPL_NOTIFY.
  56   This routine reads data from the SPI part in the buffer provided.
  57
  58   @param[in]  This           Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data
  59                              structure.
  60   @param[in]  FlashAddress   Address in the flash to start reading
  61   @param[in]  LengthInBytes  Read length in bytes
  62   @param[out] Buffer         Address of a buffer to receive the data
  63
  64   @retval EFI_SUCCESS            The data was read successfully.
  65   @retval EFI_INVALID_PARAMETER  Buffer is NULL, or
  66                                  FlashAddress >= This->FlashSize, or
  67                                  LengthInBytes > This->FlashSize - FlashAddress
  68
  69 **/
  70 typedef
  71 EFI_STATUS
  72 (EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_READ_DATA) (
  73   IN  CONST EFI_SPI_NOR_FLASH_PROTOCOL  *This,
  74   IN  UINT32                            FlashAddress,
  75   IN  UINT32                            LengthInBytes,
  76   OUT UINT8                             *Buffer
  77   );
  78
  79 /**
  80   Read the flash status register.
  81
  82   This routine must be called at or below TPL_NOTIFY.
  83   This routine reads the flash part status register.
  84
  85   @param[in]  This           Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data
  86                              structure.
  87   @param[in]  LengthInBytes  Number of status bytes to read.
  88   @param[out] FlashStatus    Pointer to a buffer to receive the flash status.
  89
  90   @retval EFI_SUCCESS  The status register was read successfully.
  91
  92 **/
  93 typedef
  94 EFI_STATUS
  95 (EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_READ_STATUS) (
  96   IN  CONST EFI_SPI_NOR_FLASH_PROTOCOL  *This,
  97   IN  UINT32                            LengthInBytes,
  98   OUT UINT8                             *FlashStatus
  99   );
 100
 101 /**
 102   Write the flash status register.
 103
 104   This routine must be called at or below TPL_N OTIFY.
 105   This routine writes the flash part status register.
 106
 107   @param[in] This           Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data
 108                             structure.
 109   @param[in] LengthInBytes  Number of status bytes to write.
 110   @param[in] FlashStatus    Pointer to a buffer containing the new status.
 111
 112   @retval EFI_SUCCESS           The status write was successful.
 113   @retval EFI_OUT_OF_RESOURCES  Failed to allocate the write buffer.
 114
 115 **/
 116 typedef
 117 EFI_STATUS
 118 (EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_STATUS) (
 119   IN CONST EFI_SPI_NOR_FLASH_PROTOCOL  *This,
 120   IN UINT32                            LengthInBytes,
 121   IN UINT8                             *FlashStatus
 122   );
 123
 124 /**
 125   Write data to the SPI flash.
 126
 127   This routine must be called at or below TPL_NOTIFY.
 128   This routine breaks up the write operation as necessary to write the data to
 129   the SPI part.
 130
 131   @param[in] This           Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data
 132                             structure.
 133   @param[in] FlashAddress   Address in the flash to start writing
 134   @param[in] LengthInBytes  Write length in bytes
 135   @param[in] Buffer         Address of a buffer containing the data
 136
 137   @retval EFI_SUCCESS            The data was written successfully.
 138   @retval EFI_INVALID_PARAMETER  Buffer is NULL, or
 139                                  FlashAddress >= This->FlashSize, or
 140                                  LengthInBytes > This->FlashSize - FlashAddress
 141   @retval EFI_OUT_OF_RESOURCES   Insufficient memory to copy buffer.
 142
 143 **/
 144 typedef
 145 EFI_STATUS
 146 (EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_DATA) (
 147   IN CONST EFI_SPI_NOR_FLASH_PROTOCOL  *This,
 148   IN UINT32                            FlashAddress,
 149   IN UINT32                            LengthInBytes,
 150   IN UINT8                             *Buffer
 151   );
 152
 153 /**
 154   Efficiently erases one or more 4KiB regions in the SPI flash.
 155
 156   This routine must be called at or below TPL_NOTIFY.
 157   This routine uses a combination of 4 KiB and larger blocks to erase the
 158   specified area.
 159
 160   @param[in] This          Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data
 161                            structure.
 162   @param[in] FlashAddress  Address within a 4 KiB block to start erasing
 163   @param[in] BlockCount    Number of 4 KiB blocks to erase
 164
 165   @retval EFI_SUCCESS            The erase was completed successfully.
 166   @retval EFI_INVALID_PARAMETER  FlashAddress >= This->FlashSize, or
 167                                  BlockCount * 4 KiB
 168                                    > This->FlashSize - FlashAddress
 169
 170 **/
 171 typedef
 172 EFI_STATUS
 173 (EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_ERASE) (
 174   IN CONST EFI_SPI_NOR_FLASH_PROTOCOL  *This,
 175   IN UINT32                            FlashAddress,
 176   IN UINT32                            BlockCount
 177   );
 178
 179 ///
 180 /// The EFI_SPI_NOR_FLASH_PROTOCOL exists in the SPI peripheral layer.
 181 /// This protocol manipulates the SPI NOR flash parts using a common set of
 182 /// commands. The board layer provides the interconnection and configuration
 183 /// details for the SPI NOR flash part. The SPI NOR flash driver uses this
 184 /// configuration data to expose a generic interface which provides the
 185 /// following APls:
 186 /// * Read manufacture and device ID
 187 /// * Read data
 188 /// * Read data using low frequency
 189 /// * Read status
 190 /// * Write data
 191 /// * Erase 4 KiB blocks
 192 /// * Erase 32 or 64 KiB blocks
 193 /// * Write status
 194 /// The EFI_SPI_NOR_FLASH_PROTOCOL also exposes some APls to set the security
 195 /// features on the legacy SPI flash controller.
 196 ///
 197 struct _EFI_SPI_NOR_FLASH_PROTOCOL {
 198   ///
 199   /// Pointer to an EFI_SPI_PERIPHERAL data structure
 200   ///
 201   CONST EFI_SPI_PERIPHERAL                *SpiPeripheral;
 202
 203   ///
 204   /// Flash size in bytes
 205   ///
 206   UINT32                                  FlashSize;
 207
 208   ///
 209   /// Manufacture and Device ID
 210   ///
 211   UINT8                                   Deviceid[3];
 212
 213   ///
 214   /// Erase block size in bytes
 215   ///
 216   UINT32                                  EraseBlockBytes;
 217
 218   ///
 219   /// Read the 3 byte manufacture and device ID from the SPI flash.
 220   ///
 221   EFI_SPI_NOR_FLASH_PROTOCOL_GET_FLASH_ID GetFlashid;
 222
 223   ///
 224   /// Read data from the SPI flash.
 225   ///
 226   EFI_SPI_NOR_FLASH_PROTOCOL_READ_DATA    ReadData;
 227
 228   ///
 229   /// Low frequency read data from the SPI flash.
 230   ///
 231   EFI_SPI_NOR_FLASH_PROTOCOL_READ_DATA    LfReadData;
 232
 233   ///
 234   /// Read the flash status register.
 235   ///
 236   EFI_SPI_NOR_FLASH_PROTOCOL_READ_STATUS  ReadStatus;
 237
 238   ///
 239   /// Write the flash status register.
 240   ///
 241   EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_STATUS WriteStatus;
 242
 243   ///
 244   /// Write data to the SPI flash.
 245   ///
 246   EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_DATA   WriteData;
 247
 248   ///
 249   /// Efficiently erases one or more 4KiB regions in the SPI flash.
 250   ///
 251   EFI_SPI_NOR_FLASH_PROTOCOL_ERASE        Erase;
 252 };
 253
 254 extern EFI_GUID gEfiSpiNorFlashProtocolGuid;
 255
 256 #endif // __SPI_NOR_FLASH_PROTOCOL_H__