9344f09215
https://bugzilla.tianocore.org/show_bug.cgi?id=1373 Replace BSD 2-Clause License with BSD+Patent License. This change is based on the following emails: https://lists.01.org/pipermail/edk2-devel/2019-February/036260.html https://lists.01.org/pipermail/edk2-devel/2018-October/030385.html RFCs with detailed process for the license change: V3: https://lists.01.org/pipermail/edk2-devel/2019-March/038116.html V2: https://lists.01.org/pipermail/edk2-devel/2019-March/037669.html V1: https://lists.01.org/pipermail/edk2-devel/2019-March/037500.html Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Michael D Kinney <michael.d.kinney@intel.com> Reviewed-by: Liming Gao <liming.gao@intel.com>
257 lines
8.2 KiB
C
257 lines
8.2 KiB
C
/** @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__
|