1 | /* SPDX-License-Identifier: GPL-2.0+ */ |
2 | /* |
3 | * Copyright (C) 2018 Exceet Electronics GmbH |
4 | * Copyright (C) 2018 Bootlin |
5 | * |
6 | * Author: |
7 | * Peter Pan <peterpandong@micron.com> |
8 | * Boris Brezillon <boris.brezillon@bootlin.com> |
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, \ |
20 | .nbytes = 1, \ |
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 |
61 | * @SPI_MEM_NO_DATA: no data transferred |
62 | * @SPI_MEM_DATA_IN: data coming from the SPI memory |
63 | * @SPI_MEM_DATA_OUT: data sent to the SPI memory |
64 | */ |
65 | enum spi_mem_data_dir { |
66 | SPI_MEM_NO_DATA, |
67 | SPI_MEM_DATA_IN, |
68 | SPI_MEM_DATA_OUT, |
69 | }; |
70 | |
71 | /** |
72 | * struct spi_mem_op - describes a SPI memory operation |
73 | * @cmd.nbytes: number of opcode bytes (only 1 or 2 are valid). The opcode is |
74 | * sent MSB-first. |
75 | * @cmd.buswidth: number of IO lines used to transmit the command |
76 | * @cmd.opcode: operation opcode |
77 | * @cmd.dtr: whether the command opcode should be sent in DTR mode or not |
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 |
81 | * @addr.dtr: whether the address should be sent in DTR mode or not |
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 |
89 | * @dummy.dtr: whether the dummy bytes should be sent in DTR mode or not |
90 | * @data.buswidth: number of IO lanes used to send/receive the data |
91 | * @data.dtr: whether the data should be sent in DTR mode or not |
92 | * @data.ecc: whether error correction is required or not |
93 | * @data.dir: direction of the transfer |
94 | * @data.nbytes: number of data bytes to send/receive. Can be zero if the |
95 | * operation does not involve transferring data |
96 | * @data.buf.in: input buffer (must be DMA-able) |
97 | * @data.buf.out: output buffer (must be DMA-able) |
98 | */ |
99 | struct spi_mem_op { |
100 | struct { |
101 | u8 nbytes; |
102 | u8 buswidth; |
103 | u8 dtr : 1; |
104 | u8 __pad : 7; |
105 | u16 opcode; |
106 | } cmd; |
107 | |
108 | struct { |
109 | u8 nbytes; |
110 | u8 buswidth; |
111 | u8 dtr : 1; |
112 | u8 __pad : 7; |
113 | u64 val; |
114 | } addr; |
115 | |
116 | struct { |
117 | u8 nbytes; |
118 | u8 buswidth; |
119 | u8 dtr : 1; |
120 | u8 __pad : 7; |
121 | } dummy; |
122 | |
123 | struct { |
124 | u8 buswidth; |
125 | u8 dtr : 1; |
126 | u8 ecc : 1; |
127 | u8 __pad : 6; |
128 | enum spi_mem_data_dir dir; |
129 | unsigned int nbytes; |
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 | |
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 | |
188 | /** |
189 | * struct spi_mem - describes a SPI memory device |
190 | * @spi: the underlying SPI device |
191 | * @drvpriv: spi_mem_driver private data |
192 | * @name: name of the SPI memory device |
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; |
203 | const char *name; |
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 |
232 | * limitations (can be alignment or max RX/TX size |
233 | * limitations) |
234 | * @supports_op: check if an operation is supported by the controller |
235 | * @exec_op: execute a SPI memory operation |
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. |
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. |
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. |
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. |
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. |
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); |
279 | const char *(*get_name)(struct spi_mem *mem); |
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); |
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); |
292 | }; |
293 | |
294 | /** |
295 | * struct spi_controller_mem_caps - SPI memory controller capabilities |
296 | * @dtr: Supports DTR operations |
297 | * @ecc: Supports operations with error correction |
298 | */ |
299 | struct spi_controller_mem_caps { |
300 | bool dtr; |
301 | bool ecc; |
302 | }; |
303 | |
304 | #define spi_mem_controller_is_capable(ctlr, cap) \ |
305 | ((ctlr)->mem_caps && (ctlr)->mem_caps->cap) |
306 | |
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); |
338 | |
339 | bool spi_mem_default_supports_op(struct spi_mem *mem, |
340 | const struct spi_mem_op *op); |
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 | } |
356 | |
357 | static inline |
358 | bool spi_mem_default_supports_op(struct spi_mem *mem, |
359 | const struct spi_mem_op *op) |
360 | { |
361 | return false; |
362 | } |
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 | |
373 | const char *spi_mem_get_name(struct spi_mem *mem); |
374 | |
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); |
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); |
388 | |
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 | |
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 */ |
409 | |