/** @file
  This file defines the Legacy SPI 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 __LEGACY_SPI_FLASH_PROTOCOL_H__
#define __LEGACY_SPI_FLASH_PROTOCOL_H__

#include <Protocol/SpiNorFlash.h>

///
/// Global ID for the Legacy SPI Flash Protocol
///
#define EFI_LEGACY_SPI_FLASH_PROTOCOL_GUID  \
  { 0xf01bed57, 0x04bc, 0x4f3f,             \
    { 0x96, 0x60, 0xd6, 0xf2, 0xea, 0x22, 0x82, 0x59 }}

typedef struct _EFI_LEGACY_SPI_FLASH_PROTOCOL EFI_LEGACY_SPI_FLASH_PROTOCOL;

/**
  Set the BIOS base address.

  This routine must be called at or below TPL_NOTIFY.
  The BIOS base address works with the protect range registers to protect
  portions of the SPI NOR flash from erase and write operat ions.
  The BIOS calls this API prior to passing control to the OS loader.

  @param[in] This             Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data
                              structure.
  @param[in] BiosBaseAddress  The BIOS base address.

  @retval EFI_SUCCESS            The BIOS base address was properly set
  @retval EFI_ACCESS_ERROR       The SPI controller is locked
  @retval EFI_INVALID_PARAMETER  BiosBaseAddress > This->MaximumOffset
  @retval EFI_UNSUPPORTED        The BIOS base address was already set or not a
                                 legacy SPI host controller

**/
typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_BIOS_BASE_ADDRESS) (
  IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL  *This,
  IN UINT32                               BiosBaseAddress
  );

/**
  Clear the SPI protect range registers.

  This routine must be called at or below TPL_NOTIFY.
  The BIOS uses this routine to set an initial condition on the SPI protect
  range registers.

  @param[in] This  Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data structure.

  @retval EFI_SUCCESS       The registers were successfully cleared
  @retval EFI_ACCESS_ERROR  The SPI controller is locked
  @retval EFI_UNSUPPORTED   Not a legacy SPI host controller

**/
typedef EFI_STATUS
(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_CLEAR_SPI_PROTECT) (
  IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL  *This
  );

/**
  Determine if the SPI range is protected.

  This routine must be called at or below TPL_NOTIFY.
  The BIOS uses this routine to verify a range in the SPI is protected.

  @param[in] This             Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data
                              structure.
  @param[in] BiosAddress      Address within a 4 KiB block to start protecting.
  @param[in] BlocksToProtect  The number of 4 KiB blocks to protect.

  @retval TRUE   The range is protected
  @retval FALSE  The range is not protected

**/
typedef
BOOLEAN
(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_IS_RANGE_PROTECTED) (
  IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL  *This,
  IN UINT32                               BiosAddress,
  IN UINT32                               BlocksToProtect
  );

/**
  Set the next protect range register.

  This routine must be called at or below TPL_NOTIFY.
  The BIOS sets the protect range register to prevent write and erase
  operations to a portion of the SPI NOR flash device.

  @param[in] This             Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data
                              structure.
  @param[in] BiosAddress      Address within a 4 KiB block to start protecting.
  @param[in] BlocksToProtect  The number of 4 KiB blocks to protect.

  @retval EFI_SUCCESS            The register was successfully updated
  @retval EFI_ACCESS_ERROR       The SPI controller is locked
  @retval EFI_INVALID_PARAMETER  BiosAddress < This->BiosBaseAddress, or
  @retval EFI_INVALID_PARAMETER  BlocksToProtect * 4 KiB
                                   > This->MaximumRangeBytes, or
                                 BiosAddress - This->BiosBaseAddress
                                   + (BlocksToProtect * 4 KiB)
                                     > This->MaximumRangeBytes
  @retval EFI_OUT_OF_RESOURCES   No protect range register available
  @retval EFI_UNSUPPORTED        Call This->SetBaseAddress because the BIOS
                                 base address is not set Not a legacy SPI host
                                 controller

**/
typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_PROTECT_NEXT_RANGE) (
  IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL  *This,
  IN UINT32                               BiosAddress,
  IN UINT32                               BlocksToProtect
  );

/**
  Lock the SPI controller configuration.

  This routine must be called at or below TPL_NOTIFY.
  This routine locks the SPI controller's configuration so that the software is
  no longer able to update:
  * Prefix table
  * Opcode menu
  * Opcode type table
  * BIOS base address
  * Protect range registers

  @param[in] This  Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data structure.

  @retval EFI_SUCCESS          The SPI controller was successfully locked
  @retval EFI_ALREADY_STARTED  The SPI controller was already locked
  @retval EFI_UNSUPPORTED      Not a legacy SPI host controller
**/
typedef
EFI_STATUS
(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_LOCK_CONTROLLER) (
  IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL  *This
  );

///
/// The EFI_LEGACY_SPI_FLASH_PROTOCOL extends the EFI_SPI_NOR_FLASH_PROTOCOL
/// with APls to support the legacy SPI flash controller.
///
struct _EFI_LEGACY_SPI_FLASH_PROTOCOL {
  ///
  /// This protocol manipulates the SPI NOR flash parts using a common set of
  /// commands.
  ///
  EFI_SPI_NOR_FLASH_PROTOCOL                       FlashProtocol;

  //
  // Legacy flash (SPI host) controller support
  //

  ///
  /// Set the BIOS base address.
  ///
  EFI_LEGACY_SPI_FLASH_PROTOCOL_BIOS_BASE_ADDRESS  BiosBaseAddress;

  ///
  /// Clear the SPI protect range registers.
  ///
  EFI_LEGACY_SPI_FLASH_PROTOCOL_CLEAR_SPI_PROTECT  ClearSpiProtect;

  ///
  /// Determine if the SPI range is protected.
  ///
  EFI_LEGACY_SPI_FLASH_PROTOCOL_IS_RANGE_PROTECTED IsRangeProtected;

  ///
  /// Set the next protect range register.
  ///
  EFI_LEGACY_SPI_FLASH_PROTOCOL_PROTECT_NEXT_RANGE ProtectNextRange;

  ///
  /// Lock the SPI controller configuration.
  ///
  EFI_LEGACY_SPI_FLASH_PROTOCOL_LOCK_CONTROLLER    LockController;
};

extern EFI_GUID gEfiLegacySpiFlashProtocolGuid;

#endif // __LEGACY_SPI_FLASH_PROTOCOL_H__