diff mbox series

dt-bindings: pinctrl: Update pinctrl-single to use yaml

Message ID 20230112083152.10277-1-tony@atomide.com
State Superseded
Headers show
Series dt-bindings: pinctrl: Update pinctrl-single to use yaml | expand

Commit Message

Tony Lindgren Jan. 12, 2023, 8:31 a.m. UTC
Update binding for yaml. Note that we are also adding the undocumented
pinctrl-single,slew-rate property. And we only use the first example from
the old binding.

Cc: Nishanth Menon <nm@ti.com>
Cc: Vignesh Raghavendra <vigneshr@ti.com>
Signed-off-by: Tony Lindgren <tony@atomide.com>
---
 .../bindings/pinctrl/pinctrl-single.txt       | 262 ------------------
 .../bindings/pinctrl/pinctrl-single.yaml      | 155 +++++++++++
 2 files changed, 155 insertions(+), 262 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt
 create mode 100644 Documentation/devicetree/bindings/pinctrl/pinctrl-single.yaml

Comments

kernel test robot Jan. 12, 2023, 8:18 p.m. UTC | #1
Hi Tony,

I love your patch! Perhaps something to improve:

[auto build test WARNING on linusw-pinctrl/devel]
[also build test WARNING on linusw-pinctrl/for-next robh/for-next krzk-dt/for-next linus/master v6.2-rc3 next-20230112]
[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/Tony-Lindgren/dt-bindings-pinctrl-Update-pinctrl-single-to-use-yaml/20230112-163350
base:   https://git.kernel.org/pub/scm/linux/kernel/git/linusw/linux-pinctrl.git devel
patch link:    https://lore.kernel.org/r/20230112083152.10277-1-tony%40atomide.com
patch subject: [PATCH] dt-bindings: pinctrl: Update pinctrl-single to use yaml
reproduce:
        # https://github.com/intel-lab-lkp/linux/commit/c0423f6fd1203d44289a8f8d52a1d56c0a6982e5
        git remote add linux-review https://github.com/intel-lab-lkp/linux
        git fetch --no-tags linux-review Tony-Lindgren/dt-bindings-pinctrl-Update-pinctrl-single-to-use-yaml/20230112-163350
        git checkout c0423f6fd1203d44289a8f8d52a1d56c0a6982e5
        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>

All warnings (new ones prefixed by >>):

>> Warning: Documentation/devicetree/bindings/arm/omap/ctrl.txt references a file that doesn't exist: Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt
>> Warning: Documentation/devicetree/bindings/pinctrl/ti,omap-pinctrl.txt references a file that doesn't exist: Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt
Tony Lindgren Jan. 13, 2023, 6:06 a.m. UTC | #2
* kernel test robot <lkp@intel.com> [230112 20:19]:
> All warnings (new ones prefixed by >>):
> 
> >> Warning: Documentation/devicetree/bindings/arm/omap/ctrl.txt references a file that doesn't exist: Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt
> >> Warning: Documentation/devicetree/bindings/pinctrl/ti,omap-pinctrl.txt references a file that doesn't exist: Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt

Thanks for the report, I'll update the patch to change the omap/ctrl.txt to
reference the new pinctlr-single.yaml file. And we can now just remove the old
pinctrl/ti,omap-pinctrl.txt.

Regards,

Tony
Rob Herring (Arm) Jan. 13, 2023, 8:20 p.m. UTC | #3
On Thu, Jan 12, 2023 at 10:31:50AM +0200, Tony Lindgren wrote:
> Update binding for yaml. Note that we are also adding the undocumented
> pinctrl-single,slew-rate property. And we only use the first example from
> the old binding.

Isn't this v2?

> 
> Cc: Nishanth Menon <nm@ti.com>
> Cc: Vignesh Raghavendra <vigneshr@ti.com>
> Signed-off-by: Tony Lindgren <tony@atomide.com>
> ---
>  .../bindings/pinctrl/pinctrl-single.txt       | 262 ------------------
>  .../bindings/pinctrl/pinctrl-single.yaml      | 155 +++++++++++
>  2 files changed, 155 insertions(+), 262 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt
>  create mode 100644 Documentation/devicetree/bindings/pinctrl/pinctrl-single.yaml
> 
> diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt
> deleted file mode 100644
> --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt
> +++ /dev/null
> @@ -1,262 +0,0 @@
> -One-register-per-pin type device tree based pinctrl driver
> -
> -Required properties:
> -- compatible : "pinctrl-single" or "pinconf-single".
> -  "pinctrl-single" means that pinconf isn't supported.
> -  "pinconf-single" means that generic pinconf is supported.
> -
> -- reg : offset and length of the register set for the mux registers
> -
> -- #pinctrl-cells : number of cells in addition to the index, set to 1
> -  or 2 for pinctrl-single,pins and set to 2 for pinctrl-single,bits
> -
> -- pinctrl-single,register-width : pinmux register access width in bits
> -
> -- pinctrl-single,function-mask : mask of allowed pinmux function bits
> -  in the pinmux register
> -
> -Optional properties:
> -- pinctrl-single,function-off : function off mode for disabled state if
> -  available and same for all registers; if not specified, disabling of
> -  pin functions is ignored
> -
> -- pinctrl-single,bit-per-mux : boolean to indicate that one register controls
> -  more than one pin, for which "pinctrl-single,function-mask" property specifies
> - position mask of pin.
> -
> -- pinctrl-single,drive-strength : array of value that are used to configure
> -  drive strength in the pinmux register. They're value of drive strength
> -  current and drive strength mask.
> -
> -		/* drive strength current, mask */
> -		pinctrl-single,power-source = <0x30 0xf0>;
> -
> -- pinctrl-single,bias-pullup : array of value that are used to configure the
> -  input bias pullup in the pinmux register.
> -
> -		/* input, enabled pullup bits, disabled pullup bits, mask */
> -		pinctrl-single,bias-pullup = <0 1 0 1>;
> -
> -- pinctrl-single,bias-pulldown : array of value that are used to configure the
> -  input bias pulldown in the pinmux register.
> -
> -		/* input, enabled pulldown bits, disabled pulldown bits, mask */
> -		pinctrl-single,bias-pulldown = <2 2 0 2>;
> -
> -  * Two bits to control input bias pullup and pulldown: User should use
> -    pinctrl-single,bias-pullup & pinctrl-single,bias-pulldown. One bit means
> -    pullup, and the other one bit means pulldown.
> -  * Three bits to control input bias enable, pullup and pulldown. User should
> -    use pinctrl-single,bias-pullup & pinctrl-single,bias-pulldown. Input bias
> -    enable bit should be included in pullup or pulldown bits.
> -  * Although driver could set PIN_CONFIG_BIAS_DISABLE, there's no property as
> -    pinctrl-single,bias-disable. Because pinctrl single driver could implement
> -    it by calling pulldown, pullup disabled.
> -
> -- pinctrl-single,input-schmitt : array of value that are used to configure
> -  input schmitt in the pinmux register. In some silicons, there're two input
> -  schmitt value (rising-edge & falling-edge) in the pinmux register.
> -
> -		/* input schmitt value, mask */
> -		pinctrl-single,input-schmitt = <0x30 0x70>;
> -
> -- pinctrl-single,input-schmitt-enable : array of value that are used to
> -  configure input schmitt enable or disable in the pinmux register.
> -
> -		/* input, enable bits, disable bits, mask */
> -		pinctrl-single,input-schmitt-enable = <0x30 0x40 0 0x70>;
> -
> -- pinctrl-single,low-power-mode : array of value that are used to configure
> -  low power mode of this pin. For some silicons, the low power mode will
> -  control the output of the pin when the pad including the pin enter low
> -  power mode.
> -		/* low power mode value, mask */
> -		pinctrl-single,low-power-mode = <0x288 0x388>;
> -
> -- pinctrl-single,gpio-range : list of value that are used to configure a GPIO
> -  range. They're value of subnode phandle, pin base in pinctrl device, pin
> -  number in this range, GPIO function value of this GPIO range.
> -  The number of parameters is depend on #pinctrl-single,gpio-range-cells
> -  property.
> -
> -		/* pin base, nr pins & gpio function */
> -		pinctrl-single,gpio-range = <&range 0 3 0>, <&range 3 9 1>;
> -
> -- interrupt-controller : standard interrupt controller binding if using
> -  interrupts for wake-up events for example. In this case pinctrl-single
> -  is set up as a chained interrupt controller and the wake-up interrupts
> -  can be requested by the drivers using request_irq().
> -
> -- #interrupt-cells : standard interrupt binding if using interrupts
> -
> -This driver assumes that there is only one register for each pin (unless the
> -pinctrl-single,bit-per-mux is set), and uses the common pinctrl bindings as
> -specified in the pinctrl-bindings.txt document in this directory.
> -
> -The pin configuration nodes for pinctrl-single are specified as pinctrl
> -register offset and values using pinctrl-single,pins. Only the bits specified
> -in pinctrl-single,function-mask are updated.
> -
> -When #pinctrl-cells = 1, then setting a pin for a device could be done with:
> -
> -	pinctrl-single,pins = <0xdc 0x118>;
> -
> -Where 0xdc is the offset from the pinctrl register base address for the device
> -pinctrl register, and 0x118 contains the desired value of the pinctrl register.
> -
> -When #pinctrl-cells = 2, then setting a pin for a device could be done with:
> -
> -	pinctrl-single,pins = <0xdc 0x30 0x07>;
> -
> -Where 0x30 is the pin configuration value and 0x07 is the pin mux mode value.
> -These two values are OR'd together to produce the value stored at offset 0xdc.
> -See the device example and static board pins example below for more information.
> -
> -In case when one register changes more than one pin's mux the
> -pinctrl-single,bits need to be used which takes three parameters:
> -
> -	pinctrl-single,bits = <0xdc 0x18 0xff>;
> -
> -Where 0xdc is the offset from the pinctrl register base address for the
> -device pinctrl register, 0x18 is the desired value, and 0xff is the sub mask to
> -be used when applying this change to the register.
> -
> -
> -Optional sub-node: In case some pins could be configured as GPIO in the pinmux
> -register, those pins could be defined as a GPIO range. This sub-node is required
> -by pinctrl-single,gpio-range property.
> -
> -Required properties in sub-node:
> -- #pinctrl-single,gpio-range-cells : the number of parameters after phandle in
> -  pinctrl-single,gpio-range property.
> -
> -	range: gpio-range {
> -		#pinctrl-single,gpio-range-cells = <3>;
> -	};

You've lost describing this.

> -
> -
> -Example:
> -
> -/* SoC common file */
> -
> -/* first controller instance for pins in core domain */
> -pmx_core: pinmux@4a100040 {
> -	compatible = "pinctrl-single";
> -	reg = <0x4a100040 0x0196>;
> -	#address-cells = <1>;
> -	#size-cells = <0>;
> -	#interrupt-cells = <1>;
> -	interrupt-controller;
> -	pinctrl-single,register-width = <16>;
> -	pinctrl-single,function-mask = <0xffff>;
> -};
> -
> -/* second controller instance for pins in wkup domain */
> -pmx_wkup: pinmux@4a31e040 {
> -	compatible = "pinctrl-single";
> -	reg = <0x4a31e040 0x0038>;
> -	#address-cells = <1>;
> -	#size-cells = <0>;
> -	#interrupt-cells = <1>;
> -	interrupt-controller;
> -	pinctrl-single,register-width = <16>;
> -	pinctrl-single,function-mask = <0xffff>;
> -};
> -
> -control_devconf0: pinmux@48002274 {
> -	compatible = "pinctrl-single";
> -	reg = <0x48002274 4>;	/* Single register */
> -	#address-cells = <1>;
> -	#size-cells = <0>;
> -	pinctrl-single,bit-per-mux;
> -	pinctrl-single,register-width = <32>;
> -	pinctrl-single,function-mask = <0x5F>;
> -};
> -
> -/* third controller instance for pins in gpio domain */
> -pmx_gpio: pinmux@d401e000 {
> -	compatible = "pinconf-single";
> -	reg = <0xd401e000 0x0330>;
> -	#address-cells = <1>;
> -	#size-cells = <1>;
> -	ranges;
> -
> -	pinctrl-single,register-width = <32>;
> -	pinctrl-single,function-mask = <7>;
> -
> -	/* sparse GPIO range could be supported */
> -	pinctrl-single,gpio-range = <&range 0 3 0>, <&range 3 9 1>,
> -				    <&range 12 1 0>, <&range 13 29 1>,
> -				    <&range 43 1 0>, <&range 44 49 1>,
> -				    <&range 94 1 1>, <&range 96 2 1>;
> -
> -	range: gpio-range {
> -		#pinctrl-single,gpio-range-cells = <3>;
> -	};
> -};
> -
> -
> -/* board specific .dts file */
> -
> -&pmx_core {
> -
> -	/*
> -	 * map all board specific static pins enabled by the pinctrl driver
> -	 * itself during the boot (or just set them up in the bootloader)
> -	 */
> -	pinctrl-names = "default";
> -	pinctrl-0 = <&board_pins>;
> -
> -	board_pins: pinmux_board_pins {
> -		pinctrl-single,pins = <
> -			0x6c 0xf
> -			0x6e 0xf
> -			0x70 0xf
> -			0x72 0xf
> -		>;
> -	};
> -
> -	uart0_pins: pinmux_uart0_pins {
> -		pinctrl-single,pins = <
> -			0x208 0		/* UART0_RXD (IOCFG138) */
> -			0x20c 0		/* UART0_TXD (IOCFG139) */
> -		>;
> -		pinctrl-single,bias-pulldown = <0 2 2>;
> -		pinctrl-single,bias-pullup = <0 1 1>;
> -	};
> -
> -	/* map uart2 pins */
> -	uart2_pins: pinmux_uart2_pins {
> -		pinctrl-single,pins = <
> -			0xd8 0x118
> -			0xda 0
> -			0xdc 0x118
> -			0xde 0
> -		>;
> -	};
> -};
> -
> -&control_devconf0 {
> -	mcbsp1_pins: pinmux_mcbsp1_pins {
> -		pinctrl-single,bits = <
> -			0x00 0x18 0x18 /* FSR/CLKR signal from FSX/CLKX pin */
> -		>;
> -	};
> -
> -	mcbsp2_clks_pins: pinmux_mcbsp2_clks_pins {
> -		pinctrl-single,bits = <
> -			0x00 0x40 0x40 /* McBSP2 CLKS from McBSP_CLKS pin */
> -		>;
> -	};
> -
> -};
> -
> -&uart1 {
> -       pinctrl-names = "default";
> -       pinctrl-0 = <&uart0_pins>;
> -};
> -
> -&uart2 {
> -       pinctrl-names = "default";
> -       pinctrl-0 = <&uart2_pins>;
> -};
> diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-single.yaml b/Documentation/devicetree/bindings/pinctrl/pinctrl-single.yaml
> new file mode 100644
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-single.yaml
> @@ -0,0 +1,155 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/pinctrl/pinctrl-single.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: One-register-per-pin type device tree based pinctrl driver
> +
> +maintainers:
> +  - Tony Lindgren <tony@atomide.com>
> +
> +description: |

Don't need '|'

> +  This binding describes pinctrl devices that use one hardware register to
> +  configure each pin.
> +
> +properties:
> +  compatible:
> +    oneOf:
> +      - items:
> +          - enum:
> +              - pinctrl-single
> +              - pinconf-single
> +      - items:
> +          - enum:
> +              - ti,am437-padconf
> +              - ti,dra7-padconf
> +              - ti,omap2420-padconf
> +              - ti,omap2430-padconf
> +              - ti,omap3-padconf
> +              - ti,omap4-padconf
> +              - ti,omap5-padconf
> +          - const: pinctrl-single
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupt-controller: true
> +
> +  '#interrupt-cells':
> +    const: 1
> +
> +  '#address-cells':
> +    const: 1
> +
> +  '#size-cells':
> +    const: 0
> +
> +  '#pinctrl-cells':
> +    enum: [ 1, 2 ]
> +
> +  '#gpio-range-cells':
> +    const: 3
> +    description: No longer needed, may exist in older files for gpio-ranges
> +    deprecated: true
> +
> +  pinctrl-single,bit-per-mux:
> +    description: Optional flag to indicate register controls more than one pin
> +    type: boolean
> +
> +  pinctrl-single,function-mask:
> +    description: Mask of the allowed register bits
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +
> +  pinctrl-single,function-off:
> +    description: Optional function off mode for disabled state
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +
> +  pinctrl-single,gpio-range:
> +    description: Optional list of pin base, nr pins & gpio function
> +    $ref: /schemas/types.yaml#/definitions/phandle-array

This needs constraints on the dimensions.

> +
> +  '#pinctrl-single,gpio-range-cells':
> +    const: 3
> +    description: Number of gpio range cells
> +    $ref: /schemas/types.yaml#/definitions/uint32

This goes in a child node based on the (deleted) example.

> +
> +  pinctrl-single,register-width:
> +    description: Width of the pin register in bits
> +    $ref: /schemas/types.yaml#/definitions/uint32

maximum: 32

or

enum: [ 8, 16, 32 ]


default: 32?


In general, constraints on these properties?

> +
> +patternProperties:
> +  '-pins((.*)?)$':
> +    type: object
> +    $ref: pinmux-node.yaml#
> +
> +    patternProperties:

These aren't patterns.

properties:

> +      pinctrl-single,pins:
> +        description:
> +          Array of pins as described in pinmux-node.yaml for pinctrl-pin-array
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +
> +      pinctrl-single,bias-pullup:
> +        description: Optional array of input, enabled pullup bits, disabled pullup bits, mask
> +        $ref: /schemas/types.yaml#/definitions/uint32-array

maxItems: 4

Or:

items:
  - description: input
  - description: enabled pullup bits
  ...

And it's always just 4 cells, or a multiple of 4 cells. The latter would 
be uint32-matrix.

Same comment on the following ones...

> +
> +      pinctrl-single,bias-pulldown:
> +        description: Optional array of input, enabled pulldown bits, disabled pulldown bits, mask
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +
> +      pinctrl-single,drive-strength:
> +        description: Optional array of drive strength current and mask
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +
> +      pinctrl-single,input-schmitt:
> +        description: Optional array of input, enable bits, disable bits, mask
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +
> +      pinctrl-single,low-power-mode:
> +        description: Optional array of low power mode value, mask
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +
> +      pinctrl-single,slew-rate:
> +        description: Optional array of slew rate and mask values
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +
> +    additionalProperties: false

In indented cases, putting this before a long list of properties is 
easier to read IMO.

> +
> +allOf:
> +  - $ref: 'pinctrl.yaml#'

Drop quotes.

> +
> +required:
> +  - compatible
> +  - reg
> +  - pinctrl-single,register-width
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/pinctrl/omap.h>

Don't need this?

> +
> +    soc {
> +      #address-cells = <1>;
> +      #size-cells = <1>;
> +
> +        pinmux@4a100040 {
> +          compatible = "pinctrl-single";
> +          reg = <0x4a100040 0x0196>;
> +          #address-cells = <1>;
> +          #size-cells = <0>;
> +          #pinctrl-cells = <2>;
> +          #interrupt-cells = <1>;
> +          interrupt-controller;
> +          pinctrl-single,register-width = <16>;
> +          pinctrl-single,function-mask = <0xffff>;
> +
> +          uart2-pins {
> +            pinctrl-single,pins =
> +              <0xd8 0x118>,
> +              <0xda 0>,
> +              <0xdc 0x118>,
> +              <0xde 0>;
> +          };
> +        };
> +      };
> -- 
> 2.39.0
Tony Lindgren Jan. 16, 2023, 6:49 a.m. UTC | #4
* Rob Herring <robh@kernel.org> [230113 20:20]:
> On Thu, Jan 12, 2023 at 10:31:50AM +0200, Tony Lindgren wrote:
> > Update binding for yaml. Note that we are also adding the undocumented
> > pinctrl-single,slew-rate property. And we only use the first example from
> > the old binding.
> 
> Isn't this v2?

Hmm yeah I posted a earlier WIP version of this in the "dt binding check
error with hash and comma" thread, will use v3 for the next version.

Regards,

Tony
Tony Lindgren Jan. 16, 2023, 11:15 a.m. UTC | #5
Hi Rob,

I ran into error "is not of type 'object'" with two dashes in the property
name.

* Rob Herring <robh@kernel.org> [230113 20:20]:
> On Thu, Jan 12, 2023 at 10:31:50AM +0200, Tony Lindgren wrote:
> > -- #pinctrl-single,gpio-range-cells : the number of parameters after phandle in
> > -  pinctrl-single,gpio-range property.
> > -
> > -	range: gpio-range {
> > -		#pinctrl-single,gpio-range-cells = <3>;
> > -	};
> 
> You've lost describing this.

Thanks for noticing. Adding something like below produces errors for the
pinctrl-single,gpio-range property name:

  pinctrl-single,gpio-range:
    description: Optional list of pin base, nr pins & gpio function
    $ref: /schemas/types.yaml#/definitions/phandle-array
    items:
      - items:
          - description: phandle of a gpio-range node
          - description: pin base
          - description: number of pins
          - description: gpio function

  pinctrl-single,gpio-range = <&range 0 3 0>;

The error is:

pinctrl-single.example.dtb: pinmux@4a100040: pinctrl-single,gpio-range:
[[1, 0, 3, 0]] is not of type 'object'

Changing the property name second dash to something else makes it go away.

This is with dtschema 2022.12. Any ideas?

Regards,

Tony
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt
deleted file mode 100644
--- a/Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt
+++ /dev/null
@@ -1,262 +0,0 @@ 
-One-register-per-pin type device tree based pinctrl driver
-
-Required properties:
-- compatible : "pinctrl-single" or "pinconf-single".
-  "pinctrl-single" means that pinconf isn't supported.
-  "pinconf-single" means that generic pinconf is supported.
-
-- reg : offset and length of the register set for the mux registers
-
-- #pinctrl-cells : number of cells in addition to the index, set to 1
-  or 2 for pinctrl-single,pins and set to 2 for pinctrl-single,bits
-
-- pinctrl-single,register-width : pinmux register access width in bits
-
-- pinctrl-single,function-mask : mask of allowed pinmux function bits
-  in the pinmux register
-
-Optional properties:
-- pinctrl-single,function-off : function off mode for disabled state if
-  available and same for all registers; if not specified, disabling of
-  pin functions is ignored
-
-- pinctrl-single,bit-per-mux : boolean to indicate that one register controls
-  more than one pin, for which "pinctrl-single,function-mask" property specifies
- position mask of pin.
-
-- pinctrl-single,drive-strength : array of value that are used to configure
-  drive strength in the pinmux register. They're value of drive strength
-  current and drive strength mask.
-
-		/* drive strength current, mask */
-		pinctrl-single,power-source = <0x30 0xf0>;
-
-- pinctrl-single,bias-pullup : array of value that are used to configure the
-  input bias pullup in the pinmux register.
-
-		/* input, enabled pullup bits, disabled pullup bits, mask */
-		pinctrl-single,bias-pullup = <0 1 0 1>;
-
-- pinctrl-single,bias-pulldown : array of value that are used to configure the
-  input bias pulldown in the pinmux register.
-
-		/* input, enabled pulldown bits, disabled pulldown bits, mask */
-		pinctrl-single,bias-pulldown = <2 2 0 2>;
-
-  * Two bits to control input bias pullup and pulldown: User should use
-    pinctrl-single,bias-pullup & pinctrl-single,bias-pulldown. One bit means
-    pullup, and the other one bit means pulldown.
-  * Three bits to control input bias enable, pullup and pulldown. User should
-    use pinctrl-single,bias-pullup & pinctrl-single,bias-pulldown. Input bias
-    enable bit should be included in pullup or pulldown bits.
-  * Although driver could set PIN_CONFIG_BIAS_DISABLE, there's no property as
-    pinctrl-single,bias-disable. Because pinctrl single driver could implement
-    it by calling pulldown, pullup disabled.
-
-- pinctrl-single,input-schmitt : array of value that are used to configure
-  input schmitt in the pinmux register. In some silicons, there're two input
-  schmitt value (rising-edge & falling-edge) in the pinmux register.
-
-		/* input schmitt value, mask */
-		pinctrl-single,input-schmitt = <0x30 0x70>;
-
-- pinctrl-single,input-schmitt-enable : array of value that are used to
-  configure input schmitt enable or disable in the pinmux register.
-
-		/* input, enable bits, disable bits, mask */
-		pinctrl-single,input-schmitt-enable = <0x30 0x40 0 0x70>;
-
-- pinctrl-single,low-power-mode : array of value that are used to configure
-  low power mode of this pin. For some silicons, the low power mode will
-  control the output of the pin when the pad including the pin enter low
-  power mode.
-		/* low power mode value, mask */
-		pinctrl-single,low-power-mode = <0x288 0x388>;
-
-- pinctrl-single,gpio-range : list of value that are used to configure a GPIO
-  range. They're value of subnode phandle, pin base in pinctrl device, pin
-  number in this range, GPIO function value of this GPIO range.
-  The number of parameters is depend on #pinctrl-single,gpio-range-cells
-  property.
-
-		/* pin base, nr pins & gpio function */
-		pinctrl-single,gpio-range = <&range 0 3 0>, <&range 3 9 1>;
-
-- interrupt-controller : standard interrupt controller binding if using
-  interrupts for wake-up events for example. In this case pinctrl-single
-  is set up as a chained interrupt controller and the wake-up interrupts
-  can be requested by the drivers using request_irq().
-
-- #interrupt-cells : standard interrupt binding if using interrupts
-
-This driver assumes that there is only one register for each pin (unless the
-pinctrl-single,bit-per-mux is set), and uses the common pinctrl bindings as
-specified in the pinctrl-bindings.txt document in this directory.
-
-The pin configuration nodes for pinctrl-single are specified as pinctrl
-register offset and values using pinctrl-single,pins. Only the bits specified
-in pinctrl-single,function-mask are updated.
-
-When #pinctrl-cells = 1, then setting a pin for a device could be done with:
-
-	pinctrl-single,pins = <0xdc 0x118>;
-
-Where 0xdc is the offset from the pinctrl register base address for the device
-pinctrl register, and 0x118 contains the desired value of the pinctrl register.
-
-When #pinctrl-cells = 2, then setting a pin for a device could be done with:
-
-	pinctrl-single,pins = <0xdc 0x30 0x07>;
-
-Where 0x30 is the pin configuration value and 0x07 is the pin mux mode value.
-These two values are OR'd together to produce the value stored at offset 0xdc.
-See the device example and static board pins example below for more information.
-
-In case when one register changes more than one pin's mux the
-pinctrl-single,bits need to be used which takes three parameters:
-
-	pinctrl-single,bits = <0xdc 0x18 0xff>;
-
-Where 0xdc is the offset from the pinctrl register base address for the
-device pinctrl register, 0x18 is the desired value, and 0xff is the sub mask to
-be used when applying this change to the register.
-
-
-Optional sub-node: In case some pins could be configured as GPIO in the pinmux
-register, those pins could be defined as a GPIO range. This sub-node is required
-by pinctrl-single,gpio-range property.
-
-Required properties in sub-node:
-- #pinctrl-single,gpio-range-cells : the number of parameters after phandle in
-  pinctrl-single,gpio-range property.
-
-	range: gpio-range {
-		#pinctrl-single,gpio-range-cells = <3>;
-	};
-
-
-Example:
-
-/* SoC common file */
-
-/* first controller instance for pins in core domain */
-pmx_core: pinmux@4a100040 {
-	compatible = "pinctrl-single";
-	reg = <0x4a100040 0x0196>;
-	#address-cells = <1>;
-	#size-cells = <0>;
-	#interrupt-cells = <1>;
-	interrupt-controller;
-	pinctrl-single,register-width = <16>;
-	pinctrl-single,function-mask = <0xffff>;
-};
-
-/* second controller instance for pins in wkup domain */
-pmx_wkup: pinmux@4a31e040 {
-	compatible = "pinctrl-single";
-	reg = <0x4a31e040 0x0038>;
-	#address-cells = <1>;
-	#size-cells = <0>;
-	#interrupt-cells = <1>;
-	interrupt-controller;
-	pinctrl-single,register-width = <16>;
-	pinctrl-single,function-mask = <0xffff>;
-};
-
-control_devconf0: pinmux@48002274 {
-	compatible = "pinctrl-single";
-	reg = <0x48002274 4>;	/* Single register */
-	#address-cells = <1>;
-	#size-cells = <0>;
-	pinctrl-single,bit-per-mux;
-	pinctrl-single,register-width = <32>;
-	pinctrl-single,function-mask = <0x5F>;
-};
-
-/* third controller instance for pins in gpio domain */
-pmx_gpio: pinmux@d401e000 {
-	compatible = "pinconf-single";
-	reg = <0xd401e000 0x0330>;
-	#address-cells = <1>;
-	#size-cells = <1>;
-	ranges;
-
-	pinctrl-single,register-width = <32>;
-	pinctrl-single,function-mask = <7>;
-
-	/* sparse GPIO range could be supported */
-	pinctrl-single,gpio-range = <&range 0 3 0>, <&range 3 9 1>,
-				    <&range 12 1 0>, <&range 13 29 1>,
-				    <&range 43 1 0>, <&range 44 49 1>,
-				    <&range 94 1 1>, <&range 96 2 1>;
-
-	range: gpio-range {
-		#pinctrl-single,gpio-range-cells = <3>;
-	};
-};
-
-
-/* board specific .dts file */
-
-&pmx_core {
-
-	/*
-	 * map all board specific static pins enabled by the pinctrl driver
-	 * itself during the boot (or just set them up in the bootloader)
-	 */
-	pinctrl-names = "default";
-	pinctrl-0 = <&board_pins>;
-
-	board_pins: pinmux_board_pins {
-		pinctrl-single,pins = <
-			0x6c 0xf
-			0x6e 0xf
-			0x70 0xf
-			0x72 0xf
-		>;
-	};
-
-	uart0_pins: pinmux_uart0_pins {
-		pinctrl-single,pins = <
-			0x208 0		/* UART0_RXD (IOCFG138) */
-			0x20c 0		/* UART0_TXD (IOCFG139) */
-		>;
-		pinctrl-single,bias-pulldown = <0 2 2>;
-		pinctrl-single,bias-pullup = <0 1 1>;
-	};
-
-	/* map uart2 pins */
-	uart2_pins: pinmux_uart2_pins {
-		pinctrl-single,pins = <
-			0xd8 0x118
-			0xda 0
-			0xdc 0x118
-			0xde 0
-		>;
-	};
-};
-
-&control_devconf0 {
-	mcbsp1_pins: pinmux_mcbsp1_pins {
-		pinctrl-single,bits = <
-			0x00 0x18 0x18 /* FSR/CLKR signal from FSX/CLKX pin */
-		>;
-	};
-
-	mcbsp2_clks_pins: pinmux_mcbsp2_clks_pins {
-		pinctrl-single,bits = <
-			0x00 0x40 0x40 /* McBSP2 CLKS from McBSP_CLKS pin */
-		>;
-	};
-
-};
-
-&uart1 {
-       pinctrl-names = "default";
-       pinctrl-0 = <&uart0_pins>;
-};
-
-&uart2 {
-       pinctrl-names = "default";
-       pinctrl-0 = <&uart2_pins>;
-};
diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-single.yaml b/Documentation/devicetree/bindings/pinctrl/pinctrl-single.yaml
new file mode 100644
--- /dev/null
+++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-single.yaml
@@ -0,0 +1,155 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/pinctrl/pinctrl-single.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: One-register-per-pin type device tree based pinctrl driver
+
+maintainers:
+  - Tony Lindgren <tony@atomide.com>
+
+description: |
+  This binding describes pinctrl devices that use one hardware register to
+  configure each pin.
+
+properties:
+  compatible:
+    oneOf:
+      - items:
+          - enum:
+              - pinctrl-single
+              - pinconf-single
+      - items:
+          - enum:
+              - ti,am437-padconf
+              - ti,dra7-padconf
+              - ti,omap2420-padconf
+              - ti,omap2430-padconf
+              - ti,omap3-padconf
+              - ti,omap4-padconf
+              - ti,omap5-padconf
+          - const: pinctrl-single
+
+  reg:
+    maxItems: 1
+
+  interrupt-controller: true
+
+  '#interrupt-cells':
+    const: 1
+
+  '#address-cells':
+    const: 1
+
+  '#size-cells':
+    const: 0
+
+  '#pinctrl-cells':
+    enum: [ 1, 2 ]
+
+  '#gpio-range-cells':
+    const: 3
+    description: No longer needed, may exist in older files for gpio-ranges
+    deprecated: true
+
+  pinctrl-single,bit-per-mux:
+    description: Optional flag to indicate register controls more than one pin
+    type: boolean
+
+  pinctrl-single,function-mask:
+    description: Mask of the allowed register bits
+    $ref: /schemas/types.yaml#/definitions/uint32
+
+  pinctrl-single,function-off:
+    description: Optional function off mode for disabled state
+    $ref: /schemas/types.yaml#/definitions/uint32
+
+  pinctrl-single,gpio-range:
+    description: Optional list of pin base, nr pins & gpio function
+    $ref: /schemas/types.yaml#/definitions/phandle-array
+
+  '#pinctrl-single,gpio-range-cells':
+    const: 3
+    description: Number of gpio range cells
+    $ref: /schemas/types.yaml#/definitions/uint32
+
+  pinctrl-single,register-width:
+    description: Width of the pin register in bits
+    $ref: /schemas/types.yaml#/definitions/uint32
+
+patternProperties:
+  '-pins((.*)?)$':
+    type: object
+    $ref: pinmux-node.yaml#
+
+    patternProperties:
+      pinctrl-single,pins:
+        description:
+          Array of pins as described in pinmux-node.yaml for pinctrl-pin-array
+        $ref: /schemas/types.yaml#/definitions/uint32-array
+
+      pinctrl-single,bias-pullup:
+        description: Optional array of input, enabled pullup bits, disabled pullup bits, mask
+        $ref: /schemas/types.yaml#/definitions/uint32-array
+
+      pinctrl-single,bias-pulldown:
+        description: Optional array of input, enabled pulldown bits, disabled pulldown bits, mask
+        $ref: /schemas/types.yaml#/definitions/uint32-array
+
+      pinctrl-single,drive-strength:
+        description: Optional array of drive strength current and mask
+        $ref: /schemas/types.yaml#/definitions/uint32-array
+
+      pinctrl-single,input-schmitt:
+        description: Optional array of input, enable bits, disable bits, mask
+        $ref: /schemas/types.yaml#/definitions/uint32-array
+
+      pinctrl-single,low-power-mode:
+        description: Optional array of low power mode value, mask
+        $ref: /schemas/types.yaml#/definitions/uint32-array
+
+      pinctrl-single,slew-rate:
+        description: Optional array of slew rate and mask values
+        $ref: /schemas/types.yaml#/definitions/uint32-array
+
+    additionalProperties: false
+
+allOf:
+  - $ref: 'pinctrl.yaml#'
+
+required:
+  - compatible
+  - reg
+  - pinctrl-single,register-width
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/pinctrl/omap.h>
+
+    soc {
+      #address-cells = <1>;
+      #size-cells = <1>;
+
+        pinmux@4a100040 {
+          compatible = "pinctrl-single";
+          reg = <0x4a100040 0x0196>;
+          #address-cells = <1>;
+          #size-cells = <0>;
+          #pinctrl-cells = <2>;
+          #interrupt-cells = <1>;
+          interrupt-controller;
+          pinctrl-single,register-width = <16>;
+          pinctrl-single,function-mask = <0xffff>;
+
+          uart2-pins {
+            pinctrl-single,pins =
+              <0xd8 0x118>,
+              <0xda 0>,
+              <0xdc 0x118>,
+              <0xde 0>;
+          };
+        };
+      };