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 | * not all driver provides supports_op(), so it can return -EOPNOTSUPP |
237 | * if the op is not supported by the driver/controller |
238 | * @get_name: get a custom name for the SPI mem device from the controller. |
239 | * This might be needed if the controller driver has been ported |
240 | * to use the SPI mem layer and a custom name is used to keep |
241 | * mtdparts compatible. |
242 | * Note that if the implementation of this function allocates memory |
243 | * dynamically, then it should do so with devm_xxx(), as we don't |
244 | * have a ->free_name() function. |
245 | * @dirmap_create: create a direct mapping descriptor that can later be used to |
246 | * access the memory device. This method is optional |
247 | * @dirmap_destroy: destroy a memory descriptor previous created by |
248 | * ->dirmap_create() |
249 | * @dirmap_read: read data from the memory device using the direct mapping |
250 | * created by ->dirmap_create(). The function can return less |
251 | * data than requested (for example when the request is crossing |
252 | * the currently mapped area), and the caller of |
253 | * spi_mem_dirmap_read() is responsible for calling it again in |
254 | * this case. |
255 | * @dirmap_write: write data to the memory device using the direct mapping |
256 | * created by ->dirmap_create(). The function can return less |
257 | * data than requested (for example when the request is crossing |
258 | * the currently mapped area), and the caller of |
259 | * spi_mem_dirmap_write() is responsible for calling it again in |
260 | * this case. |
261 | * @poll_status: poll memory device status until (status & mask) == match or |
262 | * when the timeout has expired. It fills the data buffer with |
263 | * the last status value. |
264 | * |
265 | * This interface should be implemented by SPI controllers providing an |
266 | * high-level interface to execute SPI memory operation, which is usually the |
267 | * case for QSPI controllers. |
268 | * |
269 | * Note on ->dirmap_{read,write}(): drivers should avoid accessing the direct |
270 | * mapping from the CPU because doing that can stall the CPU waiting for the |
271 | * SPI mem transaction to finish, and this will make real-time maintainers |
272 | * unhappy and might make your system less reactive. Instead, drivers should |
273 | * use DMA to access this direct mapping. |
274 | */ |
275 | struct spi_controller_mem_ops { |
276 | int (*adjust_op_size)(struct spi_mem *mem, struct spi_mem_op *op); |
277 | bool (*supports_op)(struct spi_mem *mem, |
278 | const struct spi_mem_op *op); |
279 | int (*exec_op)(struct spi_mem *mem, |
280 | const struct spi_mem_op *op); |
281 | const char *(*get_name)(struct spi_mem *mem); |
282 | int (*dirmap_create)(struct spi_mem_dirmap_desc *desc); |
283 | void (*dirmap_destroy)(struct spi_mem_dirmap_desc *desc); |
284 | ssize_t (*dirmap_read)(struct spi_mem_dirmap_desc *desc, |
285 | u64 offs, size_t len, void *buf); |
286 | ssize_t (*dirmap_write)(struct spi_mem_dirmap_desc *desc, |
287 | u64 offs, size_t len, const void *buf); |
288 | int (*poll_status)(struct spi_mem *mem, |
289 | const struct spi_mem_op *op, |
290 | u16 mask, u16 match, |
291 | unsigned long initial_delay_us, |
292 | unsigned long polling_rate_us, |
293 | unsigned long timeout_ms); |
294 | }; |
295 | |
296 | /** |
297 | * struct spi_controller_mem_caps - SPI memory controller capabilities |
298 | * @dtr: Supports DTR operations |
299 | * @ecc: Supports operations with error correction |
300 | */ |
301 | struct spi_controller_mem_caps { |
302 | bool dtr; |
303 | bool ecc; |
304 | }; |
305 | |
306 | #define spi_mem_controller_is_capable(ctlr, cap) \ |
307 | ((ctlr)->mem_caps && (ctlr)->mem_caps->cap) |
308 | |
309 | /** |
310 | * struct spi_mem_driver - SPI memory driver |
311 | * @spidrv: inherit from a SPI driver |
312 | * @probe: probe a SPI memory. Usually where detection/initialization takes |
313 | * place |
314 | * @remove: remove a SPI memory |
315 | * @shutdown: take appropriate action when the system is shutdown |
316 | * |
317 | * This is just a thin wrapper around a spi_driver. The core takes care of |
318 | * allocating the spi_mem object and forwarding the probe/remove/shutdown |
319 | * request to the spi_mem_driver. The reason we use this wrapper is because |
320 | * we might have to stuff more information into the spi_mem struct to let |
321 | * SPI controllers know more about the SPI memory they interact with, and |
322 | * having this intermediate layer allows us to do that without adding more |
323 | * useless fields to the spi_device object. |
324 | */ |
325 | struct spi_mem_driver { |
326 | struct spi_driver spidrv; |
327 | int (*probe)(struct spi_mem *mem); |
328 | int (*remove)(struct spi_mem *mem); |
329 | void (*shutdown)(struct spi_mem *mem); |
330 | }; |
331 | |
332 | #if IS_ENABLED(CONFIG_SPI_MEM) |
333 | int spi_controller_dma_map_mem_op_data(struct spi_controller *ctlr, |
334 | const struct spi_mem_op *op, |
335 | struct sg_table *sg); |
336 | |
337 | void spi_controller_dma_unmap_mem_op_data(struct spi_controller *ctlr, |
338 | const struct spi_mem_op *op, |
339 | struct sg_table *sg); |
340 | |
341 | bool spi_mem_default_supports_op(struct spi_mem *mem, |
342 | const struct spi_mem_op *op); |
343 | #else |
344 | static inline int |
345 | spi_controller_dma_map_mem_op_data(struct spi_controller *ctlr, |
346 | const struct spi_mem_op *op, |
347 | struct sg_table *sg) |
348 | { |
349 | return -ENOTSUPP; |
350 | } |
351 | |
352 | static inline void |
353 | spi_controller_dma_unmap_mem_op_data(struct spi_controller *ctlr, |
354 | const struct spi_mem_op *op, |
355 | struct sg_table *sg) |
356 | { |
357 | } |
358 | |
359 | static inline |
360 | bool spi_mem_default_supports_op(struct spi_mem *mem, |
361 | const struct spi_mem_op *op) |
362 | { |
363 | return false; |
364 | } |
365 | #endif /* CONFIG_SPI_MEM */ |
366 | |
367 | int spi_mem_adjust_op_size(struct spi_mem *mem, struct spi_mem_op *op); |
368 | |
369 | bool spi_mem_supports_op(struct spi_mem *mem, |
370 | const struct spi_mem_op *op); |
371 | |
372 | int spi_mem_exec_op(struct spi_mem *mem, |
373 | const struct spi_mem_op *op); |
374 | |
375 | const char *spi_mem_get_name(struct spi_mem *mem); |
376 | |
377 | struct spi_mem_dirmap_desc * |
378 | spi_mem_dirmap_create(struct spi_mem *mem, |
379 | const struct spi_mem_dirmap_info *info); |
380 | void spi_mem_dirmap_destroy(struct spi_mem_dirmap_desc *desc); |
381 | ssize_t spi_mem_dirmap_read(struct spi_mem_dirmap_desc *desc, |
382 | u64 offs, size_t len, void *buf); |
383 | ssize_t spi_mem_dirmap_write(struct spi_mem_dirmap_desc *desc, |
384 | u64 offs, size_t len, const void *buf); |
385 | struct spi_mem_dirmap_desc * |
386 | devm_spi_mem_dirmap_create(struct device *dev, struct spi_mem *mem, |
387 | const struct spi_mem_dirmap_info *info); |
388 | void devm_spi_mem_dirmap_destroy(struct device *dev, |
389 | struct spi_mem_dirmap_desc *desc); |
390 | |
391 | int spi_mem_poll_status(struct spi_mem *mem, |
392 | const struct spi_mem_op *op, |
393 | u16 mask, u16 match, |
394 | unsigned long initial_delay_us, |
395 | unsigned long polling_delay_us, |
396 | u16 timeout_ms); |
397 | |
398 | int spi_mem_driver_register_with_owner(struct spi_mem_driver *drv, |
399 | struct module *owner); |
400 | |
401 | void spi_mem_driver_unregister(struct spi_mem_driver *drv); |
402 | |
403 | #define spi_mem_driver_register(__drv) \ |
404 | spi_mem_driver_register_with_owner(__drv, THIS_MODULE) |
405 | |
406 | #define module_spi_mem_driver(__drv) \ |
407 | module_driver(__drv, spi_mem_driver_register, \ |
408 | spi_mem_driver_unregister) |
409 | |
410 | #endif /* __LINUX_SPI_MEM_H */ |
411 | |