[1/4] dt-binding: gpio: Add Qualcomm SMSM device tree documentation

Commit Message

Bjorn Andersson Aug. 27, 2015, 5:37 p.m. UTC

This documents a device tree binding for exposing the Qualcomm Shared
Memory State Machine as a set of gpio- and interrupt-controllers.

Signed-off-by: Bjorn Andersson <[e-mail]>
---
 .../devicetree/bindings/gpio/qcom,smsm.txt         | 114 +++++++++++++++++++++
 drivers/gpio/Kconfig                               |   8 ++
 drivers/gpio/Makefile                              |   1 +
 3 files changed, 123 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/gpio/qcom,smsm.txt

Comments

Rob Herring Aug. 31, 2015, 3:43 p.m. UTC | #1

On Thu, Aug 27, 2015 at 12:37 PM, Bjorn Andersson
<[e-mail]> wrote:
> This documents a device tree binding for exposing the Qualcomm Shared
> Memory State Machine as a set of gpio- and interrupt-controllers.
>
> Signed-off-by: Bjorn Andersson <[e-mail]>
> ---
>  .../devicetree/bindings/gpio/qcom,smsm.txt         | 114 +++++++++++++++++++++

>  drivers/gpio/Kconfig                               |   8 ++
>  drivers/gpio/Makefile                              |   1 +

Presumably this goes in patch 2.

>  3 files changed, 123 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/gpio/qcom,smsm.txt
>
> diff --git a/Documentation/devicetree/bindings/gpio/qcom,smsm.txt b/Documentation/devicetree/bindings/gpio/qcom,smsm.txt
> new file mode 100644
> index 000000000000..06201ba76594
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/gpio/qcom,smsm.txt
> @@ -0,0 +1,114 @@
> +Qualcomm Shared Memory State Machine
> +
> +The Shared Memory State Machine facilitates broadcasting of single bit state
> +information between the processors in a Qualcomm SoC. Each processor is
> +assigned 32 bits of state that can be modified. A processor can through a
> +matrix of bitmaps signal subscription of notifications upon changes to a
> +certain bit owned by a certain remote processor.

Are all the bits s/w driven, but somehow fixed in their functional definition?

> +This document defines the binding for a driver that implements and exposes this
> +a GPIO controller and a set of interrupt controllers.

I imagine Linus will have thoughts about that.

> +
> +- compatible:
> +       Usage: required
> +       Value type: <string>
> +       Definition: must be one of:
> +                   "qcom,smsm"

There are not versions of the h/w?

> +
> +- qcom,ipc-N:
> +       Usage: required
> +       Value type: <prop-encoded-array>
> +       Definition: three entries specifying the outgoing ipc bit used for
> +                   signaling the N:th remote processor
> +                   - phandle to a syscon node representing the apcs registers
> +                   - u32 representing offset to the register within the syscon
> +                   - u32 representing the ipc bit within the register
> +
> +- qcom,local-host:
> +       Usage: optional
> +       Value type: <u32>
> +       Definition: identifier of the local processor in the list of hosts, or
> +                   in other words specifier of the column in the subscription
> +                   matrix representing the local processor
> +                   defaults to host 0
> +
> +- #address-cells:
> +       Usage: required
> +       Value type: <u32>
> +       Definition: must be 1
> +
> +- #size-cells:
> +       Usage: required
> +       Value type: <u32>
> +       Definition: must be 0
> +
> += SUBNODES
> +Each processor's state bits are described by a subnode of the smsm device node.
> +A node can either be a gpio-controller - denoting the local processors bits -
> +or an interrupt-controller - denoting a remote processors state bits.  The node
> +names are not important.
> +
> +- reg:
> +       Usage: required
> +       Value type: <u32>
> +       Definition: specifies the offset, in words, of the first bit for this
> +                   entry
> +
> +- gpio-controller:
> +       Usage: required for local entry
> +       Value type: <empty>
> +       Definition: marks the entry as a gpio-controller and the state bits to
> +                   belong to the local processor
> +
> +- #gpio-cells:
> +       Usage: required for local entry
> +       Value type: <u32>
> +       Definition: must be 2 - denotes bit number and GPIO flags
> +
> +- interrupt-controller:
> +       Usage: required for remote entries
> +       Value type: <empty>
> +       Definition: marks the entry as a interrupt-controller and the state bits
> +                   to belong to a remote processor
> +
> +- #interrupt-cells:
> +       Usage: required for remote entries
> +       Value type: <u32>
> +       Definition: must be 2 - denotes bit number and IRQ flags
> +
> +- interrupts:
> +       Usage: required for remote entries
> +       Value type: <prop-encoded-array>
> +       Definition: one entry specifying remote IRQ used by the remote processor
> +                   to signal changes of its state bits
> +
> +
> += EXAMPLE
> +The following example shows the SMEM setup for controlling properties of the
> +wireless processor, defined from the 8974 apps processor's point-of-view. It
> +encompasses one outbound entry and the outgoing interrupt for the wireless
> +processor.
> +
> +smsm {
> +       compatible = "qcom,smsm";
> +
> +       #address-cells = <1>;
> +       #size-cells = <0>;
> +
> +       qcom,ipc-3 = <&apcs 8 19>;
> +
> +       apps_smsm: apps@0 {
> +               reg = <0>;
> +
> +               gpio-controller;
> +               #gpio-cells = <2>;
> +       };
> +
> +       wcnss_smsm: wcnss@7 {
> +               reg = <7>;
> +               interrupts = <0 144 1>;
> +
> +               interrupt-controller;
> +               #interrupt-cells = <2>;
> +       };
> +};
> diff --git a/drivers/gpio/Kconfig b/drivers/gpio/Kconfig
> index b4fc9e4d24c6..0e57b60faae8 100644
> --- a/drivers/gpio/Kconfig
> +++ b/drivers/gpio/Kconfig
> @@ -354,6 +354,14 @@ config GPIO_PXA
>         help
>           Say yes here to support the PXA GPIO device
>
> +config GPIO_QCOM_SMSM
> +       bool "Qualcomm Shared Memory State Machine"
> +       depends on QCOM_SMEM
> +       help
> +         Say yes here to support the Qualcomm Shared Memory State Machine.
> +         The state machine is represented by bits in shared memory and is
> +         exposed to the system as GPIOs.
> +
>  config GPIO_RCAR
>         tristate "Renesas R-Car GPIO"
>         depends on ARM && (ARCH_SHMOBILE || COMPILE_TEST)
> diff --git a/drivers/gpio/Makefile b/drivers/gpio/Makefile
> index f79a7c482a99..0fd213892403 100644
> --- a/drivers/gpio/Makefile
> +++ b/drivers/gpio/Makefile
> @@ -75,6 +75,7 @@ obj-$(CONFIG_GPIO_PCF857X)    += gpio-pcf857x.o
>  obj-$(CONFIG_GPIO_PCH)         += gpio-pch.o
>  obj-$(CONFIG_GPIO_PL061)       += gpio-pl061.o
>  obj-$(CONFIG_GPIO_PXA)         += gpio-pxa.o
> +obj-$(CONFIG_GPIO_QCOM_SMSM)   += gpio-qcom-smsm.o
>  obj-$(CONFIG_GPIO_RC5T583)     += gpio-rc5t583.o
>  obj-$(CONFIG_GPIO_RDC321X)     += gpio-rdc321x.o
>  obj-$(CONFIG_GPIO_RCAR)                += gpio-rcar.o
> --
> 1.8.2.2
>
--
To unsubscribe from this list: send the line "unsubscribe linux-arm-msm" in
the body of a message to [e-mail]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Bjorn Andersson Sept. 1, 2015, 5:26 a.m. UTC | #2

On Mon 31 Aug 08:43 PDT 2015, Rob Herring wrote:

> On Thu, Aug 27, 2015 at 12:37 PM, Bjorn Andersson
> <[e-mail]> wrote:
> > This documents a device tree binding for exposing the Qualcomm Shared
> > Memory State Machine as a set of gpio- and interrupt-controllers.
> >
> > Signed-off-by: Bjorn Andersson <[e-mail]>
> > ---
> >  .../devicetree/bindings/gpio/qcom,smsm.txt         | 114 +++++++++++++++++++++
> 
> >  drivers/gpio/Kconfig                               |   8 ++
> >  drivers/gpio/Makefile                              |   1 +
> 
> Presumably this goes in patch 2.
> 

Of course, my git-fu let me down.

> >  3 files changed, 123 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/gpio/qcom,smsm.txt
> >
> > diff --git a/Documentation/devicetree/bindings/gpio/qcom,smsm.txt b/Documentation/devicetree/bindings/gpio/qcom,smsm.txt
> > new file mode 100644
> > index 000000000000..06201ba76594
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/gpio/qcom,smsm.txt
> > @@ -0,0 +1,114 @@
> > +Qualcomm Shared Memory State Machine
> > +
> > +The Shared Memory State Machine facilitates broadcasting of single bit state
> > +information between the processors in a Qualcomm SoC. Each processor is
> > +assigned 32 bits of state that can be modified. A processor can through a
> > +matrix of bitmaps signal subscription of notifications upon changes to a
> > +certain bit owned by a certain remote processor.
> 
> Are all the bits s/w driven, but somehow fixed in their functional definition?
> 

There's a wide range of systems implementing this, but I think it's all
software. The definition of the individual bits used to be defined by
one large enum, but it looks like Qualcomm ran out of bits and started
to re-use them.

But the functions are always well defined for a given platform.

> > +This document defines the binding for a driver that implements and exposes this
> > +a GPIO controller and a set of interrupt controllers.
> 
> I imagine Linus will have thoughts about that.
> 

Looking forward to hearing his comments :)

I have not been able to find any other suitable framework to expose this
functionality with and I am hoping to not be forced to create a new one
as this one fits the purpose well.

> > +
> > +- compatible:
> > +       Usage: required
> > +       Value type: <string>
> > +       Definition: must be one of:
> > +                   "qcom,smsm"
> 
> There are not versions of the h/w?
> 

There are basically 2 versions; the original version comprised the
application cpu and the modem cpu, sometime around 2008-2009 this was
replaced with something called "N-way SMSM" - i.e. this implementation.
The only change since then is in the number of entries and number of
hosts - which we can determine in runtime if it's not compatible with
the original sizes.


So I have not been able to find any reasons to be more specific.


Thanks for taking a look.

Regards,
Bjorn
--
To unsubscribe from this list: send the line "unsubscribe linux-arm-msm" in
the body of a message to [e-mail]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Stanimir Varbanov Sept. 1, 2015, 8:18 a.m. UTC | #3

On 08/27/2015 08:37 PM, Bjorn Andersson wrote:
> This documents a device tree binding for exposing the Qualcomm Shared
> Memory State Machine as a set of gpio- and interrupt-controllers.
> 
> Signed-off-by: Bjorn Andersson <[e-mail]>
> ---
>  .../devicetree/bindings/gpio/qcom,smsm.txt         | 114 +++++++++++++++++++++

<snip>

> += EXAMPLE
> +The following example shows the SMEM setup for controlling properties of the
> +wireless processor, defined from the 8974 apps processor's point-of-view. It
> +encompasses one outbound entry and the outgoing interrupt for the wireless
> +processor.
> +
> +smsm {
> +	compatible = "qcom,smsm";
> +
> +	#address-cells = <1>;
> +	#size-cells = <0>;
> +
> +	qcom,ipc-3 = <&apcs 8 19>;

Can we use something more descriptive here, for example

qcom,ipc-rpm = <&apcs 8 19>;

and replace these magic numbers with defines?

> +
> +	apps_smsm: apps@0 {
> +		reg = <0>;
> +
> +		gpio-controller;
> +		#gpio-cells = <2>;
> +	};
> +
> +	wcnss_smsm: wcnss@7 {
> +		reg = <7>;
> +		interrupts = <0 144 1>;
> +
> +		interrupt-controller;
> +		#interrupt-cells = <2>;
> +	};
> +};

Bjorn Andersson Sept. 1, 2015, 9:50 p.m. UTC | #4

On Tue 01 Sep 01:18 PDT 2015, Stanimir Varbanov wrote:

> On 08/27/2015 08:37 PM, Bjorn Andersson wrote:
> > This documents a device tree binding for exposing the Qualcomm Shared
> > Memory State Machine as a set of gpio- and interrupt-controllers.
> > 
> > Signed-off-by: Bjorn Andersson <[e-mail]>
> > ---
> >  .../devicetree/bindings/gpio/qcom,smsm.txt         | 114 +++++++++++++++++++++
> 
> <snip>
> 
> > += EXAMPLE
> > +The following example shows the SMEM setup for controlling properties of the
> > +wireless processor, defined from the 8974 apps processor's point-of-view. It
> > +encompasses one outbound entry and the outgoing interrupt for the wireless
> > +processor.
> > +
> > +smsm {
> > +	compatible = "qcom,smsm";
> > +
> > +	#address-cells = <1>;
> > +	#size-cells = <0>;
> > +
> > +	qcom,ipc-3 = <&apcs 8 19>;
> 
> Can we use something more descriptive here, for example
> 
> qcom,ipc-rpm = <&apcs 8 19>;

Not really, because in the view of smsm we don't now which host the rpm
would represent. But most likely 3 would mean WCNSS, per the enum in
caf.

> 
> and replace these magic numbers with defines?
> 

I don't know what those defines would be named, what you have here is
bit 19 in the 8th byte - straight from the register documentation.

> > +
> > +	apps_smsm: apps@0 {
> > +		reg = <0>;
> > +
> > +		gpio-controller;
> > +		#gpio-cells = <2>;
> > +	};
> > +
> > +	wcnss_smsm: wcnss@7 {
> > +		reg = <7>;
> > +		interrupts = <0 144 1>;
> > +
> > +		interrupt-controller;
> > +		#interrupt-cells = <2>;
> > +	};
> > +};

Regards,
Bjorn
--
To unsubscribe from this list: send the line "unsubscribe linux-arm-msm" in
the body of a message to [e-mail]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Linus Walleij Sept. 8, 2015, 12:53 p.m. UTC | #5

On Mon, Aug 31, 2015 at 5:43 PM, Rob Herring <[e-mail]> wrote:
> On Thu, Aug 27, 2015 at 12:37 PM, Bjorn Andersson <[e-mail]> wrote:

>> This documents a device tree binding for exposing the Qualcomm Shared
>> Memory State Machine as a set of gpio- and interrupt-controllers.
>>
>> Signed-off-by: Bjorn Andersson <[e-mail]>

>> +This document defines the binding for a driver that implements and exposes this
>> +a GPIO controller and a set of interrupt controllers.
>
> I imagine Linus will have thoughts about that.

Yeah you bet :D

I wrote a lengthy answer to patch 0.

Point being: if we insist on this being modeled as "a kind of GPIO", then
*BSD and Windows also has to think of it as "a kind of GPIO" meaning
we put Linux implementation details into the DT bindings.

At least the idea Rob had about register-bit-* bindings should be respected
see for example:
Documentation/devicetree/bindings/leds/register-bit-led.txt

That naming is neutral, even if we end up solving it in Linux with a GPIO
abstraction, it doesn't enforce that on $OTHER_OS.

Yours,
Linus Walleij
--
To unsubscribe from this list: send the line "unsubscribe linux-arm-msm" in
the body of a message to [e-mail]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Patch

diff --git a/Documentation/devicetree/bindings/gpio/qcom,smsm.txt b/Documentation/devicetree/bindings/gpio/qcom,smsm.txt
new file mode 100644
index 000000000000..06201ba76594
--- /dev/null
+++ b/Documentation/devicetree/bindings/gpio/qcom,smsm.txt
@@ -0,0 +1,114 @@ 
+Qualcomm Shared Memory State Machine
+
+The Shared Memory State Machine facilitates broadcasting of single bit state
+information between the processors in a Qualcomm SoC. Each processor is
+assigned 32 bits of state that can be modified. A processor can through a
+matrix of bitmaps signal subscription of notifications upon changes to a
+certain bit owned by a certain remote processor.
+
+This document defines the binding for a driver that implements and exposes this
+a GPIO controller and a set of interrupt controllers.
+
+- compatible:
+	Usage: required
+	Value type: <string>
+	Definition: must be one of:
+		    "qcom,smsm"
+
+- qcom,ipc-N:
+	Usage: required
+	Value type: <prop-encoded-array>
+	Definition: three entries specifying the outgoing ipc bit used for
+		    signaling the N:th remote processor
+		    - phandle to a syscon node representing the apcs registers
+		    - u32 representing offset to the register within the syscon
+		    - u32 representing the ipc bit within the register
+
+- qcom,local-host:
+	Usage: optional
+	Value type: <u32>
+	Definition: identifier of the local processor in the list of hosts, or
+		    in other words specifier of the column in the subscription
+		    matrix representing the local processor
+		    defaults to host 0
+
+- #address-cells:
+	Usage: required
+	Value type: <u32>
+	Definition: must be 1
+
+- #size-cells:
+	Usage: required
+	Value type: <u32>
+	Definition: must be 0
+
+= SUBNODES
+Each processor's state bits are described by a subnode of the smsm device node.
+A node can either be a gpio-controller - denoting the local processors bits -
+or an interrupt-controller - denoting a remote processors state bits.  The node
+names are not important.
+
+- reg:
+	Usage: required
+	Value type: <u32>
+	Definition: specifies the offset, in words, of the first bit for this
+		    entry
+
+- gpio-controller:
+	Usage: required for local entry
+	Value type: <empty>
+	Definition: marks the entry as a gpio-controller and the state bits to
+		    belong to the local processor
+
+- #gpio-cells:
+	Usage: required for local entry
+	Value type: <u32>
+	Definition: must be 2 - denotes bit number and GPIO flags
+
+- interrupt-controller:
+	Usage: required for remote entries
+	Value type: <empty>
+	Definition: marks the entry as a interrupt-controller and the state bits
+		    to belong to a remote processor
+
+- #interrupt-cells:
+	Usage: required for remote entries
+	Value type: <u32>
+	Definition: must be 2 - denotes bit number and IRQ flags
+
+- interrupts:
+	Usage: required for remote entries
+	Value type: <prop-encoded-array>
+	Definition: one entry specifying remote IRQ used by the remote processor
+		    to signal changes of its state bits
+
+
+= EXAMPLE
+The following example shows the SMEM setup for controlling properties of the
+wireless processor, defined from the 8974 apps processor's point-of-view. It
+encompasses one outbound entry and the outgoing interrupt for the wireless
+processor.
+
+smsm {
+	compatible = "qcom,smsm";
+
+	#address-cells = <1>;
+	#size-cells = <0>;
+
+	qcom,ipc-3 = <&apcs 8 19>;
+
+	apps_smsm: apps@0 {
+		reg = <0>;
+
+		gpio-controller;
+		#gpio-cells = <2>;
+	};
+
+	wcnss_smsm: wcnss@7 {
+		reg = <7>;
+		interrupts = <0 144 1>;
+
+		interrupt-controller;
+		#interrupt-cells = <2>;
+	};
+};
diff --git a/drivers/gpio/Kconfig b/drivers/gpio/Kconfig
index b4fc9e4d24c6..0e57b60faae8 100644
--- a/drivers/gpio/Kconfig
+++ b/drivers/gpio/Kconfig
@@ -354,6 +354,14 @@  config GPIO_PXA
 	help
 	  Say yes here to support the PXA GPIO device
 
+config GPIO_QCOM_SMSM
+	bool "Qualcomm Shared Memory State Machine"
+	depends on QCOM_SMEM
+	help
+	  Say yes here to support the Qualcomm Shared Memory State Machine.
+	  The state machine is represented by bits in shared memory and is
+	  exposed to the system as GPIOs.
+
 config GPIO_RCAR
 	tristate "Renesas R-Car GPIO"
 	depends on ARM && (ARCH_SHMOBILE || COMPILE_TEST)
diff --git a/drivers/gpio/Makefile b/drivers/gpio/Makefile
index f79a7c482a99..0fd213892403 100644
--- a/drivers/gpio/Makefile
+++ b/drivers/gpio/Makefile
@@ -75,6 +75,7 @@  obj-$(CONFIG_GPIO_PCF857X)	+= gpio-pcf857x.o
 obj-$(CONFIG_GPIO_PCH)		+= gpio-pch.o
 obj-$(CONFIG_GPIO_PL061)	+= gpio-pl061.o
 obj-$(CONFIG_GPIO_PXA)		+= gpio-pxa.o
+obj-$(CONFIG_GPIO_QCOM_SMSM)	+= gpio-qcom-smsm.o
 obj-$(CONFIG_GPIO_RC5T583)	+= gpio-rc5t583.o
 obj-$(CONFIG_GPIO_RDC321X)	+= gpio-rdc321x.o
 obj-$(CONFIG_GPIO_RCAR)		+= gpio-rcar.o