1 How to port a SPI driver to driver model 2 ======================================== 3 4 Here is a rough step-by-step guide. It is based around converting the 5 exynos SPI driver to driver model (DM) and the example code is based 6 around U-Boot v2014.10-rc2 (commit be9f643). This has been updated for 7 v2015.04. 8 9 It is quite long since it includes actual code examples. 10 11 Before driver model, SPI drivers have their own private structure which 12 contains 'struct spi_slave'. With driver model, 'struct spi_slave' still 13 exists, but now it is 'per-child data' for the SPI bus. Each child of the 14 SPI bus is a SPI slave. The information that was stored in the 15 driver-specific slave structure can now be port in private data for the 16 SPI bus. 17 18 For example, struct tegra_spi_slave looks like this: 19 20 struct tegra_spi_slave { 21 struct spi_slave slave; 22 struct tegra_spi_ctrl *ctrl; 23 }; 24 25 In this case 'slave' will be in per-child data, and 'ctrl' will be in the 26 SPI's buses private data. 27 28 29 0. How long does this take? 30 31 You should be able to complete this within 2 hours, including testing but 32 excluding preparing the patches. The API is basically the same as before 33 with only minor changes: 34 35 - methods to set speed and mode are separated out 36 - cs_info is used to get information on a chip select 37 38 39 1. Enable driver mode for SPI and SPI flash 40 41 Add these to your board config: 42 43 CONFIG_DM_SPI 44 CONFIG_DM_SPI_FLASH 45 46 47 2. Add the skeleton 48 49 Put this code at the bottom of your existing driver file: 50 51 struct spi_slave *spi_setup_slave(unsigned int busnum, unsigned int cs, 52 unsigned int max_hz, unsigned int mode) 53 { 54 return NULL; 55 } 56 57 struct spi_slave *spi_setup_slave_fdt(const void *blob, int slave_node, 58 int spi_node) 59 { 60 return NULL; 61 } 62 63 static int exynos_spi_ofdata_to_platdata(struct udevice *dev) 64 { 65 return -ENODEV; 66 } 67 68 static int exynos_spi_probe(struct udevice *dev) 69 { 70 return -ENODEV; 71 } 72 73 static int exynos_spi_remove(struct udevice *dev) 74 { 75 return -ENODEV; 76 } 77 78 static int exynos_spi_claim_bus(struct udevice *dev) 79 { 80 81 return -ENODEV; 82 } 83 84 static int exynos_spi_release_bus(struct udevice *dev) 85 { 86 87 return -ENODEV; 88 } 89 90 static int exynos_spi_xfer(struct udevice *dev, unsigned int bitlen, 91 const void *dout, void *din, unsigned long flags) 92 { 93 94 return -ENODEV; 95 } 96 97 static int exynos_spi_set_speed(struct udevice *dev, uint speed) 98 { 99 return -ENODEV; 100 } 101 102 static int exynos_spi_set_mode(struct udevice *dev, uint mode) 103 { 104 return -ENODEV; 105 } 106 107 static int exynos_cs_info(struct udevice *bus, uint cs, 108 struct spi_cs_info *info) 109 { 110 return -ENODEV; 111 } 112 113 static const struct dm_spi_ops exynos_spi_ops = { 114 .claim_bus = exynos_spi_claim_bus, 115 .release_bus = exynos_spi_release_bus, 116 .xfer = exynos_spi_xfer, 117 .set_speed = exynos_spi_set_speed, 118 .set_mode = exynos_spi_set_mode, 119 .cs_info = exynos_cs_info, 120 }; 121 122 static const struct udevice_id exynos_spi_ids[] = { 123 { .compatible = "samsung,exynos-spi" }, 124 { } 125 }; 126 127 U_BOOT_DRIVER(exynos_spi) = { 128 .name = "exynos_spi", 129 .id = UCLASS_SPI, 130 .of_match = exynos_spi_ids, 131 .ops = &exynos_spi_ops, 132 .ofdata_to_platdata = exynos_spi_ofdata_to_platdata, 133 .probe = exynos_spi_probe, 134 .remove = exynos_spi_remove, 135 }; 136 137 138 3. Replace 'exynos' in the above code with your driver name 139 140 141 4. #ifdef out all of the code in your driver except for the above 142 143 This will allow you to get it building, which means you can work 144 incrementally. Since all the methods return an error initially, there is 145 less chance that you will accidentally leave something in. 146 147 Also, even though your conversion is basically a rewrite, it might help 148 reviewers if you leave functions in the same place in the file, 149 particularly for large drivers. 150 151 152 5. Add some includes 153 154 Add these includes to your driver: 155 156 #include <dm.h> 157 #include <errno.h> 158 159 160 6. Build 161 162 At this point you should be able to build U-Boot for your board with the 163 empty SPI driver. You still have empty methods in your driver, but we will 164 write these one by one. 165 166 If you have spi_init() functions or the like that are called from your 167 board then the build will fail. Remove these calls and make a note of the 168 init that needs to be done. 169 170 171 7. Set up your platform data structure 172 173 This will hold the information your driver to operate, like its hardware 174 address or maximum frequency. 175 176 You may already have a struct like this, or you may need to create one 177 from some of the #defines or global variables in the driver. 178 179 Note that this information is not the run-time information. It should not 180 include state that changes. It should be fixed throughout the live of 181 U-Boot. Run-time information comes later. 182 183 Here is what was in the exynos spi driver: 184 185 struct spi_bus { 186 enum periph_id periph_id; 187 s32 frequency; /* Default clock frequency, -1 for none */ 188 struct exynos_spi *regs; 189 int inited; /* 1 if this bus is ready for use */ 190 int node; 191 uint deactivate_delay_us; /* Delay to wait after deactivate */ 192 }; 193 194 Of these, inited is handled by DM and node is the device tree node, which 195 DM tells you. The name is not quite right. So in this case we would use: 196 197 struct exynos_spi_platdata { 198 enum periph_id periph_id; 199 s32 frequency; /* Default clock frequency, -1 for none */ 200 struct exynos_spi *regs; 201 uint deactivate_delay_us; /* Delay to wait after deactivate */ 202 }; 203 204 205 8a. Write ofdata_to_platdata() [for device tree only] 206 207 This method will convert information in the device tree node into a C 208 structure in your driver (called platform data). If you are not using 209 device tree, go to 8b. 210 211 DM will automatically allocate the struct for us when we are using device 212 tree, but we need to tell it the size: 213 214 U_BOOT_DRIVER(spi_exynos) = { 215 ... 216 .platdata_auto_alloc_size = sizeof(struct exynos_spi_platdata), 217 218 219 Here is a sample function. It gets a pointer to the platform data and 220 fills in the fields from device tree. 221 222 static int exynos_spi_ofdata_to_platdata(struct udevice *bus) 223 { 224 struct exynos_spi_platdata *plat = bus->platdata; 225 const void *blob = gd->fdt_blob; 226 int node = dev_of_offset(bus); 227 228 plat->regs = (struct exynos_spi *)fdtdec_get_addr(blob, node, "reg"); 229 plat->periph_id = pinmux_decode_periph_id(blob, node); 230 231 if (plat->periph_id == PERIPH_ID_NONE) { 232 debug("%s: Invalid peripheral ID %d\n", __func__, 233 plat->periph_id); 234 return -FDT_ERR_NOTFOUND; 235 } 236 237 /* Use 500KHz as a suitable default */ 238 plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency", 239 500000); 240 plat->deactivate_delay_us = fdtdec_get_int(blob, node, 241 "spi-deactivate-delay", 0); 242 debug("%s: regs=%p, periph_id=%d, max-frequency=%d, deactivate_delay=%d\n", 243 __func__, plat->regs, plat->periph_id, plat->frequency, 244 plat->deactivate_delay_us); 245 246 return 0; 247 } 248 249 250 8b. Add the platform data [non-device-tree only] 251 252 Specify this data in a U_BOOT_DEVICE() declaration in your board file: 253 254 struct exynos_spi_platdata platdata_spi0 = { 255 .periph_id = ... 256 .frequency = ... 257 .regs = ... 258 .deactivate_delay_us = ... 259 }; 260 261 U_BOOT_DEVICE(board_spi0) = { 262 .name = "exynos_spi", 263 .platdata = &platdata_spi0, 264 }; 265 266 You will unfortunately need to put the struct definition into a header file 267 in this case so that your board file can use it. 268 269 270 9. Add the device private data 271 272 Most devices have some private data which they use to keep track of things 273 while active. This is the run-time information and needs to be stored in 274 a structure. There is probably a structure in the driver that includes a 275 'struct spi_slave', so you can use that. 276 277 struct exynos_spi_slave { 278 struct spi_slave slave; 279 struct exynos_spi *regs; 280 unsigned int freq; /* Default frequency */ 281 unsigned int mode; 282 enum periph_id periph_id; /* Peripheral ID for this device */ 283 unsigned int fifo_size; 284 int skip_preamble; 285 struct spi_bus *bus; /* Pointer to our SPI bus info */ 286 ulong last_transaction_us; /* Time of last transaction end */ 287 }; 288 289 290 We should rename this to make its purpose more obvious, and get rid of 291 the slave structure, so we have: 292 293 struct exynos_spi_priv { 294 struct exynos_spi *regs; 295 unsigned int freq; /* Default frequency */ 296 unsigned int mode; 297 enum periph_id periph_id; /* Peripheral ID for this device */ 298 unsigned int fifo_size; 299 int skip_preamble; 300 ulong last_transaction_us; /* Time of last transaction end */ 301 }; 302 303 304 DM can auto-allocate this also: 305 306 U_BOOT_DRIVER(spi_exynos) = { 307 ... 308 .priv_auto_alloc_size = sizeof(struct exynos_spi_priv), 309 310 311 Note that this is created before the probe method is called, and destroyed 312 after the remove method is called. It will be zeroed when the probe 313 method is called. 314 315 316 10. Add the probe() and remove() methods 317 318 Note: It's a good idea to build repeatedly as you are working, to avoid a 319 huge amount of work getting things compiling at the end. 320 321 The probe method is supposed to set up the hardware. U-Boot used to use 322 spi_setup_slave() to do this. So take a look at this function and see 323 what you can copy out to set things up. 324 325 326 static int exynos_spi_probe(struct udevice *bus) 327 { 328 struct exynos_spi_platdata *plat = dev_get_platdata(bus); 329 struct exynos_spi_priv *priv = dev_get_priv(bus); 330 331 priv->regs = plat->regs; 332 if (plat->periph_id == PERIPH_ID_SPI1 || 333 plat->periph_id == PERIPH_ID_SPI2) 334 priv->fifo_size = 64; 335 else 336 priv->fifo_size = 256; 337 338 priv->skip_preamble = 0; 339 priv->last_transaction_us = timer_get_us(); 340 priv->freq = plat->frequency; 341 priv->periph_id = plat->periph_id; 342 343 return 0; 344 } 345 346 This implementation doesn't actually touch the hardware, which is somewhat 347 unusual for a driver. In this case we will do that when the device is 348 claimed by something that wants to use the SPI bus. 349 350 For remove we could shut down the clocks, but in this case there is 351 nothing to do. DM frees any memory that it allocated, so we can just 352 remove exynos_spi_remove() and its reference in U_BOOT_DRIVER. 353 354 355 11. Implement set_speed() 356 357 This should set up clocks so that the SPI bus is running at the right 358 speed. With the old API spi_claim_bus() would normally do this and several 359 of the following functions, so let's look at that function: 360 361 int spi_claim_bus(struct spi_slave *slave) 362 { 363 struct exynos_spi_slave *spi_slave = to_exynos_spi(slave); 364 struct exynos_spi *regs = spi_slave->regs; 365 u32 reg = 0; 366 int ret; 367 368 ret = set_spi_clk(spi_slave->periph_id, 369 spi_slave->freq); 370 if (ret < 0) { 371 debug("%s: Failed to setup spi clock\n", __func__); 372 return ret; 373 } 374 375 exynos_pinmux_config(spi_slave->periph_id, PINMUX_FLAG_NONE); 376 377 spi_flush_fifo(slave); 378 379 reg = readl(®s->ch_cfg); 380 reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L); 381 382 if (spi_slave->mode & SPI_CPHA) 383 reg |= SPI_CH_CPHA_B; 384 385 if (spi_slave->mode & SPI_CPOL) 386 reg |= SPI_CH_CPOL_L; 387 388 writel(reg, ®s->ch_cfg); 389 writel(SPI_FB_DELAY_180, ®s->fb_clk); 390 391 return 0; 392 } 393 394 395 It sets up the speed, mode, pinmux, feedback delay and clears the FIFOs. 396 With DM these will happen in separate methods. 397 398 399 Here is an example for the speed part: 400 401 static int exynos_spi_set_speed(struct udevice *bus, uint speed) 402 { 403 struct exynos_spi_platdata *plat = bus->platdata; 404 struct exynos_spi_priv *priv = dev_get_priv(bus); 405 int ret; 406 407 if (speed > plat->frequency) 408 speed = plat->frequency; 409 ret = set_spi_clk(priv->periph_id, speed); 410 if (ret) 411 return ret; 412 priv->freq = speed; 413 debug("%s: regs=%p, speed=%d\n", __func__, priv->regs, priv->freq); 414 415 return 0; 416 } 417 418 419 12. Implement set_mode() 420 421 This should adjust the SPI mode (polarity, etc.). Again this code probably 422 comes from the old spi_claim_bus(). Here is an example: 423 424 425 static int exynos_spi_set_mode(struct udevice *bus, uint mode) 426 { 427 struct exynos_spi_priv *priv = dev_get_priv(bus); 428 uint32_t reg; 429 430 reg = readl(&priv->regs->ch_cfg); 431 reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L); 432 433 if (mode & SPI_CPHA) 434 reg |= SPI_CH_CPHA_B; 435 436 if (mode & SPI_CPOL) 437 reg |= SPI_CH_CPOL_L; 438 439 writel(reg, &priv->regs->ch_cfg); 440 priv->mode = mode; 441 debug("%s: regs=%p, mode=%d\n", __func__, priv->regs, priv->mode); 442 443 return 0; 444 } 445 446 447 13. Implement claim_bus() 448 449 This is where a client wants to make use of the bus, so claims it first. 450 At this point we need to make sure everything is set up ready for data 451 transfer. Note that this function is wholly internal to the driver - at 452 present the SPI uclass never calls it. 453 454 Here again we look at the old claim function and see some code that is 455 needed. It is anything unrelated to speed and mode: 456 457 static int exynos_spi_claim_bus(struct udevice *bus) 458 { 459 struct exynos_spi_priv *priv = dev_get_priv(bus); 460 461 exynos_pinmux_config(priv->periph_id, PINMUX_FLAG_NONE); 462 spi_flush_fifo(priv->regs); 463 464 writel(SPI_FB_DELAY_180, &priv->regs->fb_clk); 465 466 return 0; 467 } 468 469 The spi_flush_fifo() function is in the removed part of the code, so we 470 need to expose it again (perhaps with an #endif before it and '#if 0' 471 after it). It only needs access to priv->regs which is why we have 472 passed that in: 473 474 /** 475 * Flush spi tx, rx fifos and reset the SPI controller 476 * 477 * @param regs Pointer to SPI registers 478 */ 479 static void spi_flush_fifo(struct exynos_spi *regs) 480 { 481 clrsetbits_le32(®s->ch_cfg, SPI_CH_HS_EN, SPI_CH_RST); 482 clrbits_le32(®s->ch_cfg, SPI_CH_RST); 483 setbits_le32(®s->ch_cfg, SPI_TX_CH_ON | SPI_RX_CH_ON); 484 } 485 486 487 14. Implement release_bus() 488 489 This releases the bus - in our example the old code in spi_release_bus() 490 is a call to spi_flush_fifo, so we add: 491 492 static int exynos_spi_release_bus(struct udevice *bus) 493 { 494 struct exynos_spi_priv *priv = dev_get_priv(bus); 495 496 spi_flush_fifo(priv->regs); 497 498 return 0; 499 } 500 501 502 15. Implement xfer() 503 504 This is the final method that we need to create, and it is where all the 505 work happens. The method parameters are the same as the old spi_xfer() with 506 the addition of a 'struct udevice' so conversion is pretty easy. Start 507 by copying the contents of spi_xfer() to your new xfer() method and proceed 508 from there. 509 510 If (flags & SPI_XFER_BEGIN) is non-zero then xfer() normally calls an 511 activate function, something like this: 512 513 void spi_cs_activate(struct spi_slave *slave) 514 { 515 struct exynos_spi_slave *spi_slave = to_exynos_spi(slave); 516 517 /* If it's too soon to do another transaction, wait */ 518 if (spi_slave->bus->deactivate_delay_us && 519 spi_slave->last_transaction_us) { 520 ulong delay_us; /* The delay completed so far */ 521 delay_us = timer_get_us() - spi_slave->last_transaction_us; 522 if (delay_us < spi_slave->bus->deactivate_delay_us) 523 udelay(spi_slave->bus->deactivate_delay_us - delay_us); 524 } 525 526 clrbits_le32(&spi_slave->regs->cs_reg, SPI_SLAVE_SIG_INACT); 527 debug("Activate CS, bus %d\n", spi_slave->slave.bus); 528 spi_slave->skip_preamble = spi_slave->mode & SPI_PREAMBLE; 529 } 530 531 The new version looks like this: 532 533 static void spi_cs_activate(struct udevice *dev) 534 { 535 struct udevice *bus = dev->parent; 536 struct exynos_spi_platdata *pdata = dev_get_platdata(bus); 537 struct exynos_spi_priv *priv = dev_get_priv(bus); 538 539 /* If it's too soon to do another transaction, wait */ 540 if (pdata->deactivate_delay_us && 541 priv->last_transaction_us) { 542 ulong delay_us; /* The delay completed so far */ 543 delay_us = timer_get_us() - priv->last_transaction_us; 544 if (delay_us < pdata->deactivate_delay_us) 545 udelay(pdata->deactivate_delay_us - delay_us); 546 } 547 548 clrbits_le32(&priv->regs->cs_reg, SPI_SLAVE_SIG_INACT); 549 debug("Activate CS, bus '%s'\n", bus->name); 550 priv->skip_preamble = priv->mode & SPI_PREAMBLE; 551 } 552 553 All we have really done here is change the pointers and print the device name 554 instead of the bus number. Other local static functions can be treated in 555 the same way. 556 557 558 16. Set up the per-child data and child pre-probe function 559 560 To minimise the pain and complexity of the SPI subsystem while the driver 561 model change-over is in place, struct spi_slave is used to reference a 562 SPI bus slave, even though that slave is actually a struct udevice. In fact 563 struct spi_slave is the device's child data. We need to make sure this space 564 is available. It is possible to allocate more space that struct spi_slave 565 needs, but this is the minimum. 566 567 U_BOOT_DRIVER(exynos_spi) = { 568 ... 569 .per_child_auto_alloc_size = sizeof(struct spi_slave), 570 } 571 572 573 17. Optional: Set up cs_info() if you want it 574 575 Sometimes it is useful to know whether a SPI chip select is valid, but this 576 is not obvious from outside the driver. In this case you can provide a 577 method for cs_info() to deal with this. If you don't provide it, then the 578 device tree will be used to determine what chip selects are valid. 579 580 Return -ENODEV if the supplied chip select is invalid, or 0 if it is valid. 581 If you don't provide the cs_info() method, -ENODEV is assumed for all 582 chip selects that do not appear in the device tree. 583 584 585 18. Test it 586 587 Now that you have the code written and it compiles, try testing it using 588 the 'sf test' command. You may need to enable CONFIG_CMD_SF_TEST for your 589 board. 590 591 592 19. Prepare patches and send them to the mailing lists 593 594 You can use 'tools/patman/patman' to prepare, check and send patches for 595 your work. See the README for details. 596 597 20. A little note about SPI uclass features: 598 599 The SPI uclass keeps some information about each device 'dev' on the bus: 600 601 struct dm_spi_slave_platdata - this is device_get_parent_platdata(dev) 602 This is where the chip select number is stored, along with 603 the default bus speed and mode. It is automatically read 604 from the device tree in spi_child_post_bind(). It must not 605 be changed at run-time after being set up because platform 606 data is supposed to be immutable at run-time. 607 struct spi_slave - this is device_get_parentdata(dev) 608 Already mentioned above. It holds run-time information about 609 the device. 610 611 There are also some SPI uclass methods that get called behind the scenes: 612 613 spi_post_bind() - called when a new bus is bound 614 This scans the device tree for devices on the bus, and binds 615 each one. This in turn causes spi_child_post_bind() to be 616 called for each, which reads the device tree information 617 into the parent (per-child) platform data. 618 spi_child_post_bind() - called when a new child is bound 619 As mentioned above this reads the device tree information 620 into the per-child platform data 621 spi_child_pre_probe() - called before a new child is probed 622 This sets up the mode and speed in struct spi_slave by 623 copying it from the parent's platform data for this child. 624 It also sets the 'dev' pointer, needed to permit passing 625 'struct spi_slave' around the place without needing a 626 separate 'struct udevice' pointer. 627 628 The above housekeeping makes it easier to write your SPI driver. 629