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