1 How to port a SPI driver to driver model
2 ========================================
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
9 It is quite long since it includes actual code examples.
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
18 For example, struct tegra_spi_slave looks like this:
20 struct tegra_spi_slave {
21 struct spi_slave slave;
22 struct tegra_spi_ctrl *ctrl;
25 In this case 'slave' will be in per-child data, and 'ctrl' will be in the
26 SPI's buses private data.
29 0. How long does this take?
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:
35 - methods to set speed and mode are separated out
36 - cs_info is used to get information on a chip select
39 1. Enable driver mode for SPI and SPI flash
41 Add these to your board config:
49 Put this code at the bottom of your existing driver file:
51 struct spi_slave *spi_setup_slave(unsigned int busnum, unsigned int cs,
52 unsigned int max_hz, unsigned int mode)
57 struct spi_slave *spi_setup_slave_fdt(const void *blob, int slave_node,
63 static int exynos_spi_ofdata_to_platdata(struct udevice *dev)
68 static int exynos_spi_probe(struct udevice *dev)
73 static int exynos_spi_remove(struct udevice *dev)
78 static int exynos_spi_claim_bus(struct udevice *dev)
84 static int exynos_spi_release_bus(struct udevice *dev)
90 static int exynos_spi_xfer(struct udevice *dev, unsigned int bitlen,
91 const void *dout, void *din, unsigned long flags)
97 static int exynos_spi_set_speed(struct udevice *dev, uint speed)
102 static int exynos_spi_set_mode(struct udevice *dev, uint mode)
107 static int exynos_cs_info(struct udevice *bus, uint cs,
108 struct spi_cs_info *info)
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,
122 static const struct udevice_id exynos_spi_ids[] = {
123 { .compatible = "samsung,exynos-spi" },
127 U_BOOT_DRIVER(exynos_spi) = {
128 .name = "exynos_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,
138 3. Replace 'exynos' in the above code with your driver name
141 4. #ifdef out all of the code in your driver except for the above
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.
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.
154 Add these includes to your driver:
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.
166 7. Set up your platform data structure
168 This will hold the information your driver to operate, like its hardware
169 address or maximum frequency.
171 You may already have a struct like this, or you may need to create one
172 from some of the #defines or global variables in the driver.
174 Note that this information is not the run-time information. It should not
175 include state that changes. It should be fixed throughout the live of
176 U-Boot. Run-time information comes later.
178 Here is what was in the exynos spi driver:
181 enum periph_id periph_id;
182 s32 frequency; /* Default clock frequency, -1 for none */
183 struct exynos_spi *regs;
184 int inited; /* 1 if this bus is ready for use */
186 uint deactivate_delay_us; /* Delay to wait after deactivate */
189 Of these, inited is handled by DM and node is the device tree node, which
190 DM tells you. The name is not quite right. So in this case we would use:
192 struct exynos_spi_platdata {
193 enum periph_id periph_id;
194 s32 frequency; /* Default clock frequency, -1 for none */
195 struct exynos_spi *regs;
196 uint deactivate_delay_us; /* Delay to wait after deactivate */
200 8a. Write ofdata_to_platdata() [for device tree only]
202 This method will convert information in the device tree node into a C
203 structure in your driver (called platform data). If you are not using
204 device tree, go to 8b.
206 DM will automatically allocate the struct for us when we are using device
207 tree, but we need to tell it the size:
209 U_BOOT_DRIVER(spi_exynos) = {
211 .platdata_auto_alloc_size = sizeof(struct exynos_spi_platdata),
214 Here is a sample function. It gets a pointer to the platform data and
215 fills in the fields from device tree.
217 static int exynos_spi_ofdata_to_platdata(struct udevice *bus)
219 struct exynos_spi_platdata *plat = bus->platdata;
220 const void *blob = gd->fdt_blob;
221 int node = dev_of_offset(bus);
223 plat->regs = (struct exynos_spi *)fdtdec_get_addr(blob, node, "reg");
224 plat->periph_id = pinmux_decode_periph_id(blob, node);
226 if (plat->periph_id == PERIPH_ID_NONE) {
227 debug("%s: Invalid peripheral ID %d\n", __func__,
229 return -FDT_ERR_NOTFOUND;
232 /* Use 500KHz as a suitable default */
233 plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency",
235 plat->deactivate_delay_us = fdtdec_get_int(blob, node,
236 "spi-deactivate-delay", 0);
237 debug("%s: regs=%p, periph_id=%d, max-frequency=%d, deactivate_delay=%d\n",
238 __func__, plat->regs, plat->periph_id, plat->frequency,
239 plat->deactivate_delay_us);
245 8b. Add the platform data [non-device-tree only]
247 Specify this data in a U_BOOT_DEVICE() declaration in your board file:
249 struct exynos_spi_platdata platdata_spi0 = {
253 .deactivate_delay_us = ...
256 U_BOOT_DEVICE(board_spi0) = {
257 .name = "exynos_spi",
258 .platdata = &platdata_spi0,
261 You will unfortunately need to put the struct definition into a header file
262 in this case so that your board file can use it.
265 9. Add the device private data
267 Most devices have some private data which they use to keep track of things
268 while active. This is the run-time information and needs to be stored in
269 a structure. There is probably a structure in the driver that includes a
270 'struct spi_slave', so you can use that.
272 struct exynos_spi_slave {
273 struct spi_slave slave;
274 struct exynos_spi *regs;
275 unsigned int freq; /* Default frequency */
277 enum periph_id periph_id; /* Peripheral ID for this device */
278 unsigned int fifo_size;
280 struct spi_bus *bus; /* Pointer to our SPI bus info */
281 ulong last_transaction_us; /* Time of last transaction end */
285 We should rename this to make its purpose more obvious, and get rid of
286 the slave structure, so we have:
288 struct exynos_spi_priv {
289 struct exynos_spi *regs;
290 unsigned int freq; /* Default frequency */
292 enum periph_id periph_id; /* Peripheral ID for this device */
293 unsigned int fifo_size;
295 ulong last_transaction_us; /* Time of last transaction end */
299 DM can auto-allocate this also:
301 U_BOOT_DRIVER(spi_exynos) = {
303 .priv_auto_alloc_size = sizeof(struct exynos_spi_priv),
306 Note that this is created before the probe method is called, and destroyed
307 after the remove method is called. It will be zeroed when the probe
311 10. Add the probe() and remove() methods
313 Note: It's a good idea to build repeatedly as you are working, to avoid a
314 huge amount of work getting things compiling at the end.
316 The probe method is supposed to set up the hardware. U-Boot used to use
317 spi_setup_slave() to do this. So take a look at this function and see
318 what you can copy out to set things up.
321 static int exynos_spi_probe(struct udevice *bus)
323 struct exynos_spi_platdata *plat = dev_get_platdata(bus);
324 struct exynos_spi_priv *priv = dev_get_priv(bus);
326 priv->regs = plat->regs;
327 if (plat->periph_id == PERIPH_ID_SPI1 ||
328 plat->periph_id == PERIPH_ID_SPI2)
329 priv->fifo_size = 64;
331 priv->fifo_size = 256;
333 priv->skip_preamble = 0;
334 priv->last_transaction_us = timer_get_us();
335 priv->freq = plat->frequency;
336 priv->periph_id = plat->periph_id;
341 This implementation doesn't actually touch the hardware, which is somewhat
342 unusual for a driver. In this case we will do that when the device is
343 claimed by something that wants to use the SPI bus.
345 For remove we could shut down the clocks, but in this case there is
346 nothing to do. DM frees any memory that it allocated, so we can just
347 remove exynos_spi_remove() and its reference in U_BOOT_DRIVER.
350 11. Implement set_speed()
352 This should set up clocks so that the SPI bus is running at the right
353 speed. With the old API spi_claim_bus() would normally do this and several
354 of the following functions, so let's look at that function:
356 int spi_claim_bus(struct spi_slave *slave)
358 struct exynos_spi_slave *spi_slave = to_exynos_spi(slave);
359 struct exynos_spi *regs = spi_slave->regs;
363 ret = set_spi_clk(spi_slave->periph_id,
366 debug("%s: Failed to setup spi clock\n", __func__);
370 exynos_pinmux_config(spi_slave->periph_id, PINMUX_FLAG_NONE);
372 spi_flush_fifo(slave);
374 reg = readl(®s->ch_cfg);
375 reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L);
377 if (spi_slave->mode & SPI_CPHA)
378 reg |= SPI_CH_CPHA_B;
380 if (spi_slave->mode & SPI_CPOL)
381 reg |= SPI_CH_CPOL_L;
383 writel(reg, ®s->ch_cfg);
384 writel(SPI_FB_DELAY_180, ®s->fb_clk);
390 It sets up the speed, mode, pinmux, feedback delay and clears the FIFOs.
391 With DM these will happen in separate methods.
394 Here is an example for the speed part:
396 static int exynos_spi_set_speed(struct udevice *bus, uint speed)
398 struct exynos_spi_platdata *plat = bus->platdata;
399 struct exynos_spi_priv *priv = dev_get_priv(bus);
402 if (speed > plat->frequency)
403 speed = plat->frequency;
404 ret = set_spi_clk(priv->periph_id, speed);
408 debug("%s: regs=%p, speed=%d\n", __func__, priv->regs, priv->freq);
414 12. Implement set_mode()
416 This should adjust the SPI mode (polarity, etc.). Again this code probably
417 comes from the old spi_claim_bus(). Here is an example:
420 static int exynos_spi_set_mode(struct udevice *bus, uint mode)
422 struct exynos_spi_priv *priv = dev_get_priv(bus);
425 reg = readl(&priv->regs->ch_cfg);
426 reg &= ~(SPI_CH_CPHA_B | SPI_CH_CPOL_L);
429 reg |= SPI_CH_CPHA_B;
432 reg |= SPI_CH_CPOL_L;
434 writel(reg, &priv->regs->ch_cfg);
436 debug("%s: regs=%p, mode=%d\n", __func__, priv->regs, priv->mode);
442 13. Implement claim_bus()
444 This is where a client wants to make use of the bus, so claims it first.
445 At this point we need to make sure everything is set up ready for data
446 transfer. Note that this function is wholly internal to the driver - at
447 present the SPI uclass never calls it.
449 Here again we look at the old claim function and see some code that is
450 needed. It is anything unrelated to speed and mode:
452 static int exynos_spi_claim_bus(struct udevice *bus)
454 struct exynos_spi_priv *priv = dev_get_priv(bus);
456 exynos_pinmux_config(priv->periph_id, PINMUX_FLAG_NONE);
457 spi_flush_fifo(priv->regs);
459 writel(SPI_FB_DELAY_180, &priv->regs->fb_clk);
464 The spi_flush_fifo() function is in the removed part of the code, so we
465 need to expose it again (perhaps with an #endif before it and '#if 0'
466 after it). It only needs access to priv->regs which is why we have
470 * Flush spi tx, rx fifos and reset the SPI controller
472 * @param regs Pointer to SPI registers
474 static void spi_flush_fifo(struct exynos_spi *regs)
476 clrsetbits_le32(®s->ch_cfg, SPI_CH_HS_EN, SPI_CH_RST);
477 clrbits_le32(®s->ch_cfg, SPI_CH_RST);
478 setbits_le32(®s->ch_cfg, SPI_TX_CH_ON | SPI_RX_CH_ON);
482 14. Implement release_bus()
484 This releases the bus - in our example the old code in spi_release_bus()
485 is a call to spi_flush_fifo, so we add:
487 static int exynos_spi_release_bus(struct udevice *bus)
489 struct exynos_spi_priv *priv = dev_get_priv(bus);
491 spi_flush_fifo(priv->regs);
499 This is the final method that we need to create, and it is where all the
500 work happens. The method parameters are the same as the old spi_xfer() with
501 the addition of a 'struct udevice' so conversion is pretty easy. Start
502 by copying the contents of spi_xfer() to your new xfer() method and proceed
505 If (flags & SPI_XFER_BEGIN) is non-zero then xfer() normally calls an
506 activate function, something like this:
508 void spi_cs_activate(struct spi_slave *slave)
510 struct exynos_spi_slave *spi_slave = to_exynos_spi(slave);
512 /* If it's too soon to do another transaction, wait */
513 if (spi_slave->bus->deactivate_delay_us &&
514 spi_slave->last_transaction_us) {
515 ulong delay_us; /* The delay completed so far */
516 delay_us = timer_get_us() - spi_slave->last_transaction_us;
517 if (delay_us < spi_slave->bus->deactivate_delay_us)
518 udelay(spi_slave->bus->deactivate_delay_us - delay_us);
521 clrbits_le32(&spi_slave->regs->cs_reg, SPI_SLAVE_SIG_INACT);
522 debug("Activate CS, bus %d\n", spi_slave->slave.bus);
523 spi_slave->skip_preamble = spi_slave->mode & SPI_PREAMBLE;
526 The new version looks like this:
528 static void spi_cs_activate(struct udevice *dev)
530 struct udevice *bus = dev->parent;
531 struct exynos_spi_platdata *pdata = dev_get_platdata(bus);
532 struct exynos_spi_priv *priv = dev_get_priv(bus);
534 /* If it's too soon to do another transaction, wait */
535 if (pdata->deactivate_delay_us &&
536 priv->last_transaction_us) {
537 ulong delay_us; /* The delay completed so far */
538 delay_us = timer_get_us() - priv->last_transaction_us;
539 if (delay_us < pdata->deactivate_delay_us)
540 udelay(pdata->deactivate_delay_us - delay_us);
543 clrbits_le32(&priv->regs->cs_reg, SPI_SLAVE_SIG_INACT);
544 debug("Activate CS, bus '%s'\n", bus->name);
545 priv->skip_preamble = priv->mode & SPI_PREAMBLE;
548 All we have really done here is change the pointers and print the device name
549 instead of the bus number. Other local static functions can be treated in
553 16. Set up the per-child data and child pre-probe function
555 To minimise the pain and complexity of the SPI subsystem while the driver
556 model change-over is in place, struct spi_slave is used to reference a
557 SPI bus slave, even though that slave is actually a struct udevice. In fact
558 struct spi_slave is the device's child data. We need to make sure this space
559 is available. It is possible to allocate more space that struct spi_slave
560 needs, but this is the minimum.
562 U_BOOT_DRIVER(exynos_spi) = {
564 .per_child_auto_alloc_size = sizeof(struct spi_slave),
568 17. Optional: Set up cs_info() if you want it
570 Sometimes it is useful to know whether a SPI chip select is valid, but this
571 is not obvious from outside the driver. In this case you can provide a
572 method for cs_info() to deal with this. If you don't provide it, then the
573 device tree will be used to determine what chip selects are valid.
575 Return -ENODEV if the supplied chip select is invalid, or 0 if it is valid.
576 If you don't provide the cs_info() method, -ENODEV is assumed for all
577 chip selects that do not appear in the device tree.
582 Now that you have the code written and it compiles, try testing it using
583 the 'sf test' command. You may need to enable CONFIG_CMD_SF_TEST for your
587 19. Prepare patches and send them to the mailing lists
589 You can use 'tools/patman/patman' to prepare, check and send patches for
590 your work. See the README for details.
592 20. A little note about SPI uclass features:
594 The SPI uclass keeps some information about each device 'dev' on the bus:
596 struct dm_spi_slave_platdata - this is device_get_parent_platdata(dev)
597 This is where the chip select number is stored, along with
598 the default bus speed and mode. It is automatically read
599 from the device tree in spi_child_post_bind(). It must not
600 be changed at run-time after being set up because platform
601 data is supposed to be immutable at run-time.
602 struct spi_slave - this is device_get_parentdata(dev)
603 Already mentioned above. It holds run-time information about
606 There are also some SPI uclass methods that get called behind the scenes:
608 spi_post_bind() - called when a new bus is bound
609 This scans the device tree for devices on the bus, and binds
610 each one. This in turn causes spi_child_post_bind() to be
611 called for each, which reads the device tree information
612 into the parent (per-child) platform data.
613 spi_child_post_bind() - called when a new child is bound
614 As mentioned above this reads the device tree information
615 into the per-child platform data
616 spi_child_pre_probe() - called before a new child is probed
617 This sets up the mode and speed in struct spi_slave by
618 copying it from the parent's platform data for this child.
619 It also sets the 'dev' pointer, needed to permit passing
620 'struct spi_slave' around the place without needing a
621 separate 'struct udevice' pointer.
623 The above housekeeping makes it easier to write your SPI driver.