Merge tag 'devicetree-for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/glikely/linux

ebv	EBV Elektronik

edt	Emerging Display Technologies

emmicro	EM Microelectronic

energymicro	Silicon Laboratories (formerly Energy Micro AS)

epcos	EPCOS AG

epfl	Ecole Polytechnique Fédérale de Lausanne

epson	Seiko Epson Corp.

gmt	Global Mixed-mode Technology, Inc.

google	Google, Inc.

gumstix	Gumstix, Inc.

gw	Gateworks Corporation

haoyu	Haoyu Microelectronic Co. Ltd.

hisilicon	Hisilicon Limited.

honeywell	Honeywell

idt	Integrated Device Technologies, Inc.

iom	Iomega Corporation

img	Imagination Technologies Ltd.

innolux	Innolux Corporation

intel	Intel Corporation

intercontrol	Inter Control Group

isee	ISEE 2007 S.L.

sii	Seiko Instruments, Inc.

silergy	Silergy Corp.

sirf	SiRF Technology, Inc.

sitronix	Sitronix Technology Corporation

smsc	Standard Microsystems Corporation

snps 	Synopsys, Inc.

solidrun	SolidRun

  VIII - Specifying device power management information (sleep property)

  IX - Specifying dma bus information

  Appendix A - Sample SOC node for MPC8540

(similar to an interrupt nexus, except that defining a standardized

sleep-map should wait until its necessity is demonstrated).

IX - Specifying dma bus information

Some devices may have DMA memory range shifted relatively to the beginning of

RAM, or even placed outside of kernel RAM. For example, the Keystone 2 SoC

worked in LPAE mode with 4G memory has:

- RAM range: [0x8 0000 0000, 0x8 FFFF FFFF]

- DMA range: [  0x8000 0000,   0xFFFF FFFF]

and DMA range is aliased into first 2G of RAM in HW.

In such cases, DMA addresses translation should be performed between CPU phys

and DMA addresses. The "dma-ranges" property is intended to be used

for describing the configuration of such system in DT.

In addition, each DMA master device on the DMA bus may or may not support

coherent DMA operations. The "dma-coherent" property is intended to be used

for identifying devices supported coherent DMA operations in DT.

* DMA Bus master

Optional property:

- dma-ranges: <prop-encoded-array> encoded as arbitrary number of triplets of

	(child-bus-address, parent-bus-address, length). Each triplet specified

	describes a contiguous DMA address range.

	The dma-ranges property is used to describe the direct memory access (DMA)

	structure of a memory-mapped bus whose device tree parent can be accessed

	from DMA operations originating from the bus. It provides a means of

	defining a mapping or translation between the physical address space of

	the bus and the physical address space of the parent of the bus.

	(for more information see ePAPR specification)

* DMA Bus child

Optional property:

- dma-ranges: <empty> value. if present - It means that DMA addresses

	translation has to be enabled for this device.

- dma-coherent: Present if dma operations are coherent

Example:

soc {

		compatible = "ti,keystone","simple-bus";

		ranges = <0x0 0x0 0x0 0xc0000000>;

		dma-ranges = <0x80000000 0x8 0x00000000 0x80000000>;

		[...]

		usb: usb@2680000 {

			compatible = "ti,keystone-dwc3";

			[...]

			dma-coherent;

		};

};

Appendix A - Sample SOC node for MPC8540

========================================

Device Tree Dynamic Resolver Notes

----------------------------------

This document describes the implementation of the in-kernel

Device Tree resolver, residing in drivers/of/resolver.c and is a

companion document to Documentation/devicetree/dt-object-internal.txt[1]

How the resolver works

----------------------

The resolver is given as an input an arbitrary tree compiled with the

proper dtc option and having a /plugin/ tag. This generates the

appropriate __fixups__ & __local_fixups__ nodes as described in [1].

In sequence the resolver works by the following steps:

1. Get the maximum device tree phandle value from the live tree + 1.

2. Adjust all the local phandles of the tree to resolve by that amount.

3. Using the __local__fixups__ node information adjust all local references

   by the same amount.

4. For each property in the __fixups__ node locate the node it references

   in the live tree. This is the label used to tag the node.

5. Retrieve the phandle of the target of the fixup.

6. For each fixup in the property locate the node:property:offset location

   and replace it with the phandle value.

    ...

 };

Figure 1, describes a generic structure of machine’s un-flattened device tree

Figure 1, describes a generic structure of machine's un-flattened device tree

considering only child and sibling pointers. There exists another pointer,

*parent, that is used to traverse the tree in the reverse direction. So, at

a particular level the child node and all the sibling nodes will have a parent

pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4’s

pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's

parent points to root node)

root (‘/’)

root ('/')

   |

child1 -> sibling2 -> sibling3 -> sibling4 -> null

   |         |           |           |

__dtb_testcases_begin - address marking the start of test data blob

__dtb_testcases_end   - address marking the end of test data blob

Secondly, it calls of_fdt_unflatten_device_tree() to unflatten the flattened

blob. And finally, if the machine’s device tree (i.e live tree) is present,

Secondly, it calls of_fdt_unflatten_tree() to unflatten the flattened

blob. And finally, if the machine's device tree (i.e live tree) is present,

then it attaches the unflattened test data tree to the live tree, else it

attaches itself as a live device tree.

live tree as explained below. To explain the same, the test data tree described

 in Figure 2 is attached to the live tree described in Figure 1.

root (‘/’)

root ('/')

    |

 testcase-data

    |

Figure 2: Example test data tree to be attached to live tree.

According to the scenario above, the live tree is already present so it isn’t

required to attach the root(‘/’) node. All other nodes are attached by calling

According to the scenario above, the live tree is already present so it isn't

required to attach the root('/') node. All other nodes are attached by calling

of_attach_node() on each node.

In the function of_attach_node(), the new node is attached as the child of the

data node is attached to the live tree above (Figure 1), the final structure is

 as shown in Figure 3.

root (‘/’)

root ('/')

   |

testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null

   |               |          |           |           |

                                          null

-----------------------------------------------------------------------

root (‘/’)

root ('/')

   |

testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null

   |               |          |           |           |

 as mentioned above.

If a duplicate node is found (i.e. if a node with same full_name property is

already present in the live tree), then the node isn’t attached rather its

properties are updated to the live tree’s node by calling the function

already present in the live tree), then the node isn't attached rather its

properties are updated to the live tree's node by calling the function

update_node_properties().

of_detach_node() to detach the nodes from the live device tree.

To detach a node, of_detach_node() first updates all_next linked list, by

attaching the previous node’s allnext to current node’s allnext pointer. And

then, it either updates the child pointer of given node’s parent to its

sibling or attaches the previous sibling to the given node’s sibling, as

attaching the previous node's allnext to current node's allnext pointer. And

then, it either updates the child pointer of given node's parent to its

sibling or attaches the previous sibling to the given node's sibling, as

appropriate. That is it :)

	bool "Device Tree Runtime self tests"

	depends on OF_IRQ && OF_EARLY_FLATTREE

	select OF_DYNAMIC

	select OF_RESOLVE

	help

	  This option builds in test cases for the device tree infrastructure

	  that are executed once at boot time, and the results dumped to the

	help

	  Helpers to allow for reservation of memory regions

config OF_RESOLVE

	bool

endmenu # OF