1 /*
2 * Copyright (c) 2006-2018, RT-Thread Development Team
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 *
6 * Change Logs:
7 * Date Author Notes
8 * 2012-11-23 Bernard Add extern "C"
9 */
10
11 #ifndef __SPI_H__
12 #define __SPI_H__
13
14 #include <stdlib.h>
15 #include <rtthread.h>
16
17 #ifdef __cplusplus
18 extern "C"{
19 #endif
20
21 #define RT_SPI_CPHA (1<<0) /* bit[0]:CPHA, clock phase */
22 #define RT_SPI_CPOL (1<<1) /* bit[1]:CPOL, clock polarity */
23 /**
24 * At CPOL=0 the base value of the clock is zero
25 * - For CPHA=0, data are captured on the clock's rising edge (low->high transition)
26 * and data are propagated on a falling edge (high->low clock transition).
27 * - For CPHA=1, data are captured on the clock's falling edge and data are
28 * propagated on a rising edge.
29 * At CPOL=1 the base value of the clock is one (inversion of CPOL=0)
30 * - For CPHA=0, data are captured on clock's falling edge and data are propagated
31 * on a rising edge.
32 * - For CPHA=1, data are captured on clock's rising edge and data are propagated
33 * on a falling edge.
34 */
35 #define RT_SPI_LSB (0<<2) /* bit[2]: 0-LSB */
36 #define RT_SPI_MSB (1<<2) /* bit[2]: 1-MSB */
37
38 #define RT_SPI_MASTER (0<<3) /* SPI master device */
39 #define RT_SPI_SLAVE (1<<3) /* SPI slave device */
40
41 #define RT_SPI_MODE_0 (0 | 0) /* CPOL = 0, CPHA = 0 */
42 #define RT_SPI_MODE_1 (0 | RT_SPI_CPHA) /* CPOL = 0, CPHA = 1 */
43 #define RT_SPI_MODE_2 (RT_SPI_CPOL | 0) /* CPOL = 1, CPHA = 0 */
44 #define RT_SPI_MODE_3 (RT_SPI_CPOL | RT_SPI_CPHA) /* CPOL = 1, CPHA = 1 */
45
46 #define RT_SPI_MODE_MASK (RT_SPI_CPHA | RT_SPI_CPOL | RT_SPI_MSB)
47
48 #define RT_SPI_BUS_MODE_SPI (1<<0)
49 #define RT_SPI_BUS_MODE_QSPI (1<<1)
50
51 #define RT_SPI_CS_HIGH (1<<4) /* Chipselect active high */
52 #define RT_SPI_NO_CS (1<<5) /* No chipselect */
53 #define RT_SPI_3WIRE (1<<6) /* SI/SO pin shared */
54 #define RT_SPI_READY (1<<7) /* Slave pulls low to pause */
55
56 /**
57 * SPI message structure
58 */
59 struct rt_spi_message
60 {
61 const void *send_buf;
62 void *recv_buf;
63 rt_size_t length;
64 struct rt_spi_message *next;
65
66 unsigned cs_take : 1;
67 unsigned cs_release : 1;
68 };
69
70 /**
71 * SPI configuration structure
72 */
73 struct rt_spi_configuration
74 {
75 rt_uint8_t mode;
76 rt_uint8_t data_width;
77 rt_uint16_t reserved;
78
79 rt_uint32_t max_hz;
80 };
81
82 struct rt_spi_ops;
83 struct rt_spi_bus
84 {
85 struct rt_device parent;
86 rt_uint8_t mode;
87 const struct rt_spi_ops *ops;
88
89 struct rt_mutex lock;
90 struct rt_spi_device *owner;
91 };
92
93 /**
94 * SPI operators
95 */
96 struct rt_spi_ops
97 {
98 rt_err_t (*configure)(struct rt_spi_device *device, struct rt_spi_configuration *configuration);
99 rt_uint32_t (*xfer)(struct rt_spi_device *device, struct rt_spi_message *message);
100 };
101
102 /**
103 * SPI Virtual BUS, one device must connected to a virtual BUS
104 */
105 struct rt_spi_device
106 {
107 struct rt_device parent;
108 struct rt_spi_bus *bus;
109
110 struct rt_spi_configuration config;
111 void *user_data;
112 };
113
114 struct rt_qspi_message
115 {
116 struct rt_spi_message parent;
117
118 /* instruction stage */
119 struct
120 {
121 rt_uint8_t content;
122 rt_uint8_t qspi_lines;
123 } instruction;
124
125 /* address and alternate_bytes stage */
126 struct
127 {
128 rt_uint32_t content;
129 rt_uint8_t size;
130 rt_uint8_t qspi_lines;
131 } address, alternate_bytes;
132
133 /* dummy_cycles stage */
134 rt_uint32_t dummy_cycles;
135
136 /* number of lines in qspi data stage, the other configuration items are in parent */
137 rt_uint8_t qspi_data_lines;
138 };
139
140 struct rt_qspi_configuration
141 {
142 struct rt_spi_configuration parent;
143 /* The size of medium */
144 rt_uint32_t medium_size;
145 /* double data rate mode */
146 rt_uint8_t ddr_mode;
147 /* the data lines max width which QSPI bus supported, such as 1, 2, 4 */
148 rt_uint8_t qspi_dl_width ;
149 };
150
151 struct rt_qspi_device
152 {
153 struct rt_spi_device parent;
154
155 struct rt_qspi_configuration config;
156
157 void (*enter_qspi_mode)(struct rt_qspi_device *device);
158
159 void (*exit_qspi_mode)(struct rt_qspi_device *device);
160 };
161
162 #define SPI_DEVICE(dev) ((struct rt_spi_device *)(dev))
163
164 /* register a SPI bus */
165 rt_err_t rt_spi_bus_register(struct rt_spi_bus *bus,
166 const char *name,
167 const struct rt_spi_ops *ops);
168
169 /* attach a device on SPI bus */
170 rt_err_t rt_spi_bus_attach_device(struct rt_spi_device *device,
171 const char *name,
172 const char *bus_name,
173 void *user_data);
174
175 /**
176 * This function takes SPI bus.
177 *
178 * @param device the SPI device attached to SPI bus
179 *
180 * @return RT_EOK on taken SPI bus successfully. others on taken SPI bus failed.
181 */
182 rt_err_t rt_spi_take_bus(struct rt_spi_device *device);
183
184 /**
185 * This function releases SPI bus.
186 *
187 * @param device the SPI device attached to SPI bus
188 *
189 * @return RT_EOK on release SPI bus successfully.
190 */
191 rt_err_t rt_spi_release_bus(struct rt_spi_device *device);
192
193 /**
194 * This function take SPI device (takes CS of SPI device).
195 *
196 * @param device the SPI device attached to SPI bus
197 *
198 * @return RT_EOK on release SPI bus successfully. others on taken SPI bus failed.
199 */
200 rt_err_t rt_spi_take(struct rt_spi_device *device);
201
202 /**
203 * This function releases SPI device (releases CS of SPI device).
204 *
205 * @param device the SPI device attached to SPI bus
206 *
207 * @return RT_EOK on release SPI device successfully.
208 */
209 rt_err_t rt_spi_release(struct rt_spi_device *device);
210
211 /* set configuration on SPI device */
212 rt_err_t rt_spi_configure(struct rt_spi_device *device,
213 struct rt_spi_configuration *cfg);
214
215 /* send data then receive data from SPI device */
216 rt_err_t rt_spi_send_then_recv(struct rt_spi_device *device,
217 const void *send_buf,
218 rt_size_t send_length,
219 void *recv_buf,
220 rt_size_t recv_length);
221
222 rt_err_t rt_spi_send_then_send(struct rt_spi_device *device,
223 const void *send_buf1,
224 rt_size_t send_length1,
225 const void *send_buf2,
226 rt_size_t send_length2);
227
228 /**
229 * This function transmits data to SPI device.
230 *
231 * @param device the SPI device attached to SPI bus
232 * @param send_buf the buffer to be transmitted to SPI device.
233 * @param recv_buf the buffer to save received data from SPI device.
234 * @param length the length of transmitted data.
235 *
236 * @return the actual length of transmitted.
237 */
238 rt_size_t rt_spi_transfer(struct rt_spi_device *device,
239 const void *send_buf,
240 void *recv_buf,
241 rt_size_t length);
242
243 /**
244 * This function transfers a message list to the SPI device.
245 *
246 * @param device the SPI device attached to SPI bus
247 * @param message the message list to be transmitted to SPI device
248 *
249 * @return RT_NULL if transmits message list successfully,
250 * SPI message which be transmitted failed.
251 */
252 struct rt_spi_message *rt_spi_transfer_message(struct rt_spi_device *device,
253 struct rt_spi_message *message);
254
rt_spi_recv(struct rt_spi_device * device,void * recv_buf,rt_size_t length)255 rt_inline rt_size_t rt_spi_recv(struct rt_spi_device *device,
256 void *recv_buf,
257 rt_size_t length)
258 {
259 return rt_spi_transfer(device, RT_NULL, recv_buf, length);
260 }
261
rt_spi_send(struct rt_spi_device * device,const void * send_buf,rt_size_t length)262 rt_inline rt_size_t rt_spi_send(struct rt_spi_device *device,
263 const void *send_buf,
264 rt_size_t length)
265 {
266 return rt_spi_transfer(device, send_buf, RT_NULL, length);
267 }
268
rt_spi_sendrecv8(struct rt_spi_device * device,rt_uint8_t data)269 rt_inline rt_uint8_t rt_spi_sendrecv8(struct rt_spi_device *device,
270 rt_uint8_t data)
271 {
272 rt_uint8_t value;
273
274 rt_spi_send_then_recv(device, &data, 1, &value, 1);
275
276 return value;
277 }
278
rt_spi_sendrecv16(struct rt_spi_device * device,rt_uint16_t data)279 rt_inline rt_uint16_t rt_spi_sendrecv16(struct rt_spi_device *device,
280 rt_uint16_t data)
281 {
282 rt_uint16_t value;
283
284 rt_spi_send_then_recv(device, &data, 2, &value, 2);
285
286 return value;
287 }
288
289 /**
290 * This function appends a message to the SPI message list.
291 *
292 * @param list the SPI message list header.
293 * @param message the message pointer to be appended to the message list.
294 */
rt_spi_message_append(struct rt_spi_message * list,struct rt_spi_message * message)295 rt_inline void rt_spi_message_append(struct rt_spi_message *list,
296 struct rt_spi_message *message)
297 {
298 RT_ASSERT(list != RT_NULL);
299 if (message == RT_NULL)
300 return; /* not append */
301
302 while (list->next != RT_NULL)
303 {
304 list = list->next;
305 }
306
307 list->next = message;
308 message->next = RT_NULL;
309 }
310
311 /**
312 * This function can set configuration on QSPI device.
313 *
314 * @param device the QSPI device attached to QSPI bus.
315 * @param cfg the configuration pointer.
316 *
317 * @return the actual length of transmitted.
318 */
319 rt_err_t rt_qspi_configure(struct rt_qspi_device *device, struct rt_qspi_configuration *cfg);
320
321 /**
322 * This function can register a SPI bus for QSPI mode.
323 *
324 * @param bus the SPI bus for QSPI mode.
325 * @param name The name of the spi bus.
326 * @param ops the SPI bus instance to be registered.
327 *
328 * @return the actual length of transmitted.
329 */
330 rt_err_t rt_qspi_bus_register(struct rt_spi_bus *bus, const char *name, const struct rt_spi_ops *ops);
331
332 /**
333 * This function transmits data to QSPI device.
334 *
335 * @param device the QSPI device attached to QSPI bus.
336 * @param message the message pointer.
337 *
338 * @return the actual length of transmitted.
339 */
340 rt_size_t rt_qspi_transfer_message(struct rt_qspi_device *device, struct rt_qspi_message *message);
341
342 /**
343 * This function can send data then receive data from QSPI device
344 *
345 * @param device the QSPI device attached to QSPI bus.
346 * @param send_buf the buffer to be transmitted to QSPI device.
347 * @param send_length the number of data to be transmitted.
348 * @param recv_buf the buffer to be recivied from QSPI device.
349 * @param recv_length the data to be recivied.
350 *
351 * @return the status of transmit.
352 */
353 rt_err_t rt_qspi_send_then_recv(struct rt_qspi_device *device, const void *send_buf, rt_size_t send_length,void *recv_buf, rt_size_t recv_length);
354
355 /**
356 * This function can send data to QSPI device
357 *
358 * @param device the QSPI device attached to QSPI bus.
359 * @param send_buf the buffer to be transmitted to QSPI device.
360 * @param send_length the number of data to be transmitted.
361 *
362 * @return the status of transmit.
363 */
364 rt_err_t rt_qspi_send(struct rt_qspi_device *device, const void *send_buf, rt_size_t length);
365
366 #ifdef __cplusplus
367 }
368 #endif
369
370 #endif
371