[RFC,1/8] dt-bindings: mfd: Add Altera Arria10 System Resource Chip bindings
diff mbox

Message ID 1459278791-3646-2-git-send-email-tthayer@opensource.altera.com
State Changes Requested, archived
Headers show

Commit Message

tthayer@opensource.altera.com March 29, 2016, 7:13 p.m. UTC
From: Thor Thayer <tthayer@opensource.altera.com>

The Altera Arria10 Devkit System Resource chip is a Multi-Function
Device, it has two subdevices:
     - GPIO
     - HWMON

This patch adds documentation for the Altera A10-SR DT bindings.

Signed-off-by: Thor Thayer <tthayer@opensource.altera.com>
---
 .../devicetree/bindings/mfd/altera-a10sr.txt       |   35 ++++++++++++++++++++
 1 file changed, 35 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mfd/altera-a10sr.txt

Comments

Lee Jones March 30, 2016, 11:35 a.m. UTC | #1
On Tue, 29 Mar 2016, tthayer@opensource.altera.com wrote:

> From: Thor Thayer <tthayer@opensource.altera.com>
> 
> The Altera Arria10 Devkit System Resource chip is a Multi-Function
> Device, it has two subdevices:
>      - GPIO
>      - HWMON
> 
> This patch adds documentation for the Altera A10-SR DT bindings.
> 
> Signed-off-by: Thor Thayer <tthayer@opensource.altera.com>
> ---
>  .../devicetree/bindings/mfd/altera-a10sr.txt       |   35 ++++++++++++++++++++
>  1 file changed, 35 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/mfd/altera-a10sr.txt
> 
> diff --git a/Documentation/devicetree/bindings/mfd/altera-a10sr.txt b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
> new file mode 100644
> index 0000000..564c761
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
> @@ -0,0 +1,35 @@
> +* Altera Arria10 Development Kit System Resource Chip
> +
> +Required parent device properties:
> +- compatible : "altr,altr_a10sr"
> +- spi-max-frequency : Maximum SPI frequency.
> +- reg : the SPI Chip Select address for the Arria10 System Resource chip

DT bindings are much easier to read in the following format:

- compatible		: "altr,altr_a10sr"
- spi-max-frequency	: Maximum SPI frequency.
- reg			: the SPI Chip Select address for the Arria10 System Resource chip

... also, sentences start with an uppercase char.

> +The A10SR consists of this varied group of sub-devices:
> +
> +Device                   Description
> +------                   ----------
> +altr_a10sr_gpio          GPIO Controller
> +altr_a10sr_hwmon         Hardware Monitor
> +
> +The LEDs are implemented entirely in the device tree using
> +the gpio-led framework.

This is a Linuxisum and should not live in DT bindings.

> +Example:
> +
> +        a10-sr: a10-sr@0 {

Nodes should be named after their device 'type'.

Does this device really start a address 0?

> +		compatible = "altr,altr-a10sr";
> +		reg = <0>;
> +		spi-max-frequency = <100000>;
> +
> +		a10sr_gpio: a10sr_gpio {

Device type only please.

> +			compatible = "altr,a10sr-gpio";
> +			gpio-controller;
> +			#gpio-cells = <2>;
> +			ngpios = <16>;
> +		};
> +
> +		a10sr_hwmon: a10sr_hwmon {

Device type only please.

> +			compatible = "altr,a10sr-hwmon";
> +		};
> +	};
Rob Herring March 31, 2016, 2:06 p.m. UTC | #2
On Wed, Mar 30, 2016 at 12:35:32PM +0100, Lee Jones wrote:
> On Tue, 29 Mar 2016, tthayer@opensource.altera.com wrote:
> 
> > From: Thor Thayer <tthayer@opensource.altera.com>
> > 
> > The Altera Arria10 Devkit System Resource chip is a Multi-Function
> > Device, it has two subdevices:
> >      - GPIO
> >      - HWMON
> > 
> > This patch adds documentation for the Altera A10-SR DT bindings.
> > 
> > Signed-off-by: Thor Thayer <tthayer@opensource.altera.com>
> > ---
> >  .../devicetree/bindings/mfd/altera-a10sr.txt       |   35 ++++++++++++++++++++
> >  1 file changed, 35 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/mfd/altera-a10sr.txt
> > 
> > diff --git a/Documentation/devicetree/bindings/mfd/altera-a10sr.txt b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
> > new file mode 100644
> > index 0000000..564c761
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
> > @@ -0,0 +1,35 @@
> > +* Altera Arria10 Development Kit System Resource Chip
> > +
> > +Required parent device properties:
> > +- compatible : "altr,altr_a10sr"

Why "altr" twice?

Don't use underscores.

> > +- spi-max-frequency : Maximum SPI frequency.
> > +- reg : the SPI Chip Select address for the Arria10 System Resource chip
> 
> DT bindings are much easier to read in the following format:
> 
> - compatible		: "altr,altr_a10sr"
> - spi-max-frequency	: Maximum SPI frequency.
> - reg			: the SPI Chip Select address for the Arria10 System Resource chip
> 
> ... also, sentences start with an uppercase char.
> 
> > +The A10SR consists of this varied group of sub-devices:
> > +
> > +Device                   Description
> > +------                   ----------
> > +altr_a10sr_gpio          GPIO Controller
> > +altr_a10sr_hwmon         Hardware Monitor
> > +
> > +The LEDs are implemented entirely in the device tree using
> > +the gpio-led framework.
> 
> This is a Linuxisum and should not live in DT bindings.
> 
> > +Example:
> > +
> > +        a10-sr: a10-sr@0 {
> 
> Nodes should be named after their device 'type'.
> 
> Does this device really start a address 0?

Being a SPI device, I imagine so.

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
tthayer@opensource.altera.com March 31, 2016, 6:21 p.m. UTC | #3
Hi Lee,

On 03/30/2016 06:35 AM, Lee Jones wrote:
> On Tue, 29 Mar 2016, tthayer@opensource.altera.com wrote:
>
>> From: Thor Thayer <tthayer@opensource.altera.com>
>>

[..snip..]

>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
>> @@ -0,0 +1,35 @@
>> +* Altera Arria10 Development Kit System Resource Chip
>> +
>> +Required parent device properties:
>> +- compatible : "altr,altr_a10sr"
>> +- spi-max-frequency : Maximum SPI frequency.
>> +- reg : the SPI Chip Select address for the Arria10 System Resource chip
>
> DT bindings are much easier to read in the following format:
>
> - compatible		: "altr,altr_a10sr"
> - spi-max-frequency	: Maximum SPI frequency.
> - reg			: the SPI Chip Select address for the Arria10 System Resource chip
>
> ... also, sentences start with an uppercase char.
>

OK.

>> +The A10SR consists of this varied group of sub-devices:
>> +
>> +Device                   Description
>> +------                   ----------
>> +altr_a10sr_gpio          GPIO Controller
>> +altr_a10sr_hwmon         Hardware Monitor
>> +
>> +The LEDs are implemented entirely in the device tree using
>> +the gpio-led framework.
>
> This is a Linuxisum and should not live in DT bindings.
>

I was following the format of other mfd binding documents such as 
Documentation/devicetree/bindings/mfd/da9055.txt so I'll need your help 
understanding this.

I'm not familiar with the phrase Linuxisum. A Google search turns up 
several threads referencing Linuxisum but I can't seem to find the 
definition. One thread seems to imply that an existing driver such as 
GPIO is a Linuxisum and should not be re-defined. Am I understanding 
correctly?

>> +Example:
>> +
>> +        a10-sr: a10-sr@0 {
>
> Nodes should be named after their device 'type'.
>
> Does this device really start a address 0?

OK. If I understand, this should be named after mfd then?
>
>> +		compatible = "altr,altr-a10sr";
>> +		reg = <0>;
>> +		spi-max-frequency = <100000>;
>> +
>> +		a10sr_gpio: a10sr_gpio {
>
> Device type only please.

And this would be a gpio?

Thanks for your comments and for reviewing!

>
>> +			compatible = "altr,a10sr-gpio";
>> +			gpio-controller;
>> +			#gpio-cells = <2>;
>> +			ngpios = <16>;
>> +		};
>> +
>> +		a10sr_hwmon: a10sr_hwmon {
>
> Device type only please.
>
>> +			compatible = "altr,a10sr-hwmon";
>> +		};
>> +	};
>
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Lee Jones April 1, 2016, 8:14 a.m. UTC | #4
On Thu, 31 Mar 2016, Thor Thayer wrote:
> On 03/30/2016 06:35 AM, Lee Jones wrote:
> >On Tue, 29 Mar 2016, tthayer@opensource.altera.com wrote:
> >
> >>From: Thor Thayer <tthayer@opensource.altera.com>

[...]

> >>+The A10SR consists of this varied group of sub-devices:
> >>+
> >>+Device                   Description
> >>+------                   ----------
> >>+altr_a10sr_gpio          GPIO Controller
> >>+altr_a10sr_hwmon         Hardware Monitor
> >>+
> >>+The LEDs are implemented entirely in the device tree using
> >>+the gpio-led framework.
> >
> >This is a Linuxisum and should not live in DT bindings.
> 
> I was following the format of other mfd binding documents such as
> Documentation/devicetree/bindings/mfd/da9055.txt so I'll need your
> help understanding this.
> 
> I'm not familiar with the phrase Linuxisum. A Google search turns up
> several threads referencing Linuxisum but I can't seem to find the
> definition. One thread seems to imply that an existing driver such
> as GPIO is a Linuxisum and should not be re-defined. Am I
> understanding correctly?

Linuxisum is a made up word.  Actually, it looks like I placed a
superfluous 'u' in there, but I assume most people would get the gist.
Some examples ending in "ism" which might push the point across are
"colloquialism" and "feminism", where the "ism" can probably be taken
to mean "pertaining to".  So in the example above, we might reasonably
conclude that I meant "pertaining to Linux", which I did.

In other words "the gpio-led framework" is something we have in Linux,
but might not exist in other OSes.  And considering DT is supposed to
be OS agnostic and the documentation relevant to all OSes, you can not
and should not document Linuxisms.

> >>+Example:
> >>+
> >>+        a10-sr: a10-sr@0 {
> >
> >Nodes should be named after their device 'type'.
> >
> >Does this device really start a address 0?
> 
> OK. If I understand, this should be named after mfd then?

MFDs are usually a little tougher, but in your case I think it should
be "resource-manager" or similar.

> >>+		compatible = "altr,altr-a10sr";
> >>+		reg = <0>;
> >>+		spi-max-frequency = <100000>;
> >>+
> >>+		a10sr_gpio: a10sr_gpio {
> >
> >Device type only please.
> 
> And this would be a gpio?

Exactly.
tthayer@opensource.altera.com April 1, 2016, 8:21 p.m. UTC | #5
On 04/01/2016 03:14 AM, Lee Jones wrote:
> On Thu, 31 Mar 2016, Thor Thayer wrote:
>> On 03/30/2016 06:35 AM, Lee Jones wrote:
>>> On Tue, 29 Mar 2016, tthayer@opensource.altera.com wrote:
>>>
>>>> From: Thor Thayer <tthayer@opensource.altera.com>
>
> [...]
>
>>>> +The A10SR consists of this varied group of sub-devices:
>>>> +
>>>> +Device                   Description
>>>> +------                   ----------
>>>> +altr_a10sr_gpio          GPIO Controller
>>>> +altr_a10sr_hwmon         Hardware Monitor
>>>> +
>>>> +The LEDs are implemented entirely in the device tree using
>>>> +the gpio-led framework.
>>>
>>> This is a Linuxisum and should not live in DT bindings.
>>
>> I was following the format of other mfd binding documents such as
>> Documentation/devicetree/bindings/mfd/da9055.txt so I'll need your
>> help understanding this.
>>
>> I'm not familiar with the phrase Linuxisum. A Google search turns up
>> several threads referencing Linuxisum but I can't seem to find the
>> definition. One thread seems to imply that an existing driver such
>> as GPIO is a Linuxisum and should not be re-defined. Am I
>> understanding correctly?
>
> Linuxisum is a made up word.  Actually, it looks like I placed a
> superfluous 'u' in there, but I assume most people would get the gist.
> Some examples ending in "ism" which might push the point across are
> "colloquialism" and "feminism", where the "ism" can probably be taken
> to mean "pertaining to".  So in the example above, we might reasonably
> conclude that I meant "pertaining to Linux", which I did.
>
> In other words "the gpio-led framework" is something we have in Linux,
> but might not exist in other OSes.  And considering DT is supposed to
> be OS agnostic and the documentation relevant to all OSes, you can not
> and should not document Linuxisms.
>

Got it. Thanks for the explanation! I'll make the changes.

>>>> +Example:
>>>> +
>>>> +        a10-sr: a10-sr@0 {
>>>
>>> Nodes should be named after their device 'type'.
>>>
>>> Does this device really start a address 0?
>>
>> OK. If I understand, this should be named after mfd then?
>
> MFDs are usually a little tougher, but in your case I think it should
> be "resource-manager" or similar.
>
>>>> +		compatible = "altr,altr-a10sr";
>>>> +		reg = <0>;
>>>> +		spi-max-frequency = <100000>;
>>>> +
>>>> +		a10sr_gpio: a10sr_gpio {
>>>
>>> Device type only please.
>>
>> And this would be a gpio?
>
> Exactly.
>
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
tthayer@opensource.altera.com April 15, 2016, 5:02 p.m. UTC | #6
Hi Lee

On 03/30/2016 06:35 AM, Lee Jones wrote:
> On Tue, 29 Mar 2016, tthayer@opensource.altera.com wrote:
>
>> From: Thor Thayer <tthayer@opensource.altera.com>
>>
>> The Altera Arria10 Devkit System Resource chip is a Multi-Function
>> Device, it has two subdevices:
>>       - GPIO
>>       - HWMON
>>
>> This patch adds documentation for the Altera A10-SR DT bindings.
>>
>> Signed-off-by: Thor Thayer <tthayer@opensource.altera.com>
>> ---
>>   .../devicetree/bindings/mfd/altera-a10sr.txt       |   35 ++++++++++++++++++++
>>   1 file changed, 35 insertions(+)
>>   create mode 100644 Documentation/devicetree/bindings/mfd/altera-a10sr.txt
>>
>> diff --git a/Documentation/devicetree/bindings/mfd/altera-a10sr.txt b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
>> new file mode 100644
>> index 0000000..564c761
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
>> @@ -0,0 +1,35 @@
>> +* Altera Arria10 Development Kit System Resource Chip
>> +
>> +Required parent device properties:
>> +- compatible : "altr,altr_a10sr"
>> +- spi-max-frequency : Maximum SPI frequency.
>> +- reg : the SPI Chip Select address for the Arria10 System Resource chip
>
> DT bindings are much easier to read in the following format:
>
> - compatible		: "altr,altr_a10sr"
> - spi-max-frequency	: Maximum SPI frequency.
> - reg			: the SPI Chip Select address for the Arria10 System Resource chip
>
> ... also, sentences start with an uppercase char.
>
>> +The A10SR consists of this varied group of sub-devices:
>> +
>> +Device                   Description
>> +------                   ----------
>> +altr_a10sr_gpio          GPIO Controller
>> +altr_a10sr_hwmon         Hardware Monitor
>> +
>> +The LEDs are implemented entirely in the device tree using
>> +the gpio-led framework.
>
> This is a Linuxisum and should not live in DT bindings.
>
>> +Example:
>> +
>> +        a10-sr: a10-sr@0 {
>
> Nodes should be named after their device 'type'.
>
> Does this device really start a address 0?
>

I see in the documentation on device trees there are a number of 
categories I can use. GPIO is easy because it is one of the categories 
but I'm not sure about the new device I'm adding since the a10sr is a 
new device.

I believe I should only call out the name and address on the SPI bus like:

a10sr@0 {

>> +		compatible = "altr,altr-a10sr";
>> +		reg = <0>;
>> +		spi-max-frequency = <100000>;
>> +
>> +		a10sr_gpio: a10sr_gpio {
>
> Device type only please.
>

and this would be a10sr_gpio: gpio-controller {

Does that seem correct?

>> +			compatible = "altr,a10sr-gpio";
>> +			gpio-controller;
>> +			#gpio-cells = <2>;
>> +			ngpios = <16>;
>> +		};
>> +
>> +		a10sr_hwmon: a10sr_hwmon {
>
> Device type only please.
>
I need to revisit where this will live (hwmon does not seem to be the 
correct place) so it will change but I can follow the format above if it 
is correct.

Thanks for reviewing.

>> +			compatible = "altr,a10sr-hwmon";
>> +		};
>> +	};
>
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Lee Jones April 18, 2016, 7:43 a.m. UTC | #7
On Fri, 15 Apr 2016, Thor Thayer wrote:
> On 03/30/2016 06:35 AM, Lee Jones wrote:
> >On Tue, 29 Mar 2016, tthayer@opensource.altera.com wrote:
> >
> >>From: Thor Thayer <tthayer@opensource.altera.com>
> >>
> >>The Altera Arria10 Devkit System Resource chip is a Multi-Function
> >>Device, it has two subdevices:
> >>      - GPIO
> >>      - HWMON
> >>
> >>This patch adds documentation for the Altera A10-SR DT bindings.
> >>
> >>Signed-off-by: Thor Thayer <tthayer@opensource.altera.com>
> >>---
> >>  .../devicetree/bindings/mfd/altera-a10sr.txt       |   35 ++++++++++++++++++++
> >>  1 file changed, 35 insertions(+)
> >>  create mode 100644 Documentation/devicetree/bindings/mfd/altera-a10sr.txt
> >>
> >>diff --git a/Documentation/devicetree/bindings/mfd/altera-a10sr.txt b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
> >>new file mode 100644
> >>index 0000000..564c761
> >>--- /dev/null
> >>+++ b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
> >>@@ -0,0 +1,35 @@
> >>+* Altera Arria10 Development Kit System Resource Chip
> >>+
> >>+Required parent device properties:
> >>+- compatible : "altr,altr_a10sr"
> >>+- spi-max-frequency : Maximum SPI frequency.
> >>+- reg : the SPI Chip Select address for the Arria10 System Resource chip
> >
> >DT bindings are much easier to read in the following format:
> >
> >- compatible		: "altr,altr_a10sr"
> >- spi-max-frequency	: Maximum SPI frequency.
> >- reg			: the SPI Chip Select address for the Arria10 System Resource chip
> >
> >... also, sentences start with an uppercase char.
> >
> >>+The A10SR consists of this varied group of sub-devices:
> >>+
> >>+Device                   Description
> >>+------                   ----------
> >>+altr_a10sr_gpio          GPIO Controller
> >>+altr_a10sr_hwmon         Hardware Monitor
> >>+
> >>+The LEDs are implemented entirely in the device tree using
> >>+the gpio-led framework.
> >
> >This is a Linuxisum and should not live in DT bindings.
> >
> >>+Example:
> >>+
> >>+        a10-sr: a10-sr@0 {
> >
> >Nodes should be named after their device 'type'.
> >
> >Does this device really start a address 0?
> >
> 
> I see in the documentation on device trees there are a number of
> categories I can use. GPIO is easy because it is one of the
> categories but I'm not sure about the new device I'm adding since
> the a10sr is a new device.

It's always difficult with MFDs as they are by their very nature, more
than one device.  But how about 'resource-manager'?

> I believe I should only call out the name and address on the SPI bus like:
> 
> a10sr@0 {

Correct.

> >>+		compatible = "altr,altr-a10sr";
> >>+		reg = <0>;
> >>+		spi-max-frequency = <100000>;
> >>+
> >>+		a10sr_gpio: a10sr_gpio {
> >
> >Device type only please.
> >
> 
> and this would be a10sr_gpio: gpio-controller {
> 
> Does that seem correct?

Also correct.  No address though?

> >>+			compatible = "altr,a10sr-gpio";
> >>+			gpio-controller;
> >>+			#gpio-cells = <2>;
> >>+			ngpios = <16>;
> >>+		};
> >>+
> >>+		a10sr_hwmon: a10sr_hwmon {
> >
> >Device type only please.
> >
> I need to revisit where this will live (hwmon does not seem to be
> the correct place) so it will change but I can follow the format
> above if it is correct.
> 
> Thanks for reviewing.
> 
> >>+			compatible = "altr,a10sr-hwmon";
> >>+		};
> >>+	};
> >
Lee Jones April 18, 2016, 7:45 a.m. UTC | #8
On Fri, 15 Apr 2016, Thor Thayer wrote:
> On 03/30/2016 06:35 AM, Lee Jones wrote:
> >On Tue, 29 Mar 2016, tthayer@opensource.altera.com wrote:
> >
> >>From: Thor Thayer <tthayer@opensource.altera.com>
> >>
> >>The Altera Arria10 Devkit System Resource chip is a Multi-Function
> >>Device, it has two subdevices:
> >>      - GPIO
> >>      - HWMON
> >>
> >>This patch adds documentation for the Altera A10-SR DT bindings.
> >>
> >>Signed-off-by: Thor Thayer <tthayer@opensource.altera.com>
> >>---
> >>  .../devicetree/bindings/mfd/altera-a10sr.txt       |   35 ++++++++++++++++++++
> >>  1 file changed, 35 insertions(+)
> >>  create mode 100644 Documentation/devicetree/bindings/mfd/altera-a10sr.txt
> >>
> >>diff --git a/Documentation/devicetree/bindings/mfd/altera-a10sr.txt b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
> >>new file mode 100644
> >>index 0000000..564c761
> >>--- /dev/null
> >>+++ b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
> >>@@ -0,0 +1,35 @@
> >>+* Altera Arria10 Development Kit System Resource Chip
> >>+
> >>+Required parent device properties:
> >>+- compatible : "altr,altr_a10sr"
> >>+- spi-max-frequency : Maximum SPI frequency.
> >>+- reg : the SPI Chip Select address for the Arria10 System Resource chip

[...]

> >>+		a10sr_hwmon: a10sr_hwmon {
> >
> >Device type only please.
> >
> I need to revisit where this will live (hwmon does not seem to be
> the correct place) so it will change but I can follow the format
> above if it is correct.

BTW, "hwmon" is a subsystem in Linux, therefore is a Linuxism and is
not allowed in DT.  What does the device *actually* do?
tthayer@opensource.altera.com April 18, 2016, 2:55 p.m. UTC | #9
Hi Lee,

On 04/18/2016 02:43 AM, Lee Jones wrote:
> On Fri, 15 Apr 2016, Thor Thayer wrote:
>> On 03/30/2016 06:35 AM, Lee Jones wrote:
>>> On Tue, 29 Mar 2016, tthayer@opensource.altera.com wrote:
>>>
>>>> From: Thor Thayer <tthayer@opensource.altera.com>
>>>>
>>>> The Altera Arria10 Devkit System Resource chip is a Multi-Function
>>>> Device, it has two subdevices:
>>>>       - GPIO
>>>>       - HWMON
>>>>
>>>> This patch adds documentation for the Altera A10-SR DT bindings.
>>>>
>>>> Signed-off-by: Thor Thayer <tthayer@opensource.altera.com>
>>>> ---
>>>>   .../devicetree/bindings/mfd/altera-a10sr.txt       |   35 ++++++++++++++++++++
>>>>   1 file changed, 35 insertions(+)
>>>>   create mode 100644 Documentation/devicetree/bindings/mfd/altera-a10sr.txt
>>>>
>>>> diff --git a/Documentation/devicetree/bindings/mfd/altera-a10sr.txt b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
>>>> new file mode 100644
>>>> index 0000000..564c761
>>>> --- /dev/null
>>>> +++ b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
>>>> @@ -0,0 +1,35 @@
>>>> +* Altera Arria10 Development Kit System Resource Chip
>>>> +
>>>> +Required parent device properties:
>>>> +- compatible : "altr,altr_a10sr"
>>>> +- spi-max-frequency : Maximum SPI frequency.
>>>> +- reg : the SPI Chip Select address for the Arria10 System Resource chip
>>>
>>> DT bindings are much easier to read in the following format:
>>>
>>> - compatible		: "altr,altr_a10sr"
>>> - spi-max-frequency	: Maximum SPI frequency.
>>> - reg			: the SPI Chip Select address for the Arria10 System Resource chip
>>>
>>> ... also, sentences start with an uppercase char.
>>>
>>>> +The A10SR consists of this varied group of sub-devices:
>>>> +
>>>> +Device                   Description
>>>> +------                   ----------
>>>> +altr_a10sr_gpio          GPIO Controller
>>>> +altr_a10sr_hwmon         Hardware Monitor
>>>> +
>>>> +The LEDs are implemented entirely in the device tree using
>>>> +the gpio-led framework.
>>>
>>> This is a Linuxisum and should not live in DT bindings.
>>>
>>>> +Example:
>>>> +
>>>> +        a10-sr: a10-sr@0 {
>>>
>>> Nodes should be named after their device 'type'.
>>>
>>> Does this device really start a address 0?
>>>
>>
>> I see in the documentation on device trees there are a number of
>> categories I can use. GPIO is easy because it is one of the
>> categories but I'm not sure about the new device I'm adding since
>> the a10sr is a new device.
>
> It's always difficult with MFDs as they are by their very nature, more
> than one device.  But how about 'resource-manager'?
>
OK. Yes, that would be a good name. Thanks.

>> I believe I should only call out the name and address on the SPI bus like:
>>
>> a10sr@0 {
>
> Correct.
>
>>>> +		compatible = "altr,altr-a10sr";
>>>> +		reg = <0>;
>>>> +		spi-max-frequency = <100000>;
>>>> +
>>>> +		a10sr_gpio: a10sr_gpio {
>>>
>>> Device type only please.
>>>
>>
>> and this would be a10sr_gpio: gpio-controller {
>>
>> Does that seem correct?
>
> Also correct.  No address though?
>

Thank you. It is at a fixed address inside the SPI device. When making 
this binding I followed the format of other gpio controllers like the 
tps65086 and lp3943 which didn't have an address.

Thanks for the clarification.

>>>> +			compatible = "altr,a10sr-gpio";
>>>> +			gpio-controller;
>>>> +			#gpio-cells = <2>;
>>>> +			ngpios = <16>;
>>>> +		};
>>>> +
>>>> +		a10sr_hwmon: a10sr_hwmon {
>>>
>>> Device type only please.
>>>
>> I need to revisit where this will live (hwmon does not seem to be
>> the correct place) so it will change but I can follow the format
>> above if it is correct.
>>
>> Thanks for reviewing.
>>
>>>> +			compatible = "altr,a10sr-hwmon";
>>>> +		};
>>>> +	};
>>>
>
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
tthayer@opensource.altera.com April 18, 2016, 3:12 p.m. UTC | #10
Hi Lee,

On 04/18/2016 02:45 AM, Lee Jones wrote:
> On Fri, 15 Apr 2016, Thor Thayer wrote:
>> On 03/30/2016 06:35 AM, Lee Jones wrote:
>>> On Tue, 29 Mar 2016, tthayer@opensource.altera.com wrote:
>>>
>>>> From: Thor Thayer <tthayer@opensource.altera.com>
>>>>
>>>> The Altera Arria10 Devkit System Resource chip is a Multi-Function
>>>> Device, it has two subdevices:
>>>>       - GPIO
>>>>       - HWMON
>>>>
>>>> This patch adds documentation for the Altera A10-SR DT bindings.
>>>>
>>>> Signed-off-by: Thor Thayer <tthayer@opensource.altera.com>
>>>> ---
>>>>   .../devicetree/bindings/mfd/altera-a10sr.txt       |   35 ++++++++++++++++++++
>>>>   1 file changed, 35 insertions(+)
>>>>   create mode 100644 Documentation/devicetree/bindings/mfd/altera-a10sr.txt
>>>>
>>>> diff --git a/Documentation/devicetree/bindings/mfd/altera-a10sr.txt b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
>>>> new file mode 100644
>>>> index 0000000..564c761
>>>> --- /dev/null
>>>> +++ b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
>>>> @@ -0,0 +1,35 @@
>>>> +* Altera Arria10 Development Kit System Resource Chip
>>>> +
>>>> +Required parent device properties:
>>>> +- compatible : "altr,altr_a10sr"
>>>> +- spi-max-frequency : Maximum SPI frequency.
>>>> +- reg : the SPI Chip Select address for the Arria10 System Resource chip
>
> [...]
>
>>>> +		a10sr_hwmon: a10sr_hwmon {
>>>
>>> Device type only please.
>>>
>> I need to revisit where this will live (hwmon does not seem to be
>> the correct place) so it will change but I can follow the format
>> above if it is correct.
>
> BTW, "hwmon" is a subsystem in Linux, therefore is a Linuxism and is
> not allowed in DT.  What does the device *actually* do?
>

OK. I'll be careful not to introduce the Linux subsystem name.

This module indicates whether the power supplies are at the correct 
voltage. It uses a boolean instead of giving an actual voltage value as 
required by HWMON. In other words it is a comparator instead of an 
Analog-to-Digital Converter.

I could call it a power supply supervisor or voltage status monitor but 
it only acts in a passive role. There is no output to trigger an error - 
only polling, so supervisor doesn't seem like a good name.

Maybe something like this?

	power_supply_status {
		compatible = "altr,a10sr-hwmon";
	}

Thanks for reviewing and helping me figure out the device tree naming.
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Lee Jones April 19, 2016, 7:23 a.m. UTC | #11
On Mon, 18 Apr 2016, Thor Thayer wrote:

> Hi Lee,
> 
> On 04/18/2016 02:45 AM, Lee Jones wrote:
> >On Fri, 15 Apr 2016, Thor Thayer wrote:
> >>On 03/30/2016 06:35 AM, Lee Jones wrote:
> >>>On Tue, 29 Mar 2016, tthayer@opensource.altera.com wrote:
> >>>
> >>>>From: Thor Thayer <tthayer@opensource.altera.com>
> >>>>
> >>>>The Altera Arria10 Devkit System Resource chip is a Multi-Function
> >>>>Device, it has two subdevices:
> >>>>      - GPIO
> >>>>      - HWMON
> >>>>
> >>>>This patch adds documentation for the Altera A10-SR DT bindings.
> >>>>
> >>>>Signed-off-by: Thor Thayer <tthayer@opensource.altera.com>
> >>>>---
> >>>>  .../devicetree/bindings/mfd/altera-a10sr.txt       |   35 ++++++++++++++++++++
> >>>>  1 file changed, 35 insertions(+)
> >>>>  create mode 100644 Documentation/devicetree/bindings/mfd/altera-a10sr.txt
> >>>>
> >>>>diff --git a/Documentation/devicetree/bindings/mfd/altera-a10sr.txt b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
> >>>>new file mode 100644
> >>>>index 0000000..564c761
> >>>>--- /dev/null
> >>>>+++ b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
> >>>>@@ -0,0 +1,35 @@
> >>>>+* Altera Arria10 Development Kit System Resource Chip
> >>>>+
> >>>>+Required parent device properties:
> >>>>+- compatible : "altr,altr_a10sr"
> >>>>+- spi-max-frequency : Maximum SPI frequency.
> >>>>+- reg : the SPI Chip Select address for the Arria10 System Resource chip
> >
> >[...]
> >
> >>>>+		a10sr_hwmon: a10sr_hwmon {
> >>>
> >>>Device type only please.
> >>>
> >>I need to revisit where this will live (hwmon does not seem to be
> >>the correct place) so it will change but I can follow the format
> >>above if it is correct.
> >
> >BTW, "hwmon" is a subsystem in Linux, therefore is a Linuxism and is
> >not allowed in DT.  What does the device *actually* do?
> >
> 
> OK. I'll be careful not to introduce the Linux subsystem name.
> 
> This module indicates whether the power supplies are at the correct
> voltage. It uses a boolean instead of giving an actual voltage value
> as required by HWMON. In other words it is a comparator instead of
> an Analog-to-Digital Converter.
> 
> I could call it a power supply supervisor or voltage status monitor
> but it only acts in a passive role. There is no output to trigger an
> error - only polling, so supervisor doesn't seem like a good name.
> 
> Maybe something like this?
> 
> 	power_supply_status {
> 		compatible = "altr,a10sr-hwmon";
> 	}
> 
> Thanks for reviewing and helping me figure out the device tree naming.

Does it have its own address space?  How complex is the device?  Not
very, by the sounds of it.  In which case, does it really need its own
driver?
tthayer@opensource.altera.com April 19, 2016, 2:38 p.m. UTC | #12
On 04/19/2016 02:23 AM, Lee Jones wrote:
> On Mon, 18 Apr 2016, Thor Thayer wrote:
>
>> Hi Lee,
>>
>> On 04/18/2016 02:45 AM, Lee Jones wrote:
>>> On Fri, 15 Apr 2016, Thor Thayer wrote:
>>>> On 03/30/2016 06:35 AM, Lee Jones wrote:
>>>>> On Tue, 29 Mar 2016, tthayer@opensource.altera.com wrote:
>>>>>
>>>>>> From: Thor Thayer <tthayer@opensource.altera.com>
>>>>>>
>>>>>> The Altera Arria10 Devkit System Resource chip is a Multi-Function
>>>>>> Device, it has two subdevices:
>>>>>>       - GPIO
>>>>>>       - HWMON
>>>>>>
>>>>>> This patch adds documentation for the Altera A10-SR DT bindings.
>>>>>>
>>>>>> Signed-off-by: Thor Thayer <tthayer@opensource.altera.com>
>>>>>> ---
>>>>>>   .../devicetree/bindings/mfd/altera-a10sr.txt       |   35 ++++++++++++++++++++
>>>>>>   1 file changed, 35 insertions(+)
>>>>>>   create mode 100644 Documentation/devicetree/bindings/mfd/altera-a10sr.txt
>>>>>>
>>>>>> diff --git a/Documentation/devicetree/bindings/mfd/altera-a10sr.txt b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
>>>>>> new file mode 100644
>>>>>> index 0000000..564c761
>>>>>> --- /dev/null
>>>>>> +++ b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
>>>>>> @@ -0,0 +1,35 @@
>>>>>> +* Altera Arria10 Development Kit System Resource Chip
>>>>>> +
>>>>>> +Required parent device properties:
>>>>>> +- compatible : "altr,altr_a10sr"
>>>>>> +- spi-max-frequency : Maximum SPI frequency.
>>>>>> +- reg : the SPI Chip Select address for the Arria10 System Resource chip
>>>
>>> [...]
>>>
>>>>>> +		a10sr_hwmon: a10sr_hwmon {
>>>>>
>>>>> Device type only please.
>>>>>
>>>> I need to revisit where this will live (hwmon does not seem to be
>>>> the correct place) so it will change but I can follow the format
>>>> above if it is correct.
>>>
>>> BTW, "hwmon" is a subsystem in Linux, therefore is a Linuxism and is
>>> not allowed in DT.  What does the device *actually* do?
>>>
>>
>> OK. I'll be careful not to introduce the Linux subsystem name.
>>
>> This module indicates whether the power supplies are at the correct
>> voltage. It uses a boolean instead of giving an actual voltage value
>> as required by HWMON. In other words it is a comparator instead of
>> an Analog-to-Digital Converter.
>>
>> I could call it a power supply supervisor or voltage status monitor
>> but it only acts in a passive role. There is no output to trigger an
>> error - only polling, so supervisor doesn't seem like a good name.
>>
>> Maybe something like this?
>>
>> 	power_supply_status {
>> 		compatible = "altr,a10sr-hwmon";
>> 	}
>>
>> Thanks for reviewing and helping me figure out the device tree naming.
>
> Does it have its own address space?  How complex is the device?  Not
> very, by the sounds of it.  In which case, does it really need its own
> driver?
>
Yes, you are correct that the voltage status is not very complex but I'd 
need a driver to expose these signals.

I initially started with an MFD because it was similar to the other MFD 
drivers. The device has GPI, GPO, voltage status, device enables, device 
present indications, and device resets.

There is a discussion now on where the voltage status driver should live 
(iio/ , hwmon/, misc/). It isn't clear to me where the device enables, 
device present indications and voltage status would go. I'm leaning 
toward a driver in the misc/ directory that would cover all of these. In 
that case, this wouldn't be a MFD driver.

Any thoughts or suggestions?

Thanks,

Thor
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Guenter Roeck April 20, 2016, 1:48 a.m. UTC | #13
On 04/19/2016 07:38 AM, Thor Thayer wrote:
>
>
> On 04/19/2016 02:23 AM, Lee Jones wrote:
>> On Mon, 18 Apr 2016, Thor Thayer wrote:
>>
>>> Hi Lee,
>>>
>>> On 04/18/2016 02:45 AM, Lee Jones wrote:
>>>> On Fri, 15 Apr 2016, Thor Thayer wrote:
>>>>> On 03/30/2016 06:35 AM, Lee Jones wrote:
>>>>>> On Tue, 29 Mar 2016, tthayer@opensource.altera.com wrote:
>>>>>>
>>>>>>> From: Thor Thayer <tthayer@opensource.altera.com>
>>>>>>>
>>>>>>> The Altera Arria10 Devkit System Resource chip is a Multi-Function
>>>>>>> Device, it has two subdevices:
>>>>>>>       - GPIO
>>>>>>>       - HWMON
>>>>>>>
>>>>>>> This patch adds documentation for the Altera A10-SR DT bindings.
>>>>>>>
>>>>>>> Signed-off-by: Thor Thayer <tthayer@opensource.altera.com>
>>>>>>> ---
>>>>>>>   .../devicetree/bindings/mfd/altera-a10sr.txt       |   35 ++++++++++++++++++++
>>>>>>>   1 file changed, 35 insertions(+)
>>>>>>>   create mode 100644 Documentation/devicetree/bindings/mfd/altera-a10sr.txt
>>>>>>>
>>>>>>> diff --git a/Documentation/devicetree/bindings/mfd/altera-a10sr.txt b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
>>>>>>> new file mode 100644
>>>>>>> index 0000000..564c761
>>>>>>> --- /dev/null
>>>>>>> +++ b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
>>>>>>> @@ -0,0 +1,35 @@
>>>>>>> +* Altera Arria10 Development Kit System Resource Chip
>>>>>>> +
>>>>>>> +Required parent device properties:
>>>>>>> +- compatible : "altr,altr_a10sr"
>>>>>>> +- spi-max-frequency : Maximum SPI frequency.
>>>>>>> +- reg : the SPI Chip Select address for the Arria10 System Resource chip
>>>>
>>>> [...]
>>>>
>>>>>>> +        a10sr_hwmon: a10sr_hwmon {
>>>>>>
>>>>>> Device type only please.
>>>>>>
>>>>> I need to revisit where this will live (hwmon does not seem to be
>>>>> the correct place) so it will change but I can follow the format
>>>>> above if it is correct.
>>>>
>>>> BTW, "hwmon" is a subsystem in Linux, therefore is a Linuxism and is
>>>> not allowed in DT.  What does the device *actually* do?
>>>>
>>>
>>> OK. I'll be careful not to introduce the Linux subsystem name.
>>>
>>> This module indicates whether the power supplies are at the correct
>>> voltage. It uses a boolean instead of giving an actual voltage value
>>> as required by HWMON. In other words it is a comparator instead of
>>> an Analog-to-Digital Converter.
>>>
>>> I could call it a power supply supervisor or voltage status monitor
>>> but it only acts in a passive role. There is no output to trigger an
>>> error - only polling, so supervisor doesn't seem like a good name.
>>>
>>> Maybe something like this?
>>>
>>>     power_supply_status {
>>>         compatible = "altr,a10sr-hwmon";
>>>     }
>>>
>>> Thanks for reviewing and helping me figure out the device tree naming.
>>
>> Does it have its own address space?  How complex is the device?  Not
>> very, by the sounds of it.  In which case, does it really need its own
>> driver?
>>
> Yes, you are correct that the voltage status is not very complex but I'd need a driver to expose these signals.
>

A completely different option might be to expose the signals as gpio pins.

Guenter

> I initially started with an MFD because it was similar to the other MFD drivers. The device has GPI, GPO, voltage status, device enables, device present indications, and device resets.
>
> There is a discussion now on where the voltage status driver should live (iio/ , hwmon/, misc/). It isn't clear to me where the device enables, device present indications and voltage status would go. I'm leaning toward a driver in the misc/ directory that would cover all of these. In that case, this wouldn't be a MFD driver.
>
> Any thoughts or suggestions?
>
> Thanks,
>
> Thor
>

--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Patch
diff mbox

diff --git a/Documentation/devicetree/bindings/mfd/altera-a10sr.txt b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
new file mode 100644
index 0000000..564c761
--- /dev/null
+++ b/Documentation/devicetree/bindings/mfd/altera-a10sr.txt
@@ -0,0 +1,35 @@ 
+* Altera Arria10 Development Kit System Resource Chip
+
+Required parent device properties:
+- compatible : "altr,altr_a10sr"
+- spi-max-frequency : Maximum SPI frequency.
+- reg : the SPI Chip Select address for the Arria10 System Resource chip
+
+The A10SR consists of this varied group of sub-devices:
+
+Device                   Description
+------                   ----------
+altr_a10sr_gpio          GPIO Controller
+altr_a10sr_hwmon         Hardware Monitor
+
+The LEDs are implemented entirely in the device tree using
+the gpio-led framework.
+
+Example:
+
+        a10-sr: a10-sr@0 {
+		compatible = "altr,altr-a10sr";
+		reg = <0>;
+		spi-max-frequency = <100000>;
+
+		a10sr_gpio: a10sr_gpio {
+			compatible = "altr,a10sr-gpio";
+			gpio-controller;
+			#gpio-cells = <2>;
+			ngpios = <16>;
+		};
+
+		a10sr_hwmon: a10sr_hwmon {
+			compatible = "altr,a10sr-hwmon";
+		};
+	};