Commit | Line | Data |
---|---|---|
c36ff266 BB |
1 | /* SPDX-License-Identifier: GPL-2.0+ */ |
2 | /* | |
3 | * Copyright (C) 2018 Exceet Electronics GmbH | |
4 | * Copyright (C) 2018 Bootlin | |
5 | * | |
7529df46 PP |
6 | * Author: |
7 | * Peter Pan <peterpandong@micron.com> | |
8 | * Boris Brezillon <boris.brezillon@bootlin.com> | |
c36ff266 BB |
9 | */ |
10 | ||
11 | #ifndef __LINUX_SPI_MEM_H | |
12 | #define __LINUX_SPI_MEM_H | |
13 | ||
14 | #include <linux/spi/spi.h> | |
15 | ||
16 | #define SPI_MEM_OP_CMD(__opcode, __buswidth) \ | |
17 | { \ | |
18 | .buswidth = __buswidth, \ | |
19 | .opcode = __opcode, \ | |
caf72df4 | 20 | .nbytes = 1, \ |
c36ff266 BB |
21 | } |
22 | ||
23 | #define SPI_MEM_OP_ADDR(__nbytes, __val, __buswidth) \ | |
24 | { \ | |
25 | .nbytes = __nbytes, \ | |
26 | .val = __val, \ | |
27 | .buswidth = __buswidth, \ | |
28 | } | |
29 | ||
30 | #define SPI_MEM_OP_NO_ADDR { } | |
31 | ||
32 | #define SPI_MEM_OP_DUMMY(__nbytes, __buswidth) \ | |
33 | { \ | |
34 | .nbytes = __nbytes, \ | |
35 | .buswidth = __buswidth, \ | |
36 | } | |
37 | ||
38 | #define SPI_MEM_OP_NO_DUMMY { } | |
39 | ||
40 | #define SPI_MEM_OP_DATA_IN(__nbytes, __buf, __buswidth) \ | |
41 | { \ | |
42 | .dir = SPI_MEM_DATA_IN, \ | |
43 | .nbytes = __nbytes, \ | |
44 | .buf.in = __buf, \ | |
45 | .buswidth = __buswidth, \ | |
46 | } | |
47 | ||
48 | #define SPI_MEM_OP_DATA_OUT(__nbytes, __buf, __buswidth) \ | |
49 | { \ | |
50 | .dir = SPI_MEM_DATA_OUT, \ | |
51 | .nbytes = __nbytes, \ | |
52 | .buf.out = __buf, \ | |
53 | .buswidth = __buswidth, \ | |
54 | } | |
55 | ||
56 | #define SPI_MEM_OP_NO_DATA { } | |
57 | ||
58 | /** | |
59 | * enum spi_mem_data_dir - describes the direction of a SPI memory data | |
60 | * transfer from the controller perspective | |
0ebb261a | 61 | * @SPI_MEM_NO_DATA: no data transferred |
c36ff266 | 62 | * @SPI_MEM_DATA_IN: data coming from the SPI memory |
6afe76a6 | 63 | * @SPI_MEM_DATA_OUT: data sent to the SPI memory |
c36ff266 BB |
64 | */ |
65 | enum spi_mem_data_dir { | |
0ebb261a | 66 | SPI_MEM_NO_DATA, |
c36ff266 BB |
67 | SPI_MEM_DATA_IN, |
68 | SPI_MEM_DATA_OUT, | |
69 | }; | |
70 | ||
71 | /** | |
72 | * struct spi_mem_op - describes a SPI memory operation | |
caf72df4 PY |
73 | * @cmd.nbytes: number of opcode bytes (only 1 or 2 are valid). The opcode is |
74 | * sent MSB-first. | |
c36ff266 BB |
75 | * @cmd.buswidth: number of IO lines used to transmit the command |
76 | * @cmd.opcode: operation opcode | |
4c5e2bba | 77 | * @cmd.dtr: whether the command opcode should be sent in DTR mode or not |
c36ff266 BB |
78 | * @addr.nbytes: number of address bytes to send. Can be zero if the operation |
79 | * does not need to send an address | |
80 | * @addr.buswidth: number of IO lines used to transmit the address cycles | |
4c5e2bba | 81 | * @addr.dtr: whether the address should be sent in DTR mode or not |
c36ff266 BB |
82 | * @addr.val: address value. This value is always sent MSB first on the bus. |
83 | * Note that only @addr.nbytes are taken into account in this | |
84 | * address value, so users should make sure the value fits in the | |
85 | * assigned number of bytes. | |
86 | * @dummy.nbytes: number of dummy bytes to send after an opcode or address. Can | |
87 | * be zero if the operation does not require dummy bytes | |
88 | * @dummy.buswidth: number of IO lanes used to transmit the dummy bytes | |
4c5e2bba | 89 | * @dummy.dtr: whether the dummy bytes should be sent in DTR mode or not |
c36ff266 | 90 | * @data.buswidth: number of IO lanes used to send/receive the data |
4c5e2bba | 91 | * @data.dtr: whether the data should be sent in DTR mode or not |
a433c2cb | 92 | * @data.ecc: whether error correction is required or not |
c36ff266 | 93 | * @data.dir: direction of the transfer |
60489f08 BB |
94 | * @data.nbytes: number of data bytes to send/receive. Can be zero if the |
95 | * operation does not involve transferring data | |
c949a8e8 BB |
96 | * @data.buf.in: input buffer (must be DMA-able) |
97 | * @data.buf.out: output buffer (must be DMA-able) | |
c36ff266 BB |
98 | */ |
99 | struct spi_mem_op { | |
100 | struct { | |
caf72df4 | 101 | u8 nbytes; |
c36ff266 | 102 | u8 buswidth; |
4c5e2bba | 103 | u8 dtr : 1; |
71c8f9cf | 104 | u8 __pad : 7; |
caf72df4 | 105 | u16 opcode; |
c36ff266 BB |
106 | } cmd; |
107 | ||
108 | struct { | |
109 | u8 nbytes; | |
110 | u8 buswidth; | |
4c5e2bba | 111 | u8 dtr : 1; |
71c8f9cf | 112 | u8 __pad : 7; |
c36ff266 BB |
113 | u64 val; |
114 | } addr; | |
115 | ||
116 | struct { | |
117 | u8 nbytes; | |
118 | u8 buswidth; | |
4c5e2bba | 119 | u8 dtr : 1; |
71c8f9cf | 120 | u8 __pad : 7; |
c36ff266 BB |
121 | } dummy; |
122 | ||
123 | struct { | |
124 | u8 buswidth; | |
4c5e2bba | 125 | u8 dtr : 1; |
a433c2cb | 126 | u8 ecc : 1; |
71c8f9cf | 127 | u8 __pad : 6; |
c36ff266 BB |
128 | enum spi_mem_data_dir dir; |
129 | unsigned int nbytes; | |
c36ff266 BB |
130 | union { |
131 | void *in; | |
132 | const void *out; | |
133 | } buf; | |
134 | } data; | |
135 | }; | |
136 | ||
137 | #define SPI_MEM_OP(__cmd, __addr, __dummy, __data) \ | |
138 | { \ | |
139 | .cmd = __cmd, \ | |
140 | .addr = __addr, \ | |
141 | .dummy = __dummy, \ | |
142 | .data = __data, \ | |
143 | } | |
144 | ||
aa167f3f BB |
145 | /** |
146 | * struct spi_mem_dirmap_info - Direct mapping information | |
147 | * @op_tmpl: operation template that should be used by the direct mapping when | |
148 | * the memory device is accessed | |
149 | * @offset: absolute offset this direct mapping is pointing to | |
150 | * @length: length in byte of this direct mapping | |
151 | * | |
152 | * These information are used by the controller specific implementation to know | |
153 | * the portion of memory that is directly mapped and the spi_mem_op that should | |
154 | * be used to access the device. | |
155 | * A direct mapping is only valid for one direction (read or write) and this | |
156 | * direction is directly encoded in the ->op_tmpl.data.dir field. | |
157 | */ | |
158 | struct spi_mem_dirmap_info { | |
159 | struct spi_mem_op op_tmpl; | |
160 | u64 offset; | |
161 | u64 length; | |
162 | }; | |
163 | ||
164 | /** | |
165 | * struct spi_mem_dirmap_desc - Direct mapping descriptor | |
166 | * @mem: the SPI memory device this direct mapping is attached to | |
167 | * @info: information passed at direct mapping creation time | |
168 | * @nodirmap: set to 1 if the SPI controller does not implement | |
169 | * ->mem_ops->dirmap_create() or when this function returned an | |
170 | * error. If @nodirmap is true, all spi_mem_dirmap_{read,write}() | |
171 | * calls will use spi_mem_exec_op() to access the memory. This is a | |
172 | * degraded mode that allows spi_mem drivers to use the same code | |
173 | * no matter whether the controller supports direct mapping or not | |
174 | * @priv: field pointing to controller specific data | |
175 | * | |
176 | * Common part of a direct mapping descriptor. This object is created by | |
177 | * spi_mem_dirmap_create() and controller implementation of ->create_dirmap() | |
178 | * can create/attach direct mapping resources to the descriptor in the ->priv | |
179 | * field. | |
180 | */ | |
181 | struct spi_mem_dirmap_desc { | |
182 | struct spi_mem *mem; | |
183 | struct spi_mem_dirmap_info info; | |
184 | unsigned int nodirmap; | |
185 | void *priv; | |
186 | }; | |
187 | ||
c36ff266 BB |
188 | /** |
189 | * struct spi_mem - describes a SPI memory device | |
190 | * @spi: the underlying SPI device | |
06bcb516 | 191 | * @drvpriv: spi_mem_driver private data |
5d27a9c8 | 192 | * @name: name of the SPI memory device |
c36ff266 BB |
193 | * |
194 | * Extra information that describe the SPI memory device and may be needed by | |
195 | * the controller to properly handle this device should be placed here. | |
196 | * | |
197 | * One example would be the device size since some controller expose their SPI | |
198 | * mem devices through a io-mapped region. | |
199 | */ | |
200 | struct spi_mem { | |
201 | struct spi_device *spi; | |
202 | void *drvpriv; | |
401c0d77 | 203 | const char *name; |
c36ff266 BB |
204 | }; |
205 | ||
206 | /** | |
207 | * struct spi_mem_set_drvdata() - attach driver private data to a SPI mem | |
208 | * device | |
209 | * @mem: memory device | |
210 | * @data: data to attach to the memory device | |
211 | */ | |
212 | static inline void spi_mem_set_drvdata(struct spi_mem *mem, void *data) | |
213 | { | |
214 | mem->drvpriv = data; | |
215 | } | |
216 | ||
217 | /** | |
218 | * struct spi_mem_get_drvdata() - get driver private data attached to a SPI mem | |
219 | * device | |
220 | * @mem: memory device | |
221 | * | |
222 | * Return: the data attached to the mem device. | |
223 | */ | |
224 | static inline void *spi_mem_get_drvdata(struct spi_mem *mem) | |
225 | { | |
226 | return mem->drvpriv; | |
227 | } | |
228 | ||
229 | /** | |
230 | * struct spi_controller_mem_ops - SPI memory operations | |
231 | * @adjust_op_size: shrink the data xfer of an operation to match controller's | |
b994d8f0 | 232 | * limitations (can be alignment or max RX/TX size |
c36ff266 BB |
233 | * limitations) |
234 | * @supports_op: check if an operation is supported by the controller | |
235 | * @exec_op: execute a SPI memory operation | |
5d27a9c8 FS |
236 | * @get_name: get a custom name for the SPI mem device from the controller. |
237 | * This might be needed if the controller driver has been ported | |
238 | * to use the SPI mem layer and a custom name is used to keep | |
239 | * mtdparts compatible. | |
240 | * Note that if the implementation of this function allocates memory | |
241 | * dynamically, then it should do so with devm_xxx(), as we don't | |
242 | * have a ->free_name() function. | |
aa167f3f BB |
243 | * @dirmap_create: create a direct mapping descriptor that can later be used to |
244 | * access the memory device. This method is optional | |
245 | * @dirmap_destroy: destroy a memory descriptor previous created by | |
246 | * ->dirmap_create() | |
247 | * @dirmap_read: read data from the memory device using the direct mapping | |
248 | * created by ->dirmap_create(). The function can return less | |
249 | * data than requested (for example when the request is crossing | |
250 | * the currently mapped area), and the caller of | |
251 | * spi_mem_dirmap_read() is responsible for calling it again in | |
252 | * this case. | |
253 | * @dirmap_write: write data to the memory device using the direct mapping | |
254 | * created by ->dirmap_create(). The function can return less | |
255 | * data than requested (for example when the request is crossing | |
256 | * the currently mapped area), and the caller of | |
257 | * spi_mem_dirmap_write() is responsible for calling it again in | |
258 | * this case. | |
c955a0cc PC |
259 | * @poll_status: poll memory device status until (status & mask) == match or |
260 | * when the timeout has expired. It fills the data buffer with | |
261 | * the last status value. | |
c36ff266 BB |
262 | * |
263 | * This interface should be implemented by SPI controllers providing an | |
264 | * high-level interface to execute SPI memory operation, which is usually the | |
265 | * case for QSPI controllers. | |
aa167f3f BB |
266 | * |
267 | * Note on ->dirmap_{read,write}(): drivers should avoid accessing the direct | |
268 | * mapping from the CPU because doing that can stall the CPU waiting for the | |
269 | * SPI mem transaction to finish, and this will make real-time maintainers | |
270 | * unhappy and might make your system less reactive. Instead, drivers should | |
271 | * use DMA to access this direct mapping. | |
c36ff266 BB |
272 | */ |
273 | struct spi_controller_mem_ops { | |
274 | int (*adjust_op_size)(struct spi_mem *mem, struct spi_mem_op *op); | |
275 | bool (*supports_op)(struct spi_mem *mem, | |
276 | const struct spi_mem_op *op); | |
277 | int (*exec_op)(struct spi_mem *mem, | |
278 | const struct spi_mem_op *op); | |
5d27a9c8 | 279 | const char *(*get_name)(struct spi_mem *mem); |
aa167f3f BB |
280 | int (*dirmap_create)(struct spi_mem_dirmap_desc *desc); |
281 | void (*dirmap_destroy)(struct spi_mem_dirmap_desc *desc); | |
282 | ssize_t (*dirmap_read)(struct spi_mem_dirmap_desc *desc, | |
283 | u64 offs, size_t len, void *buf); | |
284 | ssize_t (*dirmap_write)(struct spi_mem_dirmap_desc *desc, | |
285 | u64 offs, size_t len, const void *buf); | |
c955a0cc PC |
286 | int (*poll_status)(struct spi_mem *mem, |
287 | const struct spi_mem_op *op, | |
288 | u16 mask, u16 match, | |
289 | unsigned long initial_delay_us, | |
290 | unsigned long polling_rate_us, | |
291 | unsigned long timeout_ms); | |
c36ff266 BB |
292 | }; |
293 | ||
4a3cc7fb MR |
294 | /** |
295 | * struct spi_controller_mem_caps - SPI memory controller capabilities | |
296 | * @dtr: Supports DTR operations | |
a433c2cb | 297 | * @ecc: Supports operations with error correction |
4a3cc7fb MR |
298 | */ |
299 | struct spi_controller_mem_caps { | |
300 | bool dtr; | |
a433c2cb | 301 | bool ecc; |
4a3cc7fb MR |
302 | }; |
303 | ||
304 | #define spi_mem_controller_is_capable(ctlr, cap) \ | |
305 | ((ctlr)->mem_caps && (ctlr)->mem_caps->cap) | |
306 | ||
c36ff266 BB |
307 | /** |
308 | * struct spi_mem_driver - SPI memory driver | |
309 | * @spidrv: inherit from a SPI driver | |
310 | * @probe: probe a SPI memory. Usually where detection/initialization takes | |
311 | * place | |
312 | * @remove: remove a SPI memory | |
313 | * @shutdown: take appropriate action when the system is shutdown | |
314 | * | |
315 | * This is just a thin wrapper around a spi_driver. The core takes care of | |
316 | * allocating the spi_mem object and forwarding the probe/remove/shutdown | |
317 | * request to the spi_mem_driver. The reason we use this wrapper is because | |
318 | * we might have to stuff more information into the spi_mem struct to let | |
319 | * SPI controllers know more about the SPI memory they interact with, and | |
320 | * having this intermediate layer allows us to do that without adding more | |
321 | * useless fields to the spi_device object. | |
322 | */ | |
323 | struct spi_mem_driver { | |
324 | struct spi_driver spidrv; | |
325 | int (*probe)(struct spi_mem *mem); | |
326 | int (*remove)(struct spi_mem *mem); | |
327 | void (*shutdown)(struct spi_mem *mem); | |
328 | }; | |
329 | ||
330 | #if IS_ENABLED(CONFIG_SPI_MEM) | |
331 | int spi_controller_dma_map_mem_op_data(struct spi_controller *ctlr, | |
332 | const struct spi_mem_op *op, | |
333 | struct sg_table *sg); | |
334 | ||
335 | void spi_controller_dma_unmap_mem_op_data(struct spi_controller *ctlr, | |
336 | const struct spi_mem_op *op, | |
337 | struct sg_table *sg); | |
72e68416 Y |
338 | |
339 | bool spi_mem_default_supports_op(struct spi_mem *mem, | |
340 | const struct spi_mem_op *op); | |
c36ff266 BB |
341 | #else |
342 | static inline int | |
343 | spi_controller_dma_map_mem_op_data(struct spi_controller *ctlr, | |
344 | const struct spi_mem_op *op, | |
345 | struct sg_table *sg) | |
346 | { | |
347 | return -ENOTSUPP; | |
348 | } | |
349 | ||
350 | static inline void | |
351 | spi_controller_dma_unmap_mem_op_data(struct spi_controller *ctlr, | |
352 | const struct spi_mem_op *op, | |
353 | struct sg_table *sg) | |
354 | { | |
355 | } | |
72e68416 | 356 | |
b5881b15 | 357 | static inline |
72e68416 Y |
358 | bool spi_mem_default_supports_op(struct spi_mem *mem, |
359 | const struct spi_mem_op *op) | |
360 | { | |
361 | return false; | |
362 | } | |
c36ff266 BB |
363 | #endif /* CONFIG_SPI_MEM */ |
364 | ||
365 | int spi_mem_adjust_op_size(struct spi_mem *mem, struct spi_mem_op *op); | |
366 | ||
367 | bool spi_mem_supports_op(struct spi_mem *mem, | |
368 | const struct spi_mem_op *op); | |
369 | ||
370 | int spi_mem_exec_op(struct spi_mem *mem, | |
371 | const struct spi_mem_op *op); | |
372 | ||
5d27a9c8 FS |
373 | const char *spi_mem_get_name(struct spi_mem *mem); |
374 | ||
aa167f3f BB |
375 | struct spi_mem_dirmap_desc * |
376 | spi_mem_dirmap_create(struct spi_mem *mem, | |
377 | const struct spi_mem_dirmap_info *info); | |
378 | void spi_mem_dirmap_destroy(struct spi_mem_dirmap_desc *desc); | |
379 | ssize_t spi_mem_dirmap_read(struct spi_mem_dirmap_desc *desc, | |
380 | u64 offs, size_t len, void *buf); | |
381 | ssize_t spi_mem_dirmap_write(struct spi_mem_dirmap_desc *desc, | |
382 | u64 offs, size_t len, const void *buf); | |
1fc1b636 BB |
383 | struct spi_mem_dirmap_desc * |
384 | devm_spi_mem_dirmap_create(struct device *dev, struct spi_mem *mem, | |
385 | const struct spi_mem_dirmap_info *info); | |
386 | void devm_spi_mem_dirmap_destroy(struct device *dev, | |
387 | struct spi_mem_dirmap_desc *desc); | |
aa167f3f | 388 | |
c955a0cc PC |
389 | int spi_mem_poll_status(struct spi_mem *mem, |
390 | const struct spi_mem_op *op, | |
391 | u16 mask, u16 match, | |
392 | unsigned long initial_delay_us, | |
393 | unsigned long polling_delay_us, | |
394 | u16 timeout_ms); | |
395 | ||
c36ff266 BB |
396 | int spi_mem_driver_register_with_owner(struct spi_mem_driver *drv, |
397 | struct module *owner); | |
398 | ||
399 | void spi_mem_driver_unregister(struct spi_mem_driver *drv); | |
400 | ||
401 | #define spi_mem_driver_register(__drv) \ | |
402 | spi_mem_driver_register_with_owner(__drv, THIS_MODULE) | |
403 | ||
404 | #define module_spi_mem_driver(__drv) \ | |
405 | module_driver(__drv, spi_mem_driver_register, \ | |
406 | spi_mem_driver_unregister) | |
407 | ||
408 | #endif /* __LINUX_SPI_MEM_H */ |