[PATCH/RFC v2 1/7] spi: Document DT bindings for SPI controllers in slave mode

From: Geert Uytterhoeven
Date: Mon Sep 12 2016 - 16:50:55 EST


Signed-off-by: Geert Uytterhoeven <geert+renesas@xxxxxxxxx>
---
v2:
- Do not create a child node in SPI slave mode. Instead, add an
"spi-slave" property, and put the mode properties in the controller
node.
---
Documentation/devicetree/bindings/spi/spi-bus.txt | 34 ++++++++++++++---------
1 file changed, 21 insertions(+), 13 deletions(-)

diff --git a/Documentation/devicetree/bindings/spi/spi-bus.txt b/Documentation/devicetree/bindings/spi/spi-bus.txt
index 17822860cb98c34d..1ae28d7cafb68dc5 100644
--- a/Documentation/devicetree/bindings/spi/spi-bus.txt
+++ b/Documentation/devicetree/bindings/spi/spi-bus.txt
@@ -1,17 +1,23 @@
SPI (Serial Peripheral Interface) busses

-SPI busses can be described with a node for the SPI master device
-and a set of child nodes for each SPI slave on the bus. For this
-discussion, it is assumed that the system's SPI controller is in
-SPI master mode. This binding does not describe SPI controllers
-in slave mode.
+SPI busses can be described with a node for the SPI controller device
+and a set of child nodes for each SPI slave on the bus. The system's SPI
+controller may be described for use in SPI master mode or in SPI slave mode,
+but not for both at the same time.

-The SPI master node requires the following properties:
+The SPI controller node requires the following properties:
+- compatible - name of SPI bus controller following generic names
+ recommended practice.
+
+In master mode, the SPI controller node requires the following additional
+properties:
- #address-cells - number of cells required to define a chip select
address on the SPI bus.
- #size-cells - should be zero.
-- compatible - name of SPI bus controller following generic names
- recommended practice.
+
+In slave mode, the SPI controller node requires one additional property:
+- spi-slave - Empty property.
+
No other properties are required in the SPI bus node. It is assumed
that a driver for an SPI bus device will understand that it is an SPI bus.
However, the binding does not attempt to define the specific method for
@@ -21,7 +27,7 @@ assumption that board specific platform code will be used to manage
chip selects. Individual drivers can define additional properties to
support describing the chip select layout.

-Optional properties:
+Optional properties (master mode only):
- cs-gpios - gpios chip select.
- num-cs - total number of chipselects.

@@ -41,12 +47,14 @@ cs1 : native
cs2 : &gpio1 1 0
cs3 : &gpio1 2 0

-SPI slave nodes must be children of the SPI master node and can
-contain the following properties.
-- reg - (required) chip select address of device.
+In master mode, SPI slave nodes must be children of the SPI controller node.
+In slave mode, the (single) slave device is represented by the controller node
+itself. SPI slave nodes can contain the following properties.
+- reg - (required, master mode only) chip select address of device.
- compatible - (required) name of SPI device following generic names
recommended practice.
-- spi-max-frequency - (required) Maximum SPI clocking speed of device in Hz.
+- spi-max-frequency - (required, master mode only) Maximum SPI clocking speed
+ of device in Hz.
- spi-cpol - (optional) Empty property indicating device requires
inverse clock polarity (CPOL) mode.
- spi-cpha - (optional) Empty property indicating device requires
--
1.9.1