DT: new pinctrl helpers

doc/guides/dts/macros.bnf

@@ -19,6 +19,8 @@ dt-macro = node-macro / other-macro
 
 ; A macro about a property value
 node-macro =  property-macro
+; A macro about the pinctrl properties in a node.
+node-macro =/ pinctrl-macro
 ; EXISTS macro: node exists in the devicetree
 node-macro =/ %s"DT_N" path-id %s"_EXISTS"
 ; Bus macros: the plain BUS is a way to access a node's bus controller.
@@ -71,6 +73,50 @@ node-macro =/ %s"DT_N" path-id %s"_REQUIRES_ORDS"
 ; The dependency ordinals of a node supports (reverse direct dependencies).
 node-macro =/ %s"DT_N" path-id %s"_SUPPORTS_ORDS"
 
+; --------------------------------------------------------------------
+; pinctrl-macro: a macro related to the pinctrl properties in a node
+;
+; These are a bit of a special case because they kind of form an array,
+; but the array indexes correspond to pinctrl-DIGIT properties in a node.
+;
+; So they're related to a node, but not just one property within the node.
+;
+; The following examples assume something like this:
+;
+;      foo {
+;              pinctrl-0 = <&bar>;
+;              pinctrl-1 = <&baz>;
+;              pinctrl-names = "default", "sleep";
+;      };
+
+; Total number of pinctrl-DIGIT properties in the node. May be zero.
+;
+;   #define DT_N_<node path>_PINCTRL_NUM 2
+pinctrl-macro = %s"DT_N" path-id %s"_PINCTRL_NUM"
+; A given pinctrl-DIGIT property exists.
+;
+;     #define DT_N_<node path>_PINCTRL_IDX_0_EXISTS 1
+;     #define DT_N_<node path>_PINCTRL_IDX_1_EXISTS 1
+pinctrl-macro =/ %s"DT_N" path-id %s"_PINCTRL_IDX_" DIGIT %s"_EXISTS"
+; A given pinctrl property name exists.
+;
+;     #define DT_N_<node path>_PINCTRL_NAME_default_EXISTS 1
+;     #define DT_N_<node path>_PINCTRL_NAME_sleep_EXISTS 1
+pinctrl-macro =/ %s"DT_N" path-id %s"_PINCTRL_NAME_" dt-name %s"_EXISTS"
+; The corresponding index number of a named pinctrl property.
+;
+;     #define DT_N_<node path>_PINCTRL_NAME_default_IDX 0
+;     #define DT_N_<node path>_PINCTRL_NAME_sleep_IDX 1
+pinctrl-macro =/ %s"DT_N" path-id %s"_PINCTRL_NAME_" dt-name %s"_IDX"
+; The node identifier for the phandle in a named pinctrl property.
+;
+;    #define DT_N_<node path>_PINCTRL_NAME_default_IDX_0_PH <node id for 'bar'>
+;
+; There's no need for a separate macro for access by index: that's
+; covered by property-macro. We only need this because the map from
+; names to properties is implicit in the structure of the DT.
+pinctrl-macro =/ %s"DT_N" path-id %s"_PINCTRL_NAME_" dt-name %s"_IDX_" DIGIT %s"_PH"
+
 ; --------------------------------------------------------------------
 ; property-macro: a macro related to a node property
 ;

doc/reference/devicetree/api.rst

@@ -254,6 +254,34 @@ channels (e.g. ADC or DAC channels) for conversion.
 
 .. doxygengroup:: devicetree-io-channels
 
+Pinctrl (pin control)
+=====================
+
+These are used to access pin control properties by name or index.
+
+Devicetree nodes may have properties which specify pin control (sometimes known
+as pin mux) settings. These are expressed using ``pinctrl-<index>`` properties
+within the node, where the ``<index>`` values are contiguous integers starting
+from 0. These may also be named using the ``pinctrl-names`` property.
+
+Here is an example:
+
+.. code-block:: DTS
+
+   node {
+       ...
+       pinctrl-0 = <&foo &bar ...>;
+       pinctrl-1 = <&baz ...>;
+       pinctrl-names = "default", "sleep";
+   };
+
+Above, ``pinctrl-0`` has name ``"default"``, and ``pinctrl-1`` has name
+``"sleep"``. The ``pinctrl-<index>`` property values contain phandles. The
+``&foo``, ``&bar``, etc. phandles within the properties point to nodes whose
+contents vary by platform, and which describe a pin configuration for the node.
+
+.. doxygengroup:: devicetree-pinctrl
+
 PWM
 ===
 

drivers/adc/adc_npcx.c

@@ -25,7 +25,7 @@ LOG_MODULE_REGISTER(adc_npcx, CONFIG_ADC_LOG_LEVEL);
 #define ADC_REGULAR_MEAST_VAL	0x0001
 
 /* ADC channel number */
-#define NPCX_ADC_CH_COUNT DT_INST_PROP_LEN(0, pinctrl_0)
+#define NPCX_ADC_CH_COUNT DT_INST_NUM_PINCTRLS_BY_IDX(0, 0)
 
 /* ADC targeted operating frequency (2MHz) */
 #define NPCX_ADC_CLK 2000000

drivers/i2c/i2c_ite_it8xxx2.c

@@ -1019,8 +1019,9 @@ static const struct i2c_driver_api i2c_it8xxx2_driver_api = {
 
 #define I2C_ITE_IT8XXX2_INIT(idx)                                              \
 	static void i2c_it8xxx2_config_func_##idx(void);                       \
-	static const struct i2c_alts_cfg i2c_alts_##idx[DT_INST_PROP_LEN       \
-		(idx, pinctrl_0)] = IT8XXX2_DT_ALT_ITEMS_LIST(idx);            \
+	static const struct i2c_alts_cfg                                       \
+		i2c_alts_##idx[DT_INST_NUM_PINCTRLS_BY_IDX(idx, 0)] =          \
+			IT8XXX2_DT_ALT_ITEMS_LIST(idx);                        \
 									       \
 	static const struct i2c_it8xxx2_config i2c_it8xxx2_cfg_##idx = {       \
 		.base = (uint8_t *)(DT_INST_REG_ADDR(idx)),                    \

drivers/pwm/pwm_ite_it8xxx2.c

@@ -51,10 +51,8 @@ struct pwm_it8xxx2_cfg {
 #define DRV_REG(dev)		(struct pwm_it8xxx2_regs *)(DRV_CONFIG(dev)->base)
 #define DEV_PINMUX(inst)	\
 	DEVICE_DT_GET(DT_PHANDLE_BY_IDX(DT_NODELABEL(pinctrl_pwm##inst), pinctrls, 0))
-#define DEV_PIN(inst)		\
-	DT_PHA(DT_PHANDLE_BY_IDX(DT_DRV_INST(inst), pinctrl_0, 0), pinctrls, pin)
-#define DEV_ALT_FUN(inst)	\
-	DT_PHA(DT_PHANDLE_BY_IDX(DT_DRV_INST(inst), pinctrl_0, 0), pinctrls, alt_func)
+#define DEV_PIN(inst)		DT_PHA(DT_INST_PINCTRL_0(inst, 0), pinctrls, pin)
+#define DEV_ALT_FUN(inst)	DT_PHA(DT_INST_PINCTRL_0(inst, 0), pinctrls, alt_func)
 
 static void pwm_enable(const struct device *dev, int enabled)
 {

dts/bindings/test/vnd,temperature-sensor.yaml → dts/bindings/test/vnd,adc-temp-sensor.yaml

@@ -21,3 +21,12 @@ properties:
 
     clocks:
       required: true
+
+    pinctrl-0:
+      type: phandles
+
+    pinctrl-1:
+      type: phandles
+
+    pinctrl-2:
+      type: phandles

dts/bindings/test/vnd,pinctrl.yaml

@@ -0,0 +1,8 @@
+# Copyright (c) 2021 Nordic Semiconductor ASA
+# SPDX-License-Identifier: Apache-2.0
+
+description: Test pin controller node
+
+compatible: "vnd,pinctrl"
+
+include: pincfg-node.yaml

include/devicetree.h

@@ -2673,5 +2673,6 @@
 #include <devicetree/fixed-partitions.h>
 #include <devicetree/zephyr.h>
 #include <devicetree/ordinals.h>
+#include <devicetree/pinctrl.h>
 
 #endif /* DEVICETREE_H */