Re: [U-Boot] [PATCH v2] dm: core: Add livetree documentation

[sjg]

On 08/31/2017 02:00 PM, Simon Glass wrote:
> On 31 August 2017 at 19:59, Simon Glass  wrote:
>> Add some documentation for the live device tree support in U-Boot. This
>> was missing from the initial series.
>>
>> Signed-off-by: Simon Glass 
>> Suggested-by: Lukasz Majewski 
>
> Reviewed-by: Łukasz Majewski 
>
> (I hope this is OK, I just fixed the typos)
>

Thanks :-)

-- 
Best regards,

Lukasz Majewski

--

DENX Software Engineering GmbH,  Managing Director: Wolfgang Denk
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: w...@denx.de

Applied to u-boot-dm, thanks!
___
U-Boot mailing list
U-Boot@lists.denx.de
https://lists.denx.de/listinfo/u-boot

Re: [U-Boot] [PATCH v2] dm: core: Add livetree documentation

[Łukasz Majewski]

On 08/31/2017 02:00 PM, Simon Glass wrote:

On 31 August 2017 at 19:59, Simon Glass  wrote:

Add some documentation for the live device tree support in U-Boot. This
was missing from the initial series.

Signed-off-by: Simon Glass 
Suggested-by: Lukasz Majewski 


Reviewed-by: Łukasz Majewski 

(I hope this is OK, I just fixed the typos)



Thanks :-)

--
Best regards,

Lukasz Majewski

--

DENX Software Engineering GmbH,  Managing Director: Wolfgang Denk
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: w...@denx.de
___
U-Boot mailing list
U-Boot@lists.denx.de
https://lists.denx.de/listinfo/u-boot

Re: [U-Boot] [PATCH v2] dm: core: Add livetree documentation

[Simon Glass]

On 31 August 2017 at 19:59, Simon Glass  wrote:
> Add some documentation for the live device tree support in U-Boot. This
> was missing from the initial series.
>
> Signed-off-by: Simon Glass 
> Suggested-by: Lukasz Majewski 

Reviewed-by: Łukasz Majewski 

(I hope this is OK, I just fixed the typos)
___
U-Boot mailing list
U-Boot@lists.denx.de
https://lists.denx.de/listinfo/u-boot

[U-Boot] [PATCH v2] dm: core: Add livetree documentation

[Simon Glass]

Add some documentation for the live device tree support in U-Boot. This
was missing from the initial series.

Signed-off-by: Simon Glass 
Suggested-by: Lukasz Majewski 
---

Changes in v2:
- Fix several typos

 doc/driver-model/livetree.txt | 272 ++
 1 file changed, 272 insertions(+)
 create mode 100644 doc/driver-model/livetree.txt

diff --git a/doc/driver-model/livetree.txt b/doc/driver-model/livetree.txt
new file mode 100644
index 00..01d4488c60
--- /dev/null
+++ b/doc/driver-model/livetree.txt
@@ -0,0 +1,272 @@
+Driver Model with Live Device Tree
+==
+
+
+Introduction
+
+
+Traditionally U-Boot has used a 'flat' device tree. This means that it
+reads directly from the device tree binary structure. It is called a flat
+device tree because nodes are listed one after the other, with the
+hierarchy detected by tags in the format.
+
+This document describes U-Boot's support for a 'live' device tree, meaning
+that the tree is loaded into a hierarchical data structure within U-Boot.
+
+
+Motivation
+--
+
+The flat device tree has several advantages:
+
+- it is the format produced by the device tree compiler, so no translation
+is needed
+
+- it is fairly compact (e.g. there is no need for pointers)
+
+- it is accessed by the libfdt library, which is well tested and stable
+
+
+However the flat device tree does have some limitations. Adding new
+properties can involve copying large amounts of data around to make room.
+The overall tree has a fixed maximum size so sometimes the tree must be
+rebuilt in a new location to create more space. Even if not adding new
+properties or nodes, scanning the tree can be slow. For example, finding
+the parent of a node is a slow process. Reading from nodes involves a
+small amount parsing which takes a little time.
+
+Driver model scans the entire device tree sequentially on start-up which
+avoids the worst of the flat tree's limitations. But if the tree is to be
+modified at run-time, a live tree is much faster. Even if no modification
+is necessary, parsing the tree once and using a live tree from then on
+seems to save a little time.
+
+
+Implementation
+--
+
+In U-Boot a live device tree ('livetree') is currently supported only
+after relocation. Therefore we need a mechanism to specify a device
+tree node regardless of whether it is in the flat tree or livetree.
+
+The 'ofnode' type provides this. An ofnode can point to either a flat tree
+node (when the live tree node is not yet set up) or a livetree node. The
+caller of an ofnode function does not need to worry about these details.
+
+The main users of the information in a device tree are  drivers. These have
+a 'struct udevice *' which is attached to a device tree node. Therefore it
+makes sense to be able to read device tree  properties using the
+'struct udevice *', rather than having to obtain the ofnode first.
+
+The 'dev_read_...()' interface provides this. It allows properties to be
+easily read from the device tree using only a device pointer. Under the
+hood it uses ofnode so it works with both flat and live device trees.
+
+
+Enabling livetree
+-
+
+CONFIG_OF_LIVE enables livetree. When this option is enabled, the flat
+tree will be used in SPL and before relocation in U-Boot proper. Just
+before relocation a livetree is built, and this is used for U-Boot proper
+after relocation.
+
+Most checks for livetree use CONFIG_IS_ENABLED(OF_LIVE). This means that
+for SPL, the CONFIG_SPL_OF_LIVE option is checked. At present this does
+not exist, since SPL does not support livetree.
+
+
+Porting drivers
+---
+
+Many existing drivers use the fdtdec interface to read device tree
+properties. This only works with a flat device tree. The drivers should be
+converted to use the dev_read_() interface.
+
+For example, the old code may be like this:
+
+struct udevice *bus;
+const void *blob = gd->fdt_blob;
+int node = dev_of_offset(bus);
+
+i2c_bus->regs = (struct i2c_ctlr *)devfdt_get_addr(dev);
+plat->frequency = fdtdec_get_int(blob, node, "spi-max-frequency", 50);
+
+The new code is:
+
+struct udevice *bus;
+
+i2c_bus->regs = (struct i2c_ctlr *)dev_read_addr(dev);
+plat->frequency = dev_read_u32_default(bus, "spi-max-frequency", 50);
+
+The dev_read_...() interface is more convenient and works with both the
+flat and live device trees. See include/dm/read.h for a list of functions.
+
+Where properties must be read from sub-nodes or other nodes, you must fall
+back to using ofnode. For example, for old code like this:
+
+const void *blob = gd->fdt_blob;
+int subnode;
+
+fdt_for_each_subnode(subnode, blob, dev_of_offset(dev)) {
+freq = fdtdec_get_int(blob, node, "spi-max-frequency", 50);
+...
+}
+
+you should use:
+
+ofnode subnode;
+
+ofnode_for_each_subnode(subnode,