[RFC 6/7] capebus: Document DT bindings
From: Pantelis Antoniou
Date: Tue Oct 30 2012 - 15:00:30 EST
Describe capebus DT bindings in detail.
Signed-off-by: Pantelis Antoniou <panto@xxxxxxxxxxxxxxxxxxxxxxx>
---
.../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>;
+};
--
1.7.12
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/