doc: document devicetree/pinctrl.h macros

Add a new section in the API reference for the newly added
devicetree/pinctrl.h macros.

Amend macros.bnf in the guide to reflect the new generated macros for
getting at pinctrl information by name.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>

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
 ===