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 __UBOOT_SPI_MEM_H 12#define __UBOOT_SPI_MEM_H 13 14#include <linux/errno.h> 15 16struct udevice; 17 18#define SPI_MEM_OP_CMD(__opcode, __buswidth) \ 19 { \ 20 .buswidth = __buswidth, \ 21 .opcode = __opcode, \ 22 .nbytes = 1, \ 23 } 24 25#define SPI_MEM_OP_ADDR(__nbytes, __val, __buswidth) \ 26 { \ 27 .nbytes = __nbytes, \ 28 .val = __val, \ 29 .buswidth = __buswidth, \ 30 } 31 32#define SPI_MEM_OP_NO_ADDR { } 33 34#define SPI_MEM_OP_DUMMY(__nbytes, __buswidth) \ 35 { \ 36 .nbytes = __nbytes, \ 37 .buswidth = __buswidth, \ 38 } 39 40#define SPI_MEM_OP_NO_DUMMY { } 41 42#define SPI_MEM_OP_DATA_IN(__nbytes, __buf, __buswidth) \ 43 { \ 44 .dir = SPI_MEM_DATA_IN, \ 45 .nbytes = __nbytes, \ 46 .buf.in = __buf, \ 47 .buswidth = __buswidth, \ 48 } 49 50#define SPI_MEM_OP_DATA_OUT(__nbytes, __buf, __buswidth) \ 51 { \ 52 .dir = SPI_MEM_DATA_OUT, \ 53 .nbytes = __nbytes, \ 54 .buf.out = __buf, \ 55 .buswidth = __buswidth, \ 56 } 57 58#define SPI_MEM_OP_NO_DATA { } 59 60/** 61 * enum spi_mem_data_dir - describes the direction of a SPI memory data 62 * transfer from the controller perspective 63 * @SPI_MEM_NO_DATA: no data transferred 64 * @SPI_MEM_DATA_IN: data coming from the SPI memory 65 * @SPI_MEM_DATA_OUT: data sent the SPI memory 66 */ 67enum spi_mem_data_dir { 68 SPI_MEM_NO_DATA, 69 SPI_MEM_DATA_IN, 70 SPI_MEM_DATA_OUT, 71}; 72 73/** 74 * struct spi_mem_op - describes a SPI memory operation 75 * @cmd.nbytes: number of opcode bytes (only 1 or 2 are valid). The opcode is 76 * sent MSB-first. 77 * @cmd.buswidth: number of IO lines used to transmit the command 78 * @cmd.opcode: operation opcode 79 * @cmd.dtr: whether the command opcode should be sent in DTR mode or not 80 * @addr.nbytes: number of address bytes to send. Can be zero if the operation 81 * does not need to send an address 82 * @addr.buswidth: number of IO lines used to transmit the address cycles 83 * @addr.val: address value. This value is always sent MSB first on the bus. 84 * Note that only @addr.nbytes are taken into account in this 85 * address value, so users should make sure the value fits in the 86 * assigned number of bytes. 87 * @addr.dtr: whether the address should be sent in DTR mode or not 88 * @dummy.nbytes: number of dummy bytes to send after an opcode or address. Can 89 * be zero if the operation does not require dummy bytes 90 * @dummy.buswidth: number of IO lanes used to transmit the dummy bytes 91 * @dummy.dtr: whether the dummy bytes should be sent in DTR mode or not 92 * @data.buswidth: number of IO lanes used to send/receive the data 93 * @data.dtr: whether the data should be sent in DTR mode or not 94 * @data.dir: direction of the transfer 95 * @data.buf.in: input buffer 96 * @data.buf.out: output buffer 97 */ 98struct spi_mem_op { 99 struct { 100 u8 nbytes; 101 u8 buswidth; 102 u8 dtr : 1; 103 u16 opcode; 104 } cmd; 105 106 struct { 107 u8 nbytes; 108 u8 buswidth; 109 u8 dtr : 1; 110 u64 val; 111 } addr; 112 113 struct { 114 u8 nbytes; 115 u8 buswidth; 116 u8 dtr : 1; 117 } dummy; 118 119 struct { 120 u8 buswidth; 121 u8 dtr : 1; 122 enum spi_mem_data_dir dir; 123 unsigned int nbytes; 124 /* buf.{in,out} must be DMA-able. */ 125 union { 126 void *in; 127 const void *out; 128 } buf; 129 } data; 130}; 131 132#define SPI_MEM_OP(__cmd, __addr, __dummy, __data) \ 133 { \ 134 .cmd = __cmd, \ 135 .addr = __addr, \ 136 .dummy = __dummy, \ 137 .data = __data, \ 138 } 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 * This information is 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 */ 152struct 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 */ 175struct spi_mem_dirmap_desc { 176 struct spi_slave *slave; 177 struct spi_mem_dirmap_info info; 178 unsigned int nodirmap; 179 void *priv; 180}; 181 182#ifndef __UBOOT__ 183/** 184 * struct spi_mem - describes a SPI memory device 185 * @spi: the underlying SPI device 186 * @drvpriv: spi_mem_driver private data 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 */ 194struct spi_mem { 195 struct udevice *dev; 196 void *drvpriv; 197}; 198 199/** 200 * struct spi_mem_set_drvdata() - attach driver private data to a SPI mem 201 * device 202 * @mem: memory device 203 * @data: data to attach to the memory device 204 */ 205static inline void spi_mem_set_drvdata(struct spi_mem *mem, void *data) 206{ 207 mem->drvpriv = data; 208} 209 210/** 211 * struct spi_mem_get_drvdata() - get driver private data attached to a SPI mem 212 * device 213 * @mem: memory device 214 * 215 * Return: the data attached to the mem device. 216 */ 217static inline void *spi_mem_get_drvdata(struct spi_mem *mem) 218{ 219 return mem->drvpriv; 220} 221#endif /* __UBOOT__ */ 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 230 * @dirmap_create: create a direct mapping descriptor that can later be used to 231 * access the memory device. This method is optional 232 * @dirmap_destroy: destroy a memory descriptor previous created by 233 * ->dirmap_create() 234 * @dirmap_read: read data from the memory device using the direct mapping 235 * created by ->dirmap_create(). The function can return less 236 * data than requested (for example when the request is crossing 237 * the currently mapped area), and the caller of 238 * spi_mem_dirmap_read() is responsible for calling it again in 239 * this case. 240 * @dirmap_write: write data to the memory device using the direct mapping 241 * created by ->dirmap_create(). The function can return less 242 * data than requested (for example when the request is crossing 243 * the currently mapped area), and the caller of 244 * spi_mem_dirmap_write() is responsible for calling it again in 245 * this case. 246 * 247 * This interface should be implemented by SPI controllers providing an 248 * high-level interface to execute SPI memory operation, which is usually the 249 * case for QSPI controllers. 250 * 251 * Note on ->dirmap_{read,write}(): drivers should avoid accessing the direct 252 * mapping from the CPU because doing that can stall the CPU waiting for the 253 * SPI mem transaction to finish, and this will make real-time maintainers 254 * unhappy and might make your system less reactive. Instead, drivers should 255 * use DMA to access this direct mapping. 256 */ 257struct spi_controller_mem_ops { 258 int (*adjust_op_size)(struct spi_slave *slave, struct spi_mem_op *op); 259 bool (*supports_op)(struct spi_slave *slave, 260 const struct spi_mem_op *op); 261 int (*exec_op)(struct spi_slave *slave, 262 const struct spi_mem_op *op); 263 int (*dirmap_create)(struct spi_mem_dirmap_desc *desc); 264 void (*dirmap_destroy)(struct spi_mem_dirmap_desc *desc); 265 ssize_t (*dirmap_read)(struct spi_mem_dirmap_desc *desc, 266 u64 offs, size_t len, void *buf); 267 ssize_t (*dirmap_write)(struct spi_mem_dirmap_desc *desc, 268 u64 offs, size_t len, const void *buf); 269}; 270 271#ifndef __UBOOT__ 272/** 273 * struct spi_mem_driver - SPI memory driver 274 * @spidrv: inherit from a SPI driver 275 * @probe: probe a SPI memory. Usually where detection/initialization takes 276 * place 277 * @remove: remove a SPI memory 278 * @shutdown: take appropriate action when the system is shutdown 279 * 280 * This is just a thin wrapper around a spi_driver. The core takes care of 281 * allocating the spi_mem object and forwarding the probe/remove/shutdown 282 * request to the spi_mem_driver. The reason we use this wrapper is because 283 * we might have to stuff more information into the spi_mem struct to let 284 * SPI controllers know more about the SPI memory they interact with, and 285 * having this intermediate layer allows us to do that without adding more 286 * useless fields to the spi_device object. 287 */ 288struct spi_mem_driver { 289 struct spi_driver spidrv; 290 int (*probe)(struct spi_mem *mem); 291 int (*remove)(struct spi_mem *mem); 292 void (*shutdown)(struct spi_mem *mem); 293}; 294 295#if IS_ENABLED(CONFIG_SPI_MEM) 296int spi_controller_dma_map_mem_op_data(struct spi_controller *ctlr, 297 const struct spi_mem_op *op, 298 struct sg_table *sg); 299 300void spi_controller_dma_unmap_mem_op_data(struct spi_controller *ctlr, 301 const struct spi_mem_op *op, 302 struct sg_table *sg); 303#else 304static inline int 305spi_controller_dma_map_mem_op_data(struct spi_controller *ctlr, 306 const struct spi_mem_op *op, 307 struct sg_table *sg) 308{ 309 return -ENOSYS; 310} 311 312static inline void 313spi_controller_dma_unmap_mem_op_data(struct spi_controller *ctlr, 314 const struct spi_mem_op *op, 315 struct sg_table *sg) 316{ 317} 318#endif /* CONFIG_SPI_MEM */ 319#endif /* __UBOOT__ */ 320 321int spi_mem_adjust_op_size(struct spi_slave *slave, struct spi_mem_op *op); 322 323bool spi_mem_supports_op(struct spi_slave *slave, const struct spi_mem_op *op); 324bool spi_mem_dtr_supports_op(struct spi_slave *slave, 325 const struct spi_mem_op *op); 326 327bool spi_mem_default_supports_op(struct spi_slave *slave, 328 const struct spi_mem_op *op); 329 330int spi_mem_exec_op(struct spi_slave *slave, const struct spi_mem_op *op); 331 332bool spi_mem_default_supports_op(struct spi_slave *mem, 333 const struct spi_mem_op *op); 334 335struct spi_mem_dirmap_desc * 336spi_mem_dirmap_create(struct spi_slave *mem, 337 const struct spi_mem_dirmap_info *info); 338void spi_mem_dirmap_destroy(struct spi_mem_dirmap_desc *desc); 339ssize_t spi_mem_dirmap_read(struct spi_mem_dirmap_desc *desc, 340 u64 offs, size_t len, void *buf); 341ssize_t spi_mem_dirmap_write(struct spi_mem_dirmap_desc *desc, 342 u64 offs, size_t len, const void *buf); 343 344#ifndef __UBOOT__ 345int spi_mem_driver_register_with_owner(struct spi_mem_driver *drv, 346 struct module *owner); 347 348void spi_mem_driver_unregister(struct spi_mem_driver *drv); 349 350#define spi_mem_driver_register(__drv) \ 351 spi_mem_driver_register_with_owner(__drv, THIS_MODULE) 352 353#define module_spi_mem_driver(__drv) \ 354 module_driver(__drv, spi_mem_driver_register, \ 355 spi_mem_driver_unregister) 356#endif 357 358#endif /* __LINUX_SPI_MEM_H */ 359