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

/** @file\r
  This file defines the SPI Host 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 __SPI_HC_PROTOCOL_H__\r
#define __SPI_HC_PROTOCOL_H__\r
\r
#include <Protocol/SpiConfiguration.h>\r
#include <Protocol/SpiIo.h>\r
\r
///\r
/// Global ID for the SPI Host Controller Protocol\r
///\r
#define EFI_SPI_HOST_GUID  \\r
  { 0xc74e5db2, 0xfa96, 0x4ae2,   \\r
    { 0xb3, 0x99, 0x15, 0x97, 0x7f, 0xe3, 0x0, 0x2d }}\r
\r
///\r
/// EDK2-style name\r
///\r
#define EFI_SPI_HC_PROTOCOL_GUID  EFI_SPI_HOST_GUID\r
\r
typedef struct _EFI_SPI_HC_PROTOCOL EFI_SPI_HC_PROTOCOL;\r
\r
/**\r
  Assert or deassert the SPI chip select.\r
\r
  This routine is called at TPL_NOTIFY.\r
  Update the value of the chip select line for a SPI peripheral. The SPI bus\r
  layer calls this routine either in the board layer or in the SPI controller\r
  to manipulate the chip select pin at the start and end of a SPI transaction.\r
\r
  @param[in] This           Pointer to an EFI_SPI_HC_PROTOCOL structure.\r
  @param[in] SpiPeripheral  The address of an EFI_SPI_PERIPHERAL data structure\r
                            describing the SPI peripheral whose chip select pin\r
                            is to be manipulated. The routine may access the\r
                            ChipSelectParameter field to gain sufficient\r
                            context to complete the operati on.\r
  @param[in] PinValue       The value to be applied to the chip select line of\r
                            the SPI peripheral.\r
\r
  @retval EFI_SUCCESS            The chip select was set as requested\r
  @retval EFI_NOT_READY          Support for the chip select is not properly\r
                                 initialized\r
  @retval EFI_INVALID_PARAMETER  The ChipSeLect value or its contents are\r
                                 invalid\r
\r
**/\r
typedef EFI_STATUS\r
(EFIAPI *EFI_SPI_HC_PROTOCOL_CHIP_SELECT) (\r
  IN CONST EFI_SPI_HC_PROTOCOL  *This,\r
  IN CONST EFI_SPI_PERIPHERAL   *SpiPeripheral,\r
  IN BOOLEAN                    PinValue\r
  );\r
\r
/**\r
  Set up the clock generator to produce the correct clock frequency, phase and\r
  polarity for a SPI chip.\r
\r
  This routine is called at TPL_NOTIFY.\r
  This routine updates the clock generator to generate the correct frequency\r
  and polarity for the SPI clock.\r
\r
  @param[in] This           Pointer to an EFI_SPI_HC_PROTOCOL structure.\r
  @param[in] SpiPeripheral  Pointer to a EFI_SPI_PERIPHERAL data structure from\r
                            which the routine can access the ClockParameter,\r
                            ClockPhase and ClockPolarity fields. The routine\r
                            also has access to the names for the SPI bus and\r
                            chip which can be used during debugging.\r
  @param[in] ClockHz        Pointer to the requested clock frequency. The SPI\r
                            host controller will choose a supported clock\r
                            frequency which is less then or equal to this\r
                            value. Specify zero to turn the clock generator\r
                            off. The actual clock frequency supported by the\r
                            SPI host controller will be returned.\r
\r
  @retval EFI_SUCCESS      The clock was set up successfully\r
  @retval EFI_UNSUPPORTED  The SPI controller was not able to support the\r
                           frequency requested by ClockHz\r
\r
**/\r
typedef EFI_STATUS\r
(EFIAPI *EFI_SPI_HC_PROTOCOL_CLOCK) (\r
  IN CONST EFI_SPI_HC_PROTOCOL  *This,\r
  IN CONST EFI_SPI_PERIPHERAL   *SpiPeripheral,\r
  IN UINT32                      *ClockHz\r
  );\r
\r
/**\r
  Perform the SPI transaction on the SPI peripheral using the SPI host\r
  controller.\r
\r
  This routine is called at TPL_NOTIFY.\r
  This routine synchronously returns EFI_SUCCESS indicating that the\r
  asynchronous SPI transaction was started. The routine then waits for\r
  completion of the SPI transaction prior to returning the final transaction\r
  status.\r
\r
  @param[in] This            Pointer to an EFI_SPI_HC_PROTOCOL structure.\r
  @param[in] BusTransaction  Pointer to a EFI_SPI_BUS_ TRANSACTION containing\r
                             the description of the SPI transaction to perform.\r
\r
  @retval EFI_SUCCESS          The transaction completed successfully\r
  @retval EFI_BAD_BUFFER_SIZE  The BusTransaction->WriteBytes value is invalid,\r
                               or the BusTransaction->ReadinBytes value is\r
                               invalid\r
  @retval EFI_UNSUPPORTED      The BusTransaction-> Transaction Type is\r
                               unsupported\r
\r
**/\r
typedef EFI_STATUS\r
(EFIAPI *EFI_SPI_HC_PROTOCOL_TRANSACTION) (\r
  IN CONST EFI_SPI_HC_PROTOCOL  *This,\r
  IN EFI_SPI_BUS_TRANSACTION    *BusTransaction\r
  );\r
\r
///\r
/// Support a SPI data transaction between the SPI controller and a SPI chip.\r
///\r
struct _EFI_SPI_HC_PROTOCOL {\r
  ///\r
  /// Host control attributes, may have zero or more of the following set:\r
  /// * HC_SUPPORTS_WRITE_ONLY_OPERATIONS\r
  /// * HC_SUPPORTS_READ_ONLY_OPERATIONS\r
  /// * HC_SUPPORTS_WRITE_THEN_READ_OPERATIONS\r
  /// * HC_TX_FRAME_IN_MOST_SIGNIFICANT_BITS\r
  ///   - The SPI host controller requires the transmit frame to be in most\r
  ///     significant bits instead of least significant bits.The host driver\r
  ///     will adjust the frames if necessary.\r
  /// * HC_RX_FRAME_IN_MOST_SIGNIFICANT_BITS\r
  ///   - The SPI host controller places the receive frame to be in most\r
  ///     significant bits instead of least significant bits.The host driver\r
  ///     will adjust the frames to be in the least significant bits if\r
  ///     necessary.\r
  /// * HC_SUPPORTS_2_BIT_DATA_BUS_W1DTH\r
  ///   - The SPI controller supports a 2 - bit data bus\r
  /// * HC_SUPPORTS_4_B1T_DATA_BUS_WIDTH\r
  ///   - The SPI controller supports a 4 - bit data bus\r
  /// * HC_TRANSFER_SIZE_INCLUDES_OPCODE\r
  ///   - Transfer size includes the opcode byte\r
  /// * HC_TRANSFER_SIZE_INCLUDES_ADDRESS\r
  ///   - Transfer size includes the 3 address bytes\r
  /// The SPI host controller must support full - duplex (receive while\r
  /// sending) operation.The SPI host controller must support a 1 - bit bus\r
  /// width.\r
  ///\r
  UINT32                          Attributes;\r
\r
  ///\r
  /// Mask of frame sizes which the SPI host controller supports. Frame size of\r
  /// N-bits is supported when bit N-1 is set. The host controller must support\r
  /// a frame size of 8-bits.\r
  ///\r
  UINT32                          FrameSizeSupportMask;\r
\r
  ///\r
  /// Maximum transfer size in bytes: 1 - Oxffffffff\r
  ///\r
  UINT32                          MaximumTransferBytes;\r
\r
  ///\r
  /// Assert or deassert the SPI chip select.\r
  ///\r
  EFI_SPI_HC_PROTOCOL_CHIP_SELECT ChipSelect;\r
\r
  ///\r
  /// Set up the clock generator to produce the correct clock frequency, phase\r
  /// and polarity for a SPI chip.\r
  ///\r
  EFI_SPI_HC_PROTOCOL_CLOCK       Clock;\r
\r
  ///\r
  /// Perform the SPI transaction on the SPI peripheral using the SPI host\r
  /// controller.\r
  ///\r
  EFI_SPI_HC_PROTOCOL_TRANSACTION Transaction;\r
};\r
\r
extern EFI_GUID gEfiSpiHcProtocolGuid;\r
\r
#endif // __SPI_HC_PROTOCOL_H__\r
Commit	Line	Data
db04b706 MH	1	/** @file\r
	2	This file defines the SPI Host 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 __SPI_HC_PROTOCOL_H__\r
	19	#define __SPI_HC_PROTOCOL_H__\r
	20	\r
	21	#include <Protocol/SpiConfiguration.h>\r
	22	#include <Protocol/SpiIo.h>\r
	23	\r
	24	///\r
	25	/// Global ID for the SPI Host Controller Protocol\r
	26	///\r
	27	#define EFI_SPI_HOST_GUID \\r
	28	{ 0xc74e5db2, 0xfa96, 0x4ae2, \\r
	29	{ 0xb3, 0x99, 0x15, 0x97, 0x7f, 0xe3, 0x0, 0x2d }}\r
	30	\r
	31	///\r
	32	/// EDK2-style name\r
	33	///\r
	34	#define EFI_SPI_HC_PROTOCOL_GUID EFI_SPI_HOST_GUID\r
	35	\r
	36	typedef struct _EFI_SPI_HC_PROTOCOL EFI_SPI_HC_PROTOCOL;\r
	37	\r
	38	/**\r
	39	Assert or deassert the SPI chip select.\r
	40	\r
	41	This routine is called at TPL_NOTIFY.\r
	42	Update the value of the chip select line for a SPI peripheral. The SPI bus\r
	43	layer calls this routine either in the board layer or in the SPI controller\r
	44	to manipulate the chip select pin at the start and end of a SPI transaction.\r
	45	\r
	46	@param[in] This Pointer to an EFI_SPI_HC_PROTOCOL structure.\r
	47	@param[in] SpiPeripheral The address of an EFI_SPI_PERIPHERAL data structure\r
	48	describing the SPI peripheral whose chip select pin\r
	49	is to be manipulated. The routine may access the\r
	50	ChipSelectParameter field to gain sufficient\r
	51	context to complete the operati on.\r
	52	@param[in] PinValue The value to be applied to the chip select line of\r
	53	the SPI peripheral.\r
	54	\r
	55	@retval EFI_SUCCESS The chip select was set as requested\r
	56	@retval EFI_NOT_READY Support for the chip select is not properly\r
	57	initialized\r
	58	@retval EFI_INVALID_PARAMETER The ChipSeLect value or its contents are\r
	59	invalid\r
	60	\r
	61	**/\r
	62	typedef EFI_STATUS\r
	63	(EFIAPI *EFI_SPI_HC_PROTOCOL_CHIP_SELECT) (\r
	64	IN CONST EFI_SPI_HC_PROTOCOL *This,\r
65	IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral,\r
66	IN BOOLEAN PinValue\r
67	);\r
68	\r
69	/**\r
70	Set up the clock generator to produce the correct clock frequency, phase and\r
71	polarity for a SPI chip.\r
72	\r
73	This routine is called at TPL_NOTIFY.\r
74	This routine updates the clock generator to generate the correct frequency\r
75	and polarity for the SPI clock.\r
76	\r
77	@param[in] This Pointer to an EFI_SPI_HC_PROTOCOL structure.\r
78	@param[in] SpiPeripheral Pointer to a EFI_SPI_PERIPHERAL data structure from\r
79	which the routine can access the ClockParameter,\r
80	ClockPhase and ClockPolarity fields. The routine\r
81	also has access to the names for the SPI bus and\r
82	chip which can be used during debugging.\r
83	@param[in] ClockHz Pointer to the requested clock frequency. The SPI\r
84	host controller will choose a supported clock\r
85	frequency which is less then or equal to this\r
86	value. Specify zero to turn the clock generator\r
87	off. The actual clock frequency supported by the\r
88	SPI host controller will be returned.\r
89	\r
90	@retval EFI_SUCCESS The clock was set up successfully\r
91	@retval EFI_UNSUPPORTED The SPI controller was not able to support the\r
92	frequency requested by ClockHz\r
93	\r
94	**/\r
95	typedef EFI_STATUS\r
96	(EFIAPI *EFI_SPI_HC_PROTOCOL_CLOCK) (\r
97	IN CONST EFI_SPI_HC_PROTOCOL *This,\r
98	IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral,\r
99	IN UINT32 *ClockHz\r
100	);\r
101	\r
102	/**\r
103	Perform the SPI transaction on the SPI peripheral using the SPI host\r
104	controller.\r
105	\r
106	This routine is called at TPL_NOTIFY.\r
107	This routine synchronously returns EFI_SUCCESS indicating that the\r
108	asynchronous SPI transaction was started. The routine then waits for\r
109	completion of the SPI transaction prior to returning the final transaction\r
110	status.\r
111	\r
112	@param[in] This Pointer to an EFI_SPI_HC_PROTOCOL structure.\r
113	@param[in] BusTransaction Pointer to a EFI_SPI_BUS_ TRANSACTION containing\r
114	the description of the SPI transaction to perform.\r
115	\r
116	@retval EFI_SUCCESS The transaction completed successfully\r
117	@retval EFI_BAD_BUFFER_SIZE The BusTransaction->WriteBytes value is invalid,\r
118	or the BusTransaction->ReadinBytes value is\r
119	invalid\r
120	@retval EFI_UNSUPPORTED The BusTransaction-> Transaction Type is\r
121	unsupported\r
122	\r
123	**/\r
124	typedef EFI_STATUS\r
125	(EFIAPI *EFI_SPI_HC_PROTOCOL_TRANSACTION) (\r
126	IN CONST EFI_SPI_HC_PROTOCOL *This,\r
127	IN EFI_SPI_BUS_TRANSACTION *BusTransaction\r
128	);\r
129	\r
130	///\r
131	/// Support a SPI data transaction between the SPI controller and a SPI chip.\r
132	///\r
133	struct _EFI_SPI_HC_PROTOCOL {\r
134	///\r
135	/// Host control attributes, may have zero or more of the following set:\r
136	/// * HC_SUPPORTS_WRITE_ONLY_OPERATIONS\r
137	/// * HC_SUPPORTS_READ_ONLY_OPERATIONS\r
138	/// * HC_SUPPORTS_WRITE_THEN_READ_OPERATIONS\r
139	/// * HC_TX_FRAME_IN_MOST_SIGNIFICANT_BITS\r
140	/// - The SPI host controller requires the transmit frame to be in most\r
141	/// significant bits instead of least significant bits.The host driver\r
142	/// will adjust the frames if necessary.\r
143	/// * HC_RX_FRAME_IN_MOST_SIGNIFICANT_BITS\r
144	/// - The SPI host controller places the receive frame to be in most\r
145	/// significant bits instead of least significant bits.The host driver\r
146	/// will adjust the frames to be in the least significant bits if\r
147	/// necessary.\r
148	/// * HC_SUPPORTS_2_BIT_DATA_BUS_W1DTH\r
149	/// - The SPI controller supports a 2 - bit data bus\r
150	/// * HC_SUPPORTS_4_B1T_DATA_BUS_WIDTH\r
151	/// - The SPI controller supports a 4 - bit data bus\r
152	/// * HC_TRANSFER_SIZE_INCLUDES_OPCODE\r
153	/// - Transfer size includes the opcode byte\r
154	/// * HC_TRANSFER_SIZE_INCLUDES_ADDRESS\r
155	/// - Transfer size includes the 3 address bytes\r
156	/// The SPI host controller must support full - duplex (receive while\r
157	/// sending) operation.The SPI host controller must support a 1 - bit bus\r
158	/// width.\r
159	///\r
160	UINT32 Attributes;\r
161	\r
162	///\r
163	/// Mask of frame sizes which the SPI host controller supports. Frame size of\r
164	/// N-bits is supported when bit N-1 is set. The host controller must support\r
165	/// a frame size of 8-bits.\r
166	///\r
167	UINT32 FrameSizeSupportMask;\r
168	\r
169	///\r
170	/// Maximum transfer size in bytes: 1 - Oxffffffff\r
171	///\r
172	UINT32 MaximumTransferBytes;\r
173	\r
174	///\r
175	/// Assert or deassert the SPI chip select.\r
176	///\r
177	EFI_SPI_HC_PROTOCOL_CHIP_SELECT ChipSelect;\r
178	\r
179	///\r
180	/// Set up the clock generator to produce the correct clock frequency, phase\r
181	/// and polarity for a SPI chip.\r
182	///\r
183	EFI_SPI_HC_PROTOCOL_CLOCK Clock;\r
184	\r
185	///\r
186	/// Perform the SPI transaction on the SPI peripheral using the SPI host\r
187	/// controller.\r
188	///\r
189	EFI_SPI_HC_PROTOCOL_TRANSACTION Transaction;\r
190	};\r
191	\r
192	extern EFI_GUID gEfiSpiHcProtocolGuid;\r
193	\r
194	#endif // __SPI_HC_PROTOCOL_H__\r