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