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