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>
260 lines
9.0 KiB
C
260 lines
9.0 KiB
C
/** @file
|
|
This file defines the Legacy SPI Controller 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_CONTROLLER_PROTOCOL_H__
|
|
#define __LEGACY_SPI_CONTROLLER_PROTOCOL_H__
|
|
|
|
///
|
|
/// Note: The UEFI PI 1.6 specification uses the character 'l' in the GUID
|
|
/// definition. This definition assumes it was supposed to be '1'.
|
|
///
|
|
/// Global ID for the Legacy SPI Controller Protocol
|
|
///
|
|
#define EFI_LEGACY_SPI_CONTROLLER_GUID \
|
|
{ 0x39136fc7, 0x1a11, 0x49de, \
|
|
{ 0xbf, 0x35, 0x0e, 0x78, 0xdd, 0xb5, 0x24, 0xfc }}
|
|
|
|
typedef
|
|
struct _EFI_LEGACY_SPI_CONTROLLER_PROTOCOL
|
|
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL;
|
|
|
|
/**
|
|
Set the erase block opcode.
|
|
|
|
This routine must be called at or below TPL_NOTIFY.
|
|
The menu table contains SPI transaction opcodes which are accessible after
|
|
the legacy SPI flash controller's configuration is locked. The board layer
|
|
specifies the erase block size for the SPI NOR flash part. The SPI NOR flash
|
|
peripheral driver selects the erase block opcode which matches the erase
|
|
block size and uses this API to load the opcode into the opcode menu table.
|
|
|
|
@param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL
|
|
structure.
|
|
@param[in] EraseBlockOpcode Erase block opcode to be placed into the opcode
|
|
menu table.
|
|
|
|
@retval EFI_SUCCESS The opcode menu table was updated
|
|
@retval EFI_ACCESS_ERROR The SPI controller is locked
|
|
|
|
**/
|
|
typedef EFI_STATUS
|
|
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_ERASE_BLOCK_OPCODE) (
|
|
IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This,
|
|
IN UINT8 EraseBlockOpcode
|
|
);
|
|
|
|
/**
|
|
Set the write status prefix opcode.
|
|
|
|
This routine must be called at or below TPL_NOTIFY.
|
|
The prefix table contains SPI transaction write prefix opcodes which are
|
|
accessible after the legacy SPI flash controller's configuration is locked.
|
|
The board layer specifies the write status prefix opcode for the SPI NOR
|
|
flash part. The SPI NOR flash peripheral driver uses this API to load the
|
|
opcode into the prefix table.
|
|
|
|
@param[in] This Pointer to an
|
|
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL structure.
|
|
@param[in] WriteStatusPrefix Prefix opcode for the write status command.
|
|
|
|
@retval EFI_SUCCESS The prefix table was updated
|
|
@retval EFI_ACCESS_ERROR The SPI controller is locked
|
|
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_WRITE_STATUS_PREFIX) (
|
|
IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This,
|
|
IN UINT8 WriteStatusPrefix
|
|
);
|
|
|
|
/**
|
|
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_CONTROLLER_PROTOCOL
|
|
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 The BIOS base address is greater than
|
|
This->Maxi.mumOffset
|
|
@retval EFI_UNSUPPORTED The BIOS base address was already set
|
|
|
|
**/
|
|
typedef EFI_STATUS
|
|
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_BIOS_BASE_ADDRESS) (
|
|
IN CONST EFI_LEGACY_SPI_CONTROLLER_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_CONTROLLER_PROTOCOL structure.
|
|
|
|
@retval EFI_SUCCESS The registers were successfully cleared
|
|
@retval EFI_ACCESS_ERROR The SPI controller is locked
|
|
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_CLEAR_SPI_PROTECT) (
|
|
IN CONST EFI_LEGACY_SPI_CONTROLLER_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_CONTROLLER_PROTOCOL
|
|
structure.
|
|
@param[in] BiosAddress Address within a 4 KiB block to start protecting.
|
|
@param[in] BytesToProtect 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_CONTROLLER_PROTOCOL_IS_RANGE_PROTECTED) (
|
|
IN CONST EFI_LEGACY_SPI_CONTROLLER_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_CONTROLLER_PROTOCOL
|
|
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
|
|
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
|
|
|
|
**/
|
|
typedef
|
|
EFI_STATUS
|
|
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_PROTECT_NEXT_RANGE) (
|
|
IN CONST EFI_LEGACY_SPI_CONTROLLER_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_CONTROLLER_PROTOCOL structure.
|
|
|
|
@retval EFI_SUCCESS The SPI controller was successfully locked
|
|
@retval EFI_ALREADY_STARTED The SPI controller was already locked
|
|
|
|
**/
|
|
typedef EFI_STATUS
|
|
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_LOCK_CONTROLLER) (
|
|
IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This
|
|
);
|
|
|
|
///
|
|
/// Support the extra features of the legacy SPI flash controller.
|
|
///
|
|
struct _EFI_LEGACY_SPI_CONTROLLER_PROTOCOL {
|
|
///
|
|
/// Maximum offset from the BIOS base address that is able to be protected.
|
|
///
|
|
UINT32 MaximumOffset;
|
|
|
|
///
|
|
/// Maximum number of bytes that can be protected by one range register.
|
|
///
|
|
UINT32 MaximumRangeBytes;
|
|
|
|
///
|
|
/// The number of registers available for protecting the BIOS.
|
|
///
|
|
UINT32 RangeRegisterCount;
|
|
|
|
///
|
|
/// Set the erase block opcode.
|
|
///
|
|
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_ERASE_BLOCK_OPCODE EraseBlockOpcode;
|
|
|
|
///
|
|
/// Set the write status prefix opcode.
|
|
///
|
|
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_WRITE_STATUS_PREFIX WriteStatusPrefix;
|
|
|
|
///
|
|
/// Set the BIOS base address.
|
|
///
|
|
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_BIOS_BASE_ADDRESS BiosBaseAddress;
|
|
|
|
///
|
|
/// Clear the SPI protect range registers.
|
|
///
|
|
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_CLEAR_SPI_PROTECT ClearSpiProtect;
|
|
|
|
///
|
|
/// Determine if the SPI range is protected.
|
|
///
|
|
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_IS_RANGE_PROTECTED IsRangeProtected;
|
|
|
|
///
|
|
/// Set the next protect range register.
|
|
///
|
|
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_PROTECT_NEXT_RANGE ProtectNextRange;
|
|
|
|
///
|
|
/// Lock the SPI controller configuration.
|
|
///
|
|
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_LOCK_CONTROLLER LockController;
|
|
};
|
|
|
|
extern EFI_GUID gEfiLegacySpiControllerProtocolGuid;
|
|
|
|
#endif // __LEGACY_SPI_CONTROLLER_PROTOCOL_H__
|