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 |
c36ff266 | 92 | * @data.dir: direction of the transfer |
60489f08 BB |
93 | * @data.nbytes: number of data bytes to send/receive. Can be zero if the |
94 | * operation does not involve transferring data | |
c949a8e8 BB |
95 | * @data.buf.in: input buffer (must be DMA-able) |
96 | * @data.buf.out: output buffer (must be DMA-able) | |
c36ff266 BB |
97 | */ |
98 | struct spi_mem_op { | |
99 | struct { | |
caf72df4 | 100 | u8 nbytes; |
c36ff266 | 101 | u8 buswidth; |
4c5e2bba | 102 | u8 dtr : 1; |
caf72df4 | 103 | u16 opcode; |
c36ff266 BB |
104 | } cmd; |
105 | ||
106 | struct { | |
107 | u8 nbytes; | |
108 | u8 buswidth; | |
4c5e2bba | 109 | u8 dtr : 1; |
c36ff266 BB |
110 | u64 val; |
111 | } addr; | |
112 | ||
113 | struct { | |
114 | u8 nbytes; | |
115 | u8 buswidth; | |
4c5e2bba | 116 | u8 dtr : 1; |
c36ff266 BB |
117 | } dummy; |
118 | ||
119 | struct { | |
120 | u8 buswidth; | |
4c5e2bba | 121 | u8 dtr : 1; |
c36ff266 BB |
122 | enum spi_mem_data_dir dir; |
123 | unsigned int nbytes; | |
c36ff266 BB |
124 | union { |
125 | void *in; | |
126 | const void *out; | |
127 | } buf; | |
128 | } data; | |
129 | }; | |
130 | ||
131 | #define SPI_MEM_OP(__cmd, __addr, __dummy, __data) \ | |
132 | { \ | |
133 | .cmd = __cmd, \ | |
134 | .addr = __addr, \ | |
135 | .dummy = __dummy, \ | |
136 | .data = __data, \ | |
137 | } | |
138 | ||
aa167f3f BB |
139 | /** |
140 | * struct spi_mem_dirmap_info - Direct mapping information | |
141 | * @op_tmpl: operation template that should be used by the direct mapping when | |
142 | * the memory device is accessed | |
143 | * @offset: absolute offset this direct mapping is pointing to | |
144 | * @length: length in byte of this direct mapping | |
145 | * | |
146 | * These information are used by the controller specific implementation to know | |
147 | * the portion of memory that is directly mapped and the spi_mem_op that should | |
148 | * be used to access the device. | |
149 | * A direct mapping is only valid for one direction (read or write) and this | |
150 | * direction is directly encoded in the ->op_tmpl.data.dir field. | |
151 | */ | |
152 | struct spi_mem_dirmap_info { | |
153 | struct spi_mem_op op_tmpl; | |
154 | u64 offset; | |
155 | u64 length; | |
156 | }; | |
157 | ||
158 | /** | |
159 | * struct spi_mem_dirmap_desc - Direct mapping descriptor | |
160 | * @mem: the SPI memory device this direct mapping is attached to | |
161 | * @info: information passed at direct mapping creation time | |
162 | * @nodirmap: set to 1 if the SPI controller does not implement | |
163 | * ->mem_ops->dirmap_create() or when this function returned an | |
164 | * error. If @nodirmap is true, all spi_mem_dirmap_{read,write}() | |
165 | * calls will use spi_mem_exec_op() to access the memory. This is a | |
166 | * degraded mode that allows spi_mem drivers to use the same code | |
167 | * no matter whether the controller supports direct mapping or not | |
168 | * @priv: field pointing to controller specific data | |
169 | * | |
170 | * Common part of a direct mapping descriptor. This object is created by | |
171 | * spi_mem_dirmap_create() and controller implementation of ->create_dirmap() | |
172 | * can create/attach direct mapping resources to the descriptor in the ->priv | |
173 | * field. | |
174 | */ | |
175 | struct spi_mem_dirmap_desc { | |
176 | struct spi_mem *mem; | |
177 | struct spi_mem_dirmap_info info; | |
178 | unsigned int nodirmap; | |
179 | void *priv; | |
180 | }; | |
181 | ||
c36ff266 BB |
182 | /** |
183 | * struct spi_mem - describes a SPI memory device | |
184 | * @spi: the underlying SPI device | |
06bcb516 | 185 | * @drvpriv: spi_mem_driver private data |
5d27a9c8 | 186 | * @name: name of the SPI memory device |
c36ff266 BB |
187 | * |
188 | * Extra information that describe the SPI memory device and may be needed by | |
189 | * the controller to properly handle this device should be placed here. | |
190 | * | |
191 | * One example would be the device size since some controller expose their SPI | |
192 | * mem devices through a io-mapped region. | |
193 | */ | |
194 | struct spi_mem { | |
195 | struct spi_device *spi; | |
196 | void *drvpriv; | |
401c0d77 | 197 | const char *name; |
c36ff266 BB |
198 | }; |
199 | ||
200 | /** | |
201 | * struct spi_mem_set_drvdata() - attach driver private data to a SPI mem | |
202 | * device | |
203 | * @mem: memory device | |
204 | * @data: data to attach to the memory device | |
205 | */ | |
206 | static inline void spi_mem_set_drvdata(struct spi_mem *mem, void *data) | |
207 | { | |
208 | mem->drvpriv = data; | |
209 | } | |
210 | ||
211 | /** | |
212 | * struct spi_mem_get_drvdata() - get driver private data attached to a SPI mem | |
213 | * device | |
214 | * @mem: memory device | |
215 | * | |
216 | * Return: the data attached to the mem device. | |
217 | */ | |
218 | static inline void *spi_mem_get_drvdata(struct spi_mem *mem) | |
219 | { | |
220 | return mem->drvpriv; | |
221 | } | |
222 | ||
223 | /** | |
224 | * struct spi_controller_mem_ops - SPI memory operations | |
225 | * @adjust_op_size: shrink the data xfer of an operation to match controller's | |
226 | * limitations (can be alignment of max RX/TX size | |
227 | * limitations) | |
228 | * @supports_op: check if an operation is supported by the controller | |
229 | * @exec_op: execute a SPI memory operation | |
5d27a9c8 FS |
230 | * @get_name: get a custom name for the SPI mem device from the controller. |
231 | * This might be needed if the controller driver has been ported | |
232 | * to use the SPI mem layer and a custom name is used to keep | |
233 | * mtdparts compatible. | |
234 | * Note that if the implementation of this function allocates memory | |
235 | * dynamically, then it should do so with devm_xxx(), as we don't | |
236 | * have a ->free_name() function. | |
aa167f3f BB |
237 | * @dirmap_create: create a direct mapping descriptor that can later be used to |
238 | * access the memory device. This method is optional | |
239 | * @dirmap_destroy: destroy a memory descriptor previous created by | |
240 | * ->dirmap_create() | |
241 | * @dirmap_read: read data from the memory device using the direct mapping | |
242 | * created by ->dirmap_create(). The function can return less | |
243 | * data than requested (for example when the request is crossing | |
244 | * the currently mapped area), and the caller of | |
245 | * spi_mem_dirmap_read() is responsible for calling it again in | |
246 | * this case. | |
247 | * @dirmap_write: write data to 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_write() is responsible for calling it again in | |
252 | * this case. | |
c955a0cc PC |
253 | * @poll_status: poll memory device status until (status & mask) == match or |
254 | * when the timeout has expired. It fills the data buffer with | |
255 | * the last status value. | |
c36ff266 BB |
256 | * |
257 | * This interface should be implemented by SPI controllers providing an | |
258 | * high-level interface to execute SPI memory operation, which is usually the | |
259 | * case for QSPI controllers. | |
aa167f3f BB |
260 | * |
261 | * Note on ->dirmap_{read,write}(): drivers should avoid accessing the direct | |
262 | * mapping from the CPU because doing that can stall the CPU waiting for the | |
263 | * SPI mem transaction to finish, and this will make real-time maintainers | |
264 | * unhappy and might make your system less reactive. Instead, drivers should | |
265 | * use DMA to access this direct mapping. | |
c36ff266 BB |
266 | */ |
267 | struct spi_controller_mem_ops { | |
268 | int (*adjust_op_size)(struct spi_mem *mem, struct spi_mem_op *op); | |
269 | bool (*supports_op)(struct spi_mem *mem, | |
270 | const struct spi_mem_op *op); | |
271 | int (*exec_op)(struct spi_mem *mem, | |
272 | const struct spi_mem_op *op); | |
5d27a9c8 | 273 | const char *(*get_name)(struct spi_mem *mem); |
aa167f3f BB |
274 | int (*dirmap_create)(struct spi_mem_dirmap_desc *desc); |
275 | void (*dirmap_destroy)(struct spi_mem_dirmap_desc *desc); | |
276 | ssize_t (*dirmap_read)(struct spi_mem_dirmap_desc *desc, | |
277 | u64 offs, size_t len, void *buf); | |
278 | ssize_t (*dirmap_write)(struct spi_mem_dirmap_desc *desc, | |
279 | u64 offs, size_t len, const void *buf); | |
c955a0cc PC |
280 | int (*poll_status)(struct spi_mem *mem, |
281 | const struct spi_mem_op *op, | |
282 | u16 mask, u16 match, | |
283 | unsigned long initial_delay_us, | |
284 | unsigned long polling_rate_us, | |
285 | unsigned long timeout_ms); | |
c36ff266 BB |
286 | }; |
287 | ||
288 | /** | |
289 | * struct spi_mem_driver - SPI memory driver | |
290 | * @spidrv: inherit from a SPI driver | |
291 | * @probe: probe a SPI memory. Usually where detection/initialization takes | |
292 | * place | |
293 | * @remove: remove a SPI memory | |
294 | * @shutdown: take appropriate action when the system is shutdown | |
295 | * | |
296 | * This is just a thin wrapper around a spi_driver. The core takes care of | |
297 | * allocating the spi_mem object and forwarding the probe/remove/shutdown | |
298 | * request to the spi_mem_driver. The reason we use this wrapper is because | |
299 | * we might have to stuff more information into the spi_mem struct to let | |
300 | * SPI controllers know more about the SPI memory they interact with, and | |
301 | * having this intermediate layer allows us to do that without adding more | |
302 | * useless fields to the spi_device object. | |
303 | */ | |
304 | struct spi_mem_driver { | |
305 | struct spi_driver spidrv; | |
306 | int (*probe)(struct spi_mem *mem); | |
307 | int (*remove)(struct spi_mem *mem); | |
308 | void (*shutdown)(struct spi_mem *mem); | |
309 | }; | |
310 | ||
311 | #if IS_ENABLED(CONFIG_SPI_MEM) | |
312 | int spi_controller_dma_map_mem_op_data(struct spi_controller *ctlr, | |
313 | const struct spi_mem_op *op, | |
314 | struct sg_table *sg); | |
315 | ||
316 | void spi_controller_dma_unmap_mem_op_data(struct spi_controller *ctlr, | |
317 | const struct spi_mem_op *op, | |
318 | struct sg_table *sg); | |
72e68416 Y |
319 | |
320 | bool spi_mem_default_supports_op(struct spi_mem *mem, | |
321 | const struct spi_mem_op *op); | |
322 | ||
539cf68c PY |
323 | bool spi_mem_dtr_supports_op(struct spi_mem *mem, |
324 | const struct spi_mem_op *op); | |
325 | ||
c36ff266 BB |
326 | #else |
327 | static inline int | |
328 | spi_controller_dma_map_mem_op_data(struct spi_controller *ctlr, | |
329 | const struct spi_mem_op *op, | |
330 | struct sg_table *sg) | |
331 | { | |
332 | return -ENOTSUPP; | |
333 | } | |
334 | ||
335 | static inline void | |
336 | spi_controller_dma_unmap_mem_op_data(struct spi_controller *ctlr, | |
337 | const struct spi_mem_op *op, | |
338 | struct sg_table *sg) | |
339 | { | |
340 | } | |
72e68416 | 341 | |
b5881b15 | 342 | static inline |
72e68416 Y |
343 | bool spi_mem_default_supports_op(struct spi_mem *mem, |
344 | const struct spi_mem_op *op) | |
345 | { | |
346 | return false; | |
347 | } | |
348 | ||
539cf68c PY |
349 | static inline |
350 | bool spi_mem_dtr_supports_op(struct spi_mem *mem, | |
351 | const struct spi_mem_op *op) | |
352 | { | |
353 | return false; | |
354 | } | |
c36ff266 BB |
355 | #endif /* CONFIG_SPI_MEM */ |
356 | ||
357 | int spi_mem_adjust_op_size(struct spi_mem *mem, struct spi_mem_op *op); | |
358 | ||
359 | bool spi_mem_supports_op(struct spi_mem *mem, | |
360 | const struct spi_mem_op *op); | |
361 | ||
362 | int spi_mem_exec_op(struct spi_mem *mem, | |
363 | const struct spi_mem_op *op); | |
364 | ||
5d27a9c8 FS |
365 | const char *spi_mem_get_name(struct spi_mem *mem); |
366 | ||
aa167f3f BB |
367 | struct spi_mem_dirmap_desc * |
368 | spi_mem_dirmap_create(struct spi_mem *mem, | |
369 | const struct spi_mem_dirmap_info *info); | |
370 | void spi_mem_dirmap_destroy(struct spi_mem_dirmap_desc *desc); | |
371 | ssize_t spi_mem_dirmap_read(struct spi_mem_dirmap_desc *desc, | |
372 | u64 offs, size_t len, void *buf); | |
373 | ssize_t spi_mem_dirmap_write(struct spi_mem_dirmap_desc *desc, | |
374 | u64 offs, size_t len, const void *buf); | |
1fc1b636 BB |
375 | struct spi_mem_dirmap_desc * |
376 | devm_spi_mem_dirmap_create(struct device *dev, struct spi_mem *mem, | |
377 | const struct spi_mem_dirmap_info *info); | |
378 | void devm_spi_mem_dirmap_destroy(struct device *dev, | |
379 | struct spi_mem_dirmap_desc *desc); | |
aa167f3f | 380 | |
c955a0cc PC |
381 | int spi_mem_poll_status(struct spi_mem *mem, |
382 | const struct spi_mem_op *op, | |
383 | u16 mask, u16 match, | |
384 | unsigned long initial_delay_us, | |
385 | unsigned long polling_delay_us, | |
386 | u16 timeout_ms); | |
387 | ||
c36ff266 BB |
388 | int spi_mem_driver_register_with_owner(struct spi_mem_driver *drv, |
389 | struct module *owner); | |
390 | ||
391 | void spi_mem_driver_unregister(struct spi_mem_driver *drv); | |
392 | ||
393 | #define spi_mem_driver_register(__drv) \ | |
394 | spi_mem_driver_register_with_owner(__drv, THIS_MODULE) | |
395 | ||
396 | #define module_spi_mem_driver(__drv) \ | |
397 | module_driver(__drv, spi_mem_driver_register, \ | |
398 | spi_mem_driver_unregister) | |
399 | ||
400 | #endif /* __LINUX_SPI_MEM_H */ |