2 This file defines the Legacy SPI Flash Protocol.
4 Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD
7 License which accompanies this distribution. The full text of the license may
8 be found at http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13 @par Revision Reference:
14 This Protocol was introduced in UEFI PI Specification 1.6.
18 #ifndef __LEGACY_SPI_FLASH_PROTOCOL_H__
19 #define __LEGACY_SPI_FLASH_PROTOCOL_H__
21 #include <Protocol/SpiNorFlash.h>
24 /// Global ID for the Legacy SPI Flash Protocol
26 #define EFI_LEGACY_SPI_FLASH_PROTOCOL_GUID \
27 { 0xf01bed57, 0x04bc, 0x4f3f, \
28 { 0x96, 0x60, 0xd6, 0xf2, 0xea, 0x22, 0x82, 0x59 }}
30 typedef struct _EFI_LEGACY_SPI_FLASH_PROTOCOL EFI_LEGACY_SPI_FLASH_PROTOCOL
;
33 Set the BIOS base address.
35 This routine must be called at or below TPL_NOTIFY.
36 The BIOS base address works with the protect range registers to protect
37 portions of the SPI NOR flash from erase and write operat ions.
38 The BIOS calls this API prior to passing control to the OS loader.
40 @param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data
42 @param[in] BiosBaseAddress The BIOS base address.
44 @retval EFI_SUCCESS The BIOS base address was properly set
45 @retval EFI_ACCESS_ERROR The SPI controller is locked
46 @retval EFI_INVALID_PARAMETER BiosBaseAddress > This->MaximumOffset
47 @retval EFI_UNSUPPORTED The BIOS base address was already set or not a
48 legacy SPI host controller
53 (EFIAPI
*EFI_LEGACY_SPI_FLASH_PROTOCOL_BIOS_BASE_ADDRESS
) (
54 IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL
*This
,
55 IN UINT32 BiosBaseAddress
59 Clear the SPI protect range registers.
61 This routine must be called at or below TPL_NOTIFY.
62 The BIOS uses this routine to set an initial condition on the SPI protect
65 @param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data structure.
67 @retval EFI_SUCCESS The registers were successfully cleared
68 @retval EFI_ACCESS_ERROR The SPI controller is locked
69 @retval EFI_UNSUPPORTED Not a legacy SPI host controller
73 (EFIAPI
*EFI_LEGACY_SPI_FLASH_PROTOCOL_CLEAR_SPI_PROTECT
) (
74 IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL
*This
78 Determine if the SPI range is protected.
80 This routine must be called at or below TPL_NOTIFY.
81 The BIOS uses this routine to verify a range in the SPI is protected.
83 @param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data
85 @param[in] BiosAddress Address within a 4 KiB block to start protecting.
86 @param[in] BlocksToProtect The number of 4 KiB blocks to protect.
88 @retval TRUE The range is protected
89 @retval FALSE The range is not protected
94 (EFIAPI
*EFI_LEGACY_SPI_FLASH_PROTOCOL_IS_RANGE_PROTECTED
) (
95 IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL
*This
,
96 IN UINT32 BiosAddress
,
97 IN UINT32 BlocksToProtect
101 Set the next protect range register.
103 This routine must be called at or below TPL_NOTIFY.
104 The BIOS sets the protect range register to prevent write and erase
105 operations to a portion of the SPI NOR flash device.
107 @param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data
109 @param[in] BiosAddress Address within a 4 KiB block to start protecting.
110 @param[in] BlocksToProtect The number of 4 KiB blocks to protect.
112 @retval EFI_SUCCESS The register was successfully updated
113 @retval EFI_ACCESS_ERROR The SPI controller is locked
114 @retval EFI_INVALID_PARAMETER BiosAddress < This->BiosBaseAddress, or
115 @retval EFI_INVALID_PARAMETER BlocksToProtect * 4 KiB
116 > This->MaximumRangeBytes, or
117 BiosAddress - This->BiosBaseAddress
118 + (BlocksToProtect * 4 KiB)
119 > This->MaximumRangeBytes
120 @retval EFI_OUT_OF_RESOURCES No protect range register available
121 @retval EFI_UNSUPPORTED Call This->SetBaseAddress because the BIOS
122 base address is not set Not a legacy SPI host
128 (EFIAPI
*EFI_LEGACY_SPI_FLASH_PROTOCOL_PROTECT_NEXT_RANGE
) (
129 IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL
*This
,
130 IN UINT32 BiosAddress
,
131 IN UINT32 BlocksToProtect
135 Lock the SPI controller configuration.
137 This routine must be called at or below TPL_NOTIFY.
138 This routine locks the SPI controller's configuration so that the software is
139 no longer able to update:
144 * Protect range registers
146 @param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data structure.
148 @retval EFI_SUCCESS The SPI controller was successfully locked
149 @retval EFI_ALREADY_STARTED The SPI controller was already locked
150 @retval EFI_UNSUPPORTED Not a legacy SPI host controller
154 (EFIAPI
*EFI_LEGACY_SPI_FLASH_PROTOCOL_LOCK_CONTROLLER
) (
155 IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL
*This
159 /// The EFI_LEGACY_SPI_FLASH_PROTOCOL extends the EFI_SPI_NOR_FLASH_PROTOCOL
160 /// with APls to support the legacy SPI flash controller.
162 struct _EFI_LEGACY_SPI_FLASH_PROTOCOL
{
164 /// This protocol manipulates the SPI NOR flash parts using a common set of
167 EFI_SPI_NOR_FLASH_PROTOCOL FlashProtocol
;
170 // Legacy flash (SPI host) controller support
174 /// Set the BIOS base address.
176 EFI_LEGACY_SPI_FLASH_PROTOCOL_BIOS_BASE_ADDRESS BiosBaseAddress
;
179 /// Clear the SPI protect range registers.
181 EFI_LEGACY_SPI_FLASH_PROTOCOL_CLEAR_SPI_PROTECT ClearSpiProtect
;
184 /// Determine if the SPI range is protected.
186 EFI_LEGACY_SPI_FLASH_PROTOCOL_IS_RANGE_PROTECTED IsRangeProtected
;
189 /// Set the next protect range register.
191 EFI_LEGACY_SPI_FLASH_PROTOCOL_PROTECT_NEXT_RANGE ProtectNextRange
;
194 /// Lock the SPI controller configuration.
196 EFI_LEGACY_SPI_FLASH_PROTOCOL_LOCK_CONTROLLER LockController
;
199 extern EFI_GUID gEfiLegacySpiFlashProtocolGuid
;
201 #endif // __LEGACY_SPI_FLASH_PROTOCOL_H__