[RFC 6/7] capebus: Document DT bindings

[Pantelis Antoniou <panto@antoniou-consulting.com>]

Describe capebus DT bindings in detail.

Signed-off-by: Pantelis Antoniou <panto@antoniou-consulting.com>
---
 .../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