| Message ID | 20230313161138.3598068-4-sean.anderson@seco.com |
|---|---|
| State | Changes Requested, archived |
| Headers | show |
| Series | phy: Add support for Lynx 10G SerDes | expand |
| Context | Check | Description |
|---|---|---|
| robh/checkpatch | warning | total: 0 errors, 3 warnings, 174 lines checked |
| robh/patch-applied | success | |
| robh/dt-meta-schema | fail | build log |
On Mon, Mar 13, 2023 at 5:12 PM Sean Anderson <sean.anderson@seco.com> wrote: > This is a generic binding for simple MMIO GPIO controllers. Although we > have a single driver for these controllers, they were previously spread > over several files. Consolidate them. The register descriptions are > adapted from the comments in the source. There is no set order for the > registers, so I have not specified one. > > Rename brcm,bcm6345-gpio to brcm,bcm63xx-gpio to reflect that bcm6345 > has moved. > > Signed-off-by: Sean Anderson <sean.anderson@seco.com> > Reviewed-by: Linus Walleij <linus.walleij@linaro.org> > --- > Linus or Bartosz, feel free to pick this up as the rest of this series > may not be merged any time soon. I think Bartosz will pick this as soon as the DT maintainers ACK it. Yours, Linus Walleij
On 13/03/2023 17:11, Sean Anderson wrote: > This is a generic binding for simple MMIO GPIO controllers. Although we > have a single driver for these controllers, they were previously spread > over several files. Consolidate them. The register descriptions are > adapted from the comments in the source. There is no set order for the > registers, so I have not specified one. > > Rename brcm,bcm6345-gpio to brcm,bcm63xx-gpio to reflect that bcm6345 > has moved. > > Signed-off-by: Sean Anderson <sean.anderson@seco.com> > Reviewed-by: Linus Walleij <linus.walleij@linaro.org> > --- > Linus or Bartosz, feel free to pick this up as the rest of this series > may not be merged any time soon. > > Changes in v11: > - Keep empty (or almost-empty) properties on a single line > - Don't use | unnecessarily > - Use gpio as the node name for examples > - Rename brcm,bcm6345-gpio.yaml to brcm,bcm63xx-gpio.yaml > > Changes in v10: > - New > > ...m6345-gpio.yaml => brcm,bcm63xx-gpio.yaml} | 16 +-- > .../devicetree/bindings/gpio/gpio-mmio.yaml | 134 ++++++++++++++++++ > .../bindings/gpio/ni,169445-nand-gpio.txt | 38 ----- > .../devicetree/bindings/gpio/wd,mbl-gpio.txt | 38 ----- > 4 files changed, 135 insertions(+), 91 deletions(-) > rename Documentation/devicetree/bindings/gpio/{brcm,bcm6345-gpio.yaml => brcm,bcm63xx-gpio.yaml} (78%) > create mode 100644 Documentation/devicetree/bindings/gpio/gpio-mmio.yaml > delete mode 100644 Documentation/devicetree/bindings/gpio/ni,169445-nand-gpio.txt > delete mode 100644 Documentation/devicetree/bindings/gpio/wd,mbl-gpio.txt > > diff --git a/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml b/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml > similarity index 78% > rename from Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml > rename to Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml > index 4d69f79df859..e11f4af49c52 100644 > --- a/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml > +++ b/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml > + > +description: > + Some simple GPIO controllers may consist of a single data register or a pair > + of set/clear-bit registers. Such controllers are common for glue logic in > + FPGAs or ASICs. Commonly, these controllers are accessed over memory-mapped > + NAND-style parallel busses. > + > +properties: > + big-endian: true > + > + compatible: Keep compatible as first property. > + enum: > + - brcm,bcm6345-gpio # Broadcom BCM6345 GPIO controller > + - wd,mbl-gpio # Western Digital MyBook Live memory-mapped GPIO controller > + - ni,169445-nand-gpio # National Instruments 169445 GPIO NAND controller I think you got comment that these comments are making things unreadable. I don't see here improvement. For example first comment is useless - you say the same as compatible. Same with last one. So only remaining WD comment should be made in new line so everything is nicely readable. BTW, order the enum by name. > + > + '#gpio-cells': > + const: 2 > + > + gpio-controller: > + true I am sure I saw comments here... https://lore.kernel.org/all/20230308231018.GA4039466-robh@kernel.org/ > + > + reg: > + minItems: 1 > + description: > + A list of registers in the controller. The width of each register is > + determined by its size. I don't understand this comment. Aren't you describing now what 'reg' is in DT spec? If so, drop. If not, please share more. > All registers must have the same width. The number > + of GPIOs is set by the width, with bit 0 corresponding to GPIO 0. > + items: > + - description: > + Register to READ the value of the GPIO lines. If GPIO line is high, > + the bit will be set. If the GPIO line is low, the bit will be cleared. > + This register may also be used to drive GPIOs if the SET register is > + omitted. > + - description: > + Register to SET the value of the GPIO lines. Setting a bit in this > + register will drive the GPIO line high. > + - description: > + Register to CLEAR the value of the GPIO lines. Setting a bit in this > + register will drive the GPIO line low. If this register is omitted, > + the SET register will be used to clear the GPIO lines as well, by > + actively writing the line with 0. > + - description: > + Register to set the line as OUTPUT. Setting a bit in this register > + will turn that line into an output line. Conversely, clearing a bit > + will turn that line into an input. > + - description: > + Register to set this line as INPUT. Setting a bit in this register > + will turn that line into an input line. Conversely, clearing a bit > + will turn that line into an output. > + > + reg-names: > + minItems: 1 > + maxItems: 5 > + items: > + enum: Why this is in any order? Other bindings were here specific, your 'reg' is also specific/fixed. > + - dat > + - set > + - clr > + - dirout > + - dirin > + > + native-endian: true > + > + no-output: > + $ref: /schemas/types.yaml#/definitions/flag > + description: > + If this property is present, the controller cannot drive the GPIO lines. > + > +required: > + - compatible > + - reg > + - reg-names > + - '#gpio-cells' > + - gpio-controller > + > +additionalProperties: false > + > +examples: > + - | > + gpio@1f300010 { > + compatible = "ni,169445-nand-gpio"; > + reg = <0x1f300010 0x4>; > + reg-names = "dat"; > + gpio-controller; > + #gpio-cells = <2>; > + }; > + > + gpio@1f300014 { > + compatible = "ni,169445-nand-gpio"; > + reg = <0x1f300014 0x4>; > + reg-names = "dat"; > + gpio-controller; > + #gpio-cells = <2>; > + no-output; > + }; No need to duplicate examples. Keep only one. Everything is the same. Best regards, Krzysztof
On 3/14/23 13:56, Krzysztof Kozlowski wrote: > On 13/03/2023 17:11, Sean Anderson wrote: >> This is a generic binding for simple MMIO GPIO controllers. Although we >> have a single driver for these controllers, they were previously spread >> over several files. Consolidate them. The register descriptions are >> adapted from the comments in the source. There is no set order for the >> registers, so I have not specified one. >> >> Rename brcm,bcm6345-gpio to brcm,bcm63xx-gpio to reflect that bcm6345 >> has moved. >> >> Signed-off-by: Sean Anderson <sean.anderson@seco.com> >> Reviewed-by: Linus Walleij <linus.walleij@linaro.org> >> --- >> Linus or Bartosz, feel free to pick this up as the rest of this series >> may not be merged any time soon. >> >> Changes in v11: >> - Keep empty (or almost-empty) properties on a single line >> - Don't use | unnecessarily >> - Use gpio as the node name for examples >> - Rename brcm,bcm6345-gpio.yaml to brcm,bcm63xx-gpio.yaml >> >> Changes in v10: >> - New >> >> ...m6345-gpio.yaml => brcm,bcm63xx-gpio.yaml} | 16 +-- >> .../devicetree/bindings/gpio/gpio-mmio.yaml | 134 ++++++++++++++++++ >> .../bindings/gpio/ni,169445-nand-gpio.txt | 38 ----- >> .../devicetree/bindings/gpio/wd,mbl-gpio.txt | 38 ----- >> 4 files changed, 135 insertions(+), 91 deletions(-) >> rename Documentation/devicetree/bindings/gpio/{brcm,bcm6345-gpio.yaml => brcm,bcm63xx-gpio.yaml} (78%) >> create mode 100644 Documentation/devicetree/bindings/gpio/gpio-mmio.yaml >> delete mode 100644 Documentation/devicetree/bindings/gpio/ni,169445-nand-gpio.txt >> delete mode 100644 Documentation/devicetree/bindings/gpio/wd,mbl-gpio.txt >> >> diff --git a/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml b/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml >> similarity index 78% >> rename from Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml >> rename to Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml >> index 4d69f79df859..e11f4af49c52 100644 >> --- a/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml >> +++ b/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml > > >> + >> +description: >> + Some simple GPIO controllers may consist of a single data register or a pair >> + of set/clear-bit registers. Such controllers are common for glue logic in >> + FPGAs or ASICs. Commonly, these controllers are accessed over memory-mapped >> + NAND-style parallel busses. >> + >> +properties: >> + big-endian: true >> + >> + compatible: > > Keep compatible as first property. I thought it was alphabetical. >> + enum: >> + - brcm,bcm6345-gpio # Broadcom BCM6345 GPIO controller >> + - wd,mbl-gpio # Western Digital MyBook Live memory-mapped GPIO controller >> + - ni,169445-nand-gpio # National Instruments 169445 GPIO NAND controller > > I think you got comment that these comments are making things > unreadable. I don't see here improvement. That was not the comment I got. | I think you can inline description: statements in the enum instead of | the # hash comments, however IIRC you have to use oneOf and | const: to do it, like I do in | Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma340.yaml | but don't overinvest in this if it is cumbersome. I investigated this and determined it was cumbersome. > For example first comment is useless - you say the same as compatible. > Same with last one. So only remaining WD comment should be made in new > line so everything is nicely readable. I don't understand what you mean by "made in new line". Anyway, I will leave just the WD comment. > BTW, order the enum by name. OK >> + >> + '#gpio-cells': >> + const: 2 >> + >> + gpio-controller: >> + true > > I am sure I saw comments here... > > https://lore.kernel.org/all/20230308231018.GA4039466-robh@kernel.org/ OK >> + >> + reg: >> + minItems: 1 >> + description: >> + A list of registers in the controller. The width of each register is >> + determined by its size. > > I don't understand this comment. Aren't you describing now what 'reg' is > in DT spec? If so, drop. If not, please share more. Each register describes exactly one hardware register. In some other device, when you see `regs = <0x8000000 0x100>`, then you may have 64 32-bit registers. But for this device, it would be one 2048-bit register. >> All registers must have the same width. The number >> + of GPIOs is set by the width, with bit 0 corresponding to GPIO 0. >> + items: >> + - description: >> + Register to READ the value of the GPIO lines. If GPIO line is high, >> + the bit will be set. If the GPIO line is low, the bit will be cleared. >> + This register may also be used to drive GPIOs if the SET register is >> + omitted. >> + - description: >> + Register to SET the value of the GPIO lines. Setting a bit in this >> + register will drive the GPIO line high. >> + - description: >> + Register to CLEAR the value of the GPIO lines. Setting a bit in this >> + register will drive the GPIO line low. If this register is omitted, >> + the SET register will be used to clear the GPIO lines as well, by >> + actively writing the line with 0. >> + - description: >> + Register to set the line as OUTPUT. Setting a bit in this register >> + will turn that line into an output line. Conversely, clearing a bit >> + will turn that line into an input. >> + - description: >> + Register to set this line as INPUT. Setting a bit in this register >> + will turn that line into an input line. Conversely, clearing a bit >> + will turn that line into an output. >> + >> + reg-names: >> + minItems: 1 >> + maxItems: 5 >> + items: >> + enum: > > Why this is in any order? Other bindings were here specific, your 'reg' > is also specific/fixed. Some devicetrees have dirout first, and other have dat first. There is no mandatory order, and some registers can be included or left out as is convenient to the devicetree author. reg is not specific/fixed either. It is just done that way for convenience (and to match the names here). >> + - dat >> + - set >> + - clr >> + - dirout >> + - dirin >> + >> + native-endian: true >> + >> + no-output: >> + $ref: /schemas/types.yaml#/definitions/flag >> + description: >> + If this property is present, the controller cannot drive the GPIO lines. >> + >> +required: >> + - compatible >> + - reg >> + - reg-names >> + - '#gpio-cells' >> + - gpio-controller >> + >> +additionalProperties: false >> + >> +examples: >> + - | >> + gpio@1f300010 { >> + compatible = "ni,169445-nand-gpio"; >> + reg = <0x1f300010 0x4>; >> + reg-names = "dat"; >> + gpio-controller; >> + #gpio-cells = <2>; >> + }; >> + >> + gpio@1f300014 { >> + compatible = "ni,169445-nand-gpio"; >> + reg = <0x1f300014 0x4>; >> + reg-names = "dat"; >> + gpio-controller; >> + #gpio-cells = <2>; >> + no-output; >> + }; > > No need to duplicate examples. Keep only one. OK > Everything is the same. Except no-output. --Sean
On 14/03/2023 19:09, Sean Anderson wrote: > On 3/14/23 13:56, Krzysztof Kozlowski wrote: >> On 13/03/2023 17:11, Sean Anderson wrote: >>> This is a generic binding for simple MMIO GPIO controllers. Although we >>> have a single driver for these controllers, they were previously spread >>> over several files. Consolidate them. The register descriptions are >>> adapted from the comments in the source. There is no set order for the >>> registers, so I have not specified one. >>> >>> Rename brcm,bcm6345-gpio to brcm,bcm63xx-gpio to reflect that bcm6345 >>> has moved. >>> >>> Signed-off-by: Sean Anderson <sean.anderson@seco.com> >>> Reviewed-by: Linus Walleij <linus.walleij@linaro.org> >>> --- >>> Linus or Bartosz, feel free to pick this up as the rest of this series >>> may not be merged any time soon. >>> >>> Changes in v11: >>> - Keep empty (or almost-empty) properties on a single line >>> - Don't use | unnecessarily >>> - Use gpio as the node name for examples >>> - Rename brcm,bcm6345-gpio.yaml to brcm,bcm63xx-gpio.yaml >>> >>> Changes in v10: >>> - New >>> >>> ...m6345-gpio.yaml => brcm,bcm63xx-gpio.yaml} | 16 +-- >>> .../devicetree/bindings/gpio/gpio-mmio.yaml | 134 ++++++++++++++++++ >>> .../bindings/gpio/ni,169445-nand-gpio.txt | 38 ----- >>> .../devicetree/bindings/gpio/wd,mbl-gpio.txt | 38 ----- >>> 4 files changed, 135 insertions(+), 91 deletions(-) >>> rename Documentation/devicetree/bindings/gpio/{brcm,bcm6345-gpio.yaml => brcm,bcm63xx-gpio.yaml} (78%) >>> create mode 100644 Documentation/devicetree/bindings/gpio/gpio-mmio.yaml >>> delete mode 100644 Documentation/devicetree/bindings/gpio/ni,169445-nand-gpio.txt >>> delete mode 100644 Documentation/devicetree/bindings/gpio/wd,mbl-gpio.txt >>> >>> diff --git a/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml b/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml >>> similarity index 78% >>> rename from Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml >>> rename to Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml >>> index 4d69f79df859..e11f4af49c52 100644 >>> --- a/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml >>> +++ b/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml >> >> >>> + >>> +description: >>> + Some simple GPIO controllers may consist of a single data register or a pair >>> + of set/clear-bit registers. Such controllers are common for glue logic in >>> + FPGAs or ASICs. Commonly, these controllers are accessed over memory-mapped >>> + NAND-style parallel busses. >>> + >>> +properties: >>> + big-endian: true >>> + >>> + compatible: >> >> Keep compatible as first property. > > I thought it was alphabetical. There is no clear rule, except that compatible is always first. In the DTS reg is second, in bindings usually as well but not always. > >>> + enum: >>> + - brcm,bcm6345-gpio # Broadcom BCM6345 GPIO controller >>> + - wd,mbl-gpio # Western Digital MyBook Live memory-mapped GPIO controller >>> + - ni,169445-nand-gpio # National Instruments 169445 GPIO NAND controller >> >> I think you got comment that these comments are making things >> unreadable. I don't see here improvement. > > That was not the comment I got. OK > > | I think you can inline description: statements in the enum instead of > | the # hash comments, however IIRC you have to use oneOf and > | const: to do it, like I do in > | Documentation/devicetree/bindings/input/touchscreen/cypress,cy8ctma340.yaml > | but don't overinvest in this if it is cumbersome. > > I investigated this and determined it was cumbersome. So just : # Western Digital MyBook Live memory-mapped GPIO controller - wd,mbl-gpio > >> For example first comment is useless - you say the same as compatible. >> Same with last one. So only remaining WD comment should be made in new >> line so everything is nicely readable. > > I don't understand what you mean by "made in new line". Anyway, I will > leave just the WD comment. > >> BTW, order the enum by name. > > OK > >>> + >>> + '#gpio-cells': >>> + const: 2 >>> + >>> + gpio-controller: >>> + true >> >> I am sure I saw comments here... >> >> https://lore.kernel.org/all/20230308231018.GA4039466-robh@kernel.org/ > > OK > >>> + >>> + reg: >>> + minItems: 1 >>> + description: >>> + A list of registers in the controller. The width of each register is >>> + determined by its size. >> >> I don't understand this comment. Aren't you describing now what 'reg' is >> in DT spec? If so, drop. If not, please share more. > > Each register describes exactly one hardware register. In some other > device, when you see `regs = <0x8000000 0x100>`, then you may have 64 > 32-bit registers. But for this device, it would be one 2048-bit > register. Ah, so you do not mean here address space size? OK then, thanks for clarification. > >>> All registers must have the same width. The number >>> + of GPIOs is set by the width, with bit 0 corresponding to GPIO 0. >>> + items: >>> + - description: >>> + Register to READ the value of the GPIO lines. If GPIO line is high, >>> + the bit will be set. If the GPIO line is low, the bit will be cleared. >>> + This register may also be used to drive GPIOs if the SET register is >>> + omitted. >>> + - description: >>> + Register to SET the value of the GPIO lines. Setting a bit in this >>> + register will drive the GPIO line high. >>> + - description: >>> + Register to CLEAR the value of the GPIO lines. Setting a bit in this >>> + register will drive the GPIO line low. If this register is omitted, >>> + the SET register will be used to clear the GPIO lines as well, by >>> + actively writing the line with 0. >>> + - description: >>> + Register to set the line as OUTPUT. Setting a bit in this register >>> + will turn that line into an output line. Conversely, clearing a bit >>> + will turn that line into an input. >>> + - description: >>> + Register to set this line as INPUT. Setting a bit in this register >>> + will turn that line into an input line. Conversely, clearing a bit >>> + will turn that line into an output. >>> + >>> + reg-names: >>> + minItems: 1 >>> + maxItems: 5 >>> + items: >>> + enum: >> >> Why this is in any order? Other bindings were here specific, your 'reg' >> is also specific/fixed. > > Some devicetrees have dirout first, and other have dat first. There is no > mandatory order, and some registers can be included or left out as is > convenient to the devicetree author. > > reg is not specific/fixed either. It is just done that way for > convenience (and to match the names here). The items have order and usually we require strict order from DTS, unless there is a reason. If there is no reason, use fixed order and then fix the DTS. > >>> + - dat >>> + - set >>> + - clr >>> + - dirout >>> + - dirin >>> + >>> + native-endian: true >>> + >>> + no-output: >>> + $ref: /schemas/types.yaml#/definitions/flag >>> + description: >>> + If this property is present, the controller cannot drive the GPIO lines. >>> + >>> +required: >>> + - compatible >>> + - reg >>> + - reg-names >>> + - '#gpio-cells' >>> + - gpio-controller >>> + >>> +additionalProperties: false >>> + >>> +examples: >>> + - | >>> + gpio@1f300010 { >>> + compatible = "ni,169445-nand-gpio"; >>> + reg = <0x1f300010 0x4>; >>> + reg-names = "dat"; >>> + gpio-controller; >>> + #gpio-cells = <2>; >>> + }; >>> + >>> + gpio@1f300014 { >>> + compatible = "ni,169445-nand-gpio"; >>> + reg = <0x1f300014 0x4>; >>> + reg-names = "dat"; >>> + gpio-controller; >>> + #gpio-cells = <2>; >>> + no-output; >>> + }; >> >> No need to duplicate examples. Keep only one. > > OK > >> Everything is the same. > > Except no-output. I would argue that even one example with no-output is enough, but sure, can be two in total. Best regards, Krzysztof
On 3/14/23 14:32, Krzysztof Kozlowski wrote: > On 14/03/2023 19:09, Sean Anderson wrote: >> On 3/14/23 13:56, Krzysztof Kozlowski wrote: >>> On 13/03/2023 17:11, Sean Anderson wrote: >>> + reg-names: >>>> + minItems: 1 >>>> + maxItems: 5 >>>> + items: >>>> + enum: >>> >>> Why this is in any order? Other bindings were here specific, your 'reg' >>> is also specific/fixed. >> >> Some devicetrees have dirout first, and other have dat first. There is no >> mandatory order, and some registers can be included or left out as is >> convenient to the devicetree author. >> >> reg is not specific/fixed either. It is just done that way for >> convenience (and to match the names here). > > The items have order and usually we require strict order from DTS, > unless there is a reason. If there is no reason, use fixed order and > then fix the DTS. The items do not have order. That is the whole point of having a separate names property. The DTs are not "broken" for taking advantage of a longstanding feature. There is no advantage to rewriting them to use a fixed order, especially when there is no precedent. This is just an area where json schema cannot completely validate devicetrees. --Sean
On 14/03/2023 19:50, Sean Anderson wrote: > On 3/14/23 14:32, Krzysztof Kozlowski wrote: >> On 14/03/2023 19:09, Sean Anderson wrote: >>> On 3/14/23 13:56, Krzysztof Kozlowski wrote: >>>> On 13/03/2023 17:11, Sean Anderson wrote: >>>> + reg-names: >>>>> + minItems: 1 >>>>> + maxItems: 5 >>>>> + items: >>>>> + enum: >>>> >>>> Why this is in any order? Other bindings were here specific, your 'reg' >>>> is also specific/fixed. >>> >>> Some devicetrees have dirout first, and other have dat first. There is no >>> mandatory order, and some registers can be included or left out as is >>> convenient to the devicetree author. >>> >>> reg is not specific/fixed either. It is just done that way for >>> convenience (and to match the names here). >> >> The items have order and usually we require strict order from DTS, >> unless there is a reason. If there is no reason, use fixed order and >> then fix the DTS. > > The items do not have order. That is the whole point of having a > separate names property. The DTs are not "broken" for taking advantage > of a longstanding feature. There is no advantage to rewriting them to > use a fixed order, especially when there is no precedent. This is just > an area where json schema cannot completely validate devicetrees. I don't understand "there is no precedent". There is - we rewrite hundreds of DTS. Just look at mine and other people commits. The reg-names are helper and entries were always expected to be ordered. On the other hand if different devices use different order, then it cannot be changed obviously (as the order is fixed). Best regards, Krzysztof
On 3/14/23 15:45, Krzysztof Kozlowski wrote: > On 14/03/2023 19:50, Sean Anderson wrote: >> On 3/14/23 14:32, Krzysztof Kozlowski wrote: >>> On 14/03/2023 19:09, Sean Anderson wrote: >>>> On 3/14/23 13:56, Krzysztof Kozlowski wrote: >>>>> On 13/03/2023 17:11, Sean Anderson wrote: >>>>> + reg-names: >>>>>> + minItems: 1 >>>>>> + maxItems: 5 >>>>>> + items: >>>>>> + enum: >>>>> >>>>> Why this is in any order? Other bindings were here specific, your 'reg' >>>>> is also specific/fixed. >>>> >>>> Some devicetrees have dirout first, and other have dat first. There is no >>>> mandatory order, and some registers can be included or left out as is >>>> convenient to the devicetree author. >>>> >>>> reg is not specific/fixed either. It is just done that way for >>>> convenience (and to match the names here). >>> >>> The items have order and usually we require strict order from DTS, >>> unless there is a reason. If there is no reason, use fixed order and >>> then fix the DTS. >> >> The items do not have order. That is the whole point of having a >> separate names property. The DTs are not "broken" for taking advantage >> of a longstanding feature. There is no advantage to rewriting them to >> use a fixed order, especially when there is no precedent. This is just >> an area where json schema cannot completely validate devicetrees. > > I don't understand "there is no precedent".There is - we rewrite > hundreds of DTS. Just look at mine and other people commits. There is no precedent for a fixed order of registers for this device. We have always used reg-names to interpret regs. > The reg-names are helper and entries were always expected to be ordered This is not the case for this device. Registers may be in any order, and some registers may be omitted (and not always the same ones). reg-names is the only way to determine which registers are present. --Sean
On 14/03/2023 20:52, Sean Anderson wrote: > On 3/14/23 15:45, Krzysztof Kozlowski wrote: >> On 14/03/2023 19:50, Sean Anderson wrote: >>> On 3/14/23 14:32, Krzysztof Kozlowski wrote: >>>> On 14/03/2023 19:09, Sean Anderson wrote: >>>>> On 3/14/23 13:56, Krzysztof Kozlowski wrote: >>>>>> On 13/03/2023 17:11, Sean Anderson wrote: >>>>>> + reg-names: >>>>>>> + minItems: 1 >>>>>>> + maxItems: 5 >>>>>>> + items: >>>>>>> + enum: >>>>>> >>>>>> Why this is in any order? Other bindings were here specific, your 'reg' >>>>>> is also specific/fixed. >>>>> >>>>> Some devicetrees have dirout first, and other have dat first. There is no >>>>> mandatory order, and some registers can be included or left out as is >>>>> convenient to the devicetree author. >>>>> >>>>> reg is not specific/fixed either. It is just done that way for >>>>> convenience (and to match the names here). >>>> >>>> The items have order and usually we require strict order from DTS, >>>> unless there is a reason. If there is no reason, use fixed order and >>>> then fix the DTS. >>> >>> The items do not have order. That is the whole point of having a >>> separate names property. The DTs are not "broken" for taking advantage >>> of a longstanding feature. There is no advantage to rewriting them to >>> use a fixed order, especially when there is no precedent. This is just >>> an area where json schema cannot completely validate devicetrees. >> >> I don't understand "there is no precedent".There is - we rewrite >> hundreds of DTS. Just look at mine and other people commits. > > There is no precedent for a fixed order of registers for this device. > We have always used reg-names to interpret regs. And who is "we"? Bootloader? Firmware? BSD? Because they all matter. It does not matter that one particular driver uses reg-names. The common rule is always the same - entries are ordered and fixed (with exceptions). > >> The reg-names are helper and entries were always expected to be ordered > > This is not the case for this device. Registers may be in any order, and Their physical order does not determine the order of entries in DT. > some registers may be omitted (and not always the same ones). OK, that's the reason. > reg-names is the > only way to determine which registers are present. Best regards, Krzysztof
Hi Sean,
I love your patch! Perhaps something to improve:
[auto build test WARNING on shawnguo/for-next]
[also build test WARNING on brgl/gpio/for-next clk/clk-next linus/master v6.3-rc2 next-20230315]
[If your patch is applied to the wrong git tree, kindly drop us a note.
And when submitting patch, we suggest to use '--base' as documented in
https://git-scm.com/docs/git-format-patch#_base_tree_information]
url: https://github.com/intel-lab-lkp/linux/commits/Sean-Anderson/dt-bindings-phy-Add-2500BASE-X-and-10GBASE-R/20230314-001522
base: https://git.kernel.org/pub/scm/linux/kernel/git/shawnguo/linux.git for-next
patch link: https://lore.kernel.org/r/20230313161138.3598068-4-sean.anderson%40seco.com
patch subject: [PATCH v11 03/13] dt-bindings: Convert gpio-mmio to yaml
reproduce:
# https://github.com/intel-lab-lkp/linux/commit/2d1e86be168e32ea3d3f11325881f7cb1e5492f8
git remote add linux-review https://github.com/intel-lab-lkp/linux
git fetch --no-tags linux-review Sean-Anderson/dt-bindings-phy-Add-2500BASE-X-and-10GBASE-R/20230314-001522
git checkout 2d1e86be168e32ea3d3f11325881f7cb1e5492f8
make menuconfig
# enable CONFIG_COMPILE_TEST, CONFIG_WARN_MISSING_DOCUMENTS, CONFIG_WARN_ABI_ERRORS
make htmldocs
If you fix the issue, kindly add following tag where applicable
| Reported-by: kernel test robot <lkp@intel.com>
| Link: https://lore.kernel.org/oe-kbuild-all/202303152008.kxRjSW73-lkp@intel.com/
All warnings (new ones prefixed by >>):
>> Warning: Documentation/devicetree/bindings/mfd/brcm,bcm6318-gpio-sysctl.yaml references a file that doesn't exist: Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml
>> Warning: Documentation/devicetree/bindings/mfd/brcm,bcm63268-gpio-sysctl.yaml references a file that doesn't exist: Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml
>> Warning: Documentation/devicetree/bindings/mfd/brcm,bcm6328-gpio-sysctl.yaml references a file that doesn't exist: Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml
>> Warning: Documentation/devicetree/bindings/mfd/brcm,bcm6358-gpio-sysctl.yaml references a file that doesn't exist: Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml
>> Warning: Documentation/devicetree/bindings/mfd/brcm,bcm6362-gpio-sysctl.yaml references a file that doesn't exist: Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml
>> Warning: Documentation/devicetree/bindings/mfd/brcm,bcm6368-gpio-sysctl.yaml references a file that doesn't exist: Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml
diff --git a/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml b/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml similarity index 78% rename from Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml rename to Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml index 4d69f79df859..e11f4af49c52 100644 --- a/Documentation/devicetree/bindings/gpio/brcm,bcm6345-gpio.yaml +++ b/Documentation/devicetree/bindings/gpio/brcm,bcm63xx-gpio.yaml @@ -4,7 +4,7 @@ $id: http://devicetree.org/schemas/gpio/brcm,bcm6345-gpio.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# -title: Broadcom BCM6345 GPIO controller +title: Broadcom BCM63xx GPIO controller maintainers: - Álvaro Fernández Rojas <noltari@gmail.com> @@ -18,8 +18,6 @@ description: |+ BCM6338 have 8-bit data and dirout registers, where GPIO state can be read and/or written, and the direction changed from input to output. - BCM6345 have 16-bit data and dirout registers, where GPIO state can be read - and/or written, and the direction changed from input to output. BCM6318, BCM6328, BCM6358, BCM6362, BCM6368 and BCM63268 have 32-bit data and dirout registers, where GPIO state can be read and/or written, and the direction changed from input to output. @@ -29,7 +27,6 @@ properties: enum: - brcm,bcm6318-gpio - brcm,bcm6328-gpio - - brcm,bcm6345-gpio - brcm,bcm6358-gpio - brcm,bcm6362-gpio - brcm,bcm6368-gpio @@ -63,17 +60,6 @@ required: additionalProperties: false examples: - - | - gpio@fffe0406 { - compatible = "brcm,bcm6345-gpio"; - reg-names = "dirout", "dat"; - reg = <0xfffe0406 2>, <0xfffe040a 2>; - native-endian; - - gpio-controller; - #gpio-cells = <2>; - }; - - | gpio@0 { compatible = "brcm,bcm63268-gpio"; diff --git a/Documentation/devicetree/bindings/gpio/gpio-mmio.yaml b/Documentation/devicetree/bindings/gpio/gpio-mmio.yaml new file mode 100644 index 000000000000..10a93a92ed78 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-mmio.yaml @@ -0,0 +1,134 @@ +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/gpio/gpio-mmio.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Generic MMIO GPIO + +maintainers: + - Linus Walleij <linus.walleij@linaro.org> + - Bartosz Golaszewski <brgl@bgdev.pl> + +description: + Some simple GPIO controllers may consist of a single data register or a pair + of set/clear-bit registers. Such controllers are common for glue logic in + FPGAs or ASICs. Commonly, these controllers are accessed over memory-mapped + NAND-style parallel busses. + +properties: + big-endian: true + + compatible: + enum: + - brcm,bcm6345-gpio # Broadcom BCM6345 GPIO controller + - wd,mbl-gpio # Western Digital MyBook Live memory-mapped GPIO controller + - ni,169445-nand-gpio # National Instruments 169445 GPIO NAND controller + + '#gpio-cells': + const: 2 + + gpio-controller: + true + + reg: + minItems: 1 + description: + A list of registers in the controller. The width of each register is + determined by its size. All registers must have the same width. The number + of GPIOs is set by the width, with bit 0 corresponding to GPIO 0. + items: + - description: + Register to READ the value of the GPIO lines. If GPIO line is high, + the bit will be set. If the GPIO line is low, the bit will be cleared. + This register may also be used to drive GPIOs if the SET register is + omitted. + - description: + Register to SET the value of the GPIO lines. Setting a bit in this + register will drive the GPIO line high. + - description: + Register to CLEAR the value of the GPIO lines. Setting a bit in this + register will drive the GPIO line low. If this register is omitted, + the SET register will be used to clear the GPIO lines as well, by + actively writing the line with 0. + - description: + Register to set the line as OUTPUT. Setting a bit in this register + will turn that line into an output line. Conversely, clearing a bit + will turn that line into an input. + - description: + Register to set this line as INPUT. Setting a bit in this register + will turn that line into an input line. Conversely, clearing a bit + will turn that line into an output. + + reg-names: + minItems: 1 + maxItems: 5 + items: + enum: + - dat + - set + - clr + - dirout + - dirin + + native-endian: true + + no-output: + $ref: /schemas/types.yaml#/definitions/flag + description: + If this property is present, the controller cannot drive the GPIO lines. + +required: + - compatible + - reg + - reg-names + - '#gpio-cells' + - gpio-controller + +additionalProperties: false + +examples: + - | + gpio@1f300010 { + compatible = "ni,169445-nand-gpio"; + reg = <0x1f300010 0x4>; + reg-names = "dat"; + gpio-controller; + #gpio-cells = <2>; + }; + + gpio@1f300014 { + compatible = "ni,169445-nand-gpio"; + reg = <0x1f300014 0x4>; + reg-names = "dat"; + gpio-controller; + #gpio-cells = <2>; + no-output; + }; + + gpio@e0000000 { + compatible = "wd,mbl-gpio"; + reg-names = "dat"; + reg = <0xe0000000 0x1>; + #gpio-cells = <2>; + gpio-controller; + }; + + gpio@e0100000 { + compatible = "wd,mbl-gpio"; + reg-names = "dat"; + reg = <0xe0100000 0x1>; + #gpio-cells = <2>; + gpio-controller; + no-output; + }; + + gpio@fffe0406 { + compatible = "brcm,bcm6345-gpio"; + reg-names = "dirout", "dat"; + reg = <0xfffe0406 2>, <0xfffe040a 2>; + native-endian; + + gpio-controller; + #gpio-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/gpio/ni,169445-nand-gpio.txt b/Documentation/devicetree/bindings/gpio/ni,169445-nand-gpio.txt deleted file mode 100644 index ca2f8c745a27..000000000000 --- a/Documentation/devicetree/bindings/gpio/ni,169445-nand-gpio.txt +++ /dev/null @@ -1,38 +0,0 @@ -Bindings for the National Instruments 169445 GPIO NAND controller - -The 169445 GPIO NAND controller has two memory mapped GPIO registers, one -for input (the ready signal) and one for output (control signals). It is -intended to be used with the GPIO NAND driver. - -Required properties: - - compatible: should be "ni,169445-nand-gpio" - - reg-names: must contain - "dat" - data register - - reg: address + size pairs describing the GPIO register sets; - order must correspond with the order of entries in reg-names - - #gpio-cells: must be set to 2. The first cell is the pin number and - the second cell is used to specify the gpio polarity: - 0 = active high - 1 = active low - - gpio-controller: Marks the device node as a gpio controller. - -Optional properties: - - no-output: disables driving output on the pins - -Examples: - gpio1: nand-gpio-out@1f300010 { - compatible = "ni,169445-nand-gpio"; - reg = <0x1f300010 0x4>; - reg-names = "dat"; - gpio-controller; - #gpio-cells = <2>; - }; - - gpio2: nand-gpio-in@1f300014 { - compatible = "ni,169445-nand-gpio"; - reg = <0x1f300014 0x4>; - reg-names = "dat"; - gpio-controller; - #gpio-cells = <2>; - no-output; - }; diff --git a/Documentation/devicetree/bindings/gpio/wd,mbl-gpio.txt b/Documentation/devicetree/bindings/gpio/wd,mbl-gpio.txt deleted file mode 100644 index 038c3a6a1f4d..000000000000 --- a/Documentation/devicetree/bindings/gpio/wd,mbl-gpio.txt +++ /dev/null @@ -1,38 +0,0 @@ -Bindings for the Western Digital's MyBook Live memory-mapped GPIO controllers. - -The Western Digital MyBook Live has two memory-mapped GPIO controllers. -Both GPIO controller only have a single 8-bit data register, where GPIO -state can be read and/or written. - -Required properties: - - compatible: should be "wd,mbl-gpio" - - reg-names: must contain - "dat" - data register - - reg: address + size pairs describing the GPIO register sets; - order must correspond with the order of entries in reg-names - - #gpio-cells: must be set to 2. The first cell is the pin number and - the second cell is used to specify the gpio polarity: - 0 = active high - 1 = active low - - gpio-controller: Marks the device node as a gpio controller. - -Optional properties: - - no-output: GPIOs are read-only. - -Examples: - gpio0: gpio0@e0000000 { - compatible = "wd,mbl-gpio"; - reg-names = "dat"; - reg = <0xe0000000 0x1>; - #gpio-cells = <2>; - gpio-controller; - }; - - gpio1: gpio1@e0100000 { - compatible = "wd,mbl-gpio"; - reg-names = "dat"; - reg = <0xe0100000 0x1>; - #gpio-cells = <2>; - gpio-controller; - no-output; - };