| /** @file |
| This file defines the SPI NOR Flash Protocol. |
| |
| Copyright (c) 2017, Intel Corporation. All rights reserved.<BR> |
| SPDX-License-Identifier: BSD-2-Clause-Patent |
| |
| @par Revision Reference: |
| This Protocol was introduced in UEFI PI Specification 1.6. |
| |
| **/ |
| |
| #ifndef __SPI_NOR_FLASH_PROTOCOL_H__ |
| #define __SPI_NOR_FLASH_PROTOCOL_H__ |
| |
| #include <Protocol/SpiConfiguration.h> |
| |
| /// |
| /// Global ID for the SPI NOR Flash Protocol |
| /// |
| #define EFI_SPI_NOR_FLASH_PROTOCOL_GUID \ |
| { 0xb57ec3fe, 0xf833, 0x4ba6, \ |
| { 0x85, 0x78, 0x2a, 0x7d, 0x6a, 0x87, 0x44, 0x4b }} |
| |
| typedef struct _EFI_SPI_NOR_FLASH_PROTOCOL EFI_SPI_NOR_FLASH_PROTOCOL; |
| |
| /** |
| Read the 3 byte manufacture and device ID from the SPI flash. |
| |
| This routine must be called at or below TPL_NOTIFY. |
| This routine reads the 3 byte manufacture and device ID from the flash part |
| filling the buffer provided. |
| |
| @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data structure. |
| @param[out] Buffer Pointer to a 3 byte buffer to receive the manufacture and |
| device ID. |
| |
| |
| |
| @retval EFI_SUCCESS The manufacture and device ID was read |
| successfully. |
| @retval EFI_INVALID_PARAMETER Buffer is NULL |
| @retval EFI_DEVICE_ERROR Invalid data received from SPI flash part. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_GET_FLASH_ID) ( |
| IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, |
| OUT UINT8 *Buffer |
| ); |
| |
| /** |
| Read data from the SPI flash. |
| |
| This routine must be called at or below TPL_NOTIFY. |
| This routine reads data from the SPI part in the buffer provided. |
| |
| @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data |
| structure. |
| @param[in] FlashAddress Address in the flash to start reading |
| @param[in] LengthInBytes Read length in bytes |
| @param[out] Buffer Address of a buffer to receive the data |
| |
| @retval EFI_SUCCESS The data was read successfully. |
| @retval EFI_INVALID_PARAMETER Buffer is NULL, or |
| FlashAddress >= This->FlashSize, or |
| LengthInBytes > This->FlashSize - FlashAddress |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_READ_DATA) ( |
| IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, |
| IN UINT32 FlashAddress, |
| IN UINT32 LengthInBytes, |
| OUT UINT8 *Buffer |
| ); |
| |
| /** |
| Read the flash status register. |
| |
| This routine must be called at or below TPL_NOTIFY. |
| This routine reads the flash part status register. |
| |
| @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data |
| structure. |
| @param[in] LengthInBytes Number of status bytes to read. |
| @param[out] FlashStatus Pointer to a buffer to receive the flash status. |
| |
| @retval EFI_SUCCESS The status register was read successfully. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_READ_STATUS) ( |
| IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, |
| IN UINT32 LengthInBytes, |
| OUT UINT8 *FlashStatus |
| ); |
| |
| /** |
| Write the flash status register. |
| |
| This routine must be called at or below TPL_N OTIFY. |
| This routine writes the flash part status register. |
| |
| @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data |
| structure. |
| @param[in] LengthInBytes Number of status bytes to write. |
| @param[in] FlashStatus Pointer to a buffer containing the new status. |
| |
| @retval EFI_SUCCESS The status write was successful. |
| @retval EFI_OUT_OF_RESOURCES Failed to allocate the write buffer. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_STATUS) ( |
| IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, |
| IN UINT32 LengthInBytes, |
| IN UINT8 *FlashStatus |
| ); |
| |
| /** |
| Write data to the SPI flash. |
| |
| This routine must be called at or below TPL_NOTIFY. |
| This routine breaks up the write operation as necessary to write the data to |
| the SPI part. |
| |
| @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data |
| structure. |
| @param[in] FlashAddress Address in the flash to start writing |
| @param[in] LengthInBytes Write length in bytes |
| @param[in] Buffer Address of a buffer containing the data |
| |
| @retval EFI_SUCCESS The data was written successfully. |
| @retval EFI_INVALID_PARAMETER Buffer is NULL, or |
| FlashAddress >= This->FlashSize, or |
| LengthInBytes > This->FlashSize - FlashAddress |
| @retval EFI_OUT_OF_RESOURCES Insufficient memory to copy buffer. |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_DATA) ( |
| IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, |
| IN UINT32 FlashAddress, |
| IN UINT32 LengthInBytes, |
| IN UINT8 *Buffer |
| ); |
| |
| /** |
| Efficiently erases one or more 4KiB regions in the SPI flash. |
| |
| This routine must be called at or below TPL_NOTIFY. |
| This routine uses a combination of 4 KiB and larger blocks to erase the |
| specified area. |
| |
| @param[in] This Pointer to an EFI_SPI_NOR_FLASH_PROTOCOL data |
| structure. |
| @param[in] FlashAddress Address within a 4 KiB block to start erasing |
| @param[in] BlockCount Number of 4 KiB blocks to erase |
| |
| @retval EFI_SUCCESS The erase was completed successfully. |
| @retval EFI_INVALID_PARAMETER FlashAddress >= This->FlashSize, or |
| BlockCount * 4 KiB |
| > This->FlashSize - FlashAddress |
| |
| **/ |
| typedef |
| EFI_STATUS |
| (EFIAPI *EFI_SPI_NOR_FLASH_PROTOCOL_ERASE) ( |
| IN CONST EFI_SPI_NOR_FLASH_PROTOCOL *This, |
| IN UINT32 FlashAddress, |
| IN UINT32 BlockCount |
| ); |
| |
| /// |
| /// The EFI_SPI_NOR_FLASH_PROTOCOL exists in the SPI peripheral layer. |
| /// This protocol manipulates the SPI NOR flash parts using a common set of |
| /// commands. The board layer provides the interconnection and configuration |
| /// details for the SPI NOR flash part. The SPI NOR flash driver uses this |
| /// configuration data to expose a generic interface which provides the |
| /// following APls: |
| /// * Read manufacture and device ID |
| /// * Read data |
| /// * Read data using low frequency |
| /// * Read status |
| /// * Write data |
| /// * Erase 4 KiB blocks |
| /// * Erase 32 or 64 KiB blocks |
| /// * Write status |
| /// The EFI_SPI_NOR_FLASH_PROTOCOL also exposes some APls to set the security |
| /// features on the legacy SPI flash controller. |
| /// |
| struct _EFI_SPI_NOR_FLASH_PROTOCOL { |
| /// |
| /// Pointer to an EFI_SPI_PERIPHERAL data structure |
| /// |
| CONST EFI_SPI_PERIPHERAL *SpiPeripheral; |
| |
| /// |
| /// Flash size in bytes |
| /// |
| UINT32 FlashSize; |
| |
| /// |
| /// Manufacture and Device ID |
| /// |
| UINT8 Deviceid[3]; |
| |
| /// |
| /// Erase block size in bytes |
| /// |
| UINT32 EraseBlockBytes; |
| |
| /// |
| /// Read the 3 byte manufacture and device ID from the SPI flash. |
| /// |
| EFI_SPI_NOR_FLASH_PROTOCOL_GET_FLASH_ID GetFlashid; |
| |
| /// |
| /// Read data from the SPI flash. |
| /// |
| EFI_SPI_NOR_FLASH_PROTOCOL_READ_DATA ReadData; |
| |
| /// |
| /// Low frequency read data from the SPI flash. |
| /// |
| EFI_SPI_NOR_FLASH_PROTOCOL_READ_DATA LfReadData; |
| |
| /// |
| /// Read the flash status register. |
| /// |
| EFI_SPI_NOR_FLASH_PROTOCOL_READ_STATUS ReadStatus; |
| |
| /// |
| /// Write the flash status register. |
| /// |
| EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_STATUS WriteStatus; |
| |
| /// |
| /// Write data to the SPI flash. |
| /// |
| EFI_SPI_NOR_FLASH_PROTOCOL_WRITE_DATA WriteData; |
| |
| /// |
| /// Efficiently erases one or more 4KiB regions in the SPI flash. |
| /// |
| EFI_SPI_NOR_FLASH_PROTOCOL_ERASE Erase; |
| }; |
| |
| extern EFI_GUID gEfiSpiNorFlashProtocolGuid; |
| |
| #endif // __SPI_NOR_FLASH_PROTOCOL_H__ |