]>
Commit | Line | Data |
---|---|---|
83d290c5 | 1 | /* SPDX-License-Identifier: GPL-2.0+ */ |
77f85581 | 2 | /* |
469146c0 JT |
3 | * Common SPI Interface: Controller-specific definitions |
4 | * | |
77f85581 WD |
5 | * (C) Copyright 2001 |
6 | * Gerald Van Baren, Custom IDEAS, vanbaren@cideas.com. | |
77f85581 WD |
7 | */ |
8 | ||
9 | #ifndef _SPI_H_ | |
10 | #define _SPI_H_ | |
11 | ||
d13f5b25 BB |
12 | #include <common.h> |
13 | ||
38254f45 | 14 | /* SPI mode flags */ |
465c00d7 JT |
15 | #define SPI_CPHA BIT(0) /* clock phase */ |
16 | #define SPI_CPOL BIT(1) /* clock polarity */ | |
17 | #define SPI_MODE_0 (0|0) /* (original MicroWire) */ | |
18 | #define SPI_MODE_1 (0|SPI_CPHA) | |
19 | #define SPI_MODE_2 (SPI_CPOL|0) | |
20 | #define SPI_MODE_3 (SPI_CPOL|SPI_CPHA) | |
21 | #define SPI_CS_HIGH BIT(2) /* CS active high */ | |
22 | #define SPI_LSB_FIRST BIT(3) /* per-word bits-on-wire */ | |
23 | #define SPI_3WIRE BIT(4) /* SI/SO signals shared */ | |
24 | #define SPI_LOOP BIT(5) /* loopback mode */ | |
25 | #define SPI_SLAVE BIT(6) /* slave mode */ | |
26 | #define SPI_PREAMBLE BIT(7) /* Skip preamble bytes */ | |
29ee0262 | 27 | #define SPI_TX_BYTE BIT(8) /* transmit with 1 wire byte */ |
2b11a41c JT |
28 | #define SPI_TX_DUAL BIT(9) /* transmit with 2 wires */ |
29 | #define SPI_TX_QUAD BIT(10) /* transmit with 4 wires */ | |
08fe9c29 | 30 | #define SPI_RX_SLOW BIT(11) /* receive with 1 wire slow */ |
3ac48d0e JT |
31 | #define SPI_RX_DUAL BIT(12) /* receive with 2 wires */ |
32 | #define SPI_RX_QUAD BIT(13) /* receive with 4 wires */ | |
658df8bd VR |
33 | #define SPI_TX_OCTAL BIT(14) /* transmit with 8 wires */ |
34 | #define SPI_RX_OCTAL BIT(15) /* receive with 8 wires */ | |
4e09cc1e | 35 | |
bb786b84 | 36 | /* Header byte that marks the start of the message */ |
ce22b922 | 37 | #define SPI_PREAMBLE_END_BYTE 0xec |
bb786b84 | 38 | |
5d69df35 | 39 | #define SPI_DEFAULT_WORDLEN 8 |
5753d09b | 40 | |
d7af6a48 | 41 | #ifdef CONFIG_DM_SPI |
d0cff03e | 42 | /* TODO(sjg@chromium.org): Remove this and use max_hz from struct spi_slave */ |
d7af6a48 SG |
43 | struct dm_spi_bus { |
44 | uint max_hz; | |
45 | }; | |
46 | ||
d0cff03e SG |
47 | /** |
48 | * struct dm_spi_platdata - platform data for all SPI slaves | |
49 | * | |
50 | * This describes a SPI slave, a child device of the SPI bus. To obtain this | |
51 | * struct from a spi_slave, use dev_get_parent_platdata(dev) or | |
52 | * dev_get_parent_platdata(slave->dev). | |
53 | * | |
54 | * This data is immuatable. Each time the device is probed, @max_hz and @mode | |
55 | * will be copied to struct spi_slave. | |
56 | * | |
57 | * @cs: Chip select number (0..n-1) | |
58 | * @max_hz: Maximum bus speed that this slave can tolerate | |
59 | * @mode: SPI mode to use for this device (see SPI mode flags) | |
60 | */ | |
61 | struct dm_spi_slave_platdata { | |
62 | unsigned int cs; | |
63 | uint max_hz; | |
64 | uint mode; | |
65 | }; | |
66 | ||
d7af6a48 SG |
67 | #endif /* CONFIG_DM_SPI */ |
68 | ||
b14ccfcf SG |
69 | /** |
70 | * enum spi_clock_phase - indicates the clock phase to use for SPI (CPHA) | |
71 | * | |
72 | * @SPI_CLOCK_PHASE_FIRST: Data sampled on the first phase | |
73 | * @SPI_CLOCK_PHASE_SECOND: Data sampled on the second phase | |
74 | */ | |
75 | enum spi_clock_phase { | |
76 | SPI_CLOCK_PHASE_FIRST, | |
77 | SPI_CLOCK_PHASE_SECOND, | |
78 | }; | |
79 | ||
80 | /** | |
81 | * enum spi_wire_mode - indicates the number of wires used for SPI | |
82 | * | |
83 | * @SPI_4_WIRE_MODE: Normal bidirectional mode with MOSI and MISO | |
84 | * @SPI_3_WIRE_MODE: Unidirectional version with a single data line SISO | |
85 | */ | |
86 | enum spi_wire_mode { | |
87 | SPI_4_WIRE_MODE, | |
88 | SPI_3_WIRE_MODE, | |
89 | }; | |
90 | ||
91 | /** | |
92 | * enum spi_polarity - indicates the polarity of the SPI bus (CPOL) | |
93 | * | |
94 | * @SPI_POLARITY_LOW: Clock is low in idle state | |
95 | * @SPI_POLARITY_HIGH: Clock is high in idle state | |
96 | */ | |
97 | enum spi_polarity { | |
98 | SPI_POLARITY_LOW, | |
99 | SPI_POLARITY_HIGH, | |
100 | }; | |
101 | ||
1b1bd9a7 | 102 | /** |
ce22b922 | 103 | * struct spi_slave - Representation of a SPI slave |
d255bb0e | 104 | * |
d7af6a48 | 105 | * For driver model this is the per-child data used by the SPI bus. It can |
bcbe3d15 | 106 | * be accessed using dev_get_parent_priv() on the slave device. The SPI uclass |
d0cff03e SG |
107 | * sets uip per_child_auto_alloc_size to sizeof(struct spi_slave), and the |
108 | * driver should not override it. Two platform data fields (max_hz and mode) | |
109 | * are copied into this structure to provide an initial value. This allows | |
110 | * them to be changed, since we should never change platform data in drivers. | |
d255bb0e | 111 | * |
d7af6a48 SG |
112 | * If not using driver model, drivers are expected to extend this with |
113 | * controller-specific data. | |
114 | * | |
115 | * @dev: SPI slave device | |
116 | * @max_hz: Maximum speed for this slave | |
60e2809a SG |
117 | * @speed: Current bus speed. This is 0 until the bus is first |
118 | * claimed. | |
d7af6a48 SG |
119 | * @bus: ID of the bus that the slave is attached to. For |
120 | * driver model this is the sequence number of the SPI | |
121 | * bus (bus->seq) so does not need to be stored | |
ce22b922 | 122 | * @cs: ID of the chip select connected to the slave. |
f5c3c033 | 123 | * @mode: SPI mode to use for this slave (see SPI mode flags) |
5753d09b | 124 | * @wordlen: Size of SPI word in number of bits |
8af74edc ÁFR |
125 | * @max_read_size: If non-zero, the maximum number of bytes which can |
126 | * be read at once. | |
ce22b922 | 127 | * @max_write_size: If non-zero, the maximum number of bytes which can |
6c94bd12 | 128 | * be written at once. |
ce22b922 | 129 | * @memory_map: Address of read-only SPI flash access. |
f77f4691 | 130 | * @flags: Indication of SPI flags. |
d255bb0e HS |
131 | */ |
132 | struct spi_slave { | |
d7af6a48 SG |
133 | #ifdef CONFIG_DM_SPI |
134 | struct udevice *dev; /* struct spi_slave is dev->parentdata */ | |
135 | uint max_hz; | |
60e2809a | 136 | uint speed; |
d7af6a48 | 137 | #else |
1b1bd9a7 JT |
138 | unsigned int bus; |
139 | unsigned int cs; | |
d0cff03e | 140 | #endif |
f5c3c033 | 141 | uint mode; |
5753d09b | 142 | unsigned int wordlen; |
8af74edc | 143 | unsigned int max_read_size; |
0c456cee | 144 | unsigned int max_write_size; |
004f15b6 | 145 | void *memory_map; |
c40f6003 | 146 | |
f77f4691 | 147 | u8 flags; |
29ee0262 JT |
148 | #define SPI_XFER_BEGIN BIT(0) /* Assert CS before transfer */ |
149 | #define SPI_XFER_END BIT(1) /* Deassert CS after transfer */ | |
c40f6003 | 150 | #define SPI_XFER_ONCE (SPI_XFER_BEGIN | SPI_XFER_END) |
29ee0262 JT |
151 | #define SPI_XFER_MMAP BIT(2) /* Memory Mapped start */ |
152 | #define SPI_XFER_MMAP_END BIT(3) /* Memory Mapped End */ | |
d255bb0e | 153 | }; |
77f85581 | 154 | |
ba6c3ce9 SG |
155 | /** |
156 | * spi_do_alloc_slave - Allocate a new SPI slave (internal) | |
157 | * | |
158 | * Allocate and zero all fields in the spi slave, and set the bus/chip | |
159 | * select. Use the helper macro spi_alloc_slave() to call this. | |
160 | * | |
1b1bd9a7 JT |
161 | * @offset: Offset of struct spi_slave within slave structure. |
162 | * @size: Size of slave structure. | |
163 | * @bus: Bus ID of the slave chip. | |
164 | * @cs: Chip select ID of the slave chip on the specified bus. | |
ba6c3ce9 SG |
165 | */ |
166 | void *spi_do_alloc_slave(int offset, int size, unsigned int bus, | |
167 | unsigned int cs); | |
168 | ||
169 | /** | |
170 | * spi_alloc_slave - Allocate a new SPI slave | |
171 | * | |
172 | * Allocate and zero all fields in the spi slave, and set the bus/chip | |
173 | * select. | |
174 | * | |
1b1bd9a7 JT |
175 | * @_struct: Name of structure to allocate (e.g. struct tegra_spi). |
176 | * This structure must contain a member 'struct spi_slave *slave'. | |
177 | * @bus: Bus ID of the slave chip. | |
178 | * @cs: Chip select ID of the slave chip on the specified bus. | |
ba6c3ce9 SG |
179 | */ |
180 | #define spi_alloc_slave(_struct, bus, cs) \ | |
181 | spi_do_alloc_slave(offsetof(_struct, slave), \ | |
182 | sizeof(_struct), bus, cs) | |
183 | ||
184 | /** | |
185 | * spi_alloc_slave_base - Allocate a new SPI slave with no private data | |
186 | * | |
187 | * Allocate and zero all fields in the spi slave, and set the bus/chip | |
188 | * select. | |
189 | * | |
1b1bd9a7 JT |
190 | * @bus: Bus ID of the slave chip. |
191 | * @cs: Chip select ID of the slave chip on the specified bus. | |
ba6c3ce9 SG |
192 | */ |
193 | #define spi_alloc_slave_base(bus, cs) \ | |
194 | spi_do_alloc_slave(0, sizeof(struct spi_slave), bus, cs) | |
195 | ||
1b1bd9a7 | 196 | /** |
d255bb0e HS |
197 | * Set up communications parameters for a SPI slave. |
198 | * | |
199 | * This must be called once for each slave. Note that this function | |
200 | * usually doesn't touch any actual hardware, it only initializes the | |
201 | * contents of spi_slave so that the hardware can be easily | |
202 | * initialized later. | |
203 | * | |
1b1bd9a7 JT |
204 | * @bus: Bus ID of the slave chip. |
205 | * @cs: Chip select ID of the slave chip on the specified bus. | |
206 | * @max_hz: Maximum SCK rate in Hz. | |
207 | * @mode: Clock polarity, clock phase and other parameters. | |
d255bb0e HS |
208 | * |
209 | * Returns: A spi_slave reference that can be used in subsequent SPI | |
210 | * calls, or NULL if one or more of the parameters are not supported. | |
211 | */ | |
212 | struct spi_slave *spi_setup_slave(unsigned int bus, unsigned int cs, | |
213 | unsigned int max_hz, unsigned int mode); | |
214 | ||
1b1bd9a7 | 215 | /** |
d255bb0e HS |
216 | * Free any memory associated with a SPI slave. |
217 | * | |
1b1bd9a7 | 218 | * @slave: The SPI slave |
d255bb0e HS |
219 | */ |
220 | void spi_free_slave(struct spi_slave *slave); | |
221 | ||
1b1bd9a7 | 222 | /** |
d255bb0e HS |
223 | * Claim the bus and prepare it for communication with a given slave. |
224 | * | |
225 | * This must be called before doing any transfers with a SPI slave. It | |
226 | * will enable and initialize any SPI hardware as necessary, and make | |
227 | * sure that the SCK line is in the correct idle state. It is not | |
228 | * allowed to claim the same bus for several slaves without releasing | |
229 | * the bus in between. | |
230 | * | |
1b1bd9a7 | 231 | * @slave: The SPI slave |
d255bb0e HS |
232 | * |
233 | * Returns: 0 if the bus was claimed successfully, or a negative value | |
234 | * if it wasn't. | |
235 | */ | |
236 | int spi_claim_bus(struct spi_slave *slave); | |
237 | ||
1b1bd9a7 | 238 | /** |
d255bb0e HS |
239 | * Release the SPI bus |
240 | * | |
241 | * This must be called once for every call to spi_claim_bus() after | |
242 | * all transfers have finished. It may disable any SPI hardware as | |
243 | * appropriate. | |
244 | * | |
1b1bd9a7 | 245 | * @slave: The SPI slave |
d255bb0e HS |
246 | */ |
247 | void spi_release_bus(struct spi_slave *slave); | |
77f85581 | 248 | |
5753d09b NK |
249 | /** |
250 | * Set the word length for SPI transactions | |
251 | * | |
252 | * Set the word length (number of bits per word) for SPI transactions. | |
253 | * | |
254 | * @slave: The SPI slave | |
255 | * @wordlen: The number of bits in a word | |
256 | * | |
257 | * Returns: 0 on success, -1 on failure. | |
258 | */ | |
259 | int spi_set_wordlen(struct spi_slave *slave, unsigned int wordlen); | |
260 | ||
1b1bd9a7 | 261 | /** |
ccdabd89 | 262 | * SPI transfer (optional if mem_ops is used) |
77f85581 WD |
263 | * |
264 | * This writes "bitlen" bits out the SPI MOSI port and simultaneously clocks | |
265 | * "bitlen" bits in the SPI MISO port. That's just the way SPI works. | |
266 | * | |
267 | * The source of the outgoing bits is the "dout" parameter and the | |
268 | * destination of the input bits is the "din" parameter. Note that "dout" | |
269 | * and "din" can point to the same memory location, in which case the | |
270 | * input data overwrites the output data (since both are buffered by | |
271 | * temporary variables, this is OK). | |
272 | * | |
77f85581 | 273 | * spi_xfer() interface: |
1b1bd9a7 JT |
274 | * @slave: The SPI slave which will be sending/receiving the data. |
275 | * @bitlen: How many bits to write and read. | |
276 | * @dout: Pointer to a string of bits to send out. The bits are | |
d255bb0e | 277 | * held in a byte array and are sent MSB first. |
1b1bd9a7 JT |
278 | * @din: Pointer to a string of bits that will be filled in. |
279 | * @flags: A bitwise combination of SPI_XFER_* flags. | |
77f85581 | 280 | * |
1b1bd9a7 | 281 | * Returns: 0 on success, not 0 on failure |
77f85581 | 282 | */ |
d255bb0e HS |
283 | int spi_xfer(struct spi_slave *slave, unsigned int bitlen, const void *dout, |
284 | void *din, unsigned long flags); | |
285 | ||
8473b321 JT |
286 | /** |
287 | * spi_write_then_read - SPI synchronous write followed by read | |
288 | * | |
289 | * This performs a half duplex transaction in which the first transaction | |
290 | * is to send the opcode and if the length of buf is non-zero then it start | |
291 | * the second transaction as tx or rx based on the need from respective slave. | |
292 | * | |
293 | * @slave: The SPI slave device with which opcode/data will be exchanged | |
294 | * @opcode: opcode used for specific transfer | |
295 | * @n_opcode: size of opcode, in bytes | |
296 | * @txbuf: buffer into which data to be written | |
297 | * @rxbuf: buffer into which data will be read | |
298 | * @n_buf: size of buf (whether it's [tx|rx]buf), in bytes | |
299 | * | |
300 | * Returns: 0 on success, not 0 on failure | |
301 | */ | |
302 | int spi_write_then_read(struct spi_slave *slave, const u8 *opcode, | |
303 | size_t n_opcode, const u8 *txbuf, u8 *rxbuf, | |
304 | size_t n_buf); | |
305 | ||
146bad96 TR |
306 | /* Copy memory mapped data */ |
307 | void spi_flash_copy_mmap(void *data, void *offset, size_t len); | |
308 | ||
1b1bd9a7 | 309 | /** |
d255bb0e HS |
310 | * Determine if a SPI chipselect is valid. |
311 | * This function is provided by the board if the low-level SPI driver | |
312 | * needs it to determine if a given chipselect is actually valid. | |
313 | * | |
314 | * Returns: 1 if bus:cs identifies a valid chip on this board, 0 | |
315 | * otherwise. | |
316 | */ | |
d7af6a48 | 317 | int spi_cs_is_valid(unsigned int bus, unsigned int cs); |
d255bb0e | 318 | |
d7af6a48 | 319 | #ifndef CONFIG_DM_SPI |
1b1bd9a7 | 320 | /** |
d255bb0e HS |
321 | * Activate a SPI chipselect. |
322 | * This function is provided by the board code when using a driver | |
323 | * that can't control its chipselects automatically (e.g. | |
324 | * common/soft_spi.c). When called, it should activate the chip select | |
325 | * to the device identified by "slave". | |
326 | */ | |
327 | void spi_cs_activate(struct spi_slave *slave); | |
328 | ||
1b1bd9a7 | 329 | /** |
d255bb0e HS |
330 | * Deactivate a SPI chipselect. |
331 | * This function is provided by the board code when using a driver | |
332 | * that can't control its chipselects automatically (e.g. | |
333 | * common/soft_spi.c). When called, it should deactivate the chip | |
334 | * select to the device identified by "slave". | |
335 | */ | |
336 | void spi_cs_deactivate(struct spi_slave *slave); | |
337 | ||
1b1bd9a7 | 338 | /** |
fa1423e7 TC |
339 | * Set transfer speed. |
340 | * This sets a new speed to be applied for next spi_xfer(). | |
1b1bd9a7 JT |
341 | * @slave: The SPI slave |
342 | * @hz: The transfer speed | |
fa1423e7 TC |
343 | */ |
344 | void spi_set_speed(struct spi_slave *slave, uint hz); | |
d7af6a48 | 345 | #endif |
fa1423e7 | 346 | |
1b1bd9a7 | 347 | /** |
d255bb0e | 348 | * Write 8 bits, then read 8 bits. |
1b1bd9a7 JT |
349 | * @slave: The SPI slave we're communicating with |
350 | * @byte: Byte to be written | |
d255bb0e HS |
351 | * |
352 | * Returns: The value that was read, or a negative value on error. | |
353 | * | |
354 | * TODO: This function probably shouldn't be inlined. | |
355 | */ | |
356 | static inline int spi_w8r8(struct spi_slave *slave, unsigned char byte) | |
357 | { | |
358 | unsigned char dout[2]; | |
359 | unsigned char din[2]; | |
360 | int ret; | |
361 | ||
362 | dout[0] = byte; | |
363 | dout[1] = 0; | |
38254f45 | 364 | |
d255bb0e HS |
365 | ret = spi_xfer(slave, 16, dout, din, SPI_XFER_BEGIN | SPI_XFER_END); |
366 | return ret < 0 ? ret : din[1]; | |
367 | } | |
77f85581 | 368 | |
d7af6a48 SG |
369 | #ifdef CONFIG_DM_SPI |
370 | ||
371 | /** | |
372 | * struct spi_cs_info - Information about a bus chip select | |
373 | * | |
374 | * @dev: Connected device, or NULL if none | |
375 | */ | |
376 | struct spi_cs_info { | |
377 | struct udevice *dev; | |
378 | }; | |
379 | ||
380 | /** | |
381 | * struct struct dm_spi_ops - Driver model SPI operations | |
382 | * | |
383 | * The uclass interface is implemented by all SPI devices which use | |
384 | * driver model. | |
385 | */ | |
386 | struct dm_spi_ops { | |
387 | /** | |
388 | * Claim the bus and prepare it for communication. | |
389 | * | |
390 | * The device provided is the slave device. It's parent controller | |
391 | * will be used to provide the communication. | |
392 | * | |
393 | * This must be called before doing any transfers with a SPI slave. It | |
394 | * will enable and initialize any SPI hardware as necessary, and make | |
395 | * sure that the SCK line is in the correct idle state. It is not | |
396 | * allowed to claim the same bus for several slaves without releasing | |
397 | * the bus in between. | |
398 | * | |
9694b724 | 399 | * @dev: The SPI slave |
d7af6a48 SG |
400 | * |
401 | * Returns: 0 if the bus was claimed successfully, or a negative value | |
402 | * if it wasn't. | |
403 | */ | |
9694b724 | 404 | int (*claim_bus)(struct udevice *dev); |
d7af6a48 SG |
405 | |
406 | /** | |
407 | * Release the SPI bus | |
408 | * | |
409 | * This must be called once for every call to spi_claim_bus() after | |
410 | * all transfers have finished. It may disable any SPI hardware as | |
411 | * appropriate. | |
412 | * | |
9694b724 | 413 | * @dev: The SPI slave |
d7af6a48 | 414 | */ |
9694b724 | 415 | int (*release_bus)(struct udevice *dev); |
d7af6a48 SG |
416 | |
417 | /** | |
418 | * Set the word length for SPI transactions | |
419 | * | |
420 | * Set the word length (number of bits per word) for SPI transactions. | |
421 | * | |
422 | * @bus: The SPI slave | |
423 | * @wordlen: The number of bits in a word | |
424 | * | |
425 | * Returns: 0 on success, -ve on failure. | |
426 | */ | |
9694b724 | 427 | int (*set_wordlen)(struct udevice *dev, unsigned int wordlen); |
d7af6a48 SG |
428 | |
429 | /** | |
430 | * SPI transfer | |
431 | * | |
432 | * This writes "bitlen" bits out the SPI MOSI port and simultaneously | |
433 | * clocks "bitlen" bits in the SPI MISO port. That's just the way SPI | |
434 | * works. | |
435 | * | |
436 | * The source of the outgoing bits is the "dout" parameter and the | |
437 | * destination of the input bits is the "din" parameter. Note that | |
438 | * "dout" and "din" can point to the same memory location, in which | |
439 | * case the input data overwrites the output data (since both are | |
440 | * buffered by temporary variables, this is OK). | |
441 | * | |
442 | * spi_xfer() interface: | |
443 | * @dev: The slave device to communicate with | |
444 | * @bitlen: How many bits to write and read. | |
445 | * @dout: Pointer to a string of bits to send out. The bits are | |
446 | * held in a byte array and are sent MSB first. | |
447 | * @din: Pointer to a string of bits that will be filled in. | |
448 | * @flags: A bitwise combination of SPI_XFER_* flags. | |
449 | * | |
450 | * Returns: 0 on success, not -1 on failure | |
451 | */ | |
452 | int (*xfer)(struct udevice *dev, unsigned int bitlen, const void *dout, | |
453 | void *din, unsigned long flags); | |
454 | ||
d13f5b25 BB |
455 | /** |
456 | * Optimized handlers for SPI memory-like operations. | |
457 | * | |
458 | * Optimized/dedicated operations for interactions with SPI memory. This | |
459 | * field is optional and should only be implemented if the controller | |
460 | * has native support for memory like operations. | |
461 | */ | |
462 | const struct spi_controller_mem_ops *mem_ops; | |
463 | ||
d7af6a48 SG |
464 | /** |
465 | * Set transfer speed. | |
466 | * This sets a new speed to be applied for next spi_xfer(). | |
467 | * @bus: The SPI bus | |
468 | * @hz: The transfer speed | |
469 | * @return 0 if OK, -ve on error | |
470 | */ | |
471 | int (*set_speed)(struct udevice *bus, uint hz); | |
472 | ||
473 | /** | |
474 | * Set the SPI mode/flags | |
475 | * | |
476 | * It is unclear if we want to set speed and mode together instead | |
477 | * of separately. | |
478 | * | |
479 | * @bus: The SPI bus | |
480 | * @mode: Requested SPI mode (SPI_... flags) | |
481 | * @return 0 if OK, -ve on error | |
482 | */ | |
483 | int (*set_mode)(struct udevice *bus, uint mode); | |
484 | ||
485 | /** | |
486 | * Get information on a chip select | |
487 | * | |
488 | * This is only called when the SPI uclass does not know about a | |
489 | * chip select, i.e. it has no attached device. It gives the driver | |
490 | * a chance to allow activity on that chip select even so. | |
491 | * | |
492 | * @bus: The SPI bus | |
493 | * @cs: The chip select (0..n-1) | |
494 | * @info: Returns information about the chip select, if valid. | |
495 | * On entry info->dev is NULL | |
4b060003 | 496 | * @return 0 if OK (and @info is set up), -EINVAL if the chip select |
d7af6a48 SG |
497 | * is invalid, other -ve value on error |
498 | */ | |
499 | int (*cs_info)(struct udevice *bus, uint cs, struct spi_cs_info *info); | |
c53b318e SG |
500 | |
501 | /** | |
502 | * get_mmap() - Get memory-mapped SPI | |
503 | * | |
504 | * @dev: The SPI flash slave device | |
505 | * @map_basep: Returns base memory address for mapped SPI | |
506 | * @map_sizep: Returns size of mapped SPI | |
507 | * @offsetp: Returns start offset of SPI flash where the map works | |
508 | * correctly (offsets before this are not visible) | |
509 | * @return 0 if OK, -EFAULT if memory mapping is not available | |
510 | */ | |
511 | int (*get_mmap)(struct udevice *dev, ulong *map_basep, | |
512 | uint *map_sizep, uint *offsetp); | |
d7af6a48 SG |
513 | }; |
514 | ||
c60e1f25 SG |
515 | struct dm_spi_emul_ops { |
516 | /** | |
517 | * SPI transfer | |
518 | * | |
519 | * This writes "bitlen" bits out the SPI MOSI port and simultaneously | |
520 | * clocks "bitlen" bits in the SPI MISO port. That's just the way SPI | |
521 | * works. Here the device is a slave. | |
522 | * | |
523 | * The source of the outgoing bits is the "dout" parameter and the | |
524 | * destination of the input bits is the "din" parameter. Note that | |
525 | * "dout" and "din" can point to the same memory location, in which | |
526 | * case the input data overwrites the output data (since both are | |
527 | * buffered by temporary variables, this is OK). | |
528 | * | |
529 | * spi_xfer() interface: | |
530 | * @slave: The SPI slave which will be sending/receiving the data. | |
531 | * @bitlen: How many bits to write and read. | |
532 | * @dout: Pointer to a string of bits sent to the device. The | |
533 | * bits are held in a byte array and are sent MSB first. | |
534 | * @din: Pointer to a string of bits that will be sent back to | |
535 | * the master. | |
536 | * @flags: A bitwise combination of SPI_XFER_* flags. | |
537 | * | |
538 | * Returns: 0 on success, not -1 on failure | |
539 | */ | |
540 | int (*xfer)(struct udevice *slave, unsigned int bitlen, | |
541 | const void *dout, void *din, unsigned long flags); | |
542 | }; | |
543 | ||
d7af6a48 SG |
544 | /** |
545 | * spi_find_bus_and_cs() - Find bus and slave devices by number | |
546 | * | |
547 | * Given a bus number and chip select, this finds the corresponding bus | |
548 | * device and slave device. Neither device is activated by this function, | |
549 | * although they may have been activated previously. | |
550 | * | |
551 | * @busnum: SPI bus number | |
552 | * @cs: Chip select to look for | |
553 | * @busp: Returns bus device | |
554 | * @devp: Return slave device | |
555 | * @return 0 if found, -ENODEV on error | |
556 | */ | |
557 | int spi_find_bus_and_cs(int busnum, int cs, struct udevice **busp, | |
558 | struct udevice **devp); | |
559 | ||
560 | /** | |
561 | * spi_get_bus_and_cs() - Find and activate bus and slave devices by number | |
562 | * | |
563 | * Given a bus number and chip select, this finds the corresponding bus | |
564 | * device and slave device. | |
565 | * | |
566 | * If no such slave exists, and drv_name is not NULL, then a new slave device | |
b0cc1b84 | 567 | * is automatically bound on this chip select with requested speed and mode. |
d7af6a48 | 568 | * |
b0cc1b84 PD |
569 | * Ths new slave device is probed ready for use with the speed and mode |
570 | * from platdata when available or the requested values. | |
d7af6a48 SG |
571 | * |
572 | * @busnum: SPI bus number | |
573 | * @cs: Chip select to look for | |
b0cc1b84 PD |
574 | * @speed: SPI speed to use for this slave when not available in platdata |
575 | * @mode: SPI mode to use for this slave when not available in platdata | |
d7af6a48 SG |
576 | * @drv_name: Name of driver to attach to this chip select |
577 | * @dev_name: Name of the new device thus created | |
578 | * @busp: Returns bus device | |
579 | * @devp: Return slave device | |
580 | * @return 0 if found, -ve on error | |
581 | */ | |
582 | int spi_get_bus_and_cs(int busnum, int cs, int speed, int mode, | |
583 | const char *drv_name, const char *dev_name, | |
584 | struct udevice **busp, struct spi_slave **devp); | |
585 | ||
586 | /** | |
587 | * spi_chip_select() - Get the chip select for a slave | |
588 | * | |
589 | * @return the chip select this slave is attached to | |
590 | */ | |
591 | int spi_chip_select(struct udevice *slave); | |
592 | ||
ff56bba2 SG |
593 | /** |
594 | * spi_find_chip_select() - Find the slave attached to chip select | |
595 | * | |
596 | * @bus: SPI bus to search | |
597 | * @cs: Chip select to look for | |
598 | * @devp: Returns the slave device if found | |
7bacce52 BM |
599 | * @return 0 if found, -EINVAL if cs is invalid, -ENODEV if no device attached, |
600 | * other -ve value on error | |
ff56bba2 SG |
601 | */ |
602 | int spi_find_chip_select(struct udevice *bus, int cs, struct udevice **devp); | |
603 | ||
d7af6a48 | 604 | /** |
d0cff03e | 605 | * spi_slave_ofdata_to_platdata() - decode standard SPI platform data |
d7af6a48 | 606 | * |
d0cff03e | 607 | * This decodes the speed and mode for a slave from a device tree node |
d7af6a48 SG |
608 | * |
609 | * @blob: Device tree blob | |
610 | * @node: Node offset to read from | |
d0cff03e | 611 | * @plat: Place to put the decoded information |
d7af6a48 | 612 | */ |
279e26f5 | 613 | int spi_slave_ofdata_to_platdata(struct udevice *dev, |
d0cff03e | 614 | struct dm_spi_slave_platdata *plat); |
d7af6a48 SG |
615 | |
616 | /** | |
617 | * spi_cs_info() - Check information on a chip select | |
618 | * | |
619 | * This checks a particular chip select on a bus to see if it has a device | |
620 | * attached, or is even valid. | |
621 | * | |
622 | * @bus: The SPI bus | |
623 | * @cs: The chip select (0..n-1) | |
624 | * @info: Returns information about the chip select, if valid | |
625 | * @return 0 if OK (and @info is set up), -ENODEV if the chip select | |
626 | * is invalid, other -ve value on error | |
627 | */ | |
628 | int spi_cs_info(struct udevice *bus, uint cs, struct spi_cs_info *info); | |
629 | ||
630 | struct sandbox_state; | |
c60e1f25 SG |
631 | |
632 | /** | |
633 | * sandbox_spi_get_emul() - get an emulator for a SPI slave | |
634 | * | |
635 | * This provides a way to attach an emulated SPI device to a particular SPI | |
636 | * slave, so that xfer() operations on the slave will be handled by the | |
637 | * emulator. If a emulator already exists on that chip select it is returned. | |
638 | * Otherwise one is created. | |
639 | * | |
640 | * @state: Sandbox state | |
641 | * @bus: SPI bus requesting the emulator | |
642 | * @slave: SPI slave device requesting the emulator | |
643 | * @emuip: Returns pointer to emulator | |
644 | * @return 0 if OK, -ve on error | |
645 | */ | |
d7af6a48 SG |
646 | int sandbox_spi_get_emul(struct sandbox_state *state, |
647 | struct udevice *bus, struct udevice *slave, | |
648 | struct udevice **emulp); | |
649 | ||
7a3eff4c PF |
650 | /** |
651 | * Claim the bus and prepare it for communication with a given slave. | |
652 | * | |
653 | * This must be called before doing any transfers with a SPI slave. It | |
654 | * will enable and initialize any SPI hardware as necessary, and make | |
655 | * sure that the SCK line is in the correct idle state. It is not | |
656 | * allowed to claim the same bus for several slaves without releasing | |
657 | * the bus in between. | |
658 | * | |
659 | * @dev: The SPI slave device | |
660 | * | |
661 | * Returns: 0 if the bus was claimed successfully, or a negative value | |
662 | * if it wasn't. | |
663 | */ | |
664 | int dm_spi_claim_bus(struct udevice *dev); | |
665 | ||
666 | /** | |
667 | * Release the SPI bus | |
668 | * | |
669 | * This must be called once for every call to dm_spi_claim_bus() after | |
670 | * all transfers have finished. It may disable any SPI hardware as | |
671 | * appropriate. | |
672 | * | |
673 | * @slave: The SPI slave device | |
674 | */ | |
675 | void dm_spi_release_bus(struct udevice *dev); | |
676 | ||
677 | /** | |
678 | * SPI transfer | |
679 | * | |
680 | * This writes "bitlen" bits out the SPI MOSI port and simultaneously clocks | |
681 | * "bitlen" bits in the SPI MISO port. That's just the way SPI works. | |
682 | * | |
683 | * The source of the outgoing bits is the "dout" parameter and the | |
684 | * destination of the input bits is the "din" parameter. Note that "dout" | |
685 | * and "din" can point to the same memory location, in which case the | |
686 | * input data overwrites the output data (since both are buffered by | |
687 | * temporary variables, this is OK). | |
688 | * | |
689 | * dm_spi_xfer() interface: | |
690 | * @dev: The SPI slave device which will be sending/receiving the data. | |
691 | * @bitlen: How many bits to write and read. | |
692 | * @dout: Pointer to a string of bits to send out. The bits are | |
693 | * held in a byte array and are sent MSB first. | |
694 | * @din: Pointer to a string of bits that will be filled in. | |
695 | * @flags: A bitwise combination of SPI_XFER_* flags. | |
696 | * | |
697 | * Returns: 0 on success, not 0 on failure | |
698 | */ | |
699 | int dm_spi_xfer(struct udevice *dev, unsigned int bitlen, | |
700 | const void *dout, void *din, unsigned long flags); | |
701 | ||
c53b318e SG |
702 | /** |
703 | * spi_get_mmap() - Get memory-mapped SPI | |
704 | * | |
705 | * @dev: SPI slave device to check | |
706 | * @map_basep: Returns base memory address for mapped SPI | |
707 | * @map_sizep: Returns size of mapped SPI | |
708 | * @offsetp: Returns start offset of SPI flash where the map works | |
709 | * correctly (offsets before this are not visible) | |
710 | * @return 0 if OK, -ENOSYS if no operation, -EFAULT if memory mapping is not | |
711 | * available | |
712 | */ | |
713 | int dm_spi_get_mmap(struct udevice *dev, ulong *map_basep, uint *map_sizep, | |
714 | uint *offsetp); | |
715 | ||
bc5701e1 | 716 | /* Access the operations for a SPI device */ |
d7af6a48 | 717 | #define spi_get_ops(dev) ((struct dm_spi_ops *)(dev)->driver->ops) |
c60e1f25 | 718 | #define spi_emul_get_ops(dev) ((struct dm_spi_emul_ops *)(dev)->driver->ops) |
d7af6a48 SG |
719 | #endif /* CONFIG_DM_SPI */ |
720 | ||
77f85581 | 721 | #endif /* _SPI_H_ */ |