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_DATA_IN: data coming from the SPI memory 61 * @SPI_MEM_DATA_OUT: data sent the SPI memory 62 */ 63 enum spi_mem_data_dir { 64 SPI_MEM_DATA_IN, 65 SPI_MEM_DATA_OUT, 66 }; 67 68 /** 69 * struct spi_mem_op - describes a SPI memory operation 70 * @cmd.buswidth: number of IO lines used to transmit the command 71 * @cmd.opcode: operation opcode 72 * @addr.nbytes: number of address bytes to send. Can be zero if the operation 73 * does not need to send an address 74 * @addr.buswidth: number of IO lines used to transmit the address cycles 75 * @addr.val: address value. This value is always sent MSB first on the bus. 76 * Note that only @addr.nbytes are taken into account in this 77 * address value, so users should make sure the value fits in the 78 * assigned number of bytes. 79 * @dummy.nbytes: number of dummy bytes to send after an opcode or address. Can 80 * be zero if the operation does not require dummy bytes 81 * @dummy.buswidth: number of IO lanes used to transmit the dummy bytes 82 * @data.buswidth: number of IO lanes used to send/receive the data 83 * @data.dir: direction of the transfer 84 * @data.nbytes: number of data bytes to send/receive. Can be zero if the 85 * operation does not involve transferring data 86 * @data.buf.in: input buffer (must be DMA-able) 87 * @data.buf.out: output buffer (must be DMA-able) 88 */ 89 struct spi_mem_op { 90 struct { 91 u8 buswidth; 92 u8 opcode; 93 } cmd; 94 95 struct { 96 u8 nbytes; 97 u8 buswidth; 98 u64 val; 99 } addr; 100 101 struct { 102 u8 nbytes; 103 u8 buswidth; 104 } dummy; 105 106 struct { 107 u8 buswidth; 108 enum spi_mem_data_dir dir; 109 unsigned int nbytes; 110 union { 111 void *in; 112 const void *out; 113 } buf; 114 } data; 115 }; 116 117 #define SPI_MEM_OP(__cmd, __addr, __dummy, __data) \ 118 { \ 119 .cmd = __cmd, \ 120 .addr = __addr, \ 121 .dummy = __dummy, \ 122 .data = __data, \ 123 } 124 125 /** 126 * struct spi_mem - describes a SPI memory device 127 * @spi: the underlying SPI device 128 * @drvpriv: spi_mem_driver private data 129 * @name: name of the SPI memory device 130 * 131 * Extra information that describe the SPI memory device and may be needed by 132 * the controller to properly handle this device should be placed here. 133 * 134 * One example would be the device size since some controller expose their SPI 135 * mem devices through a io-mapped region. 136 */ 137 struct spi_mem { 138 struct spi_device *spi; 139 void *drvpriv; 140 const char *name; 141 }; 142 143 /** 144 * struct spi_mem_set_drvdata() - attach driver private data to a SPI mem 145 * device 146 * @mem: memory device 147 * @data: data to attach to the memory device 148 */ 149 static inline void spi_mem_set_drvdata(struct spi_mem *mem, void *data) 150 { 151 mem->drvpriv = data; 152 } 153 154 /** 155 * struct spi_mem_get_drvdata() - get driver private data attached to a SPI mem 156 * device 157 * @mem: memory device 158 * 159 * Return: the data attached to the mem device. 160 */ 161 static inline void *spi_mem_get_drvdata(struct spi_mem *mem) 162 { 163 return mem->drvpriv; 164 } 165 166 /** 167 * struct spi_controller_mem_ops - SPI memory operations 168 * @adjust_op_size: shrink the data xfer of an operation to match controller's 169 * limitations (can be alignment of max RX/TX size 170 * limitations) 171 * @supports_op: check if an operation is supported by the controller 172 * @exec_op: execute a SPI memory operation 173 * @get_name: get a custom name for the SPI mem device from the controller. 174 * This might be needed if the controller driver has been ported 175 * to use the SPI mem layer and a custom name is used to keep 176 * mtdparts compatible. 177 * Note that if the implementation of this function allocates memory 178 * dynamically, then it should do so with devm_xxx(), as we don't 179 * have a ->free_name() function. 180 * 181 * This interface should be implemented by SPI controllers providing an 182 * high-level interface to execute SPI memory operation, which is usually the 183 * case for QSPI controllers. 184 */ 185 struct spi_controller_mem_ops { 186 int (*adjust_op_size)(struct spi_mem *mem, struct spi_mem_op *op); 187 bool (*supports_op)(struct spi_mem *mem, 188 const struct spi_mem_op *op); 189 int (*exec_op)(struct spi_mem *mem, 190 const struct spi_mem_op *op); 191 const char *(*get_name)(struct spi_mem *mem); 192 }; 193 194 /** 195 * struct spi_mem_driver - SPI memory driver 196 * @spidrv: inherit from a SPI driver 197 * @probe: probe a SPI memory. Usually where detection/initialization takes 198 * place 199 * @remove: remove a SPI memory 200 * @shutdown: take appropriate action when the system is shutdown 201 * 202 * This is just a thin wrapper around a spi_driver. The core takes care of 203 * allocating the spi_mem object and forwarding the probe/remove/shutdown 204 * request to the spi_mem_driver. The reason we use this wrapper is because 205 * we might have to stuff more information into the spi_mem struct to let 206 * SPI controllers know more about the SPI memory they interact with, and 207 * having this intermediate layer allows us to do that without adding more 208 * useless fields to the spi_device object. 209 */ 210 struct spi_mem_driver { 211 struct spi_driver spidrv; 212 int (*probe)(struct spi_mem *mem); 213 int (*remove)(struct spi_mem *mem); 214 void (*shutdown)(struct spi_mem *mem); 215 }; 216 217 #if IS_ENABLED(CONFIG_SPI_MEM) 218 int spi_controller_dma_map_mem_op_data(struct spi_controller *ctlr, 219 const struct spi_mem_op *op, 220 struct sg_table *sg); 221 222 void spi_controller_dma_unmap_mem_op_data(struct spi_controller *ctlr, 223 const struct spi_mem_op *op, 224 struct sg_table *sg); 225 #else 226 static inline int 227 spi_controller_dma_map_mem_op_data(struct spi_controller *ctlr, 228 const struct spi_mem_op *op, 229 struct sg_table *sg) 230 { 231 return -ENOTSUPP; 232 } 233 234 static inline void 235 spi_controller_dma_unmap_mem_op_data(struct spi_controller *ctlr, 236 const struct spi_mem_op *op, 237 struct sg_table *sg) 238 { 239 } 240 #endif /* CONFIG_SPI_MEM */ 241 242 int spi_mem_adjust_op_size(struct spi_mem *mem, struct spi_mem_op *op); 243 244 bool spi_mem_supports_op(struct spi_mem *mem, 245 const struct spi_mem_op *op); 246 247 int spi_mem_exec_op(struct spi_mem *mem, 248 const struct spi_mem_op *op); 249 250 const char *spi_mem_get_name(struct spi_mem *mem); 251 252 int spi_mem_driver_register_with_owner(struct spi_mem_driver *drv, 253 struct module *owner); 254 255 void spi_mem_driver_unregister(struct spi_mem_driver *drv); 256 257 #define spi_mem_driver_register(__drv) \ 258 spi_mem_driver_register_with_owner(__drv, THIS_MODULE) 259 260 #define module_spi_mem_driver(__drv) \ 261 module_driver(__drv, spi_mem_driver_register, \ 262 spi_mem_driver_unregister) 263 264 #endif /* __LINUX_SPI_MEM_H */ 265