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