]>
Commit | Line | Data |
---|---|---|
db04b706 MH |
1 | /** @file\r |
2 | This file defines the SPI I/O 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 __SPI_IO_PROTOCOL_H__\r | |
13 | #define __SPI_IO_PROTOCOL_H__\r | |
14 | \r | |
15 | #include <Protocol/LegacySpiController.h>\r | |
16 | #include <Protocol/SpiConfiguration.h>\r | |
17 | \r | |
18 | typedef struct _EFI_SPI_IO_PROTOCOL EFI_SPI_IO_PROTOCOL;\r | |
19 | \r | |
20 | ///\r | |
21 | /// Note: The UEFI PI 1.6 specification does not specify values for the\r | |
22 | /// members below. The order matches the specification.\r | |
23 | ///\r | |
24 | typedef enum {\r | |
25 | ///\r | |
26 | /// Data flowing in both direction between the host and\r | |
27 | /// SPI peripheral.ReadBytes must equal WriteBytes and both ReadBuffer and\r | |
28 | /// WriteBuffer must be provided.\r | |
29 | ///\r | |
30 | SPI_TRANSACTION_FULL_DUPLEX,\r | |
31 | \r | |
32 | ///\r | |
33 | /// Data flowing from the host to the SPI peripheral.ReadBytes must be\r | |
34 | /// zero.WriteBytes must be non - zero and WriteBuffer must be provided.\r | |
35 | ///\r | |
36 | SPI_TRANSACTION_WRITE_ONLY,\r | |
37 | \r | |
38 | ///\r | |
39 | /// Data flowing from the SPI peripheral to the host.WriteBytes must be\r | |
40 | /// zero.ReadBytes must be non - zero and ReadBuffer must be provided.\r | |
41 | ///\r | |
42 | SPI_TRANSACTION_READ_ONLY,\r | |
43 | \r | |
44 | ///\r | |
45 | /// Data first flowing from the host to the SPI peripheral and then data\r | |
46 | /// flows from the SPI peripheral to the host.These types of operations get\r | |
47 | /// used for SPI flash devices when control data (opcode, address) must be\r | |
48 | /// passed to the SPI peripheral to specify the data to be read.\r | |
49 | ///\r | |
50 | SPI_TRANSACTION_WRITE_THEN_READ\r | |
51 | } EFI_SPI_TRANSACTION_TYPE;\r | |
52 | \r | |
53 | /**\r | |
54 | Initiate a SPI transaction between the host and a SPI peripheral.\r | |
55 | \r | |
56 | This routine must be called at or below TPL_NOTIFY.\r | |
57 | This routine works with the SPI bus layer to pass the SPI transaction to the\r | |
58 | SPI controller for execution on the SPI bus. There are four types of\r | |
59 | supported transactions supported by this routine:\r | |
60 | * Full Duplex: WriteBuffer and ReadBuffer are the same size.\r | |
61 | * Write Only: WriteBuffer contains data for SPI peripheral, ReadBytes = 0\r | |
62 | * Read Only: ReadBuffer to receive data from SPI peripheral, WriteBytes = 0\r | |
63 | * Write Then Read: WriteBuffer contains control data to write to SPI\r | |
64 | peripheral before data is placed into the ReadBuffer.\r | |
65 | Both WriteBytes and ReadBytes must be non-zero.\r | |
66 | \r | |
67 | @param[in] This Pointer to an EFI_SPI_IO_PROTOCOL structure.\r | |
68 | @param[in] TransactionType Type of SPI transaction.\r | |
69 | @param[in] DebugTransaction Set TRUE only when debugging is desired.\r | |
70 | Debugging may be turned on for a single SPI\r | |
71 | transaction. Only this transaction will display\r | |
72 | debugging messages. All other transactions with\r | |
73 | this value set to FALSE will not display any\r | |
74 | debugging messages.\r | |
75 | @param[in] ClockHz Specify the ClockHz value as zero (0) to use\r | |
76 | the maximum clock frequency supported by the\r | |
77 | SPI controller and part. Specify a non-zero\r | |
78 | value only when a specific SPI transaction\r | |
79 | requires a reduced clock rate.\r | |
80 | @param[in] BusWidth Width of the SPI bus in bits: 1, 2, 4\r | |
81 | @param[in] FrameSize Frame size in bits, range: 1 - 32\r | |
82 | @param[in] WriteBytes The length of the WriteBuffer in bytes.\r | |
83 | Specify zero for read-only operations.\r | |
84 | @param[in] WriteBuffer The buffer containing data to be sent from the\r | |
85 | host to the SPI chip. Specify NULL for read\r | |
86 | only operations.\r | |
87 | * Frame sizes 1-8 bits: UINT8 (one byte) per\r | |
88 | frame\r | |
89 | * Frame sizes 7-16 bits: UINT16 (two bytes) per\r | |
90 | frame\r | |
91 | * Frame sizes 17-32 bits: UINT32 (four bytes)\r | |
92 | per frame The transmit frame is in the least\r | |
93 | significant N bits.\r | |
94 | @param[in] ReadBytes The length of the ReadBuffer in bytes.\r | |
95 | Specify zero for write-only operations.\r | |
96 | @param[out] ReadBuffer The buffer to receeive data from the SPI chip\r | |
97 | during the transaction. Specify NULL for write\r | |
98 | only operations.\r | |
99 | * Frame sizes 1-8 bits: UINT8 (one byte) per\r | |
100 | frame\r | |
101 | * Frame sizes 7-16 bits: UINT16 (two bytes) per\r | |
102 | frame\r | |
103 | * Frame sizes 17-32 bits: UINT32 (four bytes)\r | |
104 | per frame The received frame is in the least\r | |
105 | significant N bits.\r | |
106 | \r | |
107 | @retval EFI_SUCCESS The SPI transaction completed successfully\r | |
108 | @retval EFI_BAD_BUFFER_SIZE The writeBytes value was invalid\r | |
109 | @retval EFI_BAD_BUFFER_SIZE The ReadBytes value was invalid\r | |
110 | @retval EFI_INVALID_PARAMETER TransactionType is not valid,\r | |
111 | or BusWidth not supported by SPI peripheral or\r | |
112 | SPI host controller,\r | |
113 | or WriteBytes non-zero and WriteBuffer is\r | |
114 | NULL,\r | |
115 | or ReadBytes non-zero and ReadBuffer is NULL,\r | |
116 | or ReadBuffer != WriteBuffer for full-duplex\r | |
117 | type,\r | |
118 | or WriteBuffer was NULL,\r | |
119 | or TPL is too high\r | |
120 | @retval EFI_OUT_OF_RESOURCES Insufficient memory for SPI transaction\r | |
121 | @retval EFI_UNSUPPORTED The FrameSize is not supported by the SPI bus\r | |
122 | layer or the SPI host controller\r | |
123 | @retval EFI_UNSUPPORTED The SPI controller was not able to support\r | |
124 | \r | |
125 | **/\r | |
126 | typedef\r | |
127 | EFI_STATUS\r | |
128 | (EFIAPI *EFI_SPI_IO_PROTOCOL_TRANSACTION) (\r | |
129 | IN CONST EFI_SPI_IO_PROTOCOL *This,\r | |
130 | IN EFI_SPI_TRANSACTION_TYPE TransactionType,\r | |
131 | IN BOOLEAN DebugTransaction,\r | |
132 | IN UINT32 ClockHz OPTIONAL,\r | |
133 | IN UINT32 BusWidth,\r | |
134 | IN UINT32 FrameSize,\r | |
135 | IN UINT32 WriteBytes,\r | |
136 | IN UINT8 *WriteBuffer,\r | |
137 | IN UINT32 ReadBytes,\r | |
138 | OUT UINT8 *ReadBuffer\r | |
139 | );\r | |
140 | \r | |
141 | /**\r | |
142 | Update the SPI peripheral associated with this SPI 10 instance.\r | |
143 | \r | |
144 | Support socketed SPI parts by allowing the SPI peripheral driver to replace\r | |
145 | the SPI peripheral after the connection is made. An example use is socketed\r | |
146 | SPI NOR flash parts, where the size and parameters change depending upon\r | |
147 | device is in the socket.\r | |
148 | \r | |
149 | @param[in] This Pointer to an EFI_SPI_IO_PROTOCOL structure.\r | |
150 | @param[in] SpiPeripheral Pointer to an EFI_SPI_PERIPHERAL structure.\r | |
151 | \r | |
152 | @retval EFI_SUCCESS The SPI peripheral was updated successfully\r | |
153 | @retval EFI_INVALID_PARAMETER The SpiPeripheral value is NULL,\r | |
154 | or the SpiPeripheral->SpiBus is NULL,\r | |
155 | or the SpiP eripheral - >SpiBus pointing at\r | |
156 | wrong bus,\r | |
157 | or the SpiP eripheral - >SpiPart is NULL\r | |
158 | \r | |
159 | **/\r | |
160 | typedef EFI_STATUS\r | |
161 | (EFIAPI *EFI_SPI_IO_PROTOCOL_UPDATE_SPI_PERIPHERAL) (\r | |
162 | IN CONST EFI_SPI_IO_PROTOCOL *This,\r | |
163 | IN CONST EFI_SPI_PERIPHERAL *SpiPeripheral\r | |
164 | );\r | |
165 | \r | |
166 | ///\r | |
167 | /// The EFI_SPI_BUS_ TRANSACTION data structure contains the description of the\r | |
168 | /// SPI transaction to perform on the host controller.\r | |
169 | ///\r | |
170 | typedef struct _EFI_SPI_BUS_TRANSACTION {\r | |
171 | ///\r | |
172 | /// Pointer to the SPI peripheral being manipulated.\r | |
173 | ///\r | |
174 | CONST EFI_SPI_PERIPHERAL *SpiPeripheral;\r | |
175 | \r | |
176 | ///\r | |
177 | /// Type of transaction specified by one of the EFI_SPI_TRANSACTION_TYPE\r | |
178 | /// values.\r | |
179 | ///\r | |
180 | EFI_SPI_TRANSACTION_TYPE TransactionType;\r | |
181 | \r | |
182 | ///\r | |
183 | /// TRUE if the transaction is being debugged. Debugging may be turned on for\r | |
184 | /// a single SPI transaction. Only this transaction will display debugging\r | |
185 | /// messages. All other transactions with this value set to FALSE will not\r | |
186 | /// display any debugging messages.\r | |
187 | ///\r | |
188 | BOOLEAN DebugTransaction;\r | |
189 | \r | |
190 | ///\r | |
191 | /// SPI bus width in bits: 1, 2, 4\r | |
192 | ///\r | |
193 | UINT32 BusWidth;\r | |
194 | \r | |
195 | ///\r | |
196 | /// Frame size in bits, range: 1 - 32\r | |
197 | ///\r | |
198 | UINT32 FrameSize;\r | |
199 | \r | |
200 | ///\r | |
201 | /// Length of the write buffer in bytes\r | |
202 | ///\r | |
203 | UINT32 WriteBytes;\r | |
204 | \r | |
205 | ///\r | |
206 | /// Buffer containing data to send to the SPI peripheral\r | |
207 | /// Frame sizes 1 - 8 bits: UINT8 (one byte) per frame\r | |
208 | /// Frame sizes 7 - 16 bits : UINT16 (two bytes) per frame\r | |
209 | ///\r | |
210 | UINT8 *WriteBuffer;\r | |
211 | \r | |
212 | ///\r | |
213 | /// Length of the read buffer in bytes\r | |
214 | ///\r | |
215 | UINT32 ReadBytes;\r | |
216 | \r | |
217 | ///\r | |
218 | /// Buffer to receive the data from the SPI peripheral\r | |
219 | /// * Frame sizes 1 - 8 bits: UINT8 (one byte) per frame\r | |
220 | /// * Frame sizes 7 - 16 bits : UINT16 (two bytes) per frame\r | |
221 | /// * Frame sizes 17 - 32 bits : UINT32 (four bytes) per frame\r | |
222 | ///\r | |
223 | UINT8 *ReadBuffer;\r | |
224 | } EFI_SPI_BUS_TRANSACTION;\r | |
225 | \r | |
226 | ///\r | |
227 | /// Support managed SPI data transactions between the SPI controller and a SPI\r | |
228 | /// chip.\r | |
229 | ///\r | |
230 | struct _EFI_SPI_IO_PROTOCOL {\r | |
231 | ///\r | |
232 | /// Address of an EFI_SPI_PERIPHERAL data structure associated with this\r | |
233 | /// protocol instance.\r | |
234 | ///\r | |
235 | CONST EFI_SPI_PERIPHERAL *SpiPeripheral;\r | |
236 | \r | |
237 | ///\r | |
238 | /// Address of the original EFI_SPI_PERIPHERAL data structure associated with\r | |
239 | /// this protocol instance.\r | |
240 | ///\r | |
241 | CONST EFI_SPI_PERIPHERAL *OriginalSpiPeripheral;\r | |
242 | \r | |
243 | ///\r | |
244 | /// Mask of frame sizes which the SPI 10 layer supports. Frame size of N-bits\r | |
245 | /// is supported when bit N-1 is set. The host controller must support a\r | |
246 | /// frame size of 8-bits. Frame sizes of 16, 24 and 32-bits are converted to\r | |
247 | /// 8-bit frame sizes by the SPI bus layer if the frame size is not supported\r | |
248 | /// by the SPI host controller.\r | |
249 | ///\r | |
250 | UINT32 FrameSizeSupportMask;\r | |
251 | \r | |
252 | ///\r | |
253 | /// Maximum transfer size in bytes: 1 - Oxffffffff\r | |
254 | ///\r | |
255 | UINT32 MaximumTransferBytes;\r | |
256 | \r | |
257 | ///\r | |
258 | /// Transaction attributes: One or more from:\r | |
259 | /// * SPI_10_SUPPORTS_2_B1T_DATA_BUS_W1DTH\r | |
260 | /// - The SPI host and peripheral supports a 2-bit data bus\r | |
261 | /// * SPI_IO_SUPPORTS_4_BIT_DATA_BUS_W1DTH\r | |
262 | /// - The SPI host and peripheral supports a 4-bit data bus\r | |
263 | /// * SPI_IO_TRANSFER_SIZE_INCLUDES_OPCODE\r | |
264 | /// - Transfer size includes the opcode byte\r | |
265 | /// * SPI_IO_TRANSFER_SIZE_INCLUDES_ADDRESS\r | |
266 | /// - Transfer size includes the 3 address bytes\r | |
267 | ///\r | |
268 | UINT32 Attributes;\r | |
269 | \r | |
270 | ///\r | |
271 | /// Pointer to legacy SPI controller protocol\r | |
272 | ///\r | |
273 | CONST EFI_LEGACY_SPI_CONTROLLER_PROTOCOL *LegacySpiProtocol;\r | |
274 | \r | |
275 | ///\r | |
276 | /// Initiate a SPI transaction between the host and a SPI peripheral.\r | |
277 | ///\r | |
278 | EFI_SPI_IO_PROTOCOL_TRANSACTION Transaction;\r | |
279 | \r | |
280 | ///\r | |
281 | /// Update the SPI peripheral associated with this SPI 10 instance.\r | |
282 | ///\r | |
283 | EFI_SPI_IO_PROTOCOL_UPDATE_SPI_PERIPHERAL UpdateSpiPeripheral;\r | |
284 | };\r | |
285 | \r | |
286 | #endif // __SPI_IO_PROTOCOL_H__\r |