1How 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). This has been updated for
7v2015.04.
8
9It is quite long since it includes actual code examples.
10
11Before driver model, SPI drivers have their own private structure which
12contains 'struct spi_slave'. With driver model, 'struct spi_slave' still
13exists, but now it is 'per-child data' for the SPI bus. Each child of the
14SPI bus is a SPI slave. The information that was stored in the
15driver-specific slave structure can now be port in private data for the
16SPI bus.
17
18For example, struct tegra_spi_slave looks like this:
19
20struct tegra_spi_slave {
21	struct spi_slave slave;
22	struct tegra_spi_ctrl *ctrl;
23};
24
25In this case 'slave' will be in per-child data, and 'ctrl' will be in the
26SPI's buses private data.
27
28
290. How long does this take?
30
31You should be able to complete this within 2 hours, including testing but
32excluding preparing the patches. The API is basically the same as before
33with 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
391. Enable driver mode for SPI and SPI flash
40
41Add these to your board config:
42
43CONFIG_DM_SPI
44CONFIG_DM_SPI_FLASH
45
46
472. Add the skeleton
48
49Put this code at the bottom of your existing driver file:
50
51struct 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
57struct spi_slave *spi_setup_slave_fdt(const void *blob, int slave_node,
58				      int spi_node)
59{
60	return NULL;
61}
62
63static int exynos_spi_ofdata_to_platdata(struct udevice *dev)
64{
65	return -ENODEV;
66}
67
68static int exynos_spi_probe(struct udevice *dev)
69{
70	return -ENODEV;
71}
72
73static int exynos_spi_remove(struct udevice *dev)
74{
75	return -ENODEV;
76}
77
78static int exynos_spi_claim_bus(struct udevice *dev)
79{
80
81	return -ENODEV;
82}
83
84static int exynos_spi_release_bus(struct udevice *dev)
85{
86
87	return -ENODEV;
88}
89
90static 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
97static int exynos_spi_set_speed(struct udevice *dev, uint speed)
98{
99	return -ENODEV;
100}
101
102static int exynos_spi_set_mode(struct udevice *dev, uint mode)
103{
104	return -ENODEV;
105}
106
107static int exynos_cs_info(struct udevice *bus, uint cs,
108			  struct spi_cs_info *info)
109{
110	return -ENODEV;
111}
112
113static 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
122static const struct udevice_id exynos_spi_ids[] = {
123	{ .compatible = "samsung,exynos-spi" },
124	{ }
125};
126
127U_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
1383. Replace 'exynos' in the above code with your driver name
139
140
1414. #ifdef out all of the code in your driver except for the above
142
143This will allow you to get it building, which means you can work
144incrementally. Since all the methods return an error initially, there is
145less chance that you will accidentally leave something in.
146
147Also, even though your conversion is basically a rewrite, it might help
148reviewers if you leave functions in the same place in the file,
149particularly for large drivers.
150
151
1525. Add some includes
153
154Add these includes to your driver:
155
156#include <dm.h>
157#include <errno.h>
158
159
1606. Build
161
162At this point you should be able to build U-Boot for your board with the
163empty SPI driver. You still have empty methods in your driver, but we will
164write these one by one.
165
166If you have spi_init() functions or the like that are called from your
167board then the build will fail. Remove these calls and make a note of the
168init that needs to be done.
169
170
1717. Set up your platform data structure
172
173This will hold the information your driver to operate, like its hardware
174address or maximum frequency.
175
176You may already have a struct like this, or you may need to create one
177from some of the #defines or global variables in the driver.
178
179Note that this information is not the run-time information. It should not
180include state that changes. It should be fixed throughout the live of
181U-Boot. Run-time information comes later.
182
183Here is what was in the exynos spi driver:
184
185struct 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
194Of these, inited is handled by DM and node is the device tree node, which
195DM tells you. The name is not quite right. So in this case we would use:
196
197struct 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
2058a. Write ofdata_to_platdata()   [for device tree only]
206
207This method will convert information in the device tree node into a C
208structure in your driver (called platform data). If you are not using
209device tree, go to 8b.
210
211DM will automatically allocate the struct for us when we are using device
212tree, but we need to tell it the size:
213
214U_BOOT_DRIVER(spi_exynos) = {
215...
216	.platdata_auto_alloc_size = sizeof(struct exynos_spi_platdata),
217
218
219Here is a sample function. It gets a pointer to the platform data and
220fills in the fields from device tree.
221
222static 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
2508b. Add the platform data  [non-device-tree only]
251
252Specify this data in a U_BOOT_DEVICE() declaration in your board file:
253
254struct exynos_spi_platdata platdata_spi0 = {
255	.periph_id = ...
256	.frequency = ...
257	.regs = ...
258	.deactivate_delay_us = ...
259};
260
261U_BOOT_DEVICE(board_spi0) = {
262	.name = "exynos_spi",
263	.platdata = &platdata_spi0,
264};
265
266You will unfortunately need to put the struct definition into a header file
267in this case so that your board file can use it.
268
269
2709. Add the device private data
271
272Most devices have some private data which they use to keep track of things
273while active. This is the run-time information and needs to be stored in
274a structure. There is probably a structure in the driver that includes a
275'struct spi_slave', so you can use that.
276
277struct 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
290We should rename this to make its purpose more obvious, and get rid of
291the slave structure, so we have:
292
293struct 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
304DM can auto-allocate this also:
305
306U_BOOT_DRIVER(spi_exynos) = {
307...
308	.priv_auto_alloc_size = sizeof(struct exynos_spi_priv),
309
310
311Note that this is created before the probe method is called, and destroyed
312after the remove method is called. It will be zeroed when the probe
313method is called.
314
315
31610. Add the probe() and remove() methods
317
318Note: It's a good idea to build repeatedly as you are working, to avoid a
319huge amount of work getting things compiling at the end.
320
321The probe method is supposed to set up the hardware. U-Boot used to use
322spi_setup_slave() to do this. So take a look at this function and see
323what you can copy out to set things up.
324
325
326static 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
346This implementation doesn't actually touch the hardware, which is somewhat
347unusual for a driver. In this case we will do that when the device is
348claimed by something that wants to use the SPI bus.
349
350For remove we could shut down the clocks, but in this case there is
351nothing to do. DM frees any memory that it allocated, so we can just
352remove exynos_spi_remove() and its reference in U_BOOT_DRIVER.
353
354
35511. Implement set_speed()
356
357This should set up clocks so that the SPI bus is running at the right
358speed. With the old API spi_claim_bus() would normally do this and several
359of the following functions, so let's look at that function:
360
361int 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
395It sets up the speed, mode, pinmux, feedback delay and clears the FIFOs.
396With DM these will happen in separate methods.
397
398
399Here is an example for the speed part:
400
401static 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
41912. Implement set_mode()
420
421This should adjust the SPI mode (polarity, etc.). Again this code probably
422comes from the old spi_claim_bus(). Here is an example:
423
424
425static 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
44713. Implement claim_bus()
448
449This is where a client wants to make use of the bus, so claims it first.
450At this point we need to make sure everything is set up ready for data
451transfer. Note that this function is wholly internal to the driver - at
452present the SPI uclass never calls it.
453
454Here again we look at the old claim function and see some code that is
455needed. It is anything unrelated to speed and mode:
456
457static 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
469The spi_flush_fifo() function is in the removed part of the code, so we
470need to expose it again (perhaps with an #endif before it and '#if 0'
471after it). It only needs access to priv->regs which is why we have
472passed that in:
473
474/**
475 * Flush spi tx, rx fifos and reset the SPI controller
476 *
477 * @param regs	Pointer to SPI registers
478 */
479static 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
48714. Implement release_bus()
488
489This releases the bus - in our example the old code in spi_release_bus()
490is a call to spi_flush_fifo, so we add:
491
492static 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
50215. Implement xfer()
503
504This is the final method that we need to create, and it is where all the
505work happens. The method parameters are the same as the old spi_xfer() with
506the addition of a 'struct udevice' so conversion is pretty easy. Start
507by copying the contents of spi_xfer() to your new xfer() method and proceed
508from there.
509
510If (flags & SPI_XFER_BEGIN) is non-zero then xfer() normally calls an
511activate function, something like this:
512
513void 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
531The new version looks like this:
532
533static 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
553All we have really done here is change the pointers and print the device name
554instead of the bus number. Other local static functions can be treated in
555the same way.
556
557
55816. Set up the per-child data and child pre-probe function
559
560To minimise the pain and complexity of the SPI subsystem while the driver
561model change-over is in place, struct spi_slave is used to reference a
562SPI bus slave, even though that slave is actually a struct udevice. In fact
563struct spi_slave is the device's child data. We need to make sure this space
564is available. It is possible to allocate more space that struct spi_slave
565needs, but this is the minimum.
566
567U_BOOT_DRIVER(exynos_spi) = {
568...
569	.per_child_auto_alloc_size	= sizeof(struct spi_slave),
570}
571
572
57317. Optional: Set up cs_info() if you want it
574
575Sometimes it is useful to know whether a SPI chip select is valid, but this
576is not obvious from outside the driver. In this case you can provide a
577method for cs_info() to deal with this. If you don't provide it, then the
578device tree will be used to determine what chip selects are valid.
579
580Return -ENODEV if the supplied chip select is invalid, or 0 if it is valid.
581If you don't provide the cs_info() method, -ENODEV is assumed for all
582chip selects that do not appear in the device tree.
583
584
58518. Test it
586
587Now that you have the code written and it compiles, try testing it using
588the 'sf test' command. You may need to enable CONFIG_CMD_SF_TEST for your
589board.
590
591
59219. Prepare patches and send them to the mailing lists
593
594You can use 'tools/patman/patman' to prepare, check and send patches for
595your work. See the README for details.
596
59720. A little note about SPI uclass features:
598
599The 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
611There 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
628The above housekeeping makes it easier to write your SPI driver.
629