Merge tag 'dt-for-linus' of git://git.secretlab.ca/git/linux

What:		/sys/firmware/devicetree/*

Date:		November 2013

Contact:	Grant Likely <grant.likely@linaro.org>

Description:

		When using OpenFirmware or a Flattened Device Tree to enumerate

		hardware, the device tree structure will be exposed in this

		directory.

		It is possible for multiple device-tree directories to exist.

		Some device drivers use a separate detached device tree which

		have no attachment to the system tree and will appear in a

		different subdirectory under /sys/firmware/devicetree.

		Userspace must not use the /sys/firmware/devicetree/base

		path directly, but instead should follow /proc/device-tree

		symlink. It is possible that the absolute path will change

		in the future, but the symlink is the stable ABI.

		The /proc/device-tree symlink replaces the devicetree /proc

		filesystem support, and has largely the same semantics and

		should be compatible with existing userspace.

		The contents of /sys/firmware/devicetree/ is a

		hierarchy of directories, one per device tree node. The

		directory name is the resolved path component name (node

		name plus address). Properties are represented as files

		in the directory. The contents of each file is the exact

		binary data from the device tree.

*** Reserved memory regions ***

Reserved memory is specified as a node under the /reserved-memory node.

The operating system shall exclude reserved memory from normal usage

one can create child nodes describing particular reserved (excluded from

normal use) memory regions. Such memory regions are usually designed for

the special usage by various device drivers.

Parameters for each memory region can be encoded into the device tree

with the following nodes:

/reserved-memory node

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

#address-cells, #size-cells (required) - standard definition

    - Should use the same values as the root node

ranges (required) - standard definition

    - Should be empty

/reserved-memory/ child nodes

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

Each child of the reserved-memory node specifies one or more regions of

reserved memory. Each child node may either use a 'reg' property to

specify a specific range of reserved memory, or a 'size' property with

optional constraints to request a dynamically allocated block of memory.

Following the generic-names recommended practice, node names should

reflect the purpose of the node (ie. "framebuffer" or "dma-pool"). Unit

address (@<address>) should be appended to the name if the node is a

static allocation.

Properties:

Requires either a) or b) below.

a) static allocation

   reg (required) - standard definition

b) dynamic allocation

   size (required) - length based on parent's #size-cells

                   - Size in bytes of memory to reserve.

   alignment (optional) - length based on parent's #size-cells

                        - Address boundary for alignment of allocation.

   alloc-ranges (optional) - prop-encoded-array (address, length pairs).

                           - Specifies regions of memory that are

                             acceptable to allocate from.

If both reg and size are present, then the reg property takes precedence

and size is ignored.

Additional properties:

compatible (optional) - standard definition

    - may contain the following strings:

        - shared-dma-pool: This indicates a region of memory meant to be

          used as a shared pool of DMA buffers for a set of devices. It can

          be used by an operating system to instanciate the necessary pool

          management subsystem if necessary.

        - vendor specific string in the form <vendor>,[<device>-]<usage>

no-map (optional) - empty property

    - Indicates the operating system must not create a virtual mapping

      of the region as part of its standard mapping of system memory,

      nor permit speculative access to it under any circumstances other

      than under the control of the device driver using the region.

reusable (optional) - empty property

    - The operating system can use the memory in this region with the

      limitation that the device driver(s) owning the region need to be

      able to reclaim it back. Typically that means that the operating

      system can use that region to store volatile or cached data that

      can be otherwise regenerated or migrated elsewhere.

Linux implementation note:

- If a "linux,cma-default" property is present, then Linux will use the

  region for the default pool of the contiguous memory allocator.

Device node references to reserved memory

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

Regions in the /reserved-memory node may be referenced by other device

nodes by adding a memory-region property to the device node.

memory-region (optional) - phandle, specifier pairs to children of /reserved-memory

Example

-------

This example defines 3 contiguous regions are defined for Linux kernel:

one default of all device drivers (named linux,cma@72000000 and 64MiB in size),

one dedicated to the framebuffer device (named framebuffer@78000000, 8MiB), and

one for multimedia processing (named multimedia-memory@77000000, 64MiB).

/ {

	#address-cells = <1>;

	#size-cells = <1>;

	memory {

		reg = <0x40000000 0x40000000>;

	};

	reserved-memory {

		#address-cells = <1>;

		#size-cells = <1>;

		ranges;

		/* global autoconfigured region for contiguous allocations */

		linux,cma {

			compatible = "shared-dma-pool";

			reusable;

			size = <0x4000000>;

			alignment = <0x2000>;

			linux,cma-default;

		};

		display_reserved: framebuffer@78000000 {

			reg = <0x78000000 0x800000>;

		};

		multimedia_reserved: multimedia@77000000 {

			compatible = "acme,multimedia-memory";

			reg = <0x77000000 0x4000000>;

		};

	};

	/* ... */

	fb0: video@12300000 {

		memory-region = <&display_reserved>;

		/* ... */

	};

	scaler: scaler@12500000 {

		memory-region = <&multimedia_reserved>;

		/* ... */

	};

	codec: codec@12600000 {

		memory-region = <&multimedia_reserved>;

		/* ... */

	};

};

This isn't an exhaustive list, but you should add new prefixes to it before

using them to avoid name-space collisions.

abilis	Abilis Systems

active-semi	Active-Semi International Inc

ad	Avionic Design GmbH

adi	Analog Devices, Inc.

allwinner	Allwinner Technology Co., Ltd.

altr	Altera Corp.

amcc	Applied Micro Circuits Corporation (APM, formally AMCC)

amd	Advanced Micro Devices (AMD), Inc.

amstaos	AMS-Taos Inc.

apm	Applied Micro Circuits Corporation (APM)

arm	ARM Ltd.

armadeus	ARMadeus Systems SARL

atmel	Atmel Corporation

auo	AU Optronics Corporation

avago	Avago Technologies

bosch	Bosch Sensortec GmbH

brcm	Broadcom Corporation

calxeda	Calxeda

capella	Capella Microsystems, Inc

cavium	Cavium, Inc.

cdns	Cadence Design Systems Inc.

chunghwa	Chunghwa Picture Tubes Ltd.

cirrus	Cirrus Logic, Inc.

cortina	Cortina Systems, Inc.

crystalfontz	Crystalfontz America, Inc.

dallas	Maxim Integrated Products (formerly Dallas Semiconductor)

davicom	DAVICOM Semiconductor, Inc.

dlink	D-Link Systems, Inc.

denx	Denx Software Engineering

edt	Emerging Display Technologies

emmicro	EM Microelectronic

fsl	Freescale Semiconductor

GEFanuc	GE Fanuc Intelligent Platforms Embedded Systems, Inc.

gef	GE Fanuc Intelligent Platforms Embedded Systems, Inc.

globalscale	Globalscale Technologies, Inc.

gmt	Global Mixed-mode Technology, Inc.

google	Google, Inc.

gumstix	Gumstix, Inc.

haoyu	Haoyu Microelectronic Co. Ltd.

hisilicon	Hisilicon Limited.

ibm	International Business Machines (IBM)

idt	Integrated Device Technologies, Inc.

img	Imagination Technologies Ltd.

intel	Intel Corporation

intercontrol	Inter Control Group

isl	Intersil

karo	Ka-Ro electronics GmbH

lacie	LaCie

lantiq	Lantiq Semiconductor

lg	LG Corporation

linux	Linux-specific binding

lsi	LSI Corp. (LSI Logic)

maxim	Maxim Integrated Products

microchip	Microchip Technology Inc.

mosaixtech	Mosaix Technologies, Inc.

moxa	Moxa

national	National Semiconductor

neonode		Neonode Inc.

netgear	NETGEAR

nintendo	Nintendo

nokia	Nokia

nvidia	NVIDIA

nxp	NXP Semiconductors

onnn	ON Semiconductor Corp.

opencores	OpenCores.org

panasonic	Panasonic Corporation

phytec	PHYTEC Messtechnik GmbH

picochip	Picochip Ltd

silabs	Silicon Laboratories

simtek

sirf	SiRF Technology, Inc.

smsc	Standard Microsystems Corporation

snps 	Synopsys, Inc.

spansion	Spansion Inc.

st	STMicroelectronics

winbond Winbond Electronics corp.

wlf	Wolfson Microelectronics

wm	Wondermedia Technologies, Inc.

xes	Extreme Engineering Solutions (X-ES)

xlnx	Xilinx

# images. Default is /boot, but you can set it to other values

export	INSTALL_PATH ?= /boot

#

# INSTALL_DTBS_PATH specifies a prefix for relocations required by build roots.

# Like INSTALL_MOD_PATH, it isn't defined in the Makefile, but can be passed as

# an argument if needed. Otherwise it defaults to the kernel install path

#

export INSTALL_DTBS_PATH ?= $(INSTALL_PATH)/dtbs/$(KERNELRELEASE)

#

# INSTALL_MOD_PATH specifies a prefix to MODLIB for module directory

# relocations required by build roots.  This is not defined in the

	select IRQ_DOMAIN

	select OF

	select OF_EARLY_FLATTREE

	select OF_RESERVED_MEM

	help

	  Include support for flattened device tree machine descriptions.