~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/include/linux/spi/spi-mem.h

Version: ~ [ linux-5.9.1 ] ~ [ linux-5.8.16 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.72 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.152 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.202 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.240 ] ~ [ linux-4.8.17 ] ~ [ linux-4.7.10 ] ~ [ linux-4.6.7 ] ~ [ linux-4.5.7 ] ~ [ linux-4.4.240 ] ~ [ linux-4.3.6 ] ~ [ linux-4.2.8 ] ~ [ linux-4.1.52 ] ~ [ linux-4.0.9 ] ~ [ linux-3.19.8 ] ~ [ linux-3.18.140 ] ~ [ linux-3.17.8 ] ~ [ linux-3.16.85 ] ~ [ linux-3.15.10 ] ~ [ linux-3.14.79 ] ~ [ linux-3.13.11 ] ~ [ linux-3.12.74 ] ~ [ linux-3.11.10 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.5 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

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

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | Wiki (Japanese) | Wiki (English) | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

osdn.jp