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

The chosen node

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

The chosen node does not represent a real device, but serves as a place

for passing data between firmware and the operating system, like boot

arguments. Data in the chosen node does not represent the hardware.

stdout-path property

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

Device trees may specify the device to be used for boot console output

with a stdout-path property under /chosen, as described in ePAPR, e.g.

/ {

	chosen {

		stdout-path = "/serial@f00:115200";

	};

	serial@f00 {

		compatible = "vendor,some-uart";

		reg = <0xf00 0x10>;

	};

};

If the character ":" is present in the value, this terminates the path.

The meaning of any characters following the ":" is device-specific, and

must be specified in the relevant binding documentation.

For UART devices, the preferred binding is a string in the form:

	<baud>{<parity>{<bits>{<flow>}}}

where

	baud	- baud rate in decimal

	parity	- 'n' (none), 'o', (odd) or 'e' (even)

	bits	- number of data bits

	flow	- 'r' (rts)

For example: 115200n8r

Implementation note: Linux will look for the property "linux,stdout-path" or

on PowerPC "stdout" if "stdout-path" is not found.  However, the

"linux,stdout-path" and "stdout" properties are deprecated. New platforms

should only use the "stdout-path" property.

- interrupts: exactly one interrupt specifier

Optional properties:

- pinctrl: When present, must have one state named "sleep"

	   and one state named "default"

- clocks:  When present, must refer to exactly one clock named

- pinctrl: When present, must have one state named "default",

	   and may contain a second name named "sleep". The former

	   state sets up pins for ordinary operation whereas

	   the latter state will put the associated pins to sleep

	   when the UART is unused

- clocks:  When present, the first clock listed must correspond to

	   the clock named UARTCLK on the IP block, i.e. the clock

	   to the external serial line, whereas the second clock

	   must correspond to the PCLK clocking the internal logic

	   of the block. Just listing one clock (the first one) is

	   deprecated.

- clocks-names: When present, the first clock listed must be named

	   "uartclk" and the second clock listed must be named

	   "apb_pclk"

- dmas:	   When present, may have one or two dma channels.

	   The first one must be named "rx", the second one

	   must be named "tx".

See also bindings/arm/primecell.txt

Example:

uart@80120000 {

	compatible = "arm,pl011", "arm,primecell";

	reg = <0x80120000 0x1000>;

	interrupts = <0 11 IRQ_TYPE_LEVEL_HIGH>;

	dmas = <&dma 13 0 0x2>, <&dma 13 0 0x0>;

	dma-names = "rx", "tx";

	clocks = <&foo_clk>, <&bar_clk>;

	clock-names = "uartclk", "apb_pclk";

};

* OF selftest platform device

** selftest

Required properties:

- compatible: must be "selftest"

All other properties are optional.

Example:

	selftest {

		compatible = "selftest";

		status = "okay";

	};

    struct  device_node *parent;

    struct  device_node *child;

    struct  device_node *sibling;

    struct  device_node *allnext;   /* next in list of all nodes */

    ...

 };

Figure 1: Generic structure of un-flattened device tree

*allnext: it is used to link all the nodes of DT into a list. So, for the

 above tree the list would be as follows:

root->child1->child11->sibling12->sibling13->child131->sibling14->sibling2->

child21->sibling22->sibling23->sibling3->child31->sibling32->sibling4->null

Before executing OF selftest, it is required to attach the test data to

machine's device tree (if present). So, when selftest_data_add() is called,

at first it reads the flattened device tree data linked into the kernel image

 test-child01      null             null             null

allnext list:

root->testcase-data->test-child0->test-child01->test-sibling1->test-sibling2

->test-sibling3->null

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

whole tree). selftest_data_remove() calls detach_node_and_children() that uses

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

appropriate. That is it :)

To detach a node, of_detach_node() 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 :)

Device Tree Overlay Notes

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

This document describes the implementation of the in-kernel

device tree overlay functionality residing in drivers/of/overlay.c and is a

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

Documentation/devicetree/dynamic-resolution-notes.txt[2]

How overlays work

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

A Device Tree's overlay purpose is to modify the kernel's live tree, and

have the modification affecting the state of the the kernel in a way that

is reflecting the changes.

Since the kernel mainly deals with devices, any new device node that result

in an active device should have it created while if the device node is either

disabled or removed all together, the affected device should be deregistered.

Lets take an example where we have a foo board with the following base tree

which is taken from [1].

---- foo.dts -----------------------------------------------------------------

	/* FOO platform */

	/ {

		compatible = "corp,foo";

		/* shared resources */

		res: res {

		};

		/* On chip peripherals */

		ocp: ocp {

			/* peripherals that are always instantiated */

			peripheral1 { ... };

		}

	};

---- foo.dts -----------------------------------------------------------------

The overlay bar.dts, when loaded (and resolved as described in [2]) should

---- bar.dts -----------------------------------------------------------------

/plugin/;	/* allow undefined label references and record them */

/ {

	....	/* various properties for loader use; i.e. part id etc. */

	fragment@0 {

		target = <&ocp>;

		__overlay__ {

			/* bar peripheral */

			bar {

				compatible = "corp,bar";

				... /* various properties and child nodes */

			}

		};

	};

};

---- bar.dts -----------------------------------------------------------------

result in foo+bar.dts

---- foo+bar.dts -------------------------------------------------------------

	/* FOO platform + bar peripheral */

	/ {

		compatible = "corp,foo";

		/* shared resources */

		res: res {

		};

		/* On chip peripherals */

		ocp: ocp {

			/* peripherals that are always instantiated */

			peripheral1 { ... };

			/* bar peripheral */

			bar {

				compatible = "corp,bar";

				... /* various properties and child nodes */

			}

		}

	};

---- foo+bar.dts -------------------------------------------------------------

As a result of the the overlay, a new device node (bar) has been created

so a bar platform device will be registered and if a matching device driver

is loaded the device will be created as expected.

Overlay in-kernel API

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

The API is quite easy to use.

1. Call of_overlay_create() to create and apply an overlay. The return value

is a cookie identifying this overlay.

2. Call of_overlay_destroy() to remove and cleanup the overlay previously

created via the call to of_overlay_create(). Removal of an overlay that

is stacked by another will not be permitted.

Finally, if you need to remove all overlays in one-go, just call

of_overlay_destroy_all() which will remove every single one in the correct

order.

Overlay DTS Format

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

The DTS of an overlay should have the following format:

{

	/* ignored properties by the overlay */

	fragment@0 {	/* first child node */

		target=<phandle>;	/* phandle target of the overlay */

	or

		target-path="/path";	/* target path of the overlay */

		__overlay__ {

			property-a;	/* add property-a to the target */

			node-a {	/* add to an existing, or create a node-a */

				...

			};

		};

	}

	fragment@1 {	/* second child node */

		...

	};

	/* more fragments follow */

}

Using the non-phandle based target method allows one to use a base DT which does

not contain a __symbols__ node, i.e. it was not compiled with the -@ option.

The __symbols__ node is only required for the target=<phandle> method, since it

contains the information required to map from a phandle to a tree location.