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

/** @file\r
  This file defines the Legacy SPI 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 __LEGACY_SPI_FLASH_PROTOCOL_H__\r
#define __LEGACY_SPI_FLASH_PROTOCOL_H__\r
\r
#include <Protocol/SpiNorFlash.h>\r
\r
///\r
/// Global ID for the Legacy SPI Flash Protocol\r
///\r
#define EFI_LEGACY_SPI_FLASH_PROTOCOL_GUID  \\r
  { 0xf01bed57, 0x04bc, 0x4f3f,             \\r
    { 0x96, 0x60, 0xd6, 0xf2, 0xea, 0x22, 0x82, 0x59 }}\r
\r
typedef struct _EFI_LEGACY_SPI_FLASH_PROTOCOL EFI_LEGACY_SPI_FLASH_PROTOCOL;\r
\r
/**\r
  Set the BIOS base address.\r
\r
  This routine must be called at or below TPL_NOTIFY.\r
  The BIOS base address works with the protect range registers to protect\r
  portions of the SPI NOR flash from erase and write operat ions.\r
  The BIOS calls this API prior to passing control to the OS loader.\r
\r
  @param[in] This             Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data\r
                              structure.\r
  @param[in] BiosBaseAddress  The BIOS base address.\r
\r
  @retval EFI_SUCCESS            The BIOS base address was properly set\r
  @retval EFI_ACCESS_ERROR       The SPI controller is locked\r
  @retval EFI_INVALID_PARAMETER  BiosBaseAddress > This->MaximumOffset\r
  @retval EFI_UNSUPPORTED        The BIOS base address was already set or not a\r
                                 legacy SPI host controller\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_BIOS_BASE_ADDRESS) (\r
  IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL  *This,\r
  IN UINT32                               BiosBaseAddress\r
  );\r
\r
/**\r
  Clear the SPI protect range registers.\r
\r
  This routine must be called at or below TPL_NOTIFY.\r
  The BIOS uses this routine to set an initial condition on the SPI protect\r
  range registers.\r
\r
  @param[in] This  Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data structure.\r
\r
  @retval EFI_SUCCESS       The registers were successfully cleared\r
  @retval EFI_ACCESS_ERROR  The SPI controller is locked\r
  @retval EFI_UNSUPPORTED   Not a legacy SPI host controller\r
\r
**/\r
typedef EFI_STATUS\r
(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_CLEAR_SPI_PROTECT) (\r
  IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL  *This\r
  );\r
\r
/**\r
  Determine if the SPI range is protected.\r
\r
  This routine must be called at or below TPL_NOTIFY.\r
  The BIOS uses this routine to verify a range in the SPI is protected.\r
\r
  @param[in] This             Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data\r
                              structure.\r
  @param[in] BiosAddress      Address within a 4 KiB block to start protecting.\r
  @param[in] BlocksToProtect  The number of 4 KiB blocks to protect.\r
\r
  @retval TRUE   The range is protected\r
  @retval FALSE  The range is not protected\r
\r
**/\r
typedef\r
BOOLEAN\r
(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_IS_RANGE_PROTECTED) (\r
  IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL  *This,\r
  IN UINT32                               BiosAddress,\r
  IN UINT32                               BlocksToProtect\r
  );\r
\r
/**\r
  Set the next protect range register.\r
\r
  This routine must be called at or below TPL_NOTIFY.\r
  The BIOS sets the protect range register to prevent write and erase\r
  operations to a portion of the SPI NOR flash device.\r
\r
  @param[in] This             Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data\r
                              structure.\r
  @param[in] BiosAddress      Address within a 4 KiB block to start protecting.\r
  @param[in] BlocksToProtect  The number of 4 KiB blocks to protect.\r
\r
  @retval EFI_SUCCESS            The register was successfully updated\r
  @retval EFI_ACCESS_ERROR       The SPI controller is locked\r
  @retval EFI_INVALID_PARAMETER  BiosAddress < This->BiosBaseAddress, or\r
  @retval EFI_INVALID_PARAMETER  BlocksToProtect * 4 KiB\r
                                   > This->MaximumRangeBytes, or\r
                                 BiosAddress - This->BiosBaseAddress\r
                                   + (BlocksToProtect * 4 KiB)\r
                                     > This->MaximumRangeBytes\r
  @retval EFI_OUT_OF_RESOURCES   No protect range register available\r
  @retval EFI_UNSUPPORTED        Call This->SetBaseAddress because the BIOS\r
                                 base address is not set Not a legacy SPI host\r
                                 controller\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_PROTECT_NEXT_RANGE) (\r
  IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL  *This,\r
  IN UINT32                               BiosAddress,\r
  IN UINT32                               BlocksToProtect\r
  );\r
\r
/**\r
  Lock the SPI controller configuration.\r
\r
  This routine must be called at or below TPL_NOTIFY.\r
  This routine locks the SPI controller's configuration so that the software is\r
  no longer able to update:\r
  * Prefix table\r
  * Opcode menu\r
  * Opcode type table\r
  * BIOS base address\r
  * Protect range registers\r
\r
  @param[in] This  Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data structure.\r
\r
  @retval EFI_SUCCESS          The SPI controller was successfully locked\r
  @retval EFI_ALREADY_STARTED  The SPI controller was already locked\r
  @retval EFI_UNSUPPORTED      Not a legacy SPI host controller\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_LOCK_CONTROLLER) (\r
  IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL  *This\r
  );\r
\r
///\r
/// The EFI_LEGACY_SPI_FLASH_PROTOCOL extends the EFI_SPI_NOR_FLASH_PROTOCOL\r
/// with APls to support the legacy SPI flash controller.\r
///\r
struct _EFI_LEGACY_SPI_FLASH_PROTOCOL {\r
  ///\r
  /// This protocol manipulates the SPI NOR flash parts using a common set of\r
  /// commands.\r
  ///\r
  EFI_SPI_NOR_FLASH_PROTOCOL                       FlashProtocol;\r
\r
  //\r
  // Legacy flash (SPI host) controller support\r
  //\r
\r
  ///\r
  /// Set the BIOS base address.\r
  ///\r
  EFI_LEGACY_SPI_FLASH_PROTOCOL_BIOS_BASE_ADDRESS  BiosBaseAddress;\r
\r
  ///\r
  /// Clear the SPI protect range registers.\r
  ///\r
  EFI_LEGACY_SPI_FLASH_PROTOCOL_CLEAR_SPI_PROTECT  ClearSpiProtect;\r
\r
  ///\r
  /// Determine if the SPI range is protected.\r
  ///\r
  EFI_LEGACY_SPI_FLASH_PROTOCOL_IS_RANGE_PROTECTED IsRangeProtected;\r
\r
  ///\r
  /// Set the next protect range register.\r
  ///\r
  EFI_LEGACY_SPI_FLASH_PROTOCOL_PROTECT_NEXT_RANGE ProtectNextRange;\r
\r
  ///\r
  /// Lock the SPI controller configuration.\r
  ///\r
  EFI_LEGACY_SPI_FLASH_PROTOCOL_LOCK_CONTROLLER    LockController;\r
};\r
\r
extern EFI_GUID gEfiLegacySpiFlashProtocolGuid;\r
\r
#endif // __LEGACY_SPI_FLASH_PROTOCOL_H__\r
Commit	Line	Data
db04b706 MH	1	/** @file\r
	2	This file defines the Legacy SPI Flash Protocol.\r
	3	\r
	4	Copyright (c) 2017, Intel Corporation. All rights reserved.<BR>\r
9344f092	5	SPDX-License-Identifier: BSD-2-Clause-Patent\r
db04b706 MH	6	\r
	7	@par Revision Reference:\r
	8	This Protocol was introduced in UEFI PI Specification 1.6.\r
	9	\r
	10	**/\r
	11	\r
	12	#ifndef __LEGACY_SPI_FLASH_PROTOCOL_H__\r
	13	#define __LEGACY_SPI_FLASH_PROTOCOL_H__\r
	14	\r
	15	#include <Protocol/SpiNorFlash.h>\r
	16	\r
	17	///\r
	18	/// Global ID for the Legacy SPI Flash Protocol\r
	19	///\r
	20	#define EFI_LEGACY_SPI_FLASH_PROTOCOL_GUID \\r
	21	{ 0xf01bed57, 0x04bc, 0x4f3f, \\r
	22	{ 0x96, 0x60, 0xd6, 0xf2, 0xea, 0x22, 0x82, 0x59 }}\r
	23	\r
	24	typedef struct _EFI_LEGACY_SPI_FLASH_PROTOCOL EFI_LEGACY_SPI_FLASH_PROTOCOL;\r
	25	\r
	26	/**\r
	27	Set the BIOS base address.\r
	28	\r
	29	This routine must be called at or below TPL_NOTIFY.\r
	30	The BIOS base address works with the protect range registers to protect\r
	31	portions of the SPI NOR flash from erase and write operat ions.\r
	32	The BIOS calls this API prior to passing control to the OS loader.\r
	33	\r
	34	@param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data\r
	35	structure.\r
	36	@param[in] BiosBaseAddress The BIOS base address.\r
	37	\r
	38	@retval EFI_SUCCESS The BIOS base address was properly set\r
	39	@retval EFI_ACCESS_ERROR The SPI controller is locked\r
	40	@retval EFI_INVALID_PARAMETER BiosBaseAddress > This->MaximumOffset\r
	41	@retval EFI_UNSUPPORTED The BIOS base address was already set or not a\r
	42	legacy SPI host controller\r
	43	\r
	44	**/\r
	45	typedef\r
	46	EFI_STATUS\r
	47	(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_BIOS_BASE_ADDRESS) (\r
	48	IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL *This,\r
	49	IN UINT32 BiosBaseAddress\r
	50	);\r
	51	\r
	52	/**\r
	53	Clear the SPI protect range registers.\r
	54	\r
	55	This routine must be called at or below TPL_NOTIFY.\r
	56	The BIOS uses this routine to set an initial condition on the SPI protect\r
	57	range registers.\r
	58	\r
	59	@param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data structure.\r
	60	\r
	61	@retval EFI_SUCCESS The registers were successfully cleared\r
	62	@retval EFI_ACCESS_ERROR The SPI controller is locked\r
	63	@retval EFI_UNSUPPORTED Not a legacy SPI host controller\r
	64	\r
	65	**/\r
	66	typedef EFI_STATUS\r
	67	(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_CLEAR_SPI_PROTECT) (\r
	68	IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL *This\r
	69	);\r
70	\r
71	/**\r
72	Determine if the SPI range is protected.\r
73	\r
74	This routine must be called at or below TPL_NOTIFY.\r
75	The BIOS uses this routine to verify a range in the SPI is protected.\r
76	\r
77	@param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data\r
78	structure.\r
79	@param[in] BiosAddress Address within a 4 KiB block to start protecting.\r
80	@param[in] BlocksToProtect The number of 4 KiB blocks to protect.\r
81	\r
82	@retval TRUE The range is protected\r
83	@retval FALSE The range is not protected\r
84	\r
85	**/\r
86	typedef\r
87	BOOLEAN\r
88	(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_IS_RANGE_PROTECTED) (\r
89	IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL *This,\r
90	IN UINT32 BiosAddress,\r
91	IN UINT32 BlocksToProtect\r
92	);\r
93	\r
94	/**\r
95	Set the next protect range register.\r
96	\r
97	This routine must be called at or below TPL_NOTIFY.\r
98	The BIOS sets the protect range register to prevent write and erase\r
99	operations to a portion of the SPI NOR flash device.\r
100	\r
101	@param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data\r
102	structure.\r
103	@param[in] BiosAddress Address within a 4 KiB block to start protecting.\r
104	@param[in] BlocksToProtect The number of 4 KiB blocks to protect.\r
105	\r
106	@retval EFI_SUCCESS The register was successfully updated\r
107	@retval EFI_ACCESS_ERROR The SPI controller is locked\r
108	@retval EFI_INVALID_PARAMETER BiosAddress < This->BiosBaseAddress, or\r
109	@retval EFI_INVALID_PARAMETER BlocksToProtect * 4 KiB\r
110	> This->MaximumRangeBytes, or\r
111	BiosAddress - This->BiosBaseAddress\r
112	+ (BlocksToProtect * 4 KiB)\r
113	> This->MaximumRangeBytes\r
114	@retval EFI_OUT_OF_RESOURCES No protect range register available\r
115	@retval EFI_UNSUPPORTED Call This->SetBaseAddress because the BIOS\r
116	base address is not set Not a legacy SPI host\r
117	controller\r
118	\r
119	**/\r
120	typedef\r
121	EFI_STATUS\r
122	(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_PROTECT_NEXT_RANGE) (\r
123	IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL *This,\r
124	IN UINT32 BiosAddress,\r
125	IN UINT32 BlocksToProtect\r
126	);\r
127	\r
128	/**\r
129	Lock the SPI controller configuration.\r
130	\r
131	This routine must be called at or below TPL_NOTIFY.\r
132	This routine locks the SPI controller's configuration so that the software is\r
133	no longer able to update:\r
134	* Prefix table\r
135	* Opcode menu\r
136	* Opcode type table\r
137	* BIOS base address\r
138	* Protect range registers\r
139	\r
140	@param[in] This Pointer to an EFI_LEGACY_SPI_FLASH_PROTOCOL data structure.\r
141	\r
142	@retval EFI_SUCCESS The SPI controller was successfully locked\r
143	@retval EFI_ALREADY_STARTED The SPI controller was already locked\r
144	@retval EFI_UNSUPPORTED Not a legacy SPI host controller\r
145	**/\r
146	typedef\r
147	EFI_STATUS\r
148	(EFIAPI *EFI_LEGACY_SPI_FLASH_PROTOCOL_LOCK_CONTROLLER) (\r
149	IN CONST EFI_LEGACY_SPI_FLASH_PROTOCOL *This\r
150	);\r
151	\r
152	///\r
153	/// The EFI_LEGACY_SPI_FLASH_PROTOCOL extends the EFI_SPI_NOR_FLASH_PROTOCOL\r
154	/// with APls to support the legacy SPI flash controller.\r
155	///\r
156	struct _EFI_LEGACY_SPI_FLASH_PROTOCOL {\r
157	///\r
158	/// This protocol manipulates the SPI NOR flash parts using a common set of\r
159	/// commands.\r
160	///\r
161	EFI_SPI_NOR_FLASH_PROTOCOL FlashProtocol;\r
162	\r
163	//\r
164	// Legacy flash (SPI host) controller support\r
165	//\r
166	\r
167	///\r
168	/// Set the BIOS base address.\r
169	///\r
170	EFI_LEGACY_SPI_FLASH_PROTOCOL_BIOS_BASE_ADDRESS BiosBaseAddress;\r
171	\r
172	///\r
173	/// Clear the SPI protect range registers.\r
174	///\r
175	EFI_LEGACY_SPI_FLASH_PROTOCOL_CLEAR_SPI_PROTECT ClearSpiProtect;\r
176	\r
177	///\r
178	/// Determine if the SPI range is protected.\r
179	///\r
180	EFI_LEGACY_SPI_FLASH_PROTOCOL_IS_RANGE_PROTECTED IsRangeProtected;\r
181	\r
182	///\r
183	/// Set the next protect range register.\r
184	///\r
185	EFI_LEGACY_SPI_FLASH_PROTOCOL_PROTECT_NEXT_RANGE ProtectNextRange;\r
186	\r
187	///\r
188	/// Lock the SPI controller configuration.\r
189	///\r
190	EFI_LEGACY_SPI_FLASH_PROTOCOL_LOCK_CONTROLLER LockController;\r
191	};\r
192	\r
193	extern EFI_GUID gEfiLegacySpiFlashProtocolGuid;\r
194	\r
195	#endif // __LEGACY_SPI_FLASH_PROTOCOL_H__\r