UefiCpuPkg: Move AsmRelocateApLoopStart from Mpfuncs.nasm to AmdSev.nasm

[mirror_edk2.git] / MdePkg / Include / Protocol / SpiNorFlash.h

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