| Message ID | 20230313161138.3598068-1-sean.anderson@seco.com |
|---|---|
| Headers | show |
| Series | phy: Add support for Lynx 10G SerDes | expand |
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
This adds support for the Lynx 10G SerDes found on the QorIQ T-series and Layerscape series. Due to limited time and hardware, only support for the LS1046ARDB and LS1088ARDB is added in this initial series. This series is ready for review by the phy maintainers. I have addressed all known feedback and there are no outstanding issues. Major reconfiguration of baud rate (e.g. 1G->10G) does not work. From my testing, SerDes register settings appear identical. The issue appears to be between the PCS and the MAC. The link itself comes up at both ends, and a mac loopback succeeds. However, a PCS loopback results in dropped packets. Perhaps there is some undocumented register in the PCS? I suspect this driver is around 95% complete, but I don't have the documentation to make it work completely. At the very least it is useful for two cases: - Although this is untested, it should support 2.5G SGMII as well as 1000BASE-KX. The latter needs MAC and PCS support, but the former should work out of the box. - It allows for clock configurations not supported by the RCW. This is very useful if you want to use e.g. SRDS_PRTCL_S1=0x3333 and =0x1133 on the same board. This is because the former setting will use PLL1 as the 1G reference, but the latter will use PLL1 as the 10G reference. Because we can reconfigure the PLLs, it is possible to always use PLL1 as the 1G reference. 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: - Convert gpio-mmio to yaml - Add compatible for QIXIS - Remove unnecessary inclusion of clk.h - Don't gate clocks in compatibility mode - Fix debugging print with incorrect error variable - Move serdes bindings to SoC dtsi - Add support for all (ethernet) serdes modes - Refer to "nodes" instead of "bindings" - Move compatible/reg first Changes in v9: - Add fsl,unused-lanes-reserved to allow for a gradual transition between firmware and Linux control of the SerDes - Change phy-type back to fsl,type, as I was getting the error '#phy-cells' is a dependency of 'phy-type' - Convert some u32s to unsigned long to match arguments - Switch from round_rate to determine_rate - Drop explicit reference to reference clock - Use .parent_names when requesting parents - Use devm_clk_hw_get_clk to pass clocks back to serdes - Fix indentation - Split off clock "driver" into its own patch to allow for better review. - Add ability to defer lane initialization to phy_init. This allows for easier transitioning between firmware-managed serdes and Linux- managed serdes, as the consumer (such as dpaa2, which knows what the firmware is doing) has the last say on who gets control. - Fix name of phy mode node - Add fsl,unused-lanes-reserved to allow a gradual transition, depending on the mac link type. - Remove unused clocks - Fix some phy mode node names Changes in v8: - Remove unused variable from lynx_ls_mode_init - Rename serdes phy handles to use _A, _B, etc. instead of _0, _1, etc. This should help remind readers that the numbering corresponds to the physical layout of the registers, and not the lane (pin) number. - Prevent PCSs from probing as phys - Rename serdes phy handles like the LS1046A - Add SFP slot binding - Fix incorrect lane ordering (it's backwards on the LS1088A just like it is in the LS1046A). - Fix duplicated lane 2 (it should have been lane 3). - Fix incorrectly-documented value for XFI1. - Remove interrupt for aquantia phy. It never fired for whatever reason, preventing the link from coming up. - Add GPIOs for QIXIS FPGA. - Enable MAC1 PCS - Remove si5341 binding Changes in v7: - Use double quotes everywhere in yaml - Break out call order into generic documentation - Refuse to switch "major" protocols - Update Kconfig to reflect restrictions - Remove set/clear of "pcs reset" bit, since it doesn't seem to fix anything. Changes in v6: - Bump PHY_TYPE_2500BASEX to 13, since PHY_TYPE_USXGMII was added in the meantime - fsl,type -> phy-type - frequence -> frequency - Update MAINTAINERS to include new files - Include bitfield.h and slab.h to allow compilation on non-arm64 arches. - Depend on COMMON_CLK and either layerscape/ppc - XGI.9 -> XFI.9 Changes in v5: - Update commit description - Dual id header - Remove references to PHY_INTERFACE_MODE_1000BASEKX to allow this series to be applied directly to linux/master. - Add fsl,lynx-10g.h to MAINTAINERS Changes in v4: - Add 2500BASE-X and 10GBASE-R phy types - Use subnodes to describe lane configuration, instead of describing PCCRs. This is the same style used by phy-cadence-sierra et al. - Add ids for Lynx 10g PLLs - Rework all debug statements to remove use of __func__. Additional information has been provided as necessary. - Consider alternative parent rates in round_rate and not in set_rate. Trying to modify out parent's rate in set_rate will deadlock. - Explicitly perform a stop/reset sequence in set_rate. This way we always ensure that the PLL is properly stopped. - Set the power-down bit when disabling the PLL. We can do this now that enable/disable aren't abused during the set rate sequence. - Fix typos in QSGMII_OFFSET and XFI_OFFSET - Rename LNmTECR0_TEQ_TYPE_PRE to LNmTECR0_TEQ_TYPE_POST to better reflect its function (adding post-cursor equalization). - Use of_clk_hw_onecell_get instead of a custom function. - Return struct clks from lynx_clks_init instead of embedding lynx_clk in lynx_priv. - Rework PCCR helper functions; T-series SoCs differ from Layerscape SoCs primarily in the layout and offset of the PCCRs. This will help bring a cleaner abstraction layer. The caps have been removed, since this handles the only current usage. - Convert to use new binding format. As a result of this, we no longer need to have protocols for PCIe or SATA. Additionally, modes now live in lynx_group instead of lynx_priv. - Remove teq from lynx_proto_params, since it can be determined from preq_ratio/postq_ratio. - Fix an early return from lynx_set_mode not releasing serdes->lock. - Rename lynx_priv.conf to .cfg, since I kept mistyping it. Changes in v3: - Manually expand yaml references - Add mode configuration to device tree - Rename remaining references to QorIQ SerDes to Lynx 10G - Fix PLL enable sequence by waiting for our reset request to be cleared before continuing. Do the same for the lock, even though it isn't as critical. Because we will delay for 1.5ms on average, use prepare instead of enable so we can sleep. - Document the status of each protocol - Fix offset of several bitfields in RECR0 - Take into account PLLRST_B, SDRST_B, and SDEN when considering whether a PLL is "enabled." - Only power off unused lanes. - Split mode lane mask into first/last lane (like group) - Read modes from device tree - Use caps to determine whether KX/KR are supported - Move modes to lynx_priv - Ensure that the protocol controller is not already in-use when we try to configure a new mode. This should only occur if the device tree is misconfigured (e.g. when QSGMII is selected on two lanes but there is only one QSGMII controller). - Split PLL drivers off into their own file - Add clock for "ext_dly" instead of writing the bit directly (and racing with any clock code). - Use kasprintf instead of open-coding the snprintf dance - Support 1000BASE-KX in lynx_lookup_proto. This still requires PCS support, so nothing is truly "enabled" yet. - Describe modes in device tree - ls1088a: Add serdes bindings Changes in v2: - Rename to fsl,lynx-10g.yaml - Refer to the device in the documentation, rather than the binding - Move compatible first - Document phy cells in the description - Allow a value of 1 for phy-cells. This allows for compatibility with the similar (but according to Ioana Ciornei different enough) lynx-28g binding. - Remove minItems - Use list for clock-names - Fix example binding having too many cells in regs - Add #clock-cells. This will allow using assigned-clocks* to configure the PLLs. - Document the structure of the compatible strings - Rename driver to Lynx 10G (etc.) - Fix not clearing group->pll after disabling it - Support 1 and 2 phy-cells - Power off lanes during probe - Clear SGMIIaCR1_PCS_EN during probe - Rename LYNX_PROTO_UNKNOWN to LYNX_PROTO_NONE - Handle 1000BASE-KX in lynx_proto_mode_prep - Use one phy cell for SerDes1, since no lanes can be grouped - Disable SerDes by default to prevent breaking boards inadvertently. Sean Anderson (13): dt-bindings: phy: Add 2500BASE-X and 10GBASE-R dt-bindings: phy: Add Lynx 10G phy binding dt-bindings: Convert gpio-mmio to yaml dt-bindings: gpio-mmio: Add compatible for QIXIS dt-bindings: clock: Add ids for Lynx 10g PLLs clk: Add Lynx 10G SerDes PLL driver phy: fsl: Add Lynx 10G SerDes driver phy: lynx10g: Enable by default on Layerscape arm64: dts: ls1046a: Add serdes nodes arm64: dts: ls1046ardb: Add serdes descriptions arm64: dts: ls1088a: Add serdes nodes arm64: dts: ls1088a: Prevent PCSs from probing as phys arm64: dts: ls1088ardb: Add serdes descriptions ...m6345-gpio.yaml => brcm,bcm63xx-gpio.yaml} | 16 +- .../devicetree/bindings/gpio/gpio-mmio.yaml | 140 ++ .../bindings/gpio/ni,169445-nand-gpio.txt | 38 - .../devicetree/bindings/gpio/wd,mbl-gpio.txt | 38 - .../devicetree/bindings/phy/fsl,lynx-10g.yaml | 248 ++++ Documentation/driver-api/phy/index.rst | 1 + Documentation/driver-api/phy/lynx_10g.rst | 58 + MAINTAINERS | 9 + .../boot/dts/freescale/fsl-ls1046a-rdb.dts | 26 + .../arm64/boot/dts/freescale/fsl-ls1046a.dtsi | 111 ++ .../boot/dts/freescale/fsl-ls1088a-rdb.dts | 82 +- .../arm64/boot/dts/freescale/fsl-ls1088a.dtsi | 156 ++- drivers/clk/Makefile | 1 + drivers/clk/clk-fsl-lynx-10g.c | 510 +++++++ drivers/phy/freescale/Kconfig | 23 + drivers/phy/freescale/Makefile | 1 + drivers/phy/freescale/phy-fsl-lynx-10g.c | 1224 +++++++++++++++++ include/dt-bindings/clock/fsl,lynx-10g.h | 14 + include/dt-bindings/phy/phy.h | 2 + include/linux/phy/lynx-10g.h | 16 + 20 files changed, 2611 insertions(+), 103 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 create mode 100644 Documentation/devicetree/bindings/phy/fsl,lynx-10g.yaml create mode 100644 Documentation/driver-api/phy/lynx_10g.rst create mode 100644 drivers/clk/clk-fsl-lynx-10g.c create mode 100644 drivers/phy/freescale/phy-fsl-lynx-10g.c create mode 100644 include/dt-bindings/clock/fsl,lynx-10g.h create mode 100644 include/linux/phy/lynx-10g.h