diff options
Diffstat (limited to 'MdePkg/Include/Protocol/SpiNorFlash.h')
| -rw-r--r-- | MdePkg/Include/Protocol/SpiNorFlash.h | 256 |
1 files changed, 256 insertions, 0 deletions
diff --git a/MdePkg/Include/Protocol/SpiNorFlash.h b/MdePkg/Include/Protocol/SpiNorFlash.h new file mode 100644 index 000000000000..0c9dca79e6f4 --- /dev/null +++ b/MdePkg/Include/Protocol/SpiNorFlash.h @@ -0,0 +1,256 @@ +/** @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__ |