1 // SPDX-License-Identifier: GPL-2.0-or-later 2 /* 3 * polling/bitbanging SPI master controller driver utilities 4 */ 5 6 #include <linux/spinlock.h> 7 #include <linux/workqueue.h> 8 #include <linux/interrupt.h> 9 #include <linux/module.h> 10 #include <linux/delay.h> 11 #include <linux/errno.h> 12 #include <linux/platform_device.h> 13 #include <linux/slab.h> 14 15 #include <linux/spi/spi.h> 16 #include <linux/spi/spi_bitbang.h> 17 18 #define SPI_BITBANG_CS_DELAY 100 19 20 21 /*----------------------------------------------------------------------*/ 22 23 /* 24 * FIRST PART (OPTIONAL): word-at-a-time spi_transfer support. 25 * Use this for GPIO or shift-register level hardware APIs. 26 * 27 * spi_bitbang_cs is in spi_device->controller_state, which is unavailable 28 * to glue code. These bitbang setup() and cleanup() routines are always 29 * used, though maybe they're called from controller-aware code. 30 * 31 * chipselect() and friends may use spi_device->controller_data and 32 * controller registers as appropriate. 33 * 34 * 35 * NOTE: SPI controller pins can often be used as GPIO pins instead, 36 * which means you could use a bitbang driver either to get hardware 37 * working quickly, or testing for differences that aren't speed related. 38 */ 39 40 struct spi_bitbang_cs { 41 unsigned nsecs; /* (clock cycle time)/2 */ 42 u32 (*txrx_word)(struct spi_device *spi, unsigned nsecs, 43 u32 word, u8 bits, unsigned flags); 44 unsigned (*txrx_bufs)(struct spi_device *, 45 u32 (*txrx_word)( 46 struct spi_device *spi, 47 unsigned nsecs, 48 u32 word, u8 bits, 49 unsigned flags), 50 unsigned, struct spi_transfer *, 51 unsigned); 52 }; 53 54 static unsigned bitbang_txrx_8( 55 struct spi_device *spi, 56 u32 (*txrx_word)(struct spi_device *spi, 57 unsigned nsecs, 58 u32 word, u8 bits, 59 unsigned flags), 60 unsigned ns, 61 struct spi_transfer *t, 62 unsigned flags 63 ) { 64 unsigned bits = t->bits_per_word; 65 unsigned count = t->len; 66 const u8 *tx = t->tx_buf; 67 u8 *rx = t->rx_buf; 68 69 while (likely(count > 0)) { 70 u8 word = 0; 71 72 if (tx) 73 word = *tx++; 74 word = txrx_word(spi, ns, word, bits, flags); 75 if (rx) 76 *rx++ = word; 77 count -= 1; 78 } 79 return t->len - count; 80 } 81 82 static unsigned bitbang_txrx_16( 83 struct spi_device *spi, 84 u32 (*txrx_word)(struct spi_device *spi, 85 unsigned nsecs, 86 u32 word, u8 bits, 87 unsigned flags), 88 unsigned ns, 89 struct spi_transfer *t, 90 unsigned flags 91 ) { 92 unsigned bits = t->bits_per_word; 93 unsigned count = t->len; 94 const u16 *tx = t->tx_buf; 95 u16 *rx = t->rx_buf; 96 97 while (likely(count > 1)) { 98 u16 word = 0; 99 100 if (tx) 101 word = *tx++; 102 word = txrx_word(spi, ns, word, bits, flags); 103 if (rx) 104 *rx++ = word; 105 count -= 2; 106 } 107 return t->len - count; 108 } 109 110 static unsigned bitbang_txrx_32( 111 struct spi_device *spi, 112 u32 (*txrx_word)(struct spi_device *spi, 113 unsigned nsecs, 114 u32 word, u8 bits, 115 unsigned flags), 116 unsigned ns, 117 struct spi_transfer *t, 118 unsigned flags 119 ) { 120 unsigned bits = t->bits_per_word; 121 unsigned count = t->len; 122 const u32 *tx = t->tx_buf; 123 u32 *rx = t->rx_buf; 124 125 while (likely(count > 3)) { 126 u32 word = 0; 127 128 if (tx) 129 word = *tx++; 130 word = txrx_word(spi, ns, word, bits, flags); 131 if (rx) 132 *rx++ = word; 133 count -= 4; 134 } 135 return t->len - count; 136 } 137 138 int spi_bitbang_setup_transfer(struct spi_device *spi, struct spi_transfer *t) 139 { 140 struct spi_bitbang_cs *cs = spi->controller_state; 141 u8 bits_per_word; 142 u32 hz; 143 144 if (t) { 145 bits_per_word = t->bits_per_word; 146 hz = t->speed_hz; 147 } else { 148 bits_per_word = 0; 149 hz = 0; 150 } 151 152 /* spi_transfer level calls that work per-word */ 153 if (!bits_per_word) 154 bits_per_word = spi->bits_per_word; 155 if (bits_per_word <= 8) 156 cs->txrx_bufs = bitbang_txrx_8; 157 else if (bits_per_word <= 16) 158 cs->txrx_bufs = bitbang_txrx_16; 159 else if (bits_per_word <= 32) 160 cs->txrx_bufs = bitbang_txrx_32; 161 else 162 return -EINVAL; 163 164 /* nsecs = (clock period)/2 */ 165 if (!hz) 166 hz = spi->max_speed_hz; 167 if (hz) { 168 cs->nsecs = (1000000000/2) / hz; 169 if (cs->nsecs > (MAX_UDELAY_MS * 1000 * 1000)) 170 return -EINVAL; 171 } 172 173 return 0; 174 } 175 EXPORT_SYMBOL_GPL(spi_bitbang_setup_transfer); 176 177 /** 178 * spi_bitbang_setup - default setup for per-word I/O loops 179 */ 180 int spi_bitbang_setup(struct spi_device *spi) 181 { 182 struct spi_bitbang_cs *cs = spi->controller_state; 183 struct spi_bitbang *bitbang; 184 185 bitbang = spi_master_get_devdata(spi->master); 186 187 if (!cs) { 188 cs = kzalloc(sizeof(*cs), GFP_KERNEL); 189 if (!cs) 190 return -ENOMEM; 191 spi->controller_state = cs; 192 } 193 194 /* per-word shift register access, in hardware or bitbanging */ 195 cs->txrx_word = bitbang->txrx_word[spi->mode & (SPI_CPOL|SPI_CPHA)]; 196 if (!cs->txrx_word) 197 return -EINVAL; 198 199 if (bitbang->setup_transfer) { 200 int retval = bitbang->setup_transfer(spi, NULL); 201 if (retval < 0) 202 return retval; 203 } 204 205 dev_dbg(&spi->dev, "%s, %u nsec/bit\n", __func__, 2 * cs->nsecs); 206 207 return 0; 208 } 209 EXPORT_SYMBOL_GPL(spi_bitbang_setup); 210 211 /** 212 * spi_bitbang_cleanup - default cleanup for per-word I/O loops 213 */ 214 void spi_bitbang_cleanup(struct spi_device *spi) 215 { 216 kfree(spi->controller_state); 217 } 218 EXPORT_SYMBOL_GPL(spi_bitbang_cleanup); 219 220 static int spi_bitbang_bufs(struct spi_device *spi, struct spi_transfer *t) 221 { 222 struct spi_bitbang_cs *cs = spi->controller_state; 223 unsigned nsecs = cs->nsecs; 224 struct spi_bitbang *bitbang; 225 226 bitbang = spi_master_get_devdata(spi->master); 227 if (bitbang->set_line_direction) { 228 int err; 229 230 err = bitbang->set_line_direction(spi, !!(t->tx_buf)); 231 if (err < 0) 232 return err; 233 } 234 235 if (spi->mode & SPI_3WIRE) { 236 unsigned flags; 237 238 flags = t->tx_buf ? SPI_MASTER_NO_RX : SPI_MASTER_NO_TX; 239 return cs->txrx_bufs(spi, cs->txrx_word, nsecs, t, flags); 240 } 241 return cs->txrx_bufs(spi, cs->txrx_word, nsecs, t, 0); 242 } 243 244 /*----------------------------------------------------------------------*/ 245 246 /* 247 * SECOND PART ... simple transfer queue runner. 248 * 249 * This costs a task context per controller, running the queue by 250 * performing each transfer in sequence. Smarter hardware can queue 251 * several DMA transfers at once, and process several controller queues 252 * in parallel; this driver doesn't match such hardware very well. 253 * 254 * Drivers can provide word-at-a-time i/o primitives, or provide 255 * transfer-at-a-time ones to leverage dma or fifo hardware. 256 */ 257 258 static int spi_bitbang_prepare_hardware(struct spi_master *spi) 259 { 260 struct spi_bitbang *bitbang; 261 262 bitbang = spi_master_get_devdata(spi); 263 264 mutex_lock(&bitbang->lock); 265 bitbang->busy = 1; 266 mutex_unlock(&bitbang->lock); 267 268 return 0; 269 } 270 271 static int spi_bitbang_transfer_one(struct spi_master *master, 272 struct spi_device *spi, 273 struct spi_transfer *transfer) 274 { 275 struct spi_bitbang *bitbang = spi_master_get_devdata(master); 276 int status = 0; 277 278 if (bitbang->setup_transfer) { 279 status = bitbang->setup_transfer(spi, transfer); 280 if (status < 0) 281 goto out; 282 } 283 284 if (transfer->len) 285 status = bitbang->txrx_bufs(spi, transfer); 286 287 if (status == transfer->len) 288 status = 0; 289 else if (status >= 0) 290 status = -EREMOTEIO; 291 292 out: 293 spi_finalize_current_transfer(master); 294 295 return status; 296 } 297 298 static int spi_bitbang_unprepare_hardware(struct spi_master *spi) 299 { 300 struct spi_bitbang *bitbang; 301 302 bitbang = spi_master_get_devdata(spi); 303 304 mutex_lock(&bitbang->lock); 305 bitbang->busy = 0; 306 mutex_unlock(&bitbang->lock); 307 308 return 0; 309 } 310 311 static void spi_bitbang_set_cs(struct spi_device *spi, bool enable) 312 { 313 struct spi_bitbang *bitbang = spi_master_get_devdata(spi->master); 314 315 /* SPI core provides CS high / low, but bitbang driver 316 * expects CS active 317 * spi device driver takes care of handling SPI_CS_HIGH 318 */ 319 enable = (!!(spi->mode & SPI_CS_HIGH) == enable); 320 321 ndelay(SPI_BITBANG_CS_DELAY); 322 bitbang->chipselect(spi, enable ? BITBANG_CS_ACTIVE : 323 BITBANG_CS_INACTIVE); 324 ndelay(SPI_BITBANG_CS_DELAY); 325 } 326 327 /*----------------------------------------------------------------------*/ 328 329 int spi_bitbang_init(struct spi_bitbang *bitbang) 330 { 331 struct spi_master *master = bitbang->master; 332 bool custom_cs; 333 334 if (!master) 335 return -EINVAL; 336 /* 337 * We only need the chipselect callback if we are actually using it. 338 * If we just use GPIO descriptors, it is surplus. If the 339 * SPI_MASTER_GPIO_SS flag is set, we always need to call the 340 * driver-specific chipselect routine. 341 */ 342 custom_cs = (!master->use_gpio_descriptors || 343 (master->flags & SPI_MASTER_GPIO_SS)); 344 345 if (custom_cs && !bitbang->chipselect) 346 return -EINVAL; 347 348 mutex_init(&bitbang->lock); 349 350 if (!master->mode_bits) 351 master->mode_bits = SPI_CPOL | SPI_CPHA | bitbang->flags; 352 353 if (master->transfer || master->transfer_one_message) 354 return -EINVAL; 355 356 master->prepare_transfer_hardware = spi_bitbang_prepare_hardware; 357 master->unprepare_transfer_hardware = spi_bitbang_unprepare_hardware; 358 master->transfer_one = spi_bitbang_transfer_one; 359 /* 360 * When using GPIO descriptors, the ->set_cs() callback doesn't even 361 * get called unless SPI_MASTER_GPIO_SS is set. 362 */ 363 if (custom_cs) 364 master->set_cs = spi_bitbang_set_cs; 365 366 if (!bitbang->txrx_bufs) { 367 bitbang->use_dma = 0; 368 bitbang->txrx_bufs = spi_bitbang_bufs; 369 if (!master->setup) { 370 if (!bitbang->setup_transfer) 371 bitbang->setup_transfer = 372 spi_bitbang_setup_transfer; 373 master->setup = spi_bitbang_setup; 374 master->cleanup = spi_bitbang_cleanup; 375 } 376 } 377 378 return 0; 379 } 380 EXPORT_SYMBOL_GPL(spi_bitbang_init); 381 382 /** 383 * spi_bitbang_start - start up a polled/bitbanging SPI master driver 384 * @bitbang: driver handle 385 * 386 * Caller should have zero-initialized all parts of the structure, and then 387 * provided callbacks for chip selection and I/O loops. If the master has 388 * a transfer method, its final step should call spi_bitbang_transfer; or, 389 * that's the default if the transfer routine is not initialized. It should 390 * also set up the bus number and number of chipselects. 391 * 392 * For i/o loops, provide callbacks either per-word (for bitbanging, or for 393 * hardware that basically exposes a shift register) or per-spi_transfer 394 * (which takes better advantage of hardware like fifos or DMA engines). 395 * 396 * Drivers using per-word I/O loops should use (or call) spi_bitbang_setup, 397 * spi_bitbang_cleanup and spi_bitbang_setup_transfer to handle those spi 398 * master methods. Those methods are the defaults if the bitbang->txrx_bufs 399 * routine isn't initialized. 400 * 401 * This routine registers the spi_master, which will process requests in a 402 * dedicated task, keeping IRQs unblocked most of the time. To stop 403 * processing those requests, call spi_bitbang_stop(). 404 * 405 * On success, this routine will take a reference to master. The caller is 406 * responsible for calling spi_bitbang_stop() to decrement the reference and 407 * spi_master_put() as counterpart of spi_alloc_master() to prevent a memory 408 * leak. 409 */ 410 int spi_bitbang_start(struct spi_bitbang *bitbang) 411 { 412 struct spi_master *master = bitbang->master; 413 int ret; 414 415 ret = spi_bitbang_init(bitbang); 416 if (ret) 417 return ret; 418 419 /* driver may get busy before register() returns, especially 420 * if someone registered boardinfo for devices 421 */ 422 ret = spi_register_master(spi_master_get(master)); 423 if (ret) 424 spi_master_put(master); 425 426 return ret; 427 } 428 EXPORT_SYMBOL_GPL(spi_bitbang_start); 429 430 /** 431 * spi_bitbang_stop - stops the task providing spi communication 432 */ 433 void spi_bitbang_stop(struct spi_bitbang *bitbang) 434 { 435 spi_unregister_master(bitbang->master); 436 } 437 EXPORT_SYMBOL_GPL(spi_bitbang_stop); 438 439 MODULE_LICENSE("GPL"); 440 441