regulator: gpio: Reword the binding document
Subsystems (2)
PATCH v2 1/1 regulator: gpio: Reword the binding document
From: Marek Vasut <[email protected]>
Reword the binding document to make it clear how the propeties work and which properties affect which other properties.
To: [email protected]
---
V2: - Make "gpios" a mandatory property
- Reword "gpio-states" property description
- Change "enable-gpio" to "enable-gpios" to match modern DT rules
Note: The recent gpio-regulator rework caused breakage. While the
changes in the gpio-regulator code were according to the DT binding document, they stopped working with older DTs. Make the binding document clearer to prevent such breakage in the future.
--- .../bindings/regulator/gpio-regulator.txt | 25 +++++++++++++------ 1 file changed, 17 insertions(+), 8 deletions(-)
Documentation/devicetree/bindings/regulator/gpio-regulator.txt +17 -8
@@ -4,16 +4,25 @@ Required properties: - compatible : Must be "regulator-gpio". - regulator-name : Defined in regulator.txt as optional, but required here. -- states : Selection of available voltages and GPIO configs. - if there are no states, then use a fixed regulator +- gpios : Array of one or more GPIO pins used to select the + regulator voltage/current listed in "states". +- states : Selection of available voltages/currents provided by + this regulator and matching GPIO configurations to + achieve them. If there are no states in the "states" + array, use a fixed regulator instead. Optional properties: -- enable-gpio : GPIO to use to enable/disable the regulator. -- gpios : GPIO group used to control voltage. -- gpios-states : gpios pin's initial states array. 0: LOW, 1: HIGH. - defualt is LOW if nothing is specified. +- enable-gpios : GPIO used to enable/disable the regulator. + Warning, the GPIO phandle flags are ignored and the + GPIO polarity is controlled solely by the presence + of "enable-active-high" DT property. This is due to + compatibility with old DTs. +- enable-active-high : Polarity of "enable-gpio" GPIO is active HIGH. + Default is active LOW. +- gpios-states : State of GPIO pins in "gpios" array that is set until + changed by the first consumer. 0: LOW, 1: HIGH. + Default is LOW if nothing else is specified. - startup-delay-us : Startup time in microseconds. -- enable-active-high : Polarity of GPIO is active high (default is low). - regulator-type : Specifies what is being regulated, must be either "voltage" or "current", defaults to voltage.
@@ -30,7 +39,7 @@ Example: regulator-max-microvolt = <2600000>; regulator-boot-on; - enable-gpio = <&gpio0 23 0x4>; + enable-gpios = <&gpio0 23 0x4>; gpios = <&gpio0 24 0x4 &gpio0 25 0x4>; states = <1800000 0x3
Signature · 1 line
2.19.2
Quoted 12 lines · On Mon, Mar 4, 2019 at 8:40 PM <[email protected]> wrote:
From: Marek Vasut <[email protected]>
Reword the binding document to make it clear how the propeties work and which properties affect which other properties.
Signed-off-by Marek Vasut <[email protected]>Cc Harald Geyer <[email protected]>Cc Kuninori Morimoto <[email protected]>Cc Linus Walleij <[email protected]>Cc Mark Brown <[email protected]>Cc Rob Herring <[email protected]>
Quoted 10 lines
To: [email protected]
---
V2: - Make "gpios" a mandatory property
- Reword "gpio-states" property description
- Change "enable-gpio" to "enable-gpios" to match modern DT rules
Note: The recent gpio-regulator rework caused breakage. While the
changes in the gpio-regulator code were according to the DT binding document, they stopped working with older DTs. Make the binding document clearer to prevent such breakage in the future.
Excellent work!
Yours,
Linus Walleij
Quoted 12 lines · [email protected] writes:
From: Marek Vasut <[email protected]>
Reword the binding document to make it clear how the propeties work and which properties affect which other properties.
Signed-off-by Marek Vasut <[email protected]>Cc Harald Geyer <[email protected]>Cc Kuninori Morimoto <[email protected]>Cc Linus Walleij <[email protected]>Cc Mark Brown <[email protected]>Cc Rob Herring <[email protected]>
Quoted 10 lines
To: [email protected]
---
V2: - Make "gpios" a mandatory property
- Reword "gpio-states" property description
- Change "enable-gpio" to "enable-gpios" to match modern DT rules
Note: The recent gpio-regulator rework caused breakage. While the
changes in the gpio-regulator code were according to the DT binding document, they stopped working with older DTs. Make the binding document clearer to prevent such breakage in the future.
Thanks for the update. I think it addresses all my concerns except for one:
Documentation/devicetree/bindings/regulator/gpio-regulator.txt Required properties: · line 24
Quoted 3 lines
+- gpios-states : State of GPIO pins in "gpios" array that is set until
Documentation/devicetree/bindings/regulator/gpio-regulator.txt +2
-0+ changed by the first consumer. 0: LOW, 1: HIGH. + Default is LOW if nothing else is specified.
I still believe this not true: There is no guarantee that the regulator core won't change the state of GPIO pins before the first consumer comes up.
I still think my proposal describes the property more acurately:
gpios-states : On operating systems, that don't support reading back gpio
values in output mode (most notably linux), this array provides the state of GPIO pins set when requesting them from the gpio controller. Systems, that are capable of preserving state when requesting the lines, are free to ignore this property. 0: LOW, 1: HIGH. Default is LOW if nothing else is specified.
Since we had this discussion already in the V1 thread and you clearly don't agree with me, the maintainers will need to decide. You can add
once Rob and/or Mark have addressed this issue.
Thanks for your work!
Harald
Quoted 27 lines · Harald Geyer
Quoted 12 lines · [email protected] writes:
From: Marek Vasut <[email protected]>
Reword the binding document to make it clear how the propeties work and which properties affect which other properties.
Signed-off-by Marek Vasut <[email protected]>Cc Harald Geyer <[email protected]>Cc Kuninori Morimoto <[email protected]>Cc Linus Walleij <[email protected]>Cc Mark Brown <[email protected]>Cc Rob Herring <[email protected]>Quoted 10 lines
To: [email protected]
---
V2: - Make "gpios" a mandatory property
- Reword "gpio-states" property description
- Change "enable-gpio" to "enable-gpios" to match modern DT rules
Note: The recent gpio-regulator rework caused breakage. While the
changes in the gpio-regulator code were according to the DT binding document, they stopped working with older DTs. Make the binding document clearer to prevent such breakage in the future.Thanks for the update. I think it addresses all my concerns except for one:
Quoted 7 lines
Documentation/devicetree/bindings/regulator/gpio-regulator.txt Required properties: · line 24
Quoted 3 lines
+- gpios-states : State of GPIO pins in "gpios" array that is set until
Documentation/devicetree/bindings/regulator/gpio-regulator.txt +2
-0+ changed by the first consumer. 0: LOW, 1: HIGH. + Default is LOW if nothing else is specified.I still believe this not true: There is no guarantee that the regulator core won't change the state of GPIO pins before the first consumer comes up.
Why would it do that ? That would completely invalidate any remaining useful-ness of this property.
Quoted 9 lines
I still think my proposal describes the property more acurately:
gpios-states : On operating systems, that don't support reading back gpio
values in output mode (most notably linux), this array provides the state of GPIO pins set when requesting them from the gpio controller. Systems, that are capable of preserving state when requesting the lines, are free to ignore this property. 0: LOW, 1: HIGH. Default is LOW if nothing else is specified.
Quoted 4 lines
Since we had this discussion already in the V1 thread and you clearly don't agree with me, the maintainers will need to decide. You can add
Reviewed-by Harald Geyer <[email protected]>once Rob and/or Mark have addressed this issue.
I think we're just looking at this from two different perspectives and for whatever reason can't reconcile them.
Quoted 3 lines
Thanks for your work!
Harald
Signature · 2 lines
Best regards, Marek Vasut
Quoted 36 lines · Marek Vasut
Quoted 27 lines · Harald Geyer
Quoted 12 lines · [email protected] writes:
From: Marek Vasut <[email protected]>
Reword the binding document to make it clear how the propeties work and which properties affect which other properties.
Signed-off-by Marek Vasut <[email protected]>Cc Harald Geyer <[email protected]>Cc Kuninori Morimoto <[email protected]>Cc Linus Walleij <[email protected]>Cc Mark Brown <[email protected]>Cc Rob Herring <[email protected]>Quoted 10 lines
To: [email protected]
---
V2: - Make "gpios" a mandatory property
- Reword "gpio-states" property description
- Change "enable-gpio" to "enable-gpios" to match modern DT rules
Note: The recent gpio-regulator rework caused breakage. While the
changes in the gpio-regulator code were according to the DT binding document, they stopped working with older DTs. Make the binding document clearer to prevent such breakage in the future.Thanks for the update. I think it addresses all my concerns except for one:
Quoted 7 lines
Documentation/devicetree/bindings/regulator/gpio-regulator.txt Required properties: · line 24
Quoted 3 lines
+- gpios-states : State of GPIO pins in "gpios" array that is set until
Documentation/devicetree/bindings/regulator/gpio-regulator.txt +2
-0+ changed by the first consumer. 0: LOW, 1: HIGH. + Default is LOW if nothing else is specified.I still believe this not true: There is no guarantee that the regulator core won't change the state of GPIO pins before the first consumer comes up.
Quoted 1 line
Why would it do that ?
Because the regulator core doesn't know about this driver specific property at all. And without any constraints placed by consumers, the core is free to choose any state whatsoever at any point in time.
Quoted 2 lines
That would completely invalidate any remaining
useful-ness of this property.
Yes, I believe this property is mostly useless. That's what I want to get across with my wording proposal. The remaining usecase, that I can see, is when the GPIOs have been setup by the bootloader and we don't want to reset them to low during probing (which some OSes might be capable of, but linux currently doesn't). Also a state of all GPIOs low might be invalid (not in the "states" property), so we shouldn't set all GPIOs to low during probing in that case.
HTH,
Harald
Quoted 25 lines
Quoted 9 lines
I still think my proposal describes the property more acurately:
gpios-states : On operating systems, that don't support reading back gpio
values in output mode (most notably linux), this array provides the state of GPIO pins set when requesting them from the gpio controller. Systems, that are capable of preserving state when requesting the lines, are free to ignore this property. 0: LOW, 1: HIGH. Default is LOW if nothing else is specified.Quoted 4 lines
Since we had this discussion already in the V1 thread and you clearly don't agree with me, the maintainers will need to decide. You can add
Reviewed-by Harald Geyer <[email protected]>once Rob and/or Mark have addressed this issue.
I think we're just looking at this from two different perspectives and for whatever reason can't reconcile them.
Quoted 3 lines
Thanks for your work!
HaraldSignature · 2 lines
Best regards, Marek Vasut
Signature · 4 lines
If you want to support my work: see http://friends.ccbib.org/harald/supporting/ or donate via CLAM to xASPBtezLNqj4cUe8MT5nZjthRSEjrRQXN or via peercoin to P98LRdhit3gZbHDBe7ta5jtXrMJUms4p7w
Quoted 37 lines · Harald Geyer
Quoted 36 lines · Marek Vasut
Quoted 34 lines · Harald Geyer
Quoted 12 lines · [email protected] writes:
From: Marek Vasut <[email protected]>
Reword the binding document to make it clear how the propeties work and which properties affect which other properties.
Signed-off-by Marek Vasut <[email protected]>Cc Harald Geyer <[email protected]>Cc Kuninori Morimoto <[email protected]>Cc Linus Walleij <[email protected]>Cc Mark Brown <[email protected]>Cc Rob Herring <[email protected]>Quoted 10 lines
To: [email protected]
---
V2: - Make "gpios" a mandatory property
- Reword "gpio-states" property description
- Change "enable-gpio" to "enable-gpios" to match modern DT rules
Note: The recent gpio-regulator rework caused breakage. While the
changes in the gpio-regulator code were according to the DT binding document, they stopped working with older DTs. Make the binding document clearer to prevent such breakage in the future.Thanks for the update. I think it addresses all my concerns except for one:
Documentation/devicetree/bindings/regulator/gpio-regulator.txt Required properties: · line 24
Quoted 3 lines
+- gpios-states : State of GPIO pins in "gpios" array that is set until
Documentation/devicetree/bindings/regulator/gpio-regulator.txt +2
-0+ changed by the first consumer. 0: LOW, 1: HIGH. + Default is LOW if nothing else is specified.I still believe this not true: There is no guarantee that the regulator core won't change the state of GPIO pins before the first consumer comes up.
Quoted 5 lines
Quoted 1 line
Why would it do that ?
Because the regulator core doesn't know about this driver specific property at all. And without any constraints placed by consumers, the core is free to choose any state whatsoever at any point in time.
But git grep seems to disagree, see drivers/regulator/gpio-regulator.c:
ret = of_property_read_u32_index(np, "gpios-states", i,
The core sets the pins to such a value until the consumer takes over.
Quoted 10 lines
Quoted 2 lines
That would completely invalidate any remaining
useful-ness of this property.Yes, I believe this property is mostly useless. That's what I want to get across with my wording proposal. The remaining usecase, that I can see, is when the GPIOs have been setup by the bootloader and we don't want to reset them to low during probing (which some OSes might be capable of, but linux currently doesn't). Also a state of all GPIOs low might be invalid (not in the "states" property), so we shouldn't set all GPIOs to low during probing in that case.
I presume the bootloader might even add this property to DT based on the state in which it leaves the GPIOs in.
Quoted 29 lines
HTH,
HaraldQuoted 25 lines
Quoted 9 lines
I still think my proposal describes the property more acurately:
gpios-states : On operating systems, that don't support reading back gpio
values in output mode (most notably linux), this array provides the state of GPIO pins set when requesting them from the gpio controller. Systems, that are capable of preserving state when requesting the lines, are free to ignore this property. 0: LOW, 1: HIGH. Default is LOW if nothing else is specified.Quoted 4 lines
Since we had this discussion already in the V1 thread and you clearly don't agree with me, the maintainers will need to decide. You can add
Reviewed-by Harald Geyer <[email protected]>once Rob and/or Mark have addressed this issue.
I think we're just looking at this from two different perspectives and for whatever reason can't reconcile them.
Quoted 3 lines
Thanks for your work!
HaraldSignature · 2 lines
Best regards, Marek Vasut
Signature · 2 lines
Best regards, Marek Vasut
Quoted 40 lines · Marek Vasut
Quoted 39 lines · Harald Geyer
Quoted 37 lines · Marek Vasut
Quoted 27 lines · Harald Geyer
Quoted 12 lines · [email protected] writes:
From: Marek Vasut <[email protected]>
Reword the binding document to make it clear how the propeties work and which properties affect which other properties.
Signed-off-by Marek Vasut <[email protected]>Cc Harald Geyer <[email protected]>Cc Kuninori Morimoto <[email protected]>Cc Linus Walleij <[email protected]>Cc Mark Brown <[email protected]>Cc Rob Herring <[email protected]>Quoted 10 lines
To: [email protected]
---
V2: - Make "gpios" a mandatory property
- Reword "gpio-states" property description
- Change "enable-gpio" to "enable-gpios" to match modern DT rules
Note: The recent gpio-regulator rework caused breakage. While the
changes in the gpio-regulator code were according to the DT binding document, they stopped working with older DTs. Make the binding document clearer to prevent such breakage in the future.Thanks for the update. I think it addresses all my concerns except for one:
Quoted 7 lines
Documentation/devicetree/bindings/regulator/gpio-regulator.txt Required properties: · line 24
Quoted 3 lines
+- gpios-states : State of GPIO pins in "gpios" array that is set until
Documentation/devicetree/bindings/regulator/gpio-regulator.txt +2
-0+ changed by the first consumer. 0: LOW, 1: HIGH. + Default is LOW if nothing else is specified.I still believe this not true: There is no guarantee that the regulator core won't change the state of GPIO pins before the first consumer comes up.
Why would it do that ?
Quoted 8 lines
Quoted 3 lines
Because the regulator core doesn't know about this driver specific property at all. And without any constraints placed by consumers, the core is free to choose any state whatsoever at any point in time.
But git grep seems to disagree, see
drivers/regulator/gpio-regulator.c:ret = of_property_read_u32_index(np, "gpios-states", i,The core sets the pins to such a value until the consumer takes over.
I think we have a misunderstanding of terminology. When I write "regulator core", I mean the driver independent regulator code. The line you quote above is part of the gpio-regulator driver and thus not part of what I call the "regulator core".
AFAICS the data from the property is only stored in a driver specific data structure (and not used at all outside of probe) but never passed to what I call the regulator core.
Why do you believe there is a guarantee that the value set during probeing is preserved until a consumer takes over?
Harald
Quoted 55 lines · Harald Geyer
Quoted 40 lines · Marek Vasut
Quoted 39 lines · Harald Geyer
Quoted 37 lines · Marek Vasut
Quoted 27 lines · Harald Geyer
Quoted 12 lines · [email protected] writes:
From: Marek Vasut <[email protected]>
Reword the binding document to make it clear how the propeties work and which properties affect which other properties.
Signed-off-by Marek Vasut <[email protected]>Cc Harald Geyer <[email protected]>Cc Kuninori Morimoto <[email protected]>Cc Linus Walleij <[email protected]>Cc Mark Brown <[email protected]>Cc Rob Herring <[email protected]>Quoted 10 lines
To: [email protected]
---
V2: - Make "gpios" a mandatory property
- Reword "gpio-states" property description
- Change "enable-gpio" to "enable-gpios" to match modern DT rules
Note: The recent gpio-regulator rework caused breakage. While the
changes in the gpio-regulator code were according to the DT binding document, they stopped working with older DTs. Make the binding document clearer to prevent such breakage in the future.Thanks for the update. I think it addresses all my concerns except for one:
Quoted 7 lines
Documentation/devicetree/bindings/regulator/gpio-regulator.txt Required properties: · line 24
Quoted 3 lines
+- gpios-states : State of GPIO pins in "gpios" array that is set until
Documentation/devicetree/bindings/regulator/gpio-regulator.txt +2
-0+ changed by the first consumer. 0: LOW, 1: HIGH. + Default is LOW if nothing else is specified.I still believe this not true: There is no guarantee that the regulator core won't change the state of GPIO pins before the first consumer comes up.
Why would it do that ?
Quoted 8 lines
Quoted 3 lines
Because the regulator core doesn't know about this driver specific property at all. And without any constraints placed by consumers, the core is free to choose any state whatsoever at any point in time.
But git grep seems to disagree, see
drivers/regulator/gpio-regulator.c:ret = of_property_read_u32_index(np, "gpios-states", i,The core sets the pins to such a value until the consumer takes over.
I think we have a misunderstanding of terminology. When I write "regulator core", I mean the driver independent regulator code. The line you quote above is part of the gpio-regulator driver and thus not part of what I call the "regulator core".
Quoted 6 lines
AFAICS the data from the property is only stored in a driver specific data structure (and not used at all outside of probe) but never passed to what I call the regulator core.
Why do you believe there is a guarantee that the value set during probeing is preserved until a consumer takes over?
It is the only sensible behavior and the behavior I see people expect from this property. I presume it solidified in this sort of semi-defined state, so we're stuck with assuming it behaves this way to maintain compatibility.
Signature · 2 lines
Best regards, Marek Vasut
Quoted 60 lines · Marek Vasut
Quoted 59 lines · Harald Geyer
Quoted 40 lines · Marek Vasut
Quoted 39 lines · Harald Geyer
Quoted 37 lines · Marek Vasut
Quoted 27 lines · Harald Geyer
Quoted 12 lines · [email protected] writes:
From: Marek Vasut <[email protected]>
Reword the binding document to make it clear how the propeties work and which properties affect which other properties.
Signed-off-by Marek Vasut <[email protected]>Cc Harald Geyer <[email protected]>Cc Kuninori Morimoto <[email protected]>Cc Linus Walleij <[email protected]>Cc Mark Brown <[email protected]>Cc Rob Herring <[email protected]>Quoted 10 lines
To: [email protected]
---
V2: - Make "gpios" a mandatory property
- Reword "gpio-states" property description
- Change "enable-gpio" to "enable-gpios" to match modern DT rules
Note: The recent gpio-regulator rework caused breakage. While the
changes in the gpio-regulator code were according to the DT binding document, they stopped working with older DTs. Make the binding document clearer to prevent such breakage in the future.Thanks for the update. I think it addresses all my concerns except for one:
Quoted 7 lines
Review
Quoted 3 lines
+- gpios-states : State of GPIO pins in "gpios" array that is set until
(quoted diff) +2
-0+ changed by the first consumer. 0: LOW, 1: HIGH. + Default is LOW if nothing else is specified.I still believe this not true: There is no guarantee that the regulator core won't change the state of GPIO pins before the first consumer comes up.
Why would it do that ?
Quoted 8 lines
Quoted 3 lines
Because the regulator core doesn't know about this driver specific property at all. And without any constraints placed by consumers, the core is free to choose any state whatsoever at any point in time.
But git grep seems to disagree, see
drivers/regulator/gpio-regulator.c:ret = of_property_read_u32_index(np, "gpios-states", i,The core sets the pins to such a value until the consumer takes over.
I think we have a misunderstanding of terminology. When I write "regulator core", I mean the driver independent regulator code. The line you quote above is part of the gpio-regulator driver and thus not part of what I call the "regulator core".
AFAICS the data from the property is only stored in a driver specific data structure (and not used at all outside of probe) but never passed to what I call the regulator core.
Quoted 7 lines
Quoted 2 lines
Why do you believe there is a guarantee that the value set during probeing is preserved until a consumer takes over?
It is the only sensible behavior and the behavior I see people expect from this property. I presume it solidified in this sort of semi-defined state, so we're stuck with assuming it behaves this way to maintain compatibility.
Maybe the behaviour you want would be more sensible, but AFAIK it just isn't true in general (it might work that way by chance in many cases). If people expect this behaviour, it is a misunderstanding of the old wording. I'd prefer we don't have to add a quirk to the regulator subsystem to cater for a misunderstanding.
I think, if you really want to go forward with making this behaviour officially maintained, then we should first add the code to linux and only then add the promise to the binding document. This isn't the scope of this patch, so I guess we would need to keep the ambiguous wording as it is for now. I believe it is more important for a binding document to be correct than to be sensible.
However I don't think we actually need to go to such extremes: In linux we currently have (arm/boot/dts and arm64/boot/dts) 38 uses of this property in 29 DTs. All the examples, that I studied in some detail, seem to either don't need this property at all or have a usecase that is supported by my proposed wording. I don't expect any problems if we just document the status quo clearly.
Harald
Quoted 82 lines · Harald Geyer
Quoted 60 lines · Marek Vasut
Quoted 59 lines · Harald Geyer
Quoted 40 lines · Marek Vasut
Quoted 39 lines · Harald Geyer
Quoted 37 lines · Marek Vasut
Quoted 27 lines · Harald Geyer
Quoted 12 lines · [email protected] writes:
From: Marek Vasut <[email protected]>
Reword the binding document to make it clear how the propeties work and which properties affect which other properties.
Signed-off-by Marek Vasut <[email protected]>Cc Harald Geyer <[email protected]>Cc Kuninori Morimoto <[email protected]>Cc Linus Walleij <[email protected]>Cc Mark Brown <[email protected]>Cc Rob Herring <[email protected]>Quoted 10 lines
To: [email protected]
---
V2: - Make "gpios" a mandatory property
- Reword "gpio-states" property description
- Change "enable-gpio" to "enable-gpios" to match modern DT rules
Note: The recent gpio-regulator rework caused breakage. While the
changes in the gpio-regulator code were according to the DT binding document, they stopped working with older DTs. Make the binding document clearer to prevent such breakage in the future.Thanks for the update. I think it addresses all my concerns except for one:
Quoted 7 lines
Review
Quoted 3 lines
+- gpios-states : State of GPIO pins in "gpios" array that is set until
(quoted diff) +2
-0+ changed by the first consumer. 0: LOW, 1: HIGH. + Default is LOW if nothing else is specified.I still believe this not true: There is no guarantee that the regulator core won't change the state of GPIO pins before the first consumer comes up.
Why would it do that ?
Quoted 8 lines
Quoted 3 lines
Because the regulator core doesn't know about this driver specific property at all. And without any constraints placed by consumers, the core is free to choose any state whatsoever at any point in time.
But git grep seems to disagree, see
drivers/regulator/gpio-regulator.c:ret = of_property_read_u32_index(np, "gpios-states", i,The core sets the pins to such a value until the consumer takes over.
I think we have a misunderstanding of terminology. When I write "regulator core", I mean the driver independent regulator code. The line you quote above is part of the gpio-regulator driver and thus not part of what I call the "regulator core".
AFAICS the data from the property is only stored in a driver specific data structure (and not used at all outside of probe) but never passed to what I call the regulator core.
Quoted 7 lines
Quoted 2 lines
Why do you believe there is a guarantee that the value set during probeing is preserved until a consumer takes over?
It is the only sensible behavior and the behavior I see people expect from this property. I presume it solidified in this sort of semi-defined state, so we're stuck with assuming it behaves this way to maintain compatibility.
Maybe the behaviour you want would be more sensible, but AFAIK it just isn't true in general (it might work that way by chance in many cases). If people expect this behaviour, it is a misunderstanding of the old wording. I'd prefer we don't have to add a quirk to the regulator subsystem to cater for a misunderstanding.
I think, if you really want to go forward with making this behaviour officially maintained, then we should first add the code to linux and only then add the promise to the binding document. This isn't the scope of this patch, so I guess we would need to keep the ambiguous wording as it is for now. I believe it is more important for a binding document to be correct than to be sensible.
Quoted 6 lines
However I don't think we actually need to go to such extremes: In linux we currently have (arm/boot/dts and arm64/boot/dts) 38 uses of this property in 29 DTs. All the examples, that I studied in some detail, seem to either don't need this property at all or have a usecase that is supported by my proposed wording. I don't expect any problems if we just document the status quo clearly.
In that case, provide a suggestion how to document this property better?
Signature · 2 lines
Best regards, Marek Vasut
Quoted 89 lines · Marek Vasut
Quoted 88 lines · Harald Geyer
Quoted 66 lines · Marek Vasut
Quoted 65 lines · Harald Geyer
Quoted 49 lines · Marek Vasut
Quoted 42 lines · Harald Geyer
Quoted 41 lines · Marek Vasut
Quoted 39 lines · Harald Geyer
Quoted 12 lines · [email protected] writes:
From: Marek Vasut <[email protected]>
Reword the binding document to make it clear how the propeties work and which properties affect which other properties.
Signed-off-by Marek Vasut <[email protected]>Cc Harald Geyer <[email protected]>Cc Kuninori Morimoto <[email protected]>Cc Linus Walleij <[email protected]>Cc Mark Brown <[email protected]>Cc Rob Herring <[email protected]>Quoted 14 lines
To: [email protected]
---
V2: - Make "gpios" a mandatory property
- Reword "gpio-states" property description
- Change "enable-gpio" to "enable-gpios" to match modern
DT rules
Note: The recent gpio-regulator rework caused breakage. While the
changes in the gpio-regulator code were according to
the DT
binding document, they stopped working with older DTs.
Make
the binding document clearer to prevent such breakage
in the
future.Thanks for the update. I think it addresses all my concerns except for one:
Review
Quoted 4 lines
+- gpios-states : State of GPIO pins in "gpios" array that is
set until(quoted diff) +2
-0+ changed by the first consumer. 0: LOW, 1: HIGH. + Default is LOW if nothing else is specified.I still believe this not true: There is no guarantee that the regulator core won't change the state of GPIO pins before the first consumer comes up.
Quoted 5 lines
Quoted 1 line
Why would it do that ?
Because the regulator core doesn't know about this driver specific property at all. And without any constraints placed by consumers, the core is free to choose any state whatsoever at any point in time.
Quoted 5 lines
But git grep seems to disagree, see
drivers/regulator/gpio-regulator.c:
ret = of_property_read_u32_index(np,
"gpios-states", i,The core sets the pins to such a value until the consumer takes over.
I think we have a misunderstanding of terminology. When I write "regulator core", I mean the driver independent regulator code. The line you quote above is part of the gpio-regulator driver and thus not part of what I call the "regulator core".
AFAICS the data from the property is only stored in a driver specific data structure (and not used at all outside of probe) but never passed to what I call the regulator core.
Quoted 7 lines
Quoted 2 lines
Why do you believe there is a guarantee that the value set during probeing is preserved until a consumer takes over?
It is the only sensible behavior and the behavior I see people expect from this property. I presume it solidified in this sort of semi-defined state, so we're stuck with assuming it behaves this way to maintain compatibility.
Maybe the behaviour you want would be more sensible, but AFAIK it just isn't true in general (it might work that way by chance in many cases). If people expect this behaviour, it is a misunderstanding of the old wording. I'd prefer we don't have to add a quirk to the regulator subsystem to cater for a misunderstanding.
I think, if you really want to go forward with making this behaviour officially maintained, then we should first add the code to linux and only then add the promise to the binding document. This isn't the scope of this patch, so I guess we would need to keep the ambiguous wording as it is for now. I believe it is more important for a binding document to be correct than to be sensible.
Quoted 8 lines
Quoted 6 lines
However I don't think we actually need to go to such extremes: In linux we currently have (arm/boot/dts and arm64/boot/dts) 38 uses of this property in 29 DTs. All the examples, that I studied in some detail, seem to either don't need this property at all or have a usecase that is supported by my proposed wording. I don't expect any problems if we just document the status quo clearly.
In that case, provide a suggestion how to document this property better?
I did: https://www.spinics.net/lists/devicetree/msg275050.html
HTH,
Harald
Signature · 4 lines
If you want to support my work: see http://friends.ccbib.org/harald/supporting/ or donate via peercoin to P98LRdhit3gZbHDBe7ta5jtXrMJUms4p7w or CLAM xASPBtezLNqj4cUe8MT5nZjthRSEjrRQXN
Quoted 105 lines · Harald Geyer
Quoted 104 lines · Marek Vasut
Quoted 102 lines · Harald Geyer
Quoted 72 lines · Marek Vasut
Quoted 71 lines · Harald Geyer
Quoted 52 lines · Marek Vasut
Quoted 44 lines · Harald Geyer
Quoted 43 lines · Marek Vasut
Quoted 41 lines · Harald Geyer
Quoted 13 lines · [email protected] writes:
From: Marek Vasut <[email protected]>
Reword the binding document to make it clear how the propeties work
and which properties affect which other properties.Signed-off-by Marek Vasut <[email protected]>Cc Harald Geyer <[email protected]>Cc Kuninori Morimoto <[email protected]>Cc Linus Walleij <[email protected]>Cc Mark Brown <[email protected]>Cc Rob Herring <[email protected]>Quoted 12 lines
To: [email protected]
---
V2: - Make "gpios" a mandatory property
- Reword "gpio-states" property description
- Change "enable-gpio" to "enable-gpios" to match modern DT rules
Note: The recent gpio-regulator rework caused breakage. While the changes in the gpio-regulator code were according to the DT binding document, they stopped working with older DTs. Make the binding document clearer to prevent such breakage in the
future.Thanks for the update. I think it addresses all my concerns except for
one:Quoted 4 lines
+- gpios-states : State of GPIO pins in "gpios" array that is set until
+ changed by the first consumer. 0: LOW, 1: HIGH. + Default is LOW if nothing else is specified.I still believe this not true: There is no guarantee that the regulator
core won't change the state of GPIO pins before the first consumer comes
up.Quoted 6 lines
Quoted 1 line
Why would it do that ?
Because the regulator core doesn't know about this driver specific property at all. And without any constraints placed by consumers, the
core is free to choose any state whatsoever at any point in time.Quoted 6 lines
But git grep seems to disagree, see
drivers/regulator/gpio-regulator.c:
ret = of_property_read_u32_index(np, "gpios-states", i,The core sets the pins to such a value until the consumer takes over.
I think we have a misunderstanding of terminology. When I write "regulator
core", I mean the driver independent regulator code. The line you quote
above is part of the gpio-regulator driver and thus not part of what I call the "regulator core".AFAICS the data from the property is only stored in a driver specific data structure (and not used at all outside of probe) but never passed to what I call the regulator core.
Quoted 8 lines
Quoted 2 lines
Why do you believe there is a guarantee that the value set during probeing is preserved until a consumer takes over?
It is the only sensible behavior and the behavior I see people expect from this property. I presume it solidified in this sort of semi-defined
state, so we're stuck with assuming it behaves this way to maintain compatibility.Maybe the behaviour you want would be more sensible, but AFAIK it just isn't true in general (it might work that way by chance in many cases). If people expect this behaviour, it is a misunderstanding of the old wording.
I'd prefer we don't have to add a quirk to the regulator subsystem to cater for a misunderstanding.I think, if you really want to go forward with making this behaviour officially maintained, then we should first add the code to linux and only then add the promise to the binding document. This isn't the scope of this patch, so I guess we would need to keep the ambiguous wording as it is for now. I believe it is more important for a binding document to be correct than to be sensible.
However I don't think we actually need to go to such extremes: In linux we currently have (arm/boot/dts and arm64/boot/dts) 38 uses of this property in 29 DTs. All the examples, that I studied in some detail, seem to either don't need this property at all or have a usecase that is supported by my proposed wording. I don't expect any problems if we just document the status quo clearly.
Quoted 3 lines
Quoted 1 line
In that case, provide a suggestion how to document this property better?
I did: https://www.spinics.net/lists/devicetree/msg275050.html
I don't like it, but I added it there and sent V3, let's see what others think.
Signature · 2 lines
Best regards, Marek Vasut