diff --git a/Documentation/ABI/testing/sysfs-class-pwm b/Documentation/ABI/testing/sysfs-class-pwm new file mode 100644 index 00000000000000..e9be1a3844cdf9 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-pwm @@ -0,0 +1,37 @@ +What: /sys/class/pwm/ +Date: March 2013 +KernelVersion: 3.11 +Contact: Lars Poeschel +Description: + + The sysfs interface for PWM is selectable as a Kconfig option. + If a driver successfully probed a pwm chip, it appears at + /sys/class/pwm/pwmchipN/ where N is the number of it's first PWM channel. A + single driver may probe multiple chips. PWMs are identified as they are + inside the kernel, using integers in the range 0..MAX_PWMS. To use an + individual PWM, you have to explicitly export it by writing it's kernel + global number into the /sys/class/pwm/export file. Write it's number to + /sys/class/pwm/unexport to make the pwm available for other uses. + After a PWM channel is exported, it is available under + /sys/class/pwm/pwmN/. Under this directory you can set the parameters for + this PWM channel and at least let it start running. + See below for the parameters. + It is recommended to set the period_ns at first and the duty_ns after that. + + See Documentation/pwm.txt for more information. + +Directory structure: + + /sys/class/pwm + /export ... asks the kernel to export a PWM to userspace + /unexport ... to return a PWM to the kernel + /pwmN ... for each exported PWM #N + /duty_ns ... r/w, length of duty portion + /period_ns ... r/w, length of the pwm period + /polarity ... r/w, normal(0) or inverse(1) polarity + only created if driver supports it + /run ... r/w, write 1 to start and 0 to stop the pwm + /pwmchipN ... for each pwmchip; #N is its first PWM + /base ... (r/o) same as N + /ngpio ... (r/o) number of PWM; numbered N .. MAX_PWMS + diff --git a/Documentation/devices.txt b/Documentation/devices.txt index 08f01e79c41a3e..38f5c7ab71e22d 100644 --- a/Documentation/devices.txt +++ b/Documentation/devices.txt @@ -2810,6 +2810,10 @@ Your cooperation is appreciated. 211 = /dev/ttyMAX2 MAX3100 serial port 2 212 = /dev/ttyMAX3 MAX3100 serial port 3 + 220 = /dev/ttyJHD0 JHD629 pseudo serial port 0 + 221 = /dev/ttyJHD1 JHD629 pseudo serial port 1 + .. + 205 char Low-density serial ports (alternate device) 0 = /dev/culu0 Callout device for ttyLU0 1 = /dev/culu1 Callout device for ttyLU1 diff --git a/Documentation/devicetree/00-INDEX b/Documentation/devicetree/00-INDEX index b78f691fd84705..fb932e235b2fdb 100644 --- a/Documentation/devicetree/00-INDEX +++ b/Documentation/devicetree/00-INDEX @@ -8,3 +8,4 @@ https://lists.ozlabs.org/listinfo/devicetree-discuss - this file booting-without-of.txt - Booting Linux without Open Firmware, describes history and format of device trees. +dt-object-internals.txt diff --git a/Documentation/devicetree/bindings/arm/omap/omap.txt b/Documentation/devicetree/bindings/arm/omap/omap.txt index d0051a7505873e..3133a4b10d992f 100644 --- a/Documentation/devicetree/bindings/arm/omap/omap.txt +++ b/Documentation/devicetree/bindings/arm/omap/omap.txt @@ -21,6 +21,8 @@ Required properties: Optional properties: - ti,no_idle_on_suspend: When present, it prevents the PM to idle the module during suspend. +- ti,deassert-hard-reset: list of hwmod and hardware reset line name pairs + (ascii strings) to be deasserted upon device instantiation. Example: diff --git a/Documentation/devicetree/bindings/bus/ti-gpmc.txt b/Documentation/devicetree/bindings/bus/ti-gpmc.txt new file mode 100644 index 00000000000000..4b87ea1194e312 --- /dev/null +++ b/Documentation/devicetree/bindings/bus/ti-gpmc.txt @@ -0,0 +1,131 @@ +Device tree bindings for OMAP general purpose memory controllers (GPMC) + +The actual devices are instantiated from the child nodes of a GPMC node. + +Required properties: + + - compatible: Should be set to one of the following: + + ti,omap2420-gpmc (omap2420) + ti,omap2430-gpmc (omap2430) + ti,omap3430-gpmc (omap3430 & omap3630) + ti,omap4430-gpmc (omap4430 & omap4460 & omap543x) + ti,am3352-gpmc (am335x devices) + + - reg: A resource specifier for the register space + (see the example below) + - ti,hwmods: Should be set to "ti,gpmc" until the DT transition is + completed. + - #address-cells: Must be set to 2 to allow memory address translation + - #size-cells: Must be set to 1 to allow CS address passing + - gpmc,num-cs: The maximum number of chip-select lines that controller + can support. + - gpmc,num-waitpins: The maximum number of wait pins that controller can + support. + - ranges: Must be set up to reflect the memory layout with four + integer values for each chip-select line in use: + + 0 + + Currently, calculated values derived from the contents + of the per-CS register GPMC_CONFIG7 (as set up by the + bootloader) are used for the physical address decoding. + As this will change in the future, filling correct + values here is a requirement. + +Timing properties for child nodes. All are optional and default to 0. + + - gpmc,sync-clk-ps: Minimum clock period for synchronous mode, in picoseconds + + Chip-select signal timings (in nanoseconds) corresponding to GPMC_CONFIG2: + - gpmc,cs-on-ns: Assertion time + - gpmc,cs-rd-off-ns: Read deassertion time + - gpmc,cs-wr-off-ns: Write deassertion time + + ADV signal timings (in nanoseconds) corresponding to GPMC_CONFIG3: + - gpmc,adv-on-ns: Assertion time + - gpmc,adv-rd-off-ns: Read deassertion time + - gpmc,adv-wr-off-ns: Write deassertion time + + WE signals timings (in nanoseconds) corresponding to GPMC_CONFIG4: + - gpmc,we-on-ns Assertion time + - gpmc,we-off-ns: Deassertion time + + OE signals timings (in nanoseconds) corresponding to GPMC_CONFIG4: + - gpmc,oe-on-ns: Assertion time + - gpmc,oe-off-ns: Deassertion time + + Access time and cycle time timings (in nanoseconds) corresponding to + GPMC_CONFIG5: + - gpmc,page-burst-access-ns: Multiple access word delay + - gpmc,access-ns: Start-cycle to first data valid delay + - gpmc,rd-cycle-ns: Total read cycle time + - gpmc,wr-cycle-ns: Total write cycle time + - gpmc,bus-turnaround-ns: Turn-around time between successive accesses + - gpmc,cycle2cycle-delay-ns: Delay between chip-select pulses + - gpmc,clk-activation-ns: GPMC clock activation time + - gpmc,wait-monitoring-ns: Start of wait monitoring with regard to valid + data + +Boolean timing parameters. If property is present parameter enabled and +disabled if omitted: + - gpmc,adv-extra-delay: ADV signal is delayed by half GPMC clock + - gpmc,cs-extra-delay: CS signal is delayed by half GPMC clock + - gpmc,cycle2cycle-diffcsen: Add "cycle2cycle-delay" between successive + accesses to a different CS + - gpmc,cycle2cycle-samecsen: Add "cycle2cycle-delay" between successive + accesses to the same CS + - gpmc,oe-extra-delay: OE signal is delayed by half GPMC clock + - gpmc,we-extra-delay: WE signal is delayed by half GPMC clock + - gpmc,time-para-granularity: Multiply all access times by 2 + +The following are only applicable to OMAP3+ and AM335x: + - gpmc,wr-access-ns: In synchronous write mode, for single or + burst accesses, defines the number of + GPMC_FCLK cycles from start access time + to the GPMC_CLK rising edge used by the + memory device for the first data capture. + - gpmc,wr-data-mux-bus-ns: In address-data multiplex mode, specifies + the time when the first data is driven on + the address-data bus. + +GPMC chip-select settings properties for child nodes. All are optional. + +- gpmc,burst-length Page/burst length. Must be 4, 8 or 16. +- gpmc,burst-wrap Enables wrap bursting +- gpmc,burst-read Enables read page/burst mode +- gpmc,burst-write Enables write page/burst mode +- gpmc,device-nand Device is NAND +- gpmc,device-width Total width of device(s) connected to a GPMC + chip-select in bytes. The GPMC supports 8-bit + and 16-bit devices and so this property must be + 1 or 2. +- gpmc,mux-add-data Address and data multiplexing configuration. + Valid values are 1 for address-address-data + multiplexing mode and 2 for address-data + multiplexing mode. +- gpmc,sync-read Enables synchronous read. Defaults to asynchronous + is this is not set. +- gpmc,sync-write Enables synchronous writes. Defaults to asynchronous + is this is not set. +- gpmc,wait-pin Wait-pin used by client. Must be less than + "gpmc,num-waitpins". +- gpmc,wait-on-read Enables wait monitoring on reads. +- gpmc,wait-on-write Enables wait monitoring on writes. + +Example for an AM33xx board: + + gpmc: gpmc@50000000 { + compatible = "ti,am3352-gpmc"; + ti,hwmods = "gpmc"; + reg = <0x50000000 0x2000>; + interrupts = <100>; + + gpmc,num-cs = <8>; + gpmc,num-waitpins = <2>; + #address-cells = <2>; + #size-cells = <1>; + ranges = <0 0 0x08000000 0x10000000>; /* CS0 @addr 0x8000000, size 0x10000000 */ + + /* child nodes go here */ + }; diff --git a/Documentation/devicetree/bindings/crypto/omap-aes.txt b/Documentation/devicetree/bindings/crypto/omap-aes.txt new file mode 100644 index 00000000000000..6b21256d67fdc8 --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/omap-aes.txt @@ -0,0 +1,37 @@ +OMAP SoC AES crypto Module + +Required properties: + +- compatible : Should contain entries for this and backward compatible + AES versions: + - "ti,omap2-aes" for OMAP2. + - "ti,omap3-aes" for OMAP3. + - "ti,omap4-aes" for OMAP4 and AM33XX. + Note that the OMAP2 and 3 versions are compatible (OMAP3 supports + more algorithms) but they are incompatible with OMAP4. +- ti,hwmods: Name of the hwmod associated with the AES odule +- reg : Offset and length of the register set for the module +- interrupt-parent : the phandle for the interrupt controller that + services interrupts for this module. +- interrupts : the interrupt number for the AES odule. + +Optional properties: +- dmas: DMA controller phandle and DMA request ordered pairs. +- dma-names: DMA request names. This string corresponds 1:1 with + the ordered pairs in dmas. The string naming is to be + "tx" for TX request and "rx" for RX request. + +Example: + /* AM335x */ + aes: aes@53500000 { + compatible = "ti,omap4-aes"; + ti,hwmods = "aes"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x53500000 0xa0>; + interrupt-parent = <&intc>; + interrupts = <102>; + dmas = <&edma 6 + &edma 5>; + dma-names = "tx", "rx"; + }; diff --git a/Documentation/devicetree/bindings/crypto/omap-sham.txt b/Documentation/devicetree/bindings/crypto/omap-sham.txt new file mode 100644 index 00000000000000..53839cc546ddbe --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/omap-sham.txt @@ -0,0 +1,35 @@ +OMAP SoC SHA crypto Module + +Required properties: + +- compatible : Should contain entries for this and backward compatible + SHAM versions: + - "ti,omap2-sham" for OMAP2 & OMAP3. + - "ti,omap4-sham" for OMAP4 and AM33XX. + Note that these two versions are incompatible. +- ti,hwmods: Name of the hwmod associated with the SHAM module +- reg : Offset and length of the register set for the module +- interrupt-parent : the phandle for the interrupt controller that + services interrupts for this module. +- interrupts : the interrupt number for the SHAM module. + +Optional properties: +- dmas: DMA controller phandle and DMA request ordered pair. + Only one rx pair is valid per SHAM module. +- dma-names: DMA request name. This string corresponds 1:1 with + the ordered pair in dmas. The string naming is to be + "rx" for RX request. + +Example: + /* AM335x */ + sham: sham@53100000 { + compatible = "ti,omap4-sham"; + ti,hwmods = "sham"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x53100000 0x200>; + interrupt-parent = <&intc>; + interrupts = <109>; + dmas = <&edma 36>; + dma-names = "rx"; + }; diff --git a/Documentation/devicetree/bindings/dma/dma.txt b/Documentation/devicetree/bindings/dma/dma.txt new file mode 100644 index 00000000000000..8f504e6bae141f --- /dev/null +++ b/Documentation/devicetree/bindings/dma/dma.txt @@ -0,0 +1,81 @@ +* Generic DMA Controller and DMA request bindings + +Generic binding to provide a way for a driver using DMA Engine to retrieve the +DMA request or channel information that goes from a hardware device to a DMA +controller. + + +* DMA controller + +Required property: +- #dma-cells: Must be at least 1. Used to provide DMA controller + specific information. See DMA client binding below for + more details. + +Optional properties: +- dma-channels: Number of DMA channels supported by the controller. +- dma-requests: Number of DMA requests signals supported by the + controller. + +Example: + + dma: dma@48000000 { + compatible = "ti,omap-sdma"; + reg = <0x48000000 0x1000>; + interrupts = <0 12 0x4 + 0 13 0x4 + 0 14 0x4 + 0 15 0x4>; + #dma-cells = <1>; + dma-channels = <32>; + dma-requests = <127>; + }; + + +* DMA client + +Client drivers should specify the DMA property using a phandle to the controller +followed by DMA controller specific data. + +Required property: +- dmas: List of one or more DMA specifiers, each consisting of + - A phandle pointing to DMA controller node + - A number of integer cells, as determined by the + #dma-cells property in the node referenced by phandle + containing DMA controller specific information. This + typically contains a DMA request line number or a + channel number, but can contain any data that is used + required for configuring a channel. +- dma-names: Contains one identifier string for each DMA specifier in + the dmas property. The specific strings that can be used + are defined in the binding of the DMA client device. + Multiple DMA specifiers can be used to represent + alternatives and in this case the dma-names for those + DMA specifiers must be identical (see examples). + +Examples: + +1. A device with one DMA read channel, one DMA write channel: + + i2c1: i2c@1 { + ... + dmas = <&dma 2 /* read channel */ + &dma 3>; /* write channel */ + dma-names = "rx", "tx"; + ... + }; + +2. A single read-write channel with three alternative DMA controllers: + + dmas = <&dma1 5 + &dma2 7 + &dma3 2>; + dma-names = "rx-tx", "rx-tx", "rx-tx"; + +3. A device with three channels, one of which has two alternatives: + + dmas = <&dma1 2 /* read channel */ + &dma1 3 /* write channel */ + &dma2 0 /* error read */ + &dma3 0>; /* alternative error read */ + dma-names = "rx", "tx", "error", "error"; diff --git a/Documentation/devicetree/bindings/dma/ti-edma.txt b/Documentation/devicetree/bindings/dma/ti-edma.txt new file mode 100644 index 00000000000000..075a60e3117833 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/ti-edma.txt @@ -0,0 +1,49 @@ +TI EDMA + +Required properties: +- compatible : "ti,edma3" +- ti,hwmods: Name of the hwmods associated to the EDMA +- ti,edma-regions: Number of regions +- ti,edma-slots: Number of slots +- ti,edma-queue-tc-map: List of transfer control to queue mappings +- ti,edma-queue-priority-map: List of queue priority mappings +- ti,edma-default-queue: Default queue value + +Optional properties: +- ti,edma-reserved-channels: List of reserved channel regions +- ti,edma-reserved-slots: List of reserved slot regions +- ti,edma-xbar-event-map: Crossbar event to channel map + +Example: + +edma: edma@49000000 { + reg = <0x49000000 0x10000>; + interrupt-parent = <&intc>; + interrupts = <12 13 14>; + compatible = "ti,edma3"; + ti,hwmods = "tpcc", "tptc0", "tptc1", "tptc2"; + #dma-cells = <1>; + dma-channels = <64>; + ti,edma-regions = <4>; + ti,edma-slots = <256>; + ti,edma-reserved-channels = <0 2 + 14 2 + 26 6 + 48 4 + 56 8>; + ti,edma-reserved-slots = <0 2 + 14 2 + 26 6 + 48 4 + 56 8 + 64 127>; + ti,edma-queue-tc-map = <0 0 + 1 1 + 2 2>; + ti,edma-queue-priority-map = <0 0 + 1 1 + 2 2>; + ti,edma-default-queue = <0>; + ti,edma-xbar-event-map = <1 12 + 2 13>; +}; diff --git a/Documentation/devicetree/bindings/mfd/ti_am335x_tscadc.txt b/Documentation/devicetree/bindings/mfd/ti_am335x_tscadc.txt new file mode 100644 index 00000000000000..0100771715d248 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/ti_am335x_tscadc.txt @@ -0,0 +1,52 @@ +Texas Instruments - TSC / ADC multi-functional device + +ti_tscadc is a multi-function device with touchscreen and ADC on chip. +This document describes the binding for mfd device. + +Required properties: +- compatible: "ti,ti-tscadc" +- reg: Specifies the address of MFD block +- interrupts: IRQ line connected to the main SoC +- interrupt-parent: The parent interrupt controller + +Optional properties: +- ti,hwmods: Hardware information related to TSC/ADC MFD device + +Sub-nodes: +Device Description +------ ----------- +tsc Touchscreen +adc Analog to digital converter + +Sub-node device required properties: +tsc: +- ti,wires: 4/5/8 wire touchscreen support on the platform. +- ti,x-plate-resistance: X plate resistance. +- ti,steps-to-configure: A step is configured to read a single co-ordinate value, + can be applied more number of times for better results. +- ti,wire-config: Order for connecting wires on touchscreen. + +adc: +- ti,adc-channels: Number of ADC channels used. + +Example: + + tscadc: tscadc@44e0d000 { + compatible = "ti,ti-tscadc"; + reg = <0x44e0d000 0x1000>; + + interrupt-parent = <&intc>; + interrupts = <16>; + ti,hwmods = "adc_tsc"; + + tsc { + ti,wires = <4>; + ti,x-plate-resistance = <200>; + ti,steps-to-configure = <5>; + ti,wire-config = <0x00 0x11 0x22 0x33>; + }; + + adc { + ti,adc-channels = <4>; + }; + }; diff --git a/Documentation/devicetree/bindings/misc/capes-beaglebone.txt b/Documentation/devicetree/bindings/misc/capes-beaglebone.txt new file mode 100644 index 00000000000000..1af627a90244bf --- /dev/null +++ b/Documentation/devicetree/bindings/misc/capes-beaglebone.txt @@ -0,0 +1,113 @@ +* TI Beaglebone DT Overlay Cape Driver + +Required properties: + +- compatible: "ti,bone-capemgr" + +- eeprom: Contains the phandle beaglebone's baseboard i2c eeprom. + +- baseboardmaps - node containing a list of supported + beaglebone revisions; each node in should have the + following properties: + - board-name: The board name stored in the baseboard + eeprom. + - compatible-name: The name which will be used for + matching compatible capes. + +- slots: node containing a list of slot nodes (which in the beaglebone + case correspond to I2C addresses for dynamically probed capes, + or an override slot definition for hardcoded capes. + - eeprom: Contains the phandle beaglebone's cape i2c eeprom. + + It is possible to define override slots that will be activated + when the baseboard matches, and/or if supplied on the kernel command + line and/or when dynamically requested on runtime. + In that case the slot is marked with + - ti,cape-override: Marks a slot override. + - compatible: any of the "runtime", "kernel", or any compatible-name + on a matching baseboardmap node. + - Any of the eeprom-format-revision, board-name, version, manufacturer, + part-number, number-of-pins, serial-number, pin-usage, vdd-3v3exp, + vdd-5v, sys-5v, dc-supplied properties which fill in the simulated + cape's EEPROM fields. The part-number field is required, the rest + are optional taking into default values. + +- capemaps: node contains list of cape mappings, which allow converting + from a part-number & version tuple to the filename of the dtbo file. + - part-number: part number contained in the EEPROM + - version node containing a + - version: specific version to map to + - dtbo: name of the dtbo file + +Example: +bone_capemgr { + compatible = "ti,bone-capemgr"; + status = "okay"; + + eeprom = <&baseboard_eeprom>; + + baseboardmaps { + baseboard_beaglebone: board@0 { + board-name = "A335BONE"; + compatible-name = "ti,beaglebone"; + }; + }; + + slots { + slot@0 { + eeprom = <&cape_eeprom0>; + }; + + slot@1 { + eeprom = <&cape_eeprom1>; + }; + + slot@2 { + eeprom = <&cape_eeprom2>; + }; + + slot@3 { + eeprom = <&cape_eeprom3>; + }; + }; + + /* mapping between board names and dtb objects */ + capemaps { + /* Weather cape */ + cape@0 { + part-number = "BB-BONE-WTHR-01"; + version@00A0 { + version = "00A0"; + dtbo = "cape-bone-weather-00A0.dtbo"; + }; + }; + }; +}; + +Example of the override syntax when used on a bone compatible foo board. + +{ + ... + + baseboardmaps { + ... + baseboard_beaglebone: board@0 { + board-name = "A335FOO"; + compatible-name = "ti,foo"; + }; + + slot@6 { + ti,cape-override; + compatible = "ti,foo"; + board-name = "FOO-hardcoded"; + version = "00A0"; + manufacturer = "Texas Instruments"; + part-number = "BB-BONE-FOO-01"; + }; + }; + +}; + +Example of the same override syntax when used from the kernel command-line: + + capemgr.extra_override=FOO-hardcoded:00A0,FOO-another-hardcoded:00A0 diff --git a/Documentation/devicetree/bindings/mmc/ti-omap-hsmmc.txt b/Documentation/devicetree/bindings/mmc/ti-omap-hsmmc.txt index ed271fc255b23c..826cc51e425fc6 100644 --- a/Documentation/devicetree/bindings/mmc/ti-omap-hsmmc.txt +++ b/Documentation/devicetree/bindings/mmc/ti-omap-hsmmc.txt @@ -20,8 +20,28 @@ ti,dual-volt: boolean, supports dual voltage cards ti,non-removable: non-removable slot (like eMMC) ti,needs-special-reset: Requires a special softreset sequence ti,needs-special-hs-handling: HSMMC IP needs special setting for handling High Speed +dmas: DMA controller phandle and DMA request value ordered pair +One tx and one rx pair is required. +dma-names: DMA request names. These strings correspond 1:1 with +the ordered pairs in dmas. The RX request must be "rx" and the +TX request must be "tx". + +Examples: + +[hwmod populated DMA resources] + + mmc1: mmc@0x4809c000 { + compatible = "ti,omap4-hsmmc"; + reg = <0x4809c000 0x400>; + ti,hwmods = "mmc1"; + ti,dual-volt; + bus-width = <4>; + vmmc-supply = <&vmmc>; /* phandle to regulator node */ + ti,non-removable; + }; + +[generic DMA request binding] -Example: mmc1: mmc@0x4809c000 { compatible = "ti,omap4-hsmmc"; reg = <0x4809c000 0x400>; @@ -30,4 +50,7 @@ Example: bus-width = <4>; vmmc-supply = <&vmmc>; /* phandle to regulator node */ ti,non-removable; + dmas = <&edma 24 + &edma 25>; + dma-names = "tx", "rx"; }; diff --git a/Documentation/devicetree/bindings/mtd/gpmc-nor.txt b/Documentation/devicetree/bindings/mtd/gpmc-nor.txt new file mode 100644 index 00000000000000..420b3ab1889015 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/gpmc-nor.txt @@ -0,0 +1,98 @@ +Device tree bindings for NOR flash connect to TI GPMC + +NOR flash connected to the TI GPMC (found on OMAP boards) are represented as +child nodes of the GPMC controller with a name of "nor". + +All timing relevant properties as well as generic GPMC child properties are +explained in a separate documents. Please refer to +Documentation/devicetree/bindings/bus/ti-gpmc.txt + +Required properties: +- bank-width: Width of NOR flash in bytes. GPMC supports 8-bit and + 16-bit devices and so must be either 1 or 2 bytes. +- compatible: Documentation/devicetree/bindings/mtd/mtd-physmap.txt +- gpmc,cs-on-ns: Chip-select assertion time +- gpmc,cs-rd-off-ns: Chip-select de-assertion time for reads +- gpmc,cs-wr-off-ns: Chip-select de-assertion time for writes +- gpmc,oe-on-ns: Output-enable assertion time +- gpmc,oe-off-ns: Output-enable de-assertion time +- gpmc,we-on-ns Write-enable assertion time +- gpmc,we-off-ns: Write-enable de-assertion time +- gpmc,access-ns: Start cycle to first data capture (read access) +- gpmc,rd-cycle-ns: Total read cycle time +- gpmc,wr-cycle-ns: Total write cycle time +- linux,mtd-name: Documentation/devicetree/bindings/mtd/mtd-physmap.txt +- reg: Chip-select, base address (relative to chip-select) + and size of NOR flash. Note that base address will be + typically 0 as this is the start of the chip-select. + +Optional properties: +- gpmc,XXX Additional GPMC timings and settings parameters. See + Documentation/devicetree/bindings/bus/ti-gpmc.txt + +Optional properties for partiton table parsing: +- #address-cells: should be set to 1 +- #size-cells: should be set to 1 + +Example: + +gpmc: gpmc@6e000000 { + compatible = "ti,omap3430-gpmc", "simple-bus"; + ti,hwmods = "gpmc"; + reg = <0x6e000000 0x1000>; + interrupts = <20>; + gpmc,num-cs = <8>; + gpmc,num-waitpins = <4>; + #address-cells = <2>; + #size-cells = <1>; + + ranges = <0 0 0x10000000 0x08000000>; + + nor@0,0 { + compatible = "cfi-flash"; + linux,mtd-name= "intel,pf48f6000m0y1be"; + #address-cells = <1>; + #size-cells = <1>; + reg = <0 0 0x08000000>; + bank-width = <2>; + + gpmc,mux-add-data; + gpmc,cs-on-ns = <0>; + gpmc,cs-rd-off-ns = <186>; + gpmc,cs-wr-off-ns = <186>; + gpmc,adv-on-ns = <12>; + gpmc,adv-rd-off-ns = <48>; + gpmc,adv-wr-off-ns = <48>; + gpmc,oe-on-ns = <54>; + gpmc,oe-off-ns = <168>; + gpmc,we-on-ns = <54>; + gpmc,we-off-ns = <168>; + gpmc,rd-cycle-ns = <186>; + gpmc,wr-cycle-ns = <186>; + gpmc,access-ns = <114>; + gpmc,page-burst-access-ns = <6>; + gpmc,bus-turnaround-ns = <12>; + gpmc,cycle2cycle-delay-ns = <18>; + gpmc,wr-data-mux-bus-ns = <90>; + gpmc,wr-access-ns = <186>; + gpmc,cycle2cycle-samecsen; + gpmc,cycle2cycle-diffcsen; + + partition@0 { + label = "bootloader-nor"; + reg = <0 0x40000>; + }; + partition@0x40000 { + label = "params-nor"; + reg = <0x40000 0x40000>; + }; + partition@0x80000 { + label = "kernel-nor"; + reg = <0x80000 0x200000>; + }; + partition@0x280000 { + label = "filesystem-nor"; + reg = <0x240000 0x7d80000>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/mtd/gpmc-onenand.txt b/Documentation/devicetree/bindings/mtd/gpmc-onenand.txt new file mode 100644 index 00000000000000..b7529424ac88e0 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/gpmc-onenand.txt @@ -0,0 +1,46 @@ +Device tree bindings for GPMC connected OneNANDs + +GPMC connected OneNAND (found on OMAP boards) are represented as child nodes of +the GPMC controller with a name of "onenand". + +All timing relevant properties as well as generic gpmc child properties are +explained in a separate documents - please refer to +Documentation/devicetree/bindings/bus/ti-gpmc.txt + +Required properties: + + - reg: The CS line the peripheral is connected to + - gpmc,device-width Width of the ONENAND device connected to the GPMC + in bytes. Must be 1 or 2. + +Optional properties: + + - dma-channel: DMA Channel index + +For inline partiton table parsing (optional): + + - #address-cells: should be set to 1 + - #size-cells: should be set to 1 + +Example for an OMAP3430 board: + + gpmc: gpmc@6e000000 { + compatible = "ti,omap3430-gpmc"; + ti,hwmods = "gpmc"; + reg = <0x6e000000 0x1000000>; + interrupts = <20>; + gpmc,num-cs = <8>; + gpmc,num-waitpins = <4>; + #address-cells = <2>; + #size-cells = <1>; + + onenand@0 { + reg = <0 0 0>; /* CS0, offset 0 */ + gpmc,device-width = <2>; + + #address-cells = <1>; + #size-cells = <1>; + + /* partitions go here */ + }; + }; diff --git a/Documentation/devicetree/bindings/net/cpsw.txt b/Documentation/devicetree/bindings/net/cpsw.txt index 6ddd0286a9b751..d46b2939406f01 100644 --- a/Documentation/devicetree/bindings/net/cpsw.txt +++ b/Documentation/devicetree/bindings/net/cpsw.txt @@ -20,6 +20,7 @@ Required properties: - cpts_clock_shift : Denominator to convert input clock ticks into nanoseconds - phy_id : Specifies slave phy id - mac-address : Specifies slave MAC address +- disable-napi : Disables driver NAPI Optional properties: - ti,hwmods : Must be "cpgmac0" diff --git a/Documentation/devicetree/bindings/net/gpmc-eth.txt b/Documentation/devicetree/bindings/net/gpmc-eth.txt new file mode 100644 index 00000000000000..24cb4e46f67504 --- /dev/null +++ b/Documentation/devicetree/bindings/net/gpmc-eth.txt @@ -0,0 +1,97 @@ +Device tree bindings for Ethernet chip connected to TI GPMC + +Besides being used to interface with external memory devices, the +General-Purpose Memory Controller can be used to connect Pseudo-SRAM devices +such as ethernet controllers to processors using the TI GPMC as a data bus. + +Ethernet controllers connected to TI GPMC are represented as child nodes of +the GPMC controller with an "ethernet" name. + +All timing relevant properties as well as generic GPMC child properties are +explained in a separate documents. Please refer to +Documentation/devicetree/bindings/bus/ti-gpmc.txt + +For the properties relevant to the ethernet controller connected to the GPMC +refer to the binding documentation of the device. For example, the documentation +for the SMSC 911x is Documentation/devicetree/bindings/net/smsc911x.txt + +Child nodes need to specify the GPMC bus address width using the "bank-width" +property but is possible that an ethernet controller also has a property to +specify the I/O registers address width. Even when the GPMC has a maximum 16-bit +address width, it supports devices with 32-bit word registers. +For example with an SMSC LAN911x/912x controller connected to the TI GPMC on an +OMAP2+ board, "bank-width = <2>;" and "reg-io-width = <4>;". + +Required properties: +- bank-width: Address width of the device in bytes. GPMC supports 8-bit + and 16-bit devices and so must be either 1 or 2 bytes. +- compatible: Compatible string property for the ethernet child device. +- gpmc,cs-on: Chip-select assertion time +- gpmc,cs-rd-off: Chip-select de-assertion time for reads +- gpmc,cs-wr-off: Chip-select de-assertion time for writes +- gpmc,oe-on: Output-enable assertion time +- gpmc,oe-off Output-enable de-assertion time +- gpmc,we-on: Write-enable assertion time +- gpmc,we-off: Write-enable de-assertion time +- gpmc,access: Start cycle to first data capture (read access) +- gpmc,rd-cycle: Total read cycle time +- gpmc,wr-cycle: Total write cycle time +- reg: Chip-select, base address (relative to chip-select) + and size of the memory mapped for the device. + Note that base address will be typically 0 as this + is the start of the chip-select. + +Optional properties: +- gpmc,XXX Additional GPMC timings and settings parameters. See + Documentation/devicetree/bindings/bus/ti-gpmc.txt + +Example: + +gpmc: gpmc@6e000000 { + compatible = "ti,omap3430-gpmc"; + ti,hwmods = "gpmc"; + reg = <0x6e000000 0x1000>; + interrupts = <20>; + gpmc,num-cs = <8>; + gpmc,num-waitpins = <4>; + #address-cells = <2>; + #size-cells = <1>; + + ranges = <5 0 0x2c000000 0x1000000>; + + ethernet@5,0 { + compatible = "smsc,lan9221", "smsc,lan9115"; + reg = <5 0 0xff>; + bank-width = <2>; + + gpmc,mux-add-data; + gpmc,cs-on = <0>; + gpmc,cs-rd-off = <186>; + gpmc,cs-wr-off = <186>; + gpmc,adv-on = <12>; + gpmc,adv-rd-off = <48>; + gpmc,adv-wr-off = <48>; + gpmc,oe-on = <54>; + gpmc,oe-off = <168>; + gpmc,we-on = <54>; + gpmc,we-off = <168>; + gpmc,rd-cycle = <186>; + gpmc,wr-cycle = <186>; + gpmc,access = <114>; + gpmc,page-burst-access = <6>; + gpmc,bus-turnaround = <12>; + gpmc,cycle2cycle-delay = <18>; + gpmc,wr-data-mux-bus = <90>; + gpmc,wr-access = <186>; + gpmc,cycle2cycle-samecsen; + gpmc,cycle2cycle-diffcsen; + + interrupt-parent = <&gpio6>; + interrupts = <16>; + vmmc-supply = <&vddvario>; + vmmc_aux-supply = <&vdd33a>; + reg-io-width = <4>; + + smsc,save-mac-address; + }; +}; diff --git a/Documentation/devicetree/bindings/rtc/rtc-omap.txt b/Documentation/devicetree/bindings/rtc/rtc-omap.txt index b47aa415c8206f..8d9f4f9a85b6bc 100644 --- a/Documentation/devicetree/bindings/rtc/rtc-omap.txt +++ b/Documentation/devicetree/bindings/rtc/rtc-omap.txt @@ -6,6 +6,10 @@ Required properties: - interrupts: rtc timer, alarm interrupts in order - interrupt-parent: phandle for the interrupt controller +Optional properties: +- ti,system-power-controller: Telling whether or not rtc is controlling + the system power. + Example: rtc@1c23000 { @@ -14,4 +18,5 @@ rtc@1c23000 { interrupts = <19 19>; interrupt-parent = <&intc>; + ti,system-power-controller; }; diff --git a/Documentation/devicetree/bindings/sound/davinci-evm-audio.txt b/Documentation/devicetree/bindings/sound/davinci-evm-audio.txt new file mode 100644 index 00000000000000..25f7180df62fa3 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/davinci-evm-audio.txt @@ -0,0 +1,53 @@ +* Texas Instruments SoC audio setups with TLV320AIC3X Codec + +Required properties: +- compatible : + "ti,dm365-voice-codec-audio" : for DM365 platforms with Voice Codec + "ti,da830-evm-audio" : for DM365/DA8xx/OMAPL1x/AM33xx + +- ti,model : The user-visible name of this sound complex. +- ti,audio-codec : The phandle of the TLV320AIC3x audio codec +- ti,mcasp-controller : The phandle of the McASP controller +- ti,codec-clock-rate : The Codec Clock rate (in Hz) applied to the Codec +- ti,audio-routing : A list of the connections between audio components. + Each entry is a pair of strings, the first being the connection's sink, + the second being the connection's source. Valid names for sources and + sinks are the codec's pins, and the jacks on the board: + + Codec pins: + + * MIC3L + * MIC3R + * LINE1L + * LINE2L + * LINE1R + * LINE2R + + Board connectors: + + * Headphone Jack + * Line Out + * Mic Jack + + +Example: + +sound { + compatible = "ti,da830-evm-audio"; + ti,model = "DA830 EVM"; + ti,audio-codec = <&tlv320aic3x>; + ti,mcasp-controller = <&mcasp1>; + ti,codec-clock-rate = <12000000>; + ti,audio-routing = + "Headphone Jack", "HPLOUT", + "Headphone Jack", "HPROUT", + "Line Out", "LLOUT", + "Line Out", "RLOUT", + "MIC3L", "Mic Bias 2V", + "MIC3R", "Mic Bias 2V", + "Mic Bias 2V", "Mic Jack", + "LINE1L", "Line In", + "LINE2L", "Line In", + "LINE1R", "Line In", + "LINE2R", "Line In"; +}; diff --git a/Documentation/devicetree/bindings/spi/omap-spi.txt b/Documentation/devicetree/bindings/spi/omap-spi.txt index 938809c6829bfd..3bd8eed64af4f0 100644 --- a/Documentation/devicetree/bindings/spi/omap-spi.txt +++ b/Documentation/devicetree/bindings/spi/omap-spi.txt @@ -10,7 +10,18 @@ Required properties: input. The default is D0 as input and D1 as output. -Example: +Optional properties: +- dmas: List of DMA controller phandle and DMA request ordered + pairs. One tx and one rx pair is required for each chip + select. +- dma-names: List of DMA request names. These strings correspond + 1:1 with the ordered pairs in dmas. The string naming is + to be "rxN" and "txN" for RX and TX requests, + respectively, where N equals the chip select number. + +Examples: + +[hwmod populated DMA resources] mcspi1: mcspi@1 { #address-cells = <1>; @@ -20,3 +31,18 @@ mcspi1: mcspi@1 { ti,spi-num-cs = <4>; }; +[generic DMA request binding] + +mcspi1: mcspi@1 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "ti,omap4-mcspi"; + ti,hwmods = "mcspi1"; + ti,spi-num-cs = <2>; + dmas = <&edma 42 + &edma 43 + &edma 44 + &edma 45>; + dma-names = "tx0", "rx0", "tx1", "rx1"; +}; + diff --git a/Documentation/devicetree/bindings/usb/omap-usb.txt b/Documentation/devicetree/bindings/usb/omap-usb.txt index 29a043ecda523d..3f0152b62ff93d 100644 --- a/Documentation/devicetree/bindings/usb/omap-usb.txt +++ b/Documentation/devicetree/bindings/usb/omap-usb.txt @@ -1,8 +1,11 @@ -OMAP GLUE +OMAP GLUE AND OTHER OMAP SPECIFIC COMPONENTS OMAP MUSB GLUE - compatible : Should be "ti,omap4-musb" or "ti,omap3-musb" - ti,hwmods : must be "usb_otg_hs" + - ti,has_mailbox : to specify that omap uses an external mailbox + (in control module) to communicate with the musb core during device connect + and disconnect. - multipoint : Should be "1" indicating the musb controller supports multipoint. This is a MUSB configuration-specific setting. - num_eps : Specifies the number of endpoints. This is also a @@ -20,6 +23,7 @@ SOC specific device node entry usb_otg_hs: usb_otg_hs@4a0ab000 { compatible = "ti,omap4-musb"; ti,hwmods = "usb_otg_hs"; + ti,has_mailbox; multipoint = <1>; num_eps = <16>; ram_bits = <12>; @@ -31,3 +35,22 @@ Board specific device node entry mode = <3>; power = <50>; }; + +OMAP CONTROL USB + +Required properties: + - compatible: Should be "ti,omap-control-usb" + - reg : Address and length of the register set for the device. It contains + the address of "control_dev_conf" and "otghs_control". + - reg-names: The names of the register addresses corresponding to the registers + filled in "reg". + - ti,has_mailbox: This is used to specify if the platform uses mailbox in + control module. + +omap_control_usb@4a002300 { + compatible = "ti,omap-control-usb"; + reg = <0x4a002300 0x4>, + <0x4a00233c 0x4>; + reg-names = "control_dev_conf", "otghs_control"; + ti,has_mailbox; +}; diff --git a/Documentation/devicetree/bindings/usb/usb-phy.txt b/Documentation/devicetree/bindings/usb/usb-phy.txt index 80d4148cb6616f..ee14cb79adfa18 100644 --- a/Documentation/devicetree/bindings/usb/usb-phy.txt +++ b/Documentation/devicetree/bindings/usb/usb-phy.txt @@ -4,14 +4,11 @@ OMAP USB2 PHY Required properties: - compatible: Should be "ti,omap-usb2" - - reg : Address and length of the register set for the device. Also -add the address of control module dev conf register until a driver for -control module is added + - reg : Address and length of the register set for the device. This is usually a subnode of ocp2scp to which it is connected. usb2phy@4a0ad080 { compatible = "ti,omap-usb2"; - reg = <0x4a0ad080 0x58>, - <0x4a002300 0x4>; + reg = <0x4a0ad080 0x58>; }; diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index 902b1b1f568e39..cb0209ad11564c 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -4,6 +4,7 @@ This isn't an exhaustive list, but you should add new prefixes to it before using them to avoid name-space collisions. ad Avionic Design GmbH +adafruit Adafruit Industries adi Analog Devices, Inc. ak Asahi Kasei Corp. amcc Applied Micro Circuits Corporation (APM, formally AMCC) @@ -48,7 +49,9 @@ schindler Schindler sil Silicon Image simtek sirf SiRF Technology, Inc. +sitronix Sitronix Technology Corp. snps Synopsys, Inc. +spansion Spansion, Inc. st STMicroelectronics stericsson ST-Ericsson ti Texas Instruments diff --git a/Documentation/devicetree/bindings/video/backlight/pwm-backlight.txt b/Documentation/devicetree/bindings/video/backlight/pwm-backlight.txt index 1e4fc727f3b180..689c7d25f750de 100644 --- a/Documentation/devicetree/bindings/video/backlight/pwm-backlight.txt +++ b/Documentation/devicetree/bindings/video/backlight/pwm-backlight.txt @@ -14,6 +14,8 @@ Required properties: Optional properties: - pwm-names: a list of names for the PWM devices specified in the "pwms" property (see PWM binding[0]) + - low_threshold_brightness: brightness threshold low level. (get linear + scales in brightness in low end of brightness levels) [0]: Documentation/devicetree/bindings/pwm/pwm.txt @@ -26,3 +28,22 @@ Example: brightness-levels = <0 4 8 16 32 64 128 255>; default-brightness-level = <6>; }; + +Example for brightness_threshold_level: + + backlight { + compatible = "pwm-backlight"; + pwms = <&pwm 0 50000>; + + brightness-levels = <0 4 8 16 32 64 128 255>; + default-brightness-level = <6>; + low_threshold_brightness = <50>; + }; +}; +Note: +Low threshold support is required to have linear brightness scale from +0 to max. For some panels, backlight absent on low end of brightness +scale. So support for Low Threshold been required. So that the scale of +brightness changed from Low Threshold to Max in scales defined in +brightness-levels. In this example 20% maximum brightness scale should +be required to turn on panel backlight. diff --git a/Documentation/devicetree/bindings/video/display-timing.txt b/Documentation/devicetree/bindings/video/display-timing.txt new file mode 100644 index 00000000000000..bf9d82bff24512 --- /dev/null +++ b/Documentation/devicetree/bindings/video/display-timing.txt @@ -0,0 +1,109 @@ +display-timing bindings +======================= + +display-timings node +-------------------- + +required properties: + - none + +optional properties: + - native-mode: The native mode for the display, in case multiple modes are + provided. When omitted, assume the first node is the native. + +timing subnode +-------------- + +required properties: + - hactive, vactive: display resolution + - hfront-porch, hback-porch, hsync-len: horizontal display timing parameters + in pixels + vfront-porch, vback-porch, vsync-len: vertical display timing parameters in + lines + - clock-frequency: display clock in Hz + +optional properties: + - hsync-active: hsync pulse is active low/high/ignored + - vsync-active: vsync pulse is active low/high/ignored + - de-active: data-enable pulse is active low/high/ignored + - pixelclk-active: with + - active high = drive pixel data on rising edge/ + sample data on falling edge + - active low = drive pixel data on falling edge/ + sample data on rising edge + - ignored = ignored + - interlaced (bool): boolean to enable interlaced mode + - doublescan (bool): boolean to enable doublescan mode + +All the optional properties that are not bool follow the following logic: + <1>: high active + <0>: low active + omitted: not used on hardware + +There are different ways of describing the capabilities of a display. The +devicetree representation corresponds to the one commonly found in datasheets +for displays. If a display supports multiple signal timings, the native-mode +can be specified. + +The parameters are defined as: + + +----------+-------------------------------------+----------+-------+ + | | . | | | + | | |vback_porch | | | + | | . | | | + +----------#######################################----------+-------+ + | # . # | | + | # | # | | + | hback # | # hfront | hsync | + | porch # | hactive # porch | len | + |<-------->#<-------+--------------------------->#<-------->|<----->| + | # | # | | + | # |vactive # | | + | # | # | | + | # . # | | + +----------#######################################----------+-------+ + | | . | | | + | | |vfront_porch | | | + | | . | | | + +----------+-------------------------------------+----------+-------+ + | | . | | | + | | |vsync_len | | | + | | . | | | + +----------+-------------------------------------+----------+-------+ + +Example: + + display-timings { + native-mode = <&timing0>; + timing0: 1080p24 { + /* 1920x1080p24 */ + clock-frequency = <52000000>; + hactive = <1920>; + vactive = <1080>; + hfront-porch = <25>; + hback-porch = <25>; + hsync-len = <25>; + vback-porch = <2>; + vfront-porch = <2>; + vsync-len = <2>; + hsync-active = <1>; + }; + }; + +Every required property also supports the use of ranges, so the commonly used +datasheet description with minimum, typical and maximum values can be used. + +Example: + + timing1: timing { + /* 1920x1080p24 */ + clock-frequency = <148500000>; + hactive = <1920>; + vactive = <1080>; + hsync-len = <0 44 60>; + hfront-porch = <80 88 95>; + hback-porch = <100 148 160>; + vfront-porch = <0 4 6>; + vback-porch = <0 36 50>; + vsync-len = <0 5 6>; + }; diff --git a/Documentation/devicetree/bindings/video/fb-da8xx.txt b/Documentation/devicetree/bindings/video/fb-da8xx.txt new file mode 100644 index 00000000000000..0741f78d92989a --- /dev/null +++ b/Documentation/devicetree/bindings/video/fb-da8xx.txt @@ -0,0 +1,37 @@ +TI LCD Controller on DA830/DA850/AM335x SoC's + +Required properties: +- compatible: + DA830 - "ti,da830-lcdc" + AM335x SoC's - "ti,am3352-lcdc", "ti,da830-lcdc" +- reg: Address range of lcdc register set +- interrupts: lcdc interrupt +- display-timings: typical videomode of lcd panel, represented as child. + Refer Documentation/devicetree/bindings/video/display-timing.txt for + display timing binding details. If multiple videomodes are mentioned + in display timings node, typical videomode has to be mentioned as the + native mode or it has to be first child (driver cares only for native + videomode). + +Example: + +lcdc@4830e000 { + compatible = "ti,am3352-lcdc", "ti,da830-lcdc"; + reg = <0x4830e000 0x1000>; + interrupts = <36>; + display-timings { + 800x480p62 { + clock-frequency = <30000000>; + hactive = <800>; + vactive = <480>; + hfront-porch = <39>; + hback-porch = <39>; + hsync-len = <47>; + vback-porch = <29>; + vfront-porch = <13>; + vsync-len = <2>; + hsync-active = <1>; + vsync-active = <1>; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/video/ssd1307fb.txt b/Documentation/devicetree/bindings/video/ssd1307fb.txt index 3d0060cff06214..7a125427ff4bf8 100644 --- a/Documentation/devicetree/bindings/video/ssd1307fb.txt +++ b/Documentation/devicetree/bindings/video/ssd1307fb.txt @@ -1,13 +1,17 @@ * Solomon SSD1307 Framebuffer Driver Required properties: - - compatible: Should be "solomon,ssd1307fb-". The only supported bus for - now is i2c. + - compatible: Should be "solomon,fb-". The only supported bus for + now is i2c, and the supported chips are ssd1306 and ssd1307. - reg: Should contain address of the controller on the I2C bus. Most likely 0x3c or 0x3d - pwm: Should contain the pwm to use according to the OF device tree PWM - specification [0] + specification [0]. Only required for the ssd1307. - reset-gpios: Should contain the GPIO used to reset the OLED display + - solomon,height: Height in pixel of the screen driven by the controller + - solomon,width: Width in pixel of the screen driven by the controller + - solomon,page-offset: Offset of pages (band of 8 pixels) that the screen is + mapped to. Optional properties: - reset-active-low: Is the reset gpio is active on physical low? diff --git a/Documentation/devicetree/dt-object-internal.txt b/Documentation/devicetree/dt-object-internal.txt new file mode 100644 index 00000000000000..f86d0547c98ea9 --- /dev/null +++ b/Documentation/devicetree/dt-object-internal.txt @@ -0,0 +1,295 @@ +Device Tree Dynamic Object format internals +------------------------------------------- + +The Device Tree for most platforms is a static representation of +the hardware capabilities. This is insufficient for many platforms +that need to dynamically insert device tree fragments to the +running kernel's live tree. + +This document explains the the device tree object format and the +modifications made to the device tree compiler, which make it possible. + +1. Simplified Problem Definition +-------------------------------- + +Assume we have a platform which boots using following simplified device tree. + +---- foo.dts ----------------------------------------------------------------- + /* FOO platform */ + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + } + }; +---- foo.dts ----------------------------------------------------------------- + +We have a number of peripherals that after probing (using some undefined method) +should result in different device tree configuration. + +We cannot boot with this static tree because due to the configuration of the +foo platform there exist multiple conficting peripherals DT fragments. + +So for the bar peripheral we would have this: + +---- 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 ------------------------------------------------------------- + +While for the baz peripheral we would have this: + +---- foo+baz.dts ------------------------------------------------------------- + /* FOO platform + baz peripheral */ + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + /* baz resources */ + baz_res: res_baz { ... }; + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + + /* baz peripheral */ + baz { + compatible = "corp,baz"; + /* reference to another point in the tree */ + ref-to-res = <&baz_res>; + ... /* various properties and child nodes */ + } + } + }; +---- foo+baz.dts ------------------------------------------------------------- + +We note that the baz case is more complicated, since the baz peripheral needs to +reference another node in the DT tree. + +2. Device Tree Object Format Requirements +----------------------------------------- + +Since the device tree is used for booting a number of very different hardware +platforms it is imperative that we tread very carefully. + +2.a) No changes to the Device Tree binary format. We cannot modify the tree +format at all and all the information we require should be encoded using device +tree itself. We can add nodes that can be safely ignored by both bootloaders and +the kernel. + +2.b) Changes to the DTS source format should be absolutely minimal, and should +only be needed for the DT fragment definitions, and not the base boot DT. + +2.c) An explicit option should be used to instruct DTC to generate the required +information needed for object resolution. Platforms that don't use the +dynamic object format can safely ignore it. + +2.d) Finally, DT syntax changes should be kept to a minimum. It should be +possible to express everything using the existing DT syntax. + +3. Implementation +----------------- + +The basic unit of addressing in Device Tree is the phandle. Turns out it's +relatively simple to extend the way phandles are generated and referenced +so that it's possible to dynamically convert symbolic references (labels) +to phandle values. + +We can roughly divide the operation into two steps. + +3.a) Compilation of the base board DTS file using the '-@' option +generates a valid DT blob with an added __symbols__ node at the root node, +containing a list of all nodes that are marked with a label. + +Using the foo.dts file above the following node will be generated; + +$ dtc -@ -O dtb -o foo.dtb -b 0 foo.dts +$ fdtdump foo.dtb +... +/ { + ... + res { + ... + linux,phandle = <0x00000001>; + phandle = <0x00000001>; + ... + }; + ocp { + ... + linux,phandle = <0x00000002>; + phandle = <0x00000002>; + ... + }; + __symbols__ { + res="/res"; + ocp="/ocp"; + }; +}; + +Notice that all the nodes that had a label have been recorded, and that +phandles have been generated for them. + +This blob can be used to boot the board normally, the __symbols__ node will +be safely ignored both by the bootloader and the kernel (the only loss will +be a few bytes of memory and disk space). + +3.b) The Device Tree fragments must be compiled with the same option but they +must also have a tag (/plugin/) that allows undefined references to labels +that are not present at compilation time to be recorded so that the runtime +loader can fix them. + +So the bar peripheral's DTS format would be of the form: + +/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 */ + } + }; + }; +}; + +Note that there's a target property that specifies the location where the +contents of the overlay node will be placed, and it references the label +in the foo.dts file. + +$ dtc -@ -O dtb -o bar.dtbo -b 0 bar.dts +$ fdtdump bar.dtbo +... +/ { + ... /* properties */ + fragment@0 { + target = <0xdeadbeef>; + __overlay__ { + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + } + }; + }; + __fixups__ { + ocp = "/fragment@0:target:0"; + }; +}; + +No __symbols__ has been generated (no label in bar.dts). +Note that the target's ocp label is undefined, so the phandle handle +value is filled with the illegal value '0xdeadbeef', while a __fixups__ +node has been generated, which marks the location in the tree where +the label lookup should store the runtime phandle value of the ocp node. + +The format of the __fixups__ node entry is + +