From patchwork Thu Nov 1 15:32:31 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Pantelis Antoniou X-Patchwork-Id: 1680711 Return-Path: X-Original-To: patchwork-linux-omap@patchwork.kernel.org Delivered-To: patchwork-process-083081@patchwork1.kernel.org Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by patchwork1.kernel.org (Postfix) with ESMTP id EDD9C40060 for ; Wed, 31 Oct 2012 17:40:30 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S933036Ab2JaRjp (ORCPT ); Wed, 31 Oct 2012 13:39:45 -0400 Received: from li42-95.members.linode.com ([209.123.162.95]:34593 "EHLO li42-95.members.linode.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S932935Ab2JaRjn (ORCPT ); Wed, 31 Oct 2012 13:39:43 -0400 Received: from sles11esa.localdomain (unknown [195.97.110.117]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) (Authenticated sender: panto) by li42-95.members.linode.com (Postfix) with ESMTPSA id A904E9C014; Wed, 31 Oct 2012 17:39:40 +0000 (UTC) From: Pantelis Antoniou To: Tony Lindgren Cc: Pantelis Antoniou , Paul Walmsley , "Hiremath, Vaibhav" , devicetree-discuss@lists.ozlabs.org, linux-kernel@vger.kernel.org, Koen Kooi , Matt Porter , Russ Dill , linux-omap@vger.kernel.org Subject: [RFC-v2 6/7] capebus: Document DT bindings Date: Thu, 1 Nov 2012 17:32:31 +0200 Message-Id: <1351783952-11804-7-git-send-email-panto@antoniou-consulting.com> X-Mailer: git-send-email 1.7.12 In-Reply-To: <1351783952-11804-1-git-send-email-panto@antoniou-consulting.com> References: <1351783952-11804-1-git-send-email-panto@antoniou-consulting.com> Sender: linux-omap-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-omap@vger.kernel.org Describe capebus DT bindings in detail. Signed-off-by: Pantelis Antoniou --- .../capebus/bone-capebus-slot-override.txt | 28 +++++++ .../devicetree/bindings/capebus/bone-capebus.txt | 50 +++++++++++ .../bindings/capebus/bone-geiger-cape.txt | 78 +++++++++++++++++ .../bindings/capebus/bone-generic-cape.txt | 97 ++++++++++++++++++++++ .../devicetree/bindings/capebus/da8xx-dt.txt | 31 +++++++ .../devicetree/bindings/capebus/i2c-dt.txt | 42 ++++++++++ .../devicetree/bindings/capebus/spi-dt.txt | 37 +++++++++ .../devicetree/bindings/capebus/ti-tscadc-dt.txt | 34 ++++++++ 8 files changed, 397 insertions(+) create mode 100644 Documentation/devicetree/bindings/capebus/bone-capebus-slot-override.txt create mode 100644 Documentation/devicetree/bindings/capebus/bone-capebus.txt create mode 100644 Documentation/devicetree/bindings/capebus/bone-geiger-cape.txt create mode 100644 Documentation/devicetree/bindings/capebus/bone-generic-cape.txt create mode 100644 Documentation/devicetree/bindings/capebus/da8xx-dt.txt create mode 100644 Documentation/devicetree/bindings/capebus/i2c-dt.txt create mode 100644 Documentation/devicetree/bindings/capebus/spi-dt.txt create mode 100644 Documentation/devicetree/bindings/capebus/ti-tscadc-dt.txt diff --git a/Documentation/devicetree/bindings/capebus/bone-capebus-slot-override.txt b/Documentation/devicetree/bindings/capebus/bone-capebus-slot-override.txt new file mode 100644 index 0000000..733d977 --- /dev/null +++ b/Documentation/devicetree/bindings/capebus/bone-capebus-slot-override.txt @@ -0,0 +1,28 @@ +* Beagle bone capebus slot override bindings + +The beagle bone capebus node can have slot override nodes. These nodes describe + an override that will take place in the specified slot. + Many boards during the prototype phase don't have an EEPROM (or are even + wired in such a way that an eeprom cannot be added). In that case you can + specify an override that will make everything work as if a real EEPROM was + there. + +Required properties: +- compatible: Override node must have the form "bone-capebus-slot-override" +- slot: Identifies the slot# to override. +- board-name: The cape's name as if provided by the board-name EEPROM field + +Optional properties: +- version: The cape's version as if provided by the version EEPROM field. +- manufacturer: The cape's manufacturer as if provided by the manufacturer + EEPROM field. + +Example: + +override@1 { + compatible = "bone-capebus-slot-override"; + slot = <1>; + board-name = "Adafruit 1.8 Cape"; + version = "00A0"; + manufacturer = "Adafruit"; +}; diff --git a/Documentation/devicetree/bindings/capebus/bone-capebus.txt b/Documentation/devicetree/bindings/capebus/bone-capebus.txt new file mode 100644 index 0000000..6d8a08d --- /dev/null +++ b/Documentation/devicetree/bindings/capebus/bone-capebus.txt @@ -0,0 +1,50 @@ +* Beagle bone capebus bindings + +The beaglebone capebus implementation is using a single capebus +node contained in the root node. A beaglebone cape is identified +at by reading an EEPROM at on of 4 possible addresses on the I2C2 bus. + +Required properties: +- compatible: Every beaglebone compatible capebus node shall have the + form "bone-capebus"; +- slots: An array of phandles pointing to the I2C node of an EEPROM that + contains the cape information. + +Optional properties: + +The child nodes of the capebus node can contain either cape nodes +or override nodes. Those cape nodes are described in their respective +binding files. + +- override nodes: Describe an override that will take place in the specified + slot. Many boards during the prototype phase don't have an EEPROM (or are even + wired in such a way that an eeprom cannot be added). In that case you can + specify an override that will make everything work as if a real EEPROM was + there. + +Override node required properties: +- compatible: For override node must have the form "bone-capebus-slot-override" +- slot: Identifies the slot# to override. +- board-name: The cape's name as if provided by the board-name EEPROM field + +Override node optional properties: +- version: The cape's version as if provided by the version EEPROM field. +- manufacturer: The cape's manufacturer as if provided by the manufacturer + EEPROM field. + +Example: + +capebus: capebus@0 { + compatible = "bone-capebus"; + + slots = <&cape_eeprom_0 &cape_eeprom_1 &cape_eeprom_2 &cape_eeprom_3>; + + [cape-nodes] + [override-nodes] + + bone_adafruit_cape: cape@5 { + compatible = "bone-generic-cape"; + // read the bone-generic-cape bindings for the rest + ... + }; +}; diff --git a/Documentation/devicetree/bindings/capebus/bone-geiger-cape.txt b/Documentation/devicetree/bindings/capebus/bone-geiger-cape.txt new file mode 100644 index 0000000..a2ed81c --- /dev/null +++ b/Documentation/devicetree/bindings/capebus/bone-geiger-cape.txt @@ -0,0 +1,78 @@ +* Beagle bone geiger cape + + A geiger cape is your run of the mill particle detector measuring + ionizing radiation. It is also the first example of how a non-generic + cape can be supported by capebus. + + The geiger cape can not be created via instantiation of a generic cape + since the component need to work together. + +Required properties: +- compatible: Generic cape nodes must have the form "bone-geiger-cape" +- board-name: The cape's name as if provided by the board-name EEPROM field +- pwms: Pointer to the PWM we require +- pwm-names: Name of the PWM. +- pwm-frequency: Frequency of the PWM in Hz +- pwm-duty-cycle: Duty cycle in percent +- event-blink-delay: Blink delay of the event led +- gpios: GPIO on which an event is detected +- vsense-name: Name of the analog input for vsense +- vsense-scale: Vsense scale to convert to mVolts +- ti-tscadc-dt compatible node for the ADC configuration +- gpio-leds compatible node for the LED configuration + +Optional properties: + +The geiger cape supports the standard pinctrl properties. + +Example: + +bone_geiger_cape: cape@1 { + compatible = "bone-geiger-cape"; + board-name = "Geiger Cape"; + + /* note that these can't be versioned... */ + pinctrl-names = "default"; + pinctrl-0 = <&bone_geiger_cape_pins>; + + pwms = <&ehrpwm1 0 500000 0>; + pwm-names = "bone-geiger-cape"; + + pwm-frequency = <20000>; /* 20KHz */ + pwm-duty-cycle = <60>; /* 60% */ + + event-blink-delay = <30>; /* 30ms */ + + gpios = <&gpio4 17 0>; /* pulse */ + + vsense-name = "AIN5"; /* analog vsense */ + vsense-scale = <37325>; /* scaling */ + + tscadc { + compatible = "ti-tscadc-dt"; + + ti,hwmods = "adc_tsc"; + + adc-channels = <8>; + }; + + gpio-leds { + compatible = "gpio-leds"; + pinctrl-names = "default"; + pinctrl-0 = <&bone_geiger_cape_led_pins>; + + geiger-led0 { + label = "geiger:green:usr0"; + gpios = <&gpio3 23 0>; + linux,default-trigger = "geiger-run"; + default-state = "off"; + }; + + geiger-led1 { + label = "geiger:red:usr1"; + gpios = <&gpio3 25 0>; + linux,default-trigger = "geiger-event"; + default-state = "off"; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/capebus/bone-generic-cape.txt b/Documentation/devicetree/bindings/capebus/bone-generic-cape.txt new file mode 100644 index 0000000..71ad2f4 --- /dev/null +++ b/Documentation/devicetree/bindings/capebus/bone-generic-cape.txt @@ -0,0 +1,97 @@ +* Beagle bone generic cape + + A generic cape is one form of cape that doesn't require any per-cape + driver for it to function. It is enough for the cape's node to be + instantiated in the right manner and the functions that the cape provides + will be available to Linux. A large number of capes fall in this category + like LCD/DVI/VGA capes, audio capes, capes with a number of gpio buttons, + capes with standard I2C/SPI/W1 parts etc. + All that's required is to describe the parts of the cape in the DT and + how they utilize the SoC peripherals and it will work, without having + to write any other driver, or modify the board support package. + + As a sidenote, a large part of the complexity of capes have to do + with version management. A cape as it goes through various steps of evolution + changes. These changes are codified by the version field on the EEPROM. + It is important that version management can be kept as simple as possible. + + The generic concept works by instantiating the child nodes that are + contained in the cape node. By default nodes that are present in the + root of the node are activated for any version. Version nodes can + contain per-version changes. In the example the da8xx-dt node differs + in the way it's instantiated, and this is expressed by the version nodes. + +Required properties: +- compatible: Generic cape nodes must have the form "bone-generic-cape" +- board-name: The cape's name as if provided by the board-name EEPROM field + +Optional properties: +- version: Only valid in a version node, and it contains the list of compatible + versions this node contains. + +The standard supported nodes of the generic cape are: + +gpio-leds, tps65217-backlight, gpio-keys, w1-gpio, pwm-backlight + +The following nodes are supported via a capebus specific bridge devices, and +their bindings described in their respective files: + +ti-tscadc-dt, da8xx-dt, i2c-dt, spi-dt + +Example: + +bone_dvi_cape: cape@0 { + + compatible = "bone-generic-cape"; + board-name = "BeagleBone DVI-D CAPE"; + + /* hacky, since this is not a proper DT platform device */ + /* but until we have DT bindings... */ + version@00A0 { + version = "00A0"; + dvi { + compatible = "da8xx-dt"; + pinctrl-names = "default"; + pinctrl-0 = <&bone_dvi_cape_dvi_00A0_pins>; + ti,hwmods = "lcdc"; + + disp-pll = <560000000>; + panel-type = "1024x768@60"; + powerdn-gpio = <&gpio2 7 0>; + }; + }; + + version@00A1 { + version = "00A1", "01"; + dvi { + compatible = "da8xx-dt"; + pinctrl-names = "default"; + pinctrl-0 = <&bone_dvi_cape_dvi_00A1_pins>; + ti,hwmods = "lcdc"; + + disp-pll = <560000000>; + panel-type = "1024x768@60"; + powerdn-gpio = <&gpio2 31 0>; + }; + }; + + gpio-leds { + compatible = "gpio-leds"; + pinctrl-names = "default"; + pinctrl-0 = <&bone_dvi_cape_led_pins>; + + dvi-led0 { + label = "dvi:green:usr0"; + gpios = <&gpio2 18 0>; + linux,default-trigger = "heartbeat"; + default-state = "off"; + }; + + dvi-led1 { + label = "dvi:green:usr1"; + gpios = <&gpio2 19 0>; + linux,default-trigger = "mmc0"; + default-state = "off"; + }; + }; +}; diff --git a/Documentation/devicetree/bindings/capebus/da8xx-dt.txt b/Documentation/devicetree/bindings/capebus/da8xx-dt.txt new file mode 100644 index 0000000..0b84063 --- /dev/null +++ b/Documentation/devicetree/bindings/capebus/da8xx-dt.txt @@ -0,0 +1,31 @@ +* DA8XX DT bindins + + This is an adapter device for use in device tree cases, since the + drivers DT bindings are not yet ready. It is bound to get away once + they are in place. Note that there is no capebus prefix, since there's + not really any dependence on capebus; the drivers can be moved out of + capebus if need be. + +Required properties: +- compatible: Must have the form "da8xx-dt" +- ti,hwmods: Must have the form "lcdc" (until hwmod DT is complete) +- disp-pll: PLL value +- panel-type: Name of the panel type connected + +Optional properties: +powerdn-gpio: GPIO controlling power + +Note that the pinctrl bindings are supported. + +Example: + +dvi { + compatible = "da8xx-dt"; + pinctrl-names = "default"; + pinctrl-0 = <&bone_dvi_cape_dvi_00A0_pins>; + ti,hwmods = "lcdc"; + + disp-pll = <560000000>; + panel-type = "1024x768@60"; + powerdn-gpio = <&gpio2 7 0>; +}; diff --git a/Documentation/devicetree/bindings/capebus/i2c-dt.txt b/Documentation/devicetree/bindings/capebus/i2c-dt.txt new file mode 100644 index 0000000..79a042a --- /dev/null +++ b/Documentation/devicetree/bindings/capebus/i2c-dt.txt @@ -0,0 +1,42 @@ +* I2C DT bindings + + This is an adapter device for use in device tree cases. + What we want to do is to add a number of I2C devices connected + to a specified i2c adapter node, and instantiate them on + successful cape match. Not only that, normally I2C adapters + are disabled in the DT tree, so in that case we enable them + first and then go about our business. + +Required properties: +- compatible: Must have the form "i2c-dt" +- parent: The phandle of the i2c adapter node +- #address-cells: The same as the parent i2c adapter node +- #size-cells: The same as the parent i2c adapter node + +Example: + +i2c2-devices { + compatible = "i2c-dt"; + #address-cells = <1>; + #size-cells = <0>; + + parent = <&i2c2>; + + /* Ambient light sensor */ + tsl2550@39 { + compatible = "tsl,tsl2550"; + reg = <0x39>; + }; + + /* Humidity Sensor */ + sht21@40 { + compatible = "sensiron,sht21"; + reg = <0x40>; + }; + + /* Barometric pressure sensor */ + bmp085@77 { + compatible = "bosch,bmp085"; + reg = <0x77>; + }; +}; diff --git a/Documentation/devicetree/bindings/capebus/spi-dt.txt b/Documentation/devicetree/bindings/capebus/spi-dt.txt new file mode 100644 index 0000000..fd70fc4 --- /dev/null +++ b/Documentation/devicetree/bindings/capebus/spi-dt.txt @@ -0,0 +1,37 @@ +* SPI DT bindings + + This is an adapter device for use in device tree cases. + What we want to do is to add a number of SPI devices connected + to a specified spi node, and instantiate them on + successful cape match. Not only that, normally SPI nodes + are disabled in the DT tree, so in that case we enable them + first and then go about our business. + +Required properties: +- compatible: Must have the form "spi-dt" +- parent: The phandle of the spi node +- #address-cells: The same as the parent spi node +- #size-cells: The same as the parent spi node + +Example: + +spi1-devices { + compatible = "spi-dt"; + #address-cells = <1>; + #size-cells = <0>; + + parent = <&spi1>; + + lcd@0 { + compatible = "adafruit,tft-lcd-1.8-red", "sitronix,st7735"; + spi-max-frequency = <8000000>; + reg = <0>; + spi-cpol; + spi-cpha; + pinctrl-names = "default"; + pinctrl-0 = <&lcd_pins>; + st7735-rst = <&gpio4 19 0>; + st7735-dc = <&gpio4 21 0>; + }; + +}; diff --git a/Documentation/devicetree/bindings/capebus/ti-tscadc-dt.txt b/Documentation/devicetree/bindings/capebus/ti-tscadc-dt.txt new file mode 100644 index 0000000..44ad4f2 --- /dev/null +++ b/Documentation/devicetree/bindings/capebus/ti-tscadc-dt.txt @@ -0,0 +1,34 @@ +* TI's TSCADC Device Tree adapter + + This is an adapter device for use in device tree cases, since the + drivers DT bindings are not yet ready. It is bound to get away once + they are in place. Note that there is no capebus prefix, since there's + not really any dependence on capebus; the drivers can be moved out of + capebus if need be. + +Required properties: +- compatible: Must have the form "ti-tscadc-dt" +- ti,hwmods: Must have the form "adc_tsc" (until hwmod DT is complete) + +Optional properties: +- adc-channels: Number of ADC channels the driver should provide. +- tsc-wires: Number of touchscreen wires +- tsc-x-plate-resistance: Touchscreen X plate resistance value +- tsc-steps: Touchscreen steps + +Note if either adc-channels or tsc-wires are missing their respective +values are set to 0. + +Example: + +tscadc { + compatible = "ti-tscadc-dt"; + + ti,hwmods = "adc_tsc"; + + tsc-wires = <4>; + tsc-x-plate-resistance = <200>; + tsc-steps = <6>; + + adc-channels = <4>; +};