[PATCH v2 1/2] dt-bindings: pps: pps-gpio: document optional pinctrl states

[Eliav Farber <farbere@amazon.com>]

When the PPS input GPIO is routed through a pin controller, a board may
need to mux those pins to a different function while pps-gpio is not
driving PPS (for example after the driver is unbound or across a kexec).

Document the optional "default" and "inactive" pinctrl-names and show
both in the example. The "default" state selects the PPS/GPIO function
and is applied by the driver core before probe; the optional "inactive"
state, when present, describes the mux to restore when the driver is
unbound or the system is shut down. As "inactive" is only the state to
restore after "default", it may only appear as the second entry, so a
"default" state is required whenever "inactive" is given.

Signed-off-by: Eliav Farber <farbere@amazon.com>
---
Changes in v2:
- Rename the released state from "idle" to "inactive"; document that
  "inactive" may only be the second entry, so a "default" state is
  required whenever "inactive" is given

 .../devicetree/bindings/pps/pps-gpio.yaml        | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/pps/pps-gpio.yaml b/Documentation/devicetree/bindings/pps/pps-gpio.yaml
index 383a838744eb..7d11ec4656ee 100644
--- a/Documentation/devicetree/bindings/pps/pps-gpio.yaml
+++ b/Documentation/devicetree/bindings/pps/pps-gpio.yaml
@@ -28,6 +28,19 @@ properties:
     description: Indicates a falling edge assert, when present. Rising edge if absent.
     type: boolean
 
+  pinctrl-names:
+    description:
+      When the PPS input is muxed through a pin controller, the "default"
+      state selects the PPS/GPIO function and is applied by the driver core
+      before probe. The optional "inactive" state, when present, is selected
+      when the driver is unbound or the system is shut down, handing the pins
+      back to their alternate function. As "inactive" is the state to restore
+      after "default", it may only appear as the second entry.
+    minItems: 1
+    items:
+      - const: default
+      - const: inactive
+
 required:
   - compatible
   - gpios
@@ -40,8 +53,9 @@ examples:
 
     pps {
         compatible = "pps-gpio";
-        pinctrl-names = "default";
+        pinctrl-names = "default", "inactive";
         pinctrl-0 = <&pinctrl_pps>;
+        pinctrl-1 = <&pinctrl_pps_inactive>;
         gpios = <&gpio1 26 GPIO_ACTIVE_HIGH>;
         assert-falling-edge;
         echo-gpios = <&gpio1 27 GPIO_ACTIVE_HIGH>;
-- 
2.47.3