/** @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__