dm: Expand and complete Kconfig in drivers/
[karo-tx-uboot.git] / doc / driver-model / spi-howto.txt
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 = bus->of_offset;
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(&regs->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, &regs->ch_cfg);
389         writel(SPI_FB_DELAY_180, &regs->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(&regs->ch_cfg, SPI_CH_HS_EN, SPI_CH_RST);
482         clrbits_le32(&regs->ch_cfg, SPI_CH_RST);
483         setbits_le32(&regs->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.