On Thu, Nov 7, 2019 at 3:42 PM Rob Herring <robh@xxxxxxxxxx> wrote: > > As pinctrl bindings have a flexible structure and no standard child node > naming convention, creating a single pinctrl schema doesn't work. Instead, > create schemas for the pin mux and config nodes which device pinctrl schema > can reference. > > Cc: Linus Walleij <linus.walleij@xxxxxxxxxx> > Cc: linux-gpio@xxxxxxxxxxxxxxx > Signed-off-by: Rob Herring <robh@xxxxxxxxxx> > --- > > We're starting to see pinctrl schema doing their own definitions for > generic properties, so we need to get something in place to reference. > > Maybe this could be combined into a single schema? Spliting it was > easier in order to just copy over the existing documentation. > > Reading thru pinctrl-bindings.txt, I'm wondering if some of it is out > of date. Do we let new bindings not use the generic muxing properties? > Do we really need to be so flexible for child node structure? Ping! > > Rob > > .../bindings/pinctrl/pincfg-node.yaml | 140 +++++++++++++ > .../bindings/pinctrl/pinctrl-bindings.txt | 192 +----------------- > .../bindings/pinctrl/pinmux-node.yaml | 132 ++++++++++++ > 3 files changed, 274 insertions(+), 190 deletions(-) > create mode 100644 Documentation/devicetree/bindings/pinctrl/pincfg-node.yaml > create mode 100644 Documentation/devicetree/bindings/pinctrl/pinmux-node.yaml > > diff --git a/Documentation/devicetree/bindings/pinctrl/pincfg-node.yaml b/Documentation/devicetree/bindings/pinctrl/pincfg-node.yaml > new file mode 100644 > index 000000000000..13b7ab9dd6d5 > --- /dev/null > +++ b/Documentation/devicetree/bindings/pinctrl/pincfg-node.yaml > @@ -0,0 +1,140 @@ > +# SPDX-License-Identifier: GPL-2.0-only > +%YAML 1.2 > +--- > +$id: http://devicetree.org/schemas/pinctrl/pincfg-node.yaml# > +$schema: http://devicetree.org/meta-schemas/core.yaml# > + > +title: Generic pin configuration node schema > + > +maintainers: > + - Linus Walleij <linus.walleij@xxxxxxxxxx> > + > +description: > + Many data items that are represented in a pin configuration node are common > + and generic. Pin control bindings should use the properties defined below > + where they are applicable; not all of these properties are relevant or useful > + for all hardware or binding structures. Each individual binding document > + should state which of these generic properties, if any, are used, and the > + structure of the DT nodes that contain these properties. > + > +properties: > + bias-disable: > + type: boolean > + description: disable any pin bias > + > + bias-high-impedance: > + type: boolean > + description: high impedance mode ("third-state", "floating") > + > + bias-bus-hold: > + type: boolean > + description: latch weakly > + > + bias-pull-up: > + oneOf: > + - type: boolean > + - $ref: /schemas/types.yaml#/definitions/uint32 > + description: pull up the pin. Takes as optional argument on hardware > + supporting it the pull strength in Ohm. > + > + bias-pull-down: > + oneOf: > + - type: boolean > + - $ref: /schemas/types.yaml#/definitions/uint32 > + description: pull down the pin. Takes as optional argument on hardware > + supporting it the pull strength in Ohm. > + > + bias-pull-pin-default: > + oneOf: > + - type: boolean > + - $ref: /schemas/types.yaml#/definitions/uint32 > + description: use pin-default pull state. Takes as optional argument on > + hardware supporting it the pull strength in Ohm. > + > + drive-push-pull: > + type: boolean > + description: drive actively high and low > + > + drive-open-drain: > + type: boolean > + description: drive with open drain > + > + drive-open-source: > + type: boolean > + description: drive with open source > + > + drive-strength: > + $ref: /schemas/types.yaml#/definitions/uint32 > + description: sink or source at most X mA > + > + drive-strength-microamp: > + description: sink or source at most X uA > + > + input-enable: > + type: boolean > + description: enable input on pin (no effect on output, such as > + enabling an input buffer) > + > + input-disable: > + type: boolean > + description: disable input on pin (no effect on output, such as > + disabling an input buffer) > + > + input-schmitt-enable: > + type: boolean > + description: enable schmitt-trigger mode > + > + input-schmitt-disable: > + type: boolean > + description: disable schmitt-trigger mode > + > + input-debounce: > + $ref: /schemas/types.yaml#/definitions/uint32 > + description: Takes the debounce time in usec as argument or 0 to disable > + debouncing > + > + power-source: > + $ref: /schemas/types.yaml#/definitions/uint32 > + description: select between different power supplies > + > + low-power-enable: > + type: boolean > + description: enable low power mode > + > + low-power-disable: > + type: boolean > + description: disable low power mode > + > + output-disable: > + type: boolean > + description: disable output on a pin (such as disable an output buffer) > + > + output-enable: > + type: boolean > + description: enable output on a pin without actively driving it > + (such as enabling an output buffer) > + > + output-low: > + type: boolean > + description: set the pin to output mode with low level > + > + output-high: > + type: boolean > + description: set the pin to output mode with high level > + > + sleep-hardware-state: > + type: boolean > + description: indicate this is sleep related state which will be > + programmed into the registers for the sleep state. > + > + slew-rate: > + $ref: /schemas/types.yaml#/definitions/uint32 > + description: set the slew rate > + > + skew-delay: > + $ref: /schemas/types.yaml#/definitions/uint32 > + description: > + this affects the expected clock skew on input pins > + and the delay before latching a value to an output > + pin. Typically indicates how many double-inverters are > + used to delay the signal. > diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt > index fcd37e93ed4d..4613bb17ace3 100644 > --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt > +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt > @@ -141,196 +141,8 @@ controller device. > > == Generic pin multiplexing node content == > > -pin multiplexing nodes: > - > -function - the mux function to select > -groups - the list of groups to select with this function > - (either this or "pins" must be specified) > -pins - the list of pins to select with this function (either > - this or "groups" must be specified) > - > -Example: > - > -state_0_node_a { > - uart0 { > - function = "uart0"; > - groups = "u0rxtx", "u0rtscts"; > - }; > -}; > -state_1_node_a { > - spi0 { > - function = "spi0"; > - groups = "spi0pins"; > - }; > -}; > -state_2_node_a { > - function = "i2c0"; > - pins = "mfio29", "mfio30"; > -}; > - > -Optionally an alternative binding can be used if more suitable depending on the > -pin controller hardware. For hardware where there is a large number of identical > -pin controller instances, naming each pin and function can easily become > -unmaintainable. This is especially the case if the same controller is used for > -different pins and functions depending on the SoC revision and packaging. > - > -For cases like this, the pin controller driver may use pinctrl-pin-array helper > -binding with a hardware based index and a number of pin configuration values: > - > -pincontroller { > - ... /* Standard DT properties for the device itself elided */ > - #pinctrl-cells = <2>; > - > - state_0_node_a { > - pinctrl-pin-array = < > - 0 A_DELAY_PS(0) G_DELAY_PS(120) > - 4 A_DELAY_PS(0) G_DELAY_PS(360) > - ... > - >; > - }; > - ... > -}; > - > -Above #pinctrl-cells specifies the number of value cells in addition to the > -index of the registers. This is similar to the interrupts-extended binding with > -one exception. There is no need to specify the phandle for each entry as that > -is already known as the defined pins are always children of the pin controller > -node. Further having the phandle pointing to another pin controller would not > -currently work as the pinctrl framework uses named modes to group pins for each > -pin control device. > - > -The index for pinctrl-pin-array must relate to the hardware for the pinctrl > -registers, and must not be a virtual index of pin instances. The reason for > -this is to avoid mapping of the index in the dts files and the pin controller > -driver as it can change. > - > -For hardware where pin multiplexing configurations have to be specified for > -each single pin the number of required sub-nodes containing "pin" and > -"function" properties can quickly escalate and become hard to write and > -maintain. > - > -For cases like this, the pin controller driver may use the pinmux helper > -property, where the pin identifier is provided with mux configuration settings > -in a pinmux group. A pinmux group consists of the pin identifier and mux > -settings represented as a single integer or an array of integers. > - > -The pinmux property accepts an array of pinmux groups, each of them describing > -a single pin multiplexing configuration. > - > -pincontroller { > - state_0_node_a { > - pinmux = <PINMUX_GROUP>, <PINMUX_GROUP>, ...; > - }; > -}; > - > -Each individual pin controller driver bindings documentation shall specify > -how pin IDs and pin multiplexing configuration are defined and assembled > -together in a pinmux group. > +See pinmux-node.yaml > > == Generic pin configuration node content == > > -Many data items that are represented in a pin configuration node are common > -and generic. Pin control bindings should use the properties defined below > -where they are applicable; not all of these properties are relevant or useful > -for all hardware or binding structures. Each individual binding document > -should state which of these generic properties, if any, are used, and the > -structure of the DT nodes that contain these properties. > - > -Supported generic properties are: > - > -pins - the list of pins that properties in the node > - apply to (either this, "group" or "pinmux" has to be > - specified) > -group - the group to apply the properties to, if the driver > - supports configuration of whole groups rather than > - individual pins (either this, "pins" or "pinmux" has > - to be specified) > -pinmux - the list of numeric pin ids and their mux settings > - that properties in the node apply to (either this, > - "pins" or "groups" have to be specified) > -bias-disable - disable any pin bias > -bias-high-impedance - high impedance mode ("third-state", "floating") > -bias-bus-hold - latch weakly > -bias-pull-up - pull up the pin > -bias-pull-down - pull down the pin > -bias-pull-pin-default - use pin-default pull state > -drive-push-pull - drive actively high and low > -drive-open-drain - drive with open drain > -drive-open-source - drive with open source > -drive-strength - sink or source at most X mA > -drive-strength-microamp - sink or source at most X uA > -input-enable - enable input on pin (no effect on output, such as > - enabling an input buffer) > -input-disable - disable input on pin (no effect on output, such as > - disabling an input buffer) > -input-schmitt-enable - enable schmitt-trigger mode > -input-schmitt-disable - disable schmitt-trigger mode > -input-debounce - debounce mode with debound time X > -power-source - select between different power supplies > -low-power-enable - enable low power mode > -low-power-disable - disable low power mode > -output-disable - disable output on a pin (such as disable an output > - buffer) > -output-enable - enable output on a pin without actively driving it > - (such as enabling an output buffer) > -output-low - set the pin to output mode with low level > -output-high - set the pin to output mode with high level > -sleep-hardware-state - indicate this is sleep related state which will be programmed > - into the registers for the sleep state. > -slew-rate - set the slew rate > -skew-delay - this affects the expected clock skew on input pins > - and the delay before latching a value to an output > - pin. Typically indicates how many double-inverters are > - used to delay the signal. > - > -For example: > - > -state_0_node_a { > - cts_rxd { > - pins = "GPIO0_AJ5", "GPIO2_AH4"; /* CTS+RXD */ > - bias-pull-up; > - }; > -}; > -state_1_node_a { > - rts_txd { > - pins = "GPIO1_AJ3", "GPIO3_AH3"; /* RTS+TXD */ > - output-high; > - }; > -}; > -state_2_node_a { > - foo { > - group = "foo-group"; > - bias-pull-up; > - }; > -}; > -state_3_node_a { > - mux { > - pinmux = <GPIOx_PINm_MUXn>, <GPIOx_PINj_MUXk)>; > - input-enable; > - }; > -}; > - > -Some of the generic properties take arguments. For those that do, the > -arguments are described below. > - > -- pins takes a list of pin names or IDs as a required argument. The specific > - binding for the hardware defines: > - - Whether the entries are integers or strings, and their meaning. > - > -- pinmux takes a list of pin IDs and mux settings as required argument. The > - specific bindings for the hardware defines: > - - How pin IDs and mux settings are defined and assembled together in a single > - integer or an array of integers. > - > -- bias-pull-up, -down and -pin-default take as optional argument on hardware > - supporting it the pull strength in Ohm. bias-disable will disable the pull. > - > -- drive-strength takes as argument the target strength in mA. > - > -- drive-strength-microamp takes as argument the target strength in uA. > - > -- input-debounce takes the debounce time in usec as argument > - or 0 to disable debouncing > - > -More in-depth documentation on these parameters can be found in > -<include/linux/pinctrl/pinconf-generic.h> > +See pincfg-node.yaml > diff --git a/Documentation/devicetree/bindings/pinctrl/pinmux-node.yaml b/Documentation/devicetree/bindings/pinctrl/pinmux-node.yaml > new file mode 100644 > index 000000000000..777623a57fd5 > --- /dev/null > +++ b/Documentation/devicetree/bindings/pinctrl/pinmux-node.yaml > @@ -0,0 +1,132 @@ > +# SPDX-License-Identifier: GPL-2.0-only > +%YAML 1.2 > +--- > +$id: http://devicetree.org/schemas/pinctrl/pinmux-node.yaml# > +$schema: http://devicetree.org/meta-schemas/core.yaml# > + > +title: Generic pin multiplexing node schema > + > +maintainers: > + - Linus Walleij <linus.walleij@xxxxxxxxxx> > + > +description: | > + The contents of the pin configuration child nodes are defined by the binding > + for the individual pin controller device. The pin configuration nodes need not > + be direct children of the pin controller device; they may be grandchildren, > + for example. Whether this is legal, and whether there is any interaction > + between the child and intermediate parent nodes, is again defined entirely by > + the binding for the individual pin controller device. > + > + While not required to be used, there are 3 generic forms of pin muxing nodes > + which pin controller devices can use. > + > + pin multiplexing nodes: > + > + Example: > + > + state_0_node_a { > + uart0 { > + function = "uart0"; > + groups = "u0rxtx", "u0rtscts"; > + }; > + }; > + state_1_node_a { > + spi0 { > + function = "spi0"; > + groups = "spi0pins"; > + }; > + }; > + state_2_node_a { > + function = "i2c0"; > + pins = "mfio29", "mfio30"; > + }; > + > + Optionally an alternative binding can be used if more suitable depending on the > + pin controller hardware. For hardware where there is a large number of identical > + pin controller instances, naming each pin and function can easily become > + unmaintainable. This is especially the case if the same controller is used for > + different pins and functions depending on the SoC revision and packaging. > + > + For cases like this, the pin controller driver may use pinctrl-pin-array helper > + binding with a hardware based index and a number of pin configuration values: > + > + pincontroller { > + ... /* Standard DT properties for the device itself elided */ > + #pinctrl-cells = <2>; > + > + state_0_node_a { > + pinctrl-pin-array = < > + 0 A_DELAY_PS(0) G_DELAY_PS(120) > + 4 A_DELAY_PS(0) G_DELAY_PS(360) > + ... > + >; > + }; > + ... > + }; > + > + Above #pinctrl-cells specifies the number of value cells in addition to the > + index of the registers. This is similar to the interrupts-extended binding with > + one exception. There is no need to specify the phandle for each entry as that > + is already known as the defined pins are always children of the pin controller > + node. Further having the phandle pointing to another pin controller would not > + currently work as the pinctrl framework uses named modes to group pins for each > + pin control device. > + > + The index for pinctrl-pin-array must relate to the hardware for the pinctrl > + registers, and must not be a virtual index of pin instances. The reason for > + this is to avoid mapping of the index in the dts files and the pin controller > + driver as it can change. > + > + For hardware where pin multiplexing configurations have to be specified for > + each single pin the number of required sub-nodes containing "pin" and > + "function" properties can quickly escalate and become hard to write and > + maintain. > + > + For cases like this, the pin controller driver may use the pinmux helper > + property, where the pin identifier is provided with mux configuration settings > + in a pinmux group. A pinmux group consists of the pin identifier and mux > + settings represented as a single integer or an array of integers. > + > + The pinmux property accepts an array of pinmux groups, each of them describing > + a single pin multiplexing configuration. > + > + pincontroller { > + state_0_node_a { > + pinmux = <PINMUX_GROUP>, <PINMUX_GROUP>, ...; > + }; > + }; > + > + Each individual pin controller driver bindings documentation shall specify > + how pin IDs and pin multiplexing configuration are defined and assembled > + together in a pinmux group. > + > +properties: > + function: > + $ref: /schemas/types.yaml#/definitions/string > + description: The mux function to select > + > + pins: > + oneOf: > + - $ref: /schemas/types.yaml#/definitions/uint32-array > + - $ref: /schemas/types.yaml#/definitions/string-array > + description: > + The list of pin identifiers that properties in the node apply to. The > + specific binding for the hardware defines whether the entries are integers > + or strings, and their meaning. > + > + group: > + $ref: /schemas/types.yaml#/definitions/string-array > + description: > + the group to apply the properties to, if the driver supports > + configuration of whole groups rather than individual pins (either > + this, "pins" or "pinmux" has to be specified) > + > + pinmux: > + allOf: > + - $ref: /schemas/types.yaml#/definitions/uint32-array > + description: > + The list of numeric pin ids and their mux settings that properties in the > + node apply to (either this, "pins" or "groups" have to be specified) > + > + pinctrl-pin-array: > + $ref: /schemas/types.yaml#/definitions/uint32-array > -- > 2.20.1 >
