blob: 3ed8c759d691d925c8c7a9be703c17bc59ca6970 [file] [log] [blame]
Simon Glass39782af2016-07-04 11:58:07 -06001Driver Model Compiled-in Device Tree / Platform Data
2====================================================
3
4
5Introduction
6------------
7
8Device tree is the standard configuration method in U-Boot. It is used to
9define what devices are in the system and provide configuration information
10to these devices.
11
12The overhead of adding device tree access to U-Boot is fairly modest,
13approximately 3KB on Thumb 2 (plus the size of the DT itself). This means
14that in most cases it is best to use device tree for configuration.
15
16However there are some very constrained environments where U-Boot needs to
17work. These include SPL with severe memory limitations. For example, some
18SoCs require a 16KB SPL image which must include a full MMC stack. In this
19case the overhead of device tree access may be too great.
20
21It is possible to create platform data manually by defining C structures
Simon Glass12696252016-07-04 11:58:42 -060022for it, and reference that data in a U_BOOT_DEVICE() declaration. This
23bypasses the use of device tree completely, effectively creating a parallel
24configuration mechanism. But it is an available option for SPL.
Simon Glass39782af2016-07-04 11:58:07 -060025
Simon Glass12696252016-07-04 11:58:42 -060026As an alternative, a new 'of-platdata' feature is provided. This converts the
Simon Glass39782af2016-07-04 11:58:07 -060027device tree contents into C code which can be compiled into the SPL binary.
28This saves the 3KB of code overhead and perhaps a few hundred more bytes due
29to more efficient storage of the data.
30
Simon Glass12696252016-07-04 11:58:42 -060031Note: Quite a bit of thought has gone into the design of this feature.
32However it still has many rough edges and comments and suggestions are
33strongly encouraged! Quite possibly there is a much better approach.
34
Simon Glass39782af2016-07-04 11:58:07 -060035
36Caveats
37-------
38
39There are many problems with this features. It should only be used when
Simon Glass12696252016-07-04 11:58:42 -060040strictly necessary. Notable problems include:
Simon Glass39782af2016-07-04 11:58:07 -060041
Simon Glass12696252016-07-04 11:58:42 -060042 - Device tree does not describe data types. But the C code must define a
43 type for each property. These are guessed using heuristics which
Simon Glass39782af2016-07-04 11:58:07 -060044 are wrong in several fairly common cases. For example an 8-byte value
45 is considered to be a 2-item integer array, and is byte-swapped. A
46 boolean value that is not present means 'false', but cannot be
47 included in the structures since there is generally no mention of it
48 in the device tree file.
49
50 - Naming of nodes and properties is automatic. This means that they follow
51 the naming in the device tree, which may result in C identifiers that
Simon Glass12696252016-07-04 11:58:42 -060052 look a bit strange.
Simon Glass39782af2016-07-04 11:58:07 -060053
54 - It is not possible to find a value given a property name. Code must use
55 the associated C member variable directly in the code. This makes
56 the code less robust in the face of device-tree changes. It also
57 makes it very unlikely that your driver code will be useful for more
58 than one SoC. Even if the code is common, each SoC will end up with
Simon Glass12696252016-07-04 11:58:42 -060059 a different C struct name, and a likely a different format for the
60 platform data.
Simon Glass39782af2016-07-04 11:58:07 -060061
62 - The platform data is provided to drivers as a C structure. The driver
63 must use the same structure to access the data. Since a driver
64 normally also supports device tree it must use #ifdef to separate
65 out this code, since the structures are only available in SPL.
66
67
68How it works
69------------
70
71The feature is enabled by CONFIG SPL_OF_PLATDATA. This is only available
72in SPL and should be tested with:
73
74 #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA)
75
76A new tool called 'dtoc' converts a device tree file either into a set of
77struct declarations, one for each compatible node, or a set of
78U_BOOT_DEVICE() declarations along with the actual platform data for each
79device. As an example, consider this MMC node:
80
81 sdmmc: dwmmc@ff0c0000 {
82 compatible = "rockchip,rk3288-dw-mshc";
83 clock-freq-min-max = <400000 150000000>;
84 clocks = <&cru HCLK_SDMMC>, <&cru SCLK_SDMMC>,
85 <&cru SCLK_SDMMC_DRV>, <&cru SCLK_SDMMC_SAMPLE>;
86 clock-names = "biu", "ciu", "ciu_drv", "ciu_sample";
87 fifo-depth = <0x100>;
88 interrupts = <GIC_SPI 32 IRQ_TYPE_LEVEL_HIGH>;
89 reg = <0xff0c0000 0x4000>;
90 bus-width = <4>;
91 cap-mmc-highspeed;
92 cap-sd-highspeed;
93 card-detect-delay = <200>;
94 disable-wp;
95 num-slots = <1>;
96 pinctrl-names = "default";
97 pinctrl-0 = <&sdmmc_clk>, <&sdmmc_cmd>, <&sdmmc_cd>, <&sdmmc_bus4>;
98 vmmc-supply = <&vcc_sd>;
99 status = "okay";
100 u-boot,dm-pre-reloc;
101 };
102
103
104Some of these properties are dropped by U-Boot under control of the
105CONFIG_OF_SPL_REMOVE_PROPS option. The rest are processed. This will produce
106the following C struct declaration:
107
108struct dtd_rockchip_rk3288_dw_mshc {
109 fdt32_t bus_width;
110 bool cap_mmc_highspeed;
111 bool cap_sd_highspeed;
112 fdt32_t card_detect_delay;
113 fdt32_t clock_freq_min_max[2];
114 struct phandle_2_cell clocks[4];
115 bool disable_wp;
116 fdt32_t fifo_depth;
117 fdt32_t interrupts[3];
118 fdt32_t num_slots;
119 fdt32_t reg[2];
Simon Glass39782af2016-07-04 11:58:07 -0600120 fdt32_t vmmc_supply;
121};
122
123and the following device declaration:
124
125static struct dtd_rockchip_rk3288_dw_mshc dtv_dwmmc_at_ff0c0000 = {
126 .fifo_depth = 0x100,
127 .cap_sd_highspeed = true,
128 .interrupts = {0x0, 0x20, 0x4},
129 .clock_freq_min_max = {0x61a80, 0x8f0d180},
130 .vmmc_supply = 0xb,
131 .num_slots = 0x1,
Simon Glass12696252016-07-04 11:58:42 -0600132 .clocks = {{&dtv_clock_controller_at_ff760000, 456},
133 {&dtv_clock_controller_at_ff760000, 68},
134 {&dtv_clock_controller_at_ff760000, 114},
135 {&dtv_clock_controller_at_ff760000, 118}},
Simon Glass39782af2016-07-04 11:58:07 -0600136 .cap_mmc_highspeed = true,
137 .disable_wp = true,
138 .bus_width = 0x4,
139 .u_boot_dm_pre_reloc = true,
140 .reg = {0xff0c0000, 0x4000},
141 .card_detect_delay = 0xc8,
142};
143U_BOOT_DEVICE(dwmmc_at_ff0c0000) = {
144 .name = "rockchip_rk3288_dw_mshc",
145 .platdata = &dtv_dwmmc_at_ff0c0000,
Simon Glass12696252016-07-04 11:58:42 -0600146 .platdata_size = sizeof(dtv_dwmmc_at_ff0c0000),
Simon Glass39782af2016-07-04 11:58:07 -0600147};
148
149The device is then instantiated at run-time and the platform data can be
150accessed using:
151
152 struct udevice *dev;
153 struct dtd_rockchip_rk3288_dw_mshc *plat = dev_get_platdata(dev);
154
155This avoids the code overhead of converting the device tree data to
156platform data in the driver. The ofdata_to_platdata() method should
157therefore do nothing in such a driver.
158
Simon Glass2cce5862017-06-13 21:10:06 -0600159Where a node has multiple compatible strings, a #define is used to make them
160equivalent, e.g.:
161
162#define dtd_rockchip_rk3299_dw_mshc dtd_rockchip_rk3288_dw_mshc
163
Simon Glass39782af2016-07-04 11:58:07 -0600164
Simon Glass12696252016-07-04 11:58:42 -0600165Converting of-platdata to a useful form
166---------------------------------------
167
168Of course it would be possible use the of-platdata directly in your driver
169whenever configuration information is required. However this meands that the
170driver will not be able to support device tree, since the of-platdata
171structure is not available when device tree is used. It would make no sense
172to use this structure if device tree were available, since the structure has
173all the limitations metioned in caveats above.
174
175Therefore it is recommended that the of-platdata structure should be used
176only in the probe() method of your driver. It cannot be used in the
177ofdata_to_platdata() method since this is not called when platform data is
178already present.
179
180
Simon Glass39782af2016-07-04 11:58:07 -0600181How to structure your driver
182----------------------------
183
184Drivers should always support device tree as an option. The of-platdata
185feature is intended as a add-on to existing drivers.
186
Simon Glass12696252016-07-04 11:58:42 -0600187Your driver should convert the platdata struct in its probe() method. The
188existing device tree decoding logic should be kept in the
189ofdata_to_platdata() method and wrapped with #if.
Simon Glass39782af2016-07-04 11:58:07 -0600190
191For example:
192
193 #include <dt-structs.h>
194
195 struct mmc_platdata {
196 #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA)
Simon Glass12696252016-07-04 11:58:42 -0600197 /* Put this first since driver model will copy the data here */
Simon Glass39782af2016-07-04 11:58:07 -0600198 struct dtd_mmc dtplat;
199 #endif
200 /*
201 * Other fields can go here, to be filled in by decoding from
Simon Glass12696252016-07-04 11:58:42 -0600202 * the device tree (or the C structures when of-platdata is used).
Simon Glass39782af2016-07-04 11:58:07 -0600203 */
204 int fifo_depth;
205 };
206
207 static int mmc_ofdata_to_platdata(struct udevice *dev)
208 {
209 #if !CONFIG_IS_ENABLED(SPL_OF_PLATDATA)
Simon Glass12696252016-07-04 11:58:42 -0600210 /* Decode the device tree data */
Simon Glass39782af2016-07-04 11:58:07 -0600211 struct mmc_platdata *plat = dev_get_platdata(dev);
212 const void *blob = gd->fdt_blob;
Simon Glasse160f7d2017-01-17 16:52:55 -0700213 int node = dev_of_offset(dev);
Simon Glass39782af2016-07-04 11:58:07 -0600214
215 plat->fifo_depth = fdtdec_get_int(blob, node, "fifo-depth", 0);
216 #endif
217
218 return 0;
219 }
220
221 static int mmc_probe(struct udevice *dev)
222 {
223 struct mmc_platdata *plat = dev_get_platdata(dev);
Simon Glass12696252016-07-04 11:58:42 -0600224
Simon Glass39782af2016-07-04 11:58:07 -0600225 #if CONFIG_IS_ENABLED(SPL_OF_PLATDATA)
Simon Glass12696252016-07-04 11:58:42 -0600226 /* Decode the of-platdata from the C structures */
Simon Glass39782af2016-07-04 11:58:07 -0600227 struct dtd_mmc *dtplat = &plat->dtplat;
228
Simon Glass12696252016-07-04 11:58:42 -0600229 plat->fifo_depth = dtplat->fifo_depth;
230 #endif
Simon Glass39782af2016-07-04 11:58:07 -0600231 /* Set up the device from the plat data */
232 writel(plat->fifo_depth, ...)
Simon Glass39782af2016-07-04 11:58:07 -0600233 }
234
235 static const struct udevice_id mmc_ids[] = {
236 { .compatible = "vendor,mmc" },
237 { }
238 };
239
240 U_BOOT_DRIVER(mmc_drv) = {
241 .name = "mmc",
242 .id = UCLASS_MMC,
243 .of_match = mmc_ids,
244 .ofdata_to_platdata = mmc_ofdata_to_platdata,
245 .probe = mmc_probe,
246 .priv_auto_alloc_size = sizeof(struct mmc_priv),
247 .platdata_auto_alloc_size = sizeof(struct mmc_platdata),
248 };
249
250
251In the case where SPL_OF_PLATDATA is enabled, platdata_auto_alloc_size is
Simon Glass12696252016-07-04 11:58:42 -0600252still used to allocate space for the platform data. This is different from
253the normal behaviour and is triggered by the use of of-platdata (strictly
254speaking it is a non-zero platdata_size which triggers this).
Simon Glass39782af2016-07-04 11:58:07 -0600255
Simon Glass12696252016-07-04 11:58:42 -0600256The of-platdata struct contents is copied from the C structure data to the
257start of the newly allocated area. In the case where device tree is used,
258the platform data is allocated, and starts zeroed. In this case the
259ofdata_to_platdata() method should still set up the platform data (and the
260of-platdata struct will not be present).
261
262SPL must use either of-platdata or device tree. Drivers cannot use both at
263the same time, but they must support device tree. Supporting of-platdata is
264optional.
265
Simon Glass39782af2016-07-04 11:58:07 -0600266The device tree becomes in accessible when CONFIG_SPL_OF_PLATDATA is enabled,
Simon Glass12696252016-07-04 11:58:42 -0600267since the device-tree access code is not compiled in. A corollary is that
268a board can only move to using of-platdata if all the drivers it uses support
269it. There would be little point in having some drivers require the device
270tree data, since then libfdt would still be needed for those drivers and
271there would be no code-size benefit.
Simon Glass39782af2016-07-04 11:58:07 -0600272
273Internals
274---------
275
276The dt-structs.h file includes the generated file
277(include/generated//dt-structs.h) if CONFIG_SPL_OF_PLATDATA is enabled.
278Otherwise (such as in U-Boot proper) these structs are not available. This
Simon Glass12696252016-07-04 11:58:42 -0600279prevents them being used inadvertently. All usage must be bracketed with
280#if CONFIG_IS_ENABLED(SPL_OF_PLATDATA).
Simon Glass39782af2016-07-04 11:58:07 -0600281
282The dt-platdata.c file contains the device declarations and is is built in
283spl/dt-platdata.c.
284
285Some phandles (thsoe that are recognised as such) are converted into
286points to platform data. This pointer can potentially be used to access the
287referenced device (by searching for the pointer value). This feature is not
288yet implemented, however.
289
290The beginnings of a libfdt Python module are provided. So far this only
291implements a subset of the features.
292
Simon Glass12696252016-07-04 11:58:42 -0600293The 'swig' tool is needed to build the libfdt Python module. If this is not
294found then the Python model is not used and a fallback is used instead, which
295makes use of fdtget.
296
297
298Credits
299-------
300
301This is an implementation of an idea by Tom Rini <trini@konsulko.com>.
Simon Glass39782af2016-07-04 11:58:07 -0600302
303
304Future work
305-----------
Simon Glass39782af2016-07-04 11:58:07 -0600306- Consider programmatically reading binding files instead of device tree
307 contents
Simon Glass39782af2016-07-04 11:58:07 -0600308- Complete the phandle feature
Simon Glass39782af2016-07-04 11:58:07 -0600309- Move to using a full Python libfdt module
310
311--
312Simon Glass <sjg@chromium.org>
Simon Glass12696252016-07-04 11:58:42 -0600313Google, Inc
Simon Glass39782af2016-07-04 11:58:07 -06003146/6/16
Simon Glass12696252016-07-04 11:58:42 -0600315Updated Independence Day 2016