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

/** @file\r
  This file defines the Legacy SPI Controller 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_CONTROLLER_PROTOCOL_H__\r
#define __LEGACY_SPI_CONTROLLER_PROTOCOL_H__\r
\r
///\r
/// Note: The UEFI PI 1.6 specification uses the character 'l' in the GUID\r
///       definition. This definition assumes it was supposed to be '1'.\r
///\r
/// Global ID for the Legacy SPI Controller Protocol\r
///\r
#define EFI_LEGACY_SPI_CONTROLLER_GUID  \\r
  { 0x39136fc7, 0x1a11, 0x49de,         \\r
    { 0xbf, 0x35, 0x0e, 0x78, 0xdd, 0xb5, 0x24, 0xfc }}\r
\r
typedef\r
struct _EFI_LEGACY_SPI_CONTROLLER_PROTOCOL\r
EFI_LEGACY_SPI_CONTROLLER_PROTOCOL;\r
\r
/**\r
  Set the erase block opcode.\r
\r
  This routine must be called at or below TPL_NOTIFY.\r
  The menu table contains SPI transaction opcodes which are accessible after\r
  the legacy SPI flash controller's configuration is locked. The board layer\r
  specifies the erase block size for the SPI NOR flash part. The SPI NOR flash\r
  peripheral driver selects the erase block opcode which matches the erase\r
  block size and uses this API to load the opcode into the opcode menu table.\r
\r
  @param[in] This              Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL\r
                               structure.\r
  @param[in] EraseBlockOpcode  Erase block opcode to be placed into the opcode\r
                               menu table.\r
\r
  @retval EFI_SUCCESS       The opcode menu table was updated\r
  @retval EFI_ACCESS_ERROR  The SPI controller is locked\r
\r
**/\r
typedef EFI_STATUS\r
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_ERASE_BLOCK_OPCODE) (\r
  IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL  *This,\r
  IN UINT8                                     EraseBlockOpcode\r
  );\r
\r
/**\r
  Set the write status prefix opcode.\r
\r
  This routine must be called at or below TPL_NOTIFY.\r
  The prefix table contains SPI transaction write prefix opcodes which are\r
  accessible after the legacy SPI flash controller's configuration is locked.\r
  The board layer specifies the write status prefix opcode for the SPI NOR\r
  flash part. The SPI NOR flash peripheral driver uses this API to load the\r
  opcode into the prefix table.\r
\r
  @param[in] This               Pointer to an\r
                                EFI_LEGACY_SPI_CONTROLLER_PROTOCOL structure.\r
  @param[in] WriteStatusPrefix  Prefix opcode for the write status command.\r
\r
  @retval EFI_SUCCESS       The prefix table was updated\r
  @retval EFI_ACCESS_ERROR  The SPI controller is locked\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_WRITE_STATUS_PREFIX) (\r
  IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL  *This,\r
  IN UINT8                                     WriteStatusPrefix\r
  );\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. The BIOS\r
  calls this API prior to passing control to the OS loader.\r
\r
  @param[in] This             Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL\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  The BIOS base address is greater than\r
                                 This->Maxi.mumOffset\r
  @retval EFI_UNSUPPORTED        The BIOS base address was already set\r
\r
**/\r
typedef EFI_STATUS\r
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_BIOS_BASE_ADDRESS) (\r
  IN CONST EFI_LEGACY_SPI_CONTROLLER_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_CONTROLLER_PROTOCOL structure.\r
\r
  @retval EFI_SUCCESS       The registers were successfully cleared\r
  @retval EFI_ACCESS_ERROR  The SPI controller is locked\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_CLEAR_SPI_PROTECT) (\r
  IN CONST EFI_LEGACY_SPI_CONTROLLER_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_CONTROLLER_PROTOCOL\r
                             structure.\r
  @param[in] BiosAddress     Address within a 4 KiB block to start protecting.\r
  @param[in] BytesToProtect  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_CONTROLLER_PROTOCOL_IS_RANGE_PROTECTED) (\r
  IN CONST EFI_LEGACY_SPI_CONTROLLER_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_CONTROLLER_PROTOCOL\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
                                 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 base\r
                                address is not set\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_PROTECT_NEXT_RANGE) (\r
  IN CONST EFI_LEGACY_SPI_CONTROLLER_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\r
  is 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_CONTROLLER_PROTOCOL structure.\r
\r
  @retval EFI_SUCCESS          The SPI controller was successfully locked\r
  @retval EFI_ALREADY_STARTED  The SPI controller was already locked\r
\r
**/\r
typedef EFI_STATUS\r
(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_LOCK_CONTROLLER) (\r
  IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL  *This\r
  );\r
\r
///\r
/// Support the extra features of the legacy SPI flash controller.\r
///\r
struct _EFI_LEGACY_SPI_CONTROLLER_PROTOCOL {\r
  ///\r
  /// Maximum offset from the BIOS base address that is able to be protected.\r
  ///\r
  UINT32                                                 MaximumOffset;\r
\r
  ///\r
  /// Maximum number of bytes that can be protected by one range register.\r
  ///\r
  UINT32                                                 MaximumRangeBytes;\r
\r
  ///\r
  /// The number of registers available for protecting the BIOS.\r
  ///\r
  UINT32                                                 RangeRegisterCount;\r
\r
  ///\r
  /// Set the erase block opcode.\r
  ///\r
  EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_ERASE_BLOCK_OPCODE  EraseBlockOpcode;\r
\r
  ///\r
  /// Set the write status prefix opcode.\r
  ///\r
  EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_WRITE_STATUS_PREFIX WriteStatusPrefix;\r
\r
  ///\r
  /// Set the BIOS base address.\r
  ///\r
  EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_BIOS_BASE_ADDRESS   BiosBaseAddress;\r
\r
  ///\r
  /// Clear the SPI protect range registers.\r
  ///\r
  EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_CLEAR_SPI_PROTECT   ClearSpiProtect;\r
\r
  ///\r
  /// Determine if the SPI range is protected.\r
  ///\r
  EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_IS_RANGE_PROTECTED  IsRangeProtected;\r
\r
  ///\r
  /// Set the next protect range register.\r
  ///\r
  EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_PROTECT_NEXT_RANGE  ProtectNextRange;\r
\r
  ///\r
  /// Lock the SPI controller configuration.\r
  ///\r
  EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_LOCK_CONTROLLER     LockController;\r
};\r
\r
extern EFI_GUID gEfiLegacySpiControllerProtocolGuid;\r
\r
#endif // __LEGACY_SPI_CONTROLLER_PROTOCOL_H__\r
Commit	Line	Data
db04b706 MH	1	/** @file\r
	2	This file defines the Legacy SPI Controller 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_CONTROLLER_PROTOCOL_H__\r
	19	#define __LEGACY_SPI_CONTROLLER_PROTOCOL_H__\r
	20	\r
	21	///\r
	22	/// Note: The UEFI PI 1.6 specification uses the character 'l' in the GUID\r
	23	/// definition. This definition assumes it was supposed to be '1'.\r
	24	///\r
	25	/// Global ID for the Legacy SPI Controller Protocol\r
	26	///\r
	27	#define EFI_LEGACY_SPI_CONTROLLER_GUID \\r
	28	{ 0x39136fc7, 0x1a11, 0x49de, \\r
	29	{ 0xbf, 0x35, 0x0e, 0x78, 0xdd, 0xb5, 0x24, 0xfc }}\r
	30	\r
	31	typedef\r
	32	struct _EFI_LEGACY_SPI_CONTROLLER_PROTOCOL\r
	33	EFI_LEGACY_SPI_CONTROLLER_PROTOCOL;\r
	34	\r
	35	/**\r
	36	Set the erase block opcode.\r
	37	\r
	38	This routine must be called at or below TPL_NOTIFY.\r
	39	The menu table contains SPI transaction opcodes which are accessible after\r
	40	the legacy SPI flash controller's configuration is locked. The board layer\r
	41	specifies the erase block size for the SPI NOR flash part. The SPI NOR flash\r
	42	peripheral driver selects the erase block opcode which matches the erase\r
	43	block size and uses this API to load the opcode into the opcode menu table.\r
	44	\r
	45	@param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL\r
	46	structure.\r
	47	@param[in] EraseBlockOpcode Erase block opcode to be placed into the opcode\r
	48	menu table.\r
	49	\r
	50	@retval EFI_SUCCESS The opcode menu table was updated\r
	51	@retval EFI_ACCESS_ERROR The SPI controller is locked\r
	52	\r
	53	**/\r
	54	typedef EFI_STATUS\r
	55	(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_ERASE_BLOCK_OPCODE) (\r
	56	IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This,\r
	57	IN UINT8 EraseBlockOpcode\r
	58	);\r
	59	\r
	60	/**\r
	61	Set the write status prefix opcode.\r
	62	\r
	63	This routine must be called at or below TPL_NOTIFY.\r
	64	The prefix table contains SPI transaction write prefix opcodes which are\r
65	accessible after the legacy SPI flash controller's configuration is locked.\r
66	The board layer specifies the write status prefix opcode for the SPI NOR\r
67	flash part. The SPI NOR flash peripheral driver uses this API to load the\r
68	opcode into the prefix table.\r
69	\r
70	@param[in] This Pointer to an\r
71	EFI_LEGACY_SPI_CONTROLLER_PROTOCOL structure.\r
72	@param[in] WriteStatusPrefix Prefix opcode for the write status command.\r
73	\r
74	@retval EFI_SUCCESS The prefix table was updated\r
75	@retval EFI_ACCESS_ERROR The SPI controller is locked\r
76	\r
77	**/\r
78	typedef\r
79	EFI_STATUS\r
80	(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_WRITE_STATUS_PREFIX) (\r
81	IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This,\r
82	IN UINT8 WriteStatusPrefix\r
83	);\r
84	\r
85	/**\r
86	Set the BIOS base address.\r
87	\r
88	This routine must be called at or below TPL_NOTIFY.\r
89	The BIOS base address works with the protect range registers to protect\r
90	portions of the SPI NOR flash from erase and write operat ions. The BIOS\r
91	calls this API prior to passing control to the OS loader.\r
92	\r
93	@param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL\r
94	structure.\r
95	@param[in] BiosBaseAddress The BIOS base address.\r
96	\r
97	@retval EFI_SUCCESS The BIOS base address was properly set\r
98	@retval EFI_ACCESS_ERROR The SPI controller is locked\r
99	@retval EFI_INVALID_PARAMETER The BIOS base address is greater than\r
100	This->Maxi.mumOffset\r
101	@retval EFI_UNSUPPORTED The BIOS base address was already set\r
102	\r
103	**/\r
104	typedef EFI_STATUS\r
105	(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_BIOS_BASE_ADDRESS) (\r
106	IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This,\r
107	IN UINT32 BiosBaseAddress\r
108	);\r
109	\r
110	/**\r
111	Clear the SPI protect range registers.\r
112	\r
113	This routine must be called at or below TPL_NOTIFY.\r
114	The BIOS uses this routine to set an initial condition on the SPI protect\r
115	range registers.\r
116	\r
117	@param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL structure.\r
118	\r
119	@retval EFI_SUCCESS The registers were successfully cleared\r
120	@retval EFI_ACCESS_ERROR The SPI controller is locked\r
121	\r
122	**/\r
123	typedef\r
124	EFI_STATUS\r
125	(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_CLEAR_SPI_PROTECT) (\r
126	IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This\r
127	);\r
128	\r
129	/**\r
130	Determine if the SPI range is protected.\r
131	\r
132	This routine must be called at or below TPL_NOTIFY.\r
133	The BIOS uses this routine to verify a range in the SPI is protected.\r
134	\r
135	@param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL\r
136	structure.\r
137	@param[in] BiosAddress Address within a 4 KiB block to start protecting.\r
138	@param[in] BytesToProtect The number of 4 KiB blocks to protect.\r
139	\r
140	@retval TRUE The range is protected\r
141	@retval FALSE The range is not protected\r
142	\r
143	**/\r
144	typedef\r
145	BOOLEAN\r
146	(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_IS_RANGE_PROTECTED) (\r
147	IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This,\r
148	IN UINT32 BiosAddress,\r
149	IN UINT32 BlocksToProtect\r
150	);\r
151	\r
152	/**\r
153	Set the next protect range register.\r
154	\r
155	This routine must be called at or below TPL_NOTIFY.\r
156	The BIOS sets the protect range register to prevent write and erase\r
157	operations to a portion of the SPI NOR flash device.\r
158	\r
159	@param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL\r
160	structure.\r
161	@param[in] BiosAddress Address within a 4 KiB block to start protecting.\r
162	@param[in] BlocksToProtect The number of 4 KiB blocks to protect.\r
163	\r
164	@retval EFI_SUCCESS The register was successfully updated\r
165	@retval EFI_ACCESS_ERROR The SPI controller is locked\r
166	@retval EFI_INVALID_PARAMETER BiosAddress < This->BiosBaseAddress, or\r
167	BlocksToProtect * 4 KiB\r
168	> This->MaximumRangeBytes, or\r
169	BiosAddress - This->BiosBaseAddress\r
170	+ (BlocksToProtect * 4 KiB)\r
171	> This->MaximumRangeBytes\r
172	@retval EFI_OUT_OF_RESOURCES No protect range register available\r
173	@retval EFI_UNSUPPORTED Call This->SetBaseAddress because the BIOS base\r
174	address is not set\r
175	\r
176	**/\r
177	typedef\r
178	EFI_STATUS\r
179	(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_PROTECT_NEXT_RANGE) (\r
180	IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This,\r
181	IN UINT32 BiosAddress,\r
182	IN UINT32 BlocksToProtect\r
183	);\r
184	\r
185	/**\r
186	Lock the SPI controller configuration.\r
187	\r
188	This routine must be called at or below TPL_NOTIFY.\r
189	This routine locks the SPI controller's configuration so that the software\r
190	is no longer able to update:\r
191	* Prefix table\r
192	* Opcode menu\r
193	* Opcode type table\r
194	* BIOS base address\r
195	* Protect range registers\r
196	\r
197	@param[in] This Pointer to an EFI_LEGACY_SPI_CONTROLLER_PROTOCOL structure.\r
198	\r
199	@retval EFI_SUCCESS The SPI controller was successfully locked\r
200	@retval EFI_ALREADY_STARTED The SPI controller was already locked\r
201	\r
202	**/\r
203	typedef EFI_STATUS\r
204	(EFIAPI *EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_LOCK_CONTROLLER) (\r
205	IN CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *This\r
206	);\r
207	\r
208	///\r
209	/// Support the extra features of the legacy SPI flash controller.\r
210	///\r
211	struct _EFI_LEGACY_SPI_CONTROLLER_PROTOCOL {\r
212	///\r
213	/// Maximum offset from the BIOS base address that is able to be protected.\r
214	///\r
215	UINT32 MaximumOffset;\r
216	\r
217	///\r
218	/// Maximum number of bytes that can be protected by one range register.\r
219	///\r
220	UINT32 MaximumRangeBytes;\r
221	\r
222	///\r
223	/// The number of registers available for protecting the BIOS.\r
224	///\r
225	UINT32 RangeRegisterCount;\r
226	\r
227	///\r
228	/// Set the erase block opcode.\r
229	///\r
230	EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_ERASE_BLOCK_OPCODE EraseBlockOpcode;\r
231	\r
232	///\r
233	/// Set the write status prefix opcode.\r
234	///\r
235	EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_WRITE_STATUS_PREFIX WriteStatusPrefix;\r
236	\r
237	///\r
238	/// Set the BIOS base address.\r
239	///\r
240	EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_BIOS_BASE_ADDRESS BiosBaseAddress;\r
241	\r
242	///\r
243	/// Clear the SPI protect range registers.\r
244	///\r
245	EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_CLEAR_SPI_PROTECT ClearSpiProtect;\r
246	\r
247	///\r
248	/// Determine if the SPI range is protected.\r
249	///\r
250	EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_IS_RANGE_PROTECTED IsRangeProtected;\r
251	\r
252	///\r
253	/// Set the next protect range register.\r
254	///\r
255	EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_PROTECT_NEXT_RANGE ProtectNextRange;\r
256	\r
257	///\r
258	/// Lock the SPI controller configuration.\r
259	///\r
260	EFI_LEGACY_SPI_CONTROLLER_PROTOCOL_LOCK_CONTROLLER LockController;\r
261	};\r
262	\r
263	extern EFI_GUID gEfiLegacySpiControllerProtocolGuid;\r
264	\r
265	#endif // __LEGACY_SPI_CONTROLLER_PROTOCOL_H__\r