Re: [PATCH v3 1/3] dt-bindings: pinctrl: Add support for Broadcom STB pin controller

[Andrea della Porta <andrea.porta@suse.com>]

Hi Rob,

On 12:20 Mon 18 Aug     , Rob Herring wrote:
> On Mon, Aug 11, 2025 at 04:46:51PM +0200, Andrea della Porta wrote:
> > From: "Ivan T. Ivanov" <iivanov@suse.de>
> > 
> > The STB pin controller represents a family whose silicon instances
> > are found e.g. on BCM2712 SoC.
> > 
> > In particular, on RaspberryPi 5, there are two separate instantiations
> > of the same IP block which differ in the number of pins that are
> > associated and the pinmux functions for each of those pins. The
> > -aon- variant stands for 'Always On'.
> > 
> > Depending on the revision of the BCM2712 (CO or D0), the pin
> > controller instance has slight differences in the register layout.
> > 
> > Signed-off-by: Ivan T. Ivanov <iivanov@suse.de>
> > Signed-off-by: Andrea della Porta <andrea.porta@suse.com>
> > ---
> >  .../pinctrl/brcm,bcm2712c0-pinctrl.yaml       | 135 ++++++++++++++++++
> >  1 file changed, 135 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/pinctrl/brcm,bcm2712c0-pinctrl.yaml
> > 
> > diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm2712c0-pinctrl.yaml b/Documentation/devicetree/bindings/pinctrl/brcm,bcm2712c0-pinctrl.yaml
> > new file mode 100644
> > index 000000000000..28d66336aa2e
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm2712c0-pinctrl.yaml
> > @@ -0,0 +1,135 @@
> > +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/pinctrl/brcm,bcm2712c0-pinctrl.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Broadcom STB family pin controller
> > +
> > +maintainers:
> > +  - Ivan T. Ivanov <iivanov@suse.de>
> > +  - A. della Porta <andrea.porta@suse.com>
> 
> Why is your first name abbrievated here?

The heuristic inside get_maintainer.pl does not correctly recognize names like
"Andrea della Porta", reporting something like:

della Porta <andrea.porta@suse.com>

and missing both the first name and the double quotes surrounding the
name/surname pair.
Something like "Andrea d. Porta" would be reported correctly but it's not an
option in my case since 'della' is not a middle name that can abbreviated,
it's just integral part of the surname.
The easy workaround I've found (the hard one being fixing get_maintainer.pl
script, of course, but I'm not a Perl guru) is to just let the name be
abbreviated.

> 
> > +
> > +description:
> > +  Broadcom's STB family of memory-mapped pin controllers.
> > +  This includes the pin controllers inside the BCM2712 SoC which
> > +  are instances of the STB family and has two silicon variants,
> > +  C0 and D0, which differs slightly in terms of registers layout.
> > +  The -aon- (Always On) variant is the same IP block but differs
> > +  in the number of pins that are associated and the pinmux functions
> > +  for each of those pins.
> 
> Wrap lines at 80. If there are paragraphs, then blank line in between 
> and use the '>' modifier.

I'm not seeing any lines exceeding 80 chars here. Ack for the
blank lines between paragraphs plus >.

> 
> > +
> > +allOf:
> > +  - $ref: pinctrl.yaml#
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - brcm,bcm2712c0-pinctrl
> > +      - brcm,bcm2712c0-aon-pinctrl
> > +      - brcm,bcm2712d0-pinctrl
> > +      - brcm,bcm2712d0-aon-pinctrl
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +patternProperties:
> > +  '-state$':
> > +    oneOf:
> > +      - $ref: '#/$defs/brcmstb-pinctrl-state'
> > +      - patternProperties:
> > +          '-pins$':
> > +            $ref: '#/$defs/brcmstb-pinctrl-state'
> > +        additionalProperties: false
> > +
> > +$defs:
> > +  brcmstb-pinctrl-state:
> > +    allOf:
> > +      - $ref: pincfg-node.yaml#
> > +      - $ref: pinmux-node.yaml#
> > +
> > +    description:
> > +      Pin controller client devices use pin configuration subnodes (children
> > +      and grandchildren) for desired pin configuration.
> > +      Client device subnodes use below standard properties.
> 
> Paragraphs here?

Ack.

> 
> > +
> > +    properties:
> > +      pins:
> > +        description:
> > +          List of gpio pins affected by the properties specified in this
> > +          subnode (either this or "groups" must be specified).
> > +        items:
> > +          pattern: '^((aon_)?s?gpio[0-6]?[0-9])|(emmc_(clk|cmd|dat[0-7]|ds))$'
> > +
> > +      function:
> > +        enum: [ gpio, alt1, alt2, alt3, alt4, alt5, alt6, alt7, alt8,
> > +                aon_cpu_standbyb, aon_fp_4sec_resetb, aon_gpclk, aon_pwm,
> > +                arm_jtag, aud_fs_clk0, avs_pmu_bsc, bsc_m0, bsc_m1, bsc_m2,
> > +                bsc_m3, clk_observe, ctl_hdmi_5v, enet0, enet0_mii, enet0_rgmii,
> > +                ext_sc_clk, fl0, fl1, gpclk0, gpclk1, gpclk2, hdmi_tx0_auto_i2c,
> > +                hdmi_tx0_bsc, hdmi_tx1_auto_i2c, hdmi_tx1_bsc, i2s_in, i2s_out,
> > +                ir_in, mtsif, mtsif_alt, mtsif_alt1, pdm, pkt, pm_led_out, sc0,
> > +                sd0, sd2, sd_card_a, sd_card_b, sd_card_c, sd_card_d, sd_card_e,
> > +                sd_card_f, sd_card_g, spdif_out, spi_m, spi_s, sr_edm_sense, te0,
> > +                te1, tsio, uart0, uart1, uart2, usb_pwr, usb_vbus, uui, vc_i2c0,
> > +                vc_i2c3, vc_i2c4, vc_i2c5, vc_i2csl, vc_pcm, vc_pwm0, vc_pwm1,
> > +                vc_spi0, vc_spi3, vc_spi4, vc_spi5, vc_uart0, vc_uart2, vc_uart3,
> > +                vc_uart4 ]
> > +
> > +        description:
> > +          Specify the alternative function to be configured for the specified
> > +          pins.
> 
> Be consistent with putting 'description' first or last.

Ack.

Many thanks,
Andrea

> 
> > +
> > +      bias-disable: true
> > +      bias-pull-down: true
> > +      bias-pull-up: true
> > +
> > +    required:
> > +      - pins
> > +
> > +    if:
> > +      properties:
> > +        pins:
> > +          not:
> > +            contains:
> > +              pattern: "^emmc_(clk|cmd|dat[0-7]|ds)$"
> > +    then:
> > +      required:
> > +        - function
> > +    else:
> > +      properties:
> > +        function: false
> > +
> > +    additionalProperties: false
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +
> > +unevaluatedProperties: false
> > +
> > +examples:
> > +  - |
> > +    brcm_pinctrl: pinctrl@7d504100 {
> > +        compatible = "brcm,bcm2712c0-pinctrl";
> > +        reg = <0x7d504100 0x30>;
> > +
> > +        bt-shutdown-default-state {
> > +           function = "gpio";
> > +           pins = "gpio29";
> > +        };
> > +
> > +        uarta-default-state {
> > +            rts-tx-pins {
> > +                function = "uart0";
> > +                pins = "gpio24", "gpio26";
> > +                bias-disable;
> > +            };
> > +
> > +            cts-rx-pins {
> > +                function = "uart0";
> > +                pins = "gpio25", "gpio27";
> > +                bias-pull-up;
> > +            };
> > +        };
> > +    };
> > -- 
> > 2.35.3
> >