]>
Commit | Line | Data |
---|---|---|
77f85581 | 1 | /* |
469146c0 JT |
2 | * Common SPI Interface: Controller-specific definitions |
3 | * | |
77f85581 WD |
4 | * (C) Copyright 2001 |
5 | * Gerald Van Baren, Custom IDEAS, vanbaren@cideas.com. | |
6 | * | |
1a459660 | 7 | * SPDX-License-Identifier: GPL-2.0+ |
77f85581 WD |
8 | */ |
9 | ||
10 | #ifndef _SPI_H_ | |
11 | #define _SPI_H_ | |
12 | ||
38254f45 GL |
13 | /* SPI mode flags */ |
14 | #define SPI_CPHA 0x01 /* clock phase */ | |
15 | #define SPI_CPOL 0x02 /* clock polarity */ | |
16 | #define SPI_MODE_0 (0|0) /* (original MicroWire) */ | |
17 | #define SPI_MODE_1 (0|SPI_CPHA) | |
18 | #define SPI_MODE_2 (SPI_CPOL|0) | |
19 | #define SPI_MODE_3 (SPI_CPOL|SPI_CPHA) | |
d255bb0e | 20 | #define SPI_CS_HIGH 0x04 /* CS active high */ |
38254f45 GL |
21 | #define SPI_LSB_FIRST 0x08 /* per-word bits-on-wire */ |
22 | #define SPI_3WIRE 0x10 /* SI/SO signals shared */ | |
23 | #define SPI_LOOP 0x20 /* loopback mode */ | |
bb786b84 RS |
24 | #define SPI_SLAVE 0x40 /* slave mode */ |
25 | #define SPI_PREAMBLE 0x80 /* Skip preamble bytes */ | |
38254f45 | 26 | |
d255bb0e | 27 | /* SPI transfer flags */ |
ce22b922 JT |
28 | #define SPI_XFER_BEGIN 0x01 /* Assert CS before transfer */ |
29 | #define SPI_XFER_END 0x02 /* Deassert CS after transfer */ | |
30 | #define SPI_XFER_MMAP 0x08 /* Memory Mapped start */ | |
31 | #define SPI_XFER_MMAP_END 0x10 /* Memory Mapped End */ | |
4700219d | 32 | #define SPI_XFER_ONCE (SPI_XFER_BEGIN | SPI_XFER_END) |
f77f4691 | 33 | #define SPI_XFER_U_PAGE (1 << 5) |
77f85581 | 34 | |
3163aaa6 JT |
35 | /* SPI TX operation modes */ |
36 | #define SPI_OPM_TX_QPP 1 << 0 | |
37 | ||
4e09cc1e JT |
38 | /* SPI RX operation modes */ |
39 | #define SPI_OPM_RX_AS 1 << 0 | |
40 | #define SPI_OPM_RX_DOUT 1 << 1 | |
41 | #define SPI_OPM_RX_DIO 1 << 2 | |
3163aaa6 | 42 | #define SPI_OPM_RX_QOF 1 << 3 |
c4ba0d82 | 43 | #define SPI_OPM_RX_QIOF 1 << 4 |
3163aaa6 | 44 | #define SPI_OPM_RX_EXTN SPI_OPM_RX_AS | SPI_OPM_RX_DOUT | \ |
c4ba0d82 JT |
45 | SPI_OPM_RX_DIO | SPI_OPM_RX_QOF | \ |
46 | SPI_OPM_RX_QIOF | |
4e09cc1e | 47 | |
f77f4691 JT |
48 | /* SPI bus connection options */ |
49 | #define SPI_CONN_DUAL_SHARED 1 << 0 | |
056fbc73 | 50 | #define SPI_CONN_DUAL_SEPARATED 1 << 1 |
f77f4691 | 51 | |
bb786b84 | 52 | /* Header byte that marks the start of the message */ |
ce22b922 | 53 | #define SPI_PREAMBLE_END_BYTE 0xec |
bb786b84 | 54 | |
5753d09b NK |
55 | #define SPI_DEFAULT_WORDLEN 8 |
56 | ||
1b1bd9a7 | 57 | /** |
ce22b922 | 58 | * struct spi_slave - Representation of a SPI slave |
d255bb0e HS |
59 | * |
60 | * Drivers are expected to extend this with controller-specific data. | |
61 | * | |
ce22b922 JT |
62 | * @bus: ID of the bus that the slave is attached to. |
63 | * @cs: ID of the chip select connected to the slave. | |
4e09cc1e | 64 | * @op_mode_rx: SPI RX operation mode. |
3163aaa6 | 65 | * @op_mode_tx: SPI TX operation mode. |
5753d09b | 66 | * @wordlen: Size of SPI word in number of bits |
ce22b922 JT |
67 | * @max_write_size: If non-zero, the maximum number of bytes which can |
68 | * be written at once, excluding command bytes. | |
69 | * @memory_map: Address of read-only SPI flash access. | |
056fbc73 | 70 | * @option: Varies SPI bus options - separate, shared bus. |
f77f4691 | 71 | * @flags: Indication of SPI flags. |
d255bb0e HS |
72 | */ |
73 | struct spi_slave { | |
1b1bd9a7 JT |
74 | unsigned int bus; |
75 | unsigned int cs; | |
4e09cc1e | 76 | u8 op_mode_rx; |
3163aaa6 | 77 | u8 op_mode_tx; |
5753d09b | 78 | unsigned int wordlen; |
0c456cee | 79 | unsigned int max_write_size; |
004f15b6 | 80 | void *memory_map; |
f77f4691 JT |
81 | u8 option; |
82 | u8 flags; | |
d255bb0e | 83 | }; |
77f85581 | 84 | |
1b1bd9a7 | 85 | /** |
77f85581 | 86 | * Initialization, must be called once on start up. |
d255bb0e HS |
87 | * |
88 | * TODO: I don't think we really need this. | |
77f85581 WD |
89 | */ |
90 | void spi_init(void); | |
91 | ||
ba6c3ce9 SG |
92 | /** |
93 | * spi_do_alloc_slave - Allocate a new SPI slave (internal) | |
94 | * | |
95 | * Allocate and zero all fields in the spi slave, and set the bus/chip | |
96 | * select. Use the helper macro spi_alloc_slave() to call this. | |
97 | * | |
1b1bd9a7 JT |
98 | * @offset: Offset of struct spi_slave within slave structure. |
99 | * @size: Size of slave structure. | |
100 | * @bus: Bus ID of the slave chip. | |
101 | * @cs: Chip select ID of the slave chip on the specified bus. | |
ba6c3ce9 SG |
102 | */ |
103 | void *spi_do_alloc_slave(int offset, int size, unsigned int bus, | |
104 | unsigned int cs); | |
105 | ||
106 | /** | |
107 | * spi_alloc_slave - Allocate a new SPI slave | |
108 | * | |
109 | * Allocate and zero all fields in the spi slave, and set the bus/chip | |
110 | * select. | |
111 | * | |
1b1bd9a7 JT |
112 | * @_struct: Name of structure to allocate (e.g. struct tegra_spi). |
113 | * This structure must contain a member 'struct spi_slave *slave'. | |
114 | * @bus: Bus ID of the slave chip. | |
115 | * @cs: Chip select ID of the slave chip on the specified bus. | |
ba6c3ce9 SG |
116 | */ |
117 | #define spi_alloc_slave(_struct, bus, cs) \ | |
118 | spi_do_alloc_slave(offsetof(_struct, slave), \ | |
119 | sizeof(_struct), bus, cs) | |
120 | ||
121 | /** | |
122 | * spi_alloc_slave_base - Allocate a new SPI slave with no private data | |
123 | * | |
124 | * Allocate and zero all fields in the spi slave, and set the bus/chip | |
125 | * select. | |
126 | * | |
1b1bd9a7 JT |
127 | * @bus: Bus ID of the slave chip. |
128 | * @cs: Chip select ID of the slave chip on the specified bus. | |
ba6c3ce9 SG |
129 | */ |
130 | #define spi_alloc_slave_base(bus, cs) \ | |
131 | spi_do_alloc_slave(0, sizeof(struct spi_slave), bus, cs) | |
132 | ||
1b1bd9a7 | 133 | /** |
d255bb0e HS |
134 | * Set up communications parameters for a SPI slave. |
135 | * | |
136 | * This must be called once for each slave. Note that this function | |
137 | * usually doesn't touch any actual hardware, it only initializes the | |
138 | * contents of spi_slave so that the hardware can be easily | |
139 | * initialized later. | |
140 | * | |
1b1bd9a7 JT |
141 | * @bus: Bus ID of the slave chip. |
142 | * @cs: Chip select ID of the slave chip on the specified bus. | |
143 | * @max_hz: Maximum SCK rate in Hz. | |
144 | * @mode: Clock polarity, clock phase and other parameters. | |
d255bb0e HS |
145 | * |
146 | * Returns: A spi_slave reference that can be used in subsequent SPI | |
147 | * calls, or NULL if one or more of the parameters are not supported. | |
148 | */ | |
149 | struct spi_slave *spi_setup_slave(unsigned int bus, unsigned int cs, | |
150 | unsigned int max_hz, unsigned int mode); | |
151 | ||
1b1bd9a7 | 152 | /** |
d255bb0e HS |
153 | * Free any memory associated with a SPI slave. |
154 | * | |
1b1bd9a7 | 155 | * @slave: The SPI slave |
d255bb0e HS |
156 | */ |
157 | void spi_free_slave(struct spi_slave *slave); | |
158 | ||
1b1bd9a7 | 159 | /** |
d255bb0e HS |
160 | * Claim the bus and prepare it for communication with a given slave. |
161 | * | |
162 | * This must be called before doing any transfers with a SPI slave. It | |
163 | * will enable and initialize any SPI hardware as necessary, and make | |
164 | * sure that the SCK line is in the correct idle state. It is not | |
165 | * allowed to claim the same bus for several slaves without releasing | |
166 | * the bus in between. | |
167 | * | |
1b1bd9a7 | 168 | * @slave: The SPI slave |
d255bb0e HS |
169 | * |
170 | * Returns: 0 if the bus was claimed successfully, or a negative value | |
171 | * if it wasn't. | |
172 | */ | |
173 | int spi_claim_bus(struct spi_slave *slave); | |
174 | ||
1b1bd9a7 | 175 | /** |
d255bb0e HS |
176 | * Release the SPI bus |
177 | * | |
178 | * This must be called once for every call to spi_claim_bus() after | |
179 | * all transfers have finished. It may disable any SPI hardware as | |
180 | * appropriate. | |
181 | * | |
1b1bd9a7 | 182 | * @slave: The SPI slave |
d255bb0e HS |
183 | */ |
184 | void spi_release_bus(struct spi_slave *slave); | |
77f85581 | 185 | |
5753d09b NK |
186 | /** |
187 | * Set the word length for SPI transactions | |
188 | * | |
189 | * Set the word length (number of bits per word) for SPI transactions. | |
190 | * | |
191 | * @slave: The SPI slave | |
192 | * @wordlen: The number of bits in a word | |
193 | * | |
194 | * Returns: 0 on success, -1 on failure. | |
195 | */ | |
196 | int spi_set_wordlen(struct spi_slave *slave, unsigned int wordlen); | |
197 | ||
1b1bd9a7 | 198 | /** |
77f85581 WD |
199 | * SPI transfer |
200 | * | |
201 | * This writes "bitlen" bits out the SPI MOSI port and simultaneously clocks | |
202 | * "bitlen" bits in the SPI MISO port. That's just the way SPI works. | |
203 | * | |
204 | * The source of the outgoing bits is the "dout" parameter and the | |
205 | * destination of the input bits is the "din" parameter. Note that "dout" | |
206 | * and "din" can point to the same memory location, in which case the | |
207 | * input data overwrites the output data (since both are buffered by | |
208 | * temporary variables, this is OK). | |
209 | * | |
77f85581 | 210 | * spi_xfer() interface: |
1b1bd9a7 JT |
211 | * @slave: The SPI slave which will be sending/receiving the data. |
212 | * @bitlen: How many bits to write and read. | |
213 | * @dout: Pointer to a string of bits to send out. The bits are | |
d255bb0e | 214 | * held in a byte array and are sent MSB first. |
1b1bd9a7 JT |
215 | * @din: Pointer to a string of bits that will be filled in. |
216 | * @flags: A bitwise combination of SPI_XFER_* flags. | |
77f85581 | 217 | * |
1b1bd9a7 | 218 | * Returns: 0 on success, not 0 on failure |
77f85581 | 219 | */ |
d255bb0e HS |
220 | int spi_xfer(struct spi_slave *slave, unsigned int bitlen, const void *dout, |
221 | void *din, unsigned long flags); | |
222 | ||
1b1bd9a7 | 223 | /** |
d255bb0e HS |
224 | * Determine if a SPI chipselect is valid. |
225 | * This function is provided by the board if the low-level SPI driver | |
226 | * needs it to determine if a given chipselect is actually valid. | |
227 | * | |
228 | * Returns: 1 if bus:cs identifies a valid chip on this board, 0 | |
229 | * otherwise. | |
230 | */ | |
231 | int spi_cs_is_valid(unsigned int bus, unsigned int cs); | |
232 | ||
1b1bd9a7 | 233 | /** |
d255bb0e HS |
234 | * Activate a SPI chipselect. |
235 | * This function is provided by the board code when using a driver | |
236 | * that can't control its chipselects automatically (e.g. | |
237 | * common/soft_spi.c). When called, it should activate the chip select | |
238 | * to the device identified by "slave". | |
239 | */ | |
240 | void spi_cs_activate(struct spi_slave *slave); | |
241 | ||
1b1bd9a7 | 242 | /** |
d255bb0e HS |
243 | * Deactivate a SPI chipselect. |
244 | * This function is provided by the board code when using a driver | |
245 | * that can't control its chipselects automatically (e.g. | |
246 | * common/soft_spi.c). When called, it should deactivate the chip | |
247 | * select to the device identified by "slave". | |
248 | */ | |
249 | void spi_cs_deactivate(struct spi_slave *slave); | |
250 | ||
1b1bd9a7 | 251 | /** |
fa1423e7 TC |
252 | * Set transfer speed. |
253 | * This sets a new speed to be applied for next spi_xfer(). | |
1b1bd9a7 JT |
254 | * @slave: The SPI slave |
255 | * @hz: The transfer speed | |
fa1423e7 TC |
256 | */ |
257 | void spi_set_speed(struct spi_slave *slave, uint hz); | |
258 | ||
1b1bd9a7 | 259 | /** |
d255bb0e | 260 | * Write 8 bits, then read 8 bits. |
1b1bd9a7 JT |
261 | * @slave: The SPI slave we're communicating with |
262 | * @byte: Byte to be written | |
d255bb0e HS |
263 | * |
264 | * Returns: The value that was read, or a negative value on error. | |
265 | * | |
266 | * TODO: This function probably shouldn't be inlined. | |
267 | */ | |
268 | static inline int spi_w8r8(struct spi_slave *slave, unsigned char byte) | |
269 | { | |
270 | unsigned char dout[2]; | |
271 | unsigned char din[2]; | |
272 | int ret; | |
273 | ||
274 | dout[0] = byte; | |
275 | dout[1] = 0; | |
38254f45 | 276 | |
d255bb0e HS |
277 | ret = spi_xfer(slave, 16, dout, din, SPI_XFER_BEGIN | SPI_XFER_END); |
278 | return ret < 0 ? ret : din[1]; | |
279 | } | |
77f85581 | 280 | |
f3424c55 HT |
281 | /** |
282 | * Set up a SPI slave for a particular device tree node | |
283 | * | |
284 | * This calls spi_setup_slave() with the correct bus number. Call | |
285 | * spi_free_slave() to free it later. | |
286 | * | |
469146c0 | 287 | * @param blob: Device tree blob |
0efc0249 SG |
288 | * @param slave_node: Slave node to use |
289 | * @param spi_node: SPI peripheral node to use | |
f3424c55 HT |
290 | * @return pointer to new spi_slave structure |
291 | */ | |
0efc0249 SG |
292 | struct spi_slave *spi_setup_slave_fdt(const void *blob, int slave_node, |
293 | int spi_node); | |
294 | ||
295 | /** | |
296 | * spi_base_setup_slave_fdt() - helper function to set up a SPI slace | |
297 | * | |
298 | * This decodes SPI properties from the slave node to determine the | |
299 | * chip select and SPI parameters. | |
300 | * | |
301 | * @blob: Device tree blob | |
302 | * @busnum: Bus number to use | |
303 | * @node: Device tree node for the SPI bus | |
304 | */ | |
305 | struct spi_slave *spi_base_setup_slave_fdt(const void *blob, int busnum, | |
306 | int node); | |
f3424c55 | 307 | |
77f85581 | 308 | #endif /* _SPI_H_ */ |