[PATCH v5 1/3] dt-bindings: clk: vc5: Add properties for configuring the SD/OE pin

[PATCH v5 1/3] dt-bindings: clk: vc5: Add properties for configuring the SD/OE pin

[Sean Anderson]

These properties allow configuring the SD/OE pin as described in the
datasheet.

Signed-off-by: Sean Anderson <sean.anderson@seco.com>
---
This patch requires the dt-schema commit 25b1b49 ("meta-schemas: Drop
restrictions on top level 'allOf'") to pass dt_binding_check.

Changes in v5:
- Don't use dummy if's for oneOfs under allOfs

Changes in v4:
- Specify that bindings should specify these properties, but don't make
  any guarantees about the driver's behavior when they are not present.
- Clarify description of idt,(en|dis)able-shutdown properties.
- Make opposing properties mutually exclusive.
- Add these properties to the example.

Changes in v3:
- Add idt,disable-shutdown and idt,output-enable-active-low to allow for
  a default of not changing the SP/SH bits at all.

Changes in v2:
- Rename idt,sd-active-high to idt,output-enable-active-high
- Add idt,enable-shutdown

 .../bindings/clock/idt,versaclock5.yaml       | 57 +++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml
index 28675b0b80f1..1abf69e6b8e9 100644
--- a/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml
+++ b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml
@@ -30,6 +30,21 @@ description: |
     3 -- OUT3
     4 -- OUT4
 
+  The idt,(en|dis)able-shutdown and idt,output-enable-active-(high|low)
+  properties control the SH (en_global_shutdown) and SP bits of the
+  Primary Source and Shutdown Register, respectively. Their behavior is
+  summarized by the following table:
+
+  SH SP Output when the SD/OE pin is Low/High
+  == == =====================================
+   0  0 Active/Inactive
+   0  1 Inactive/Active
+   1  0 Active/Shutdown
+   1  1 Inactive/Shutdown
+
+  One of idt,(en|dis)able-shutdown and one of
+  idt,output-enable-active-(high|low) should be specified.
+
 maintainers:
   - Luca Ceresoli <luca@lucaceresoli.net>
 
@@ -64,6 +79,34 @@ properties:
     maximum: 22760
     description: Optional load capacitor for XTAL1 and XTAL2
 
+  idt,enable-shutdown:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description: |
+      Enable the shutdown functionality. The chip will be shut down if
+      the SD/OE pin is driven high. This corresponds to setting the SH
+      bit of the Primary Source and Shutdown Register.
+
+  idt,disable-shutdown:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description: |
+      Disable the shutdown functionality. The chip will never be shut
+      down based on the value of the SD/OE pin. This corresponds to
+      clearing the SH bit of the Primary Source and Shutdown Register.
+
+  idt,output-enable-active-high:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description: |
+      This enables output when the SD/OE pin is high, and disables
+      output when the SD/OE pin is low. This corresponds to setting the
+      SP bit of the Primary Source and Shutdown Register.
+
+  idt,output-enable-active-low:
+    $ref: /schemas/types.yaml#/definitions/flag
+    description: |
+      This disables output when the SD/OE pin is high, and enables
+      output when the SD/OE pin is low. This corresponds to clearing the
+      SP bit of the Primary Source and Shutdown Register.
+
 patternProperties:
   "^OUT[1-4]$":
     type: object
@@ -109,6 +152,16 @@ allOf:
       required:
         - clock-names
         - clocks
+  - oneOf:
+      - required:
+          - idt,enable-shutdown
+      - required:
+          - idt,disable-shutdown
+  - oneOf:
+      - required:
+          - idt,output-enable-active-high
+      - required:
+          - idt,output-enable-active-low
 
 additionalProperties: false
 
@@ -138,6 +191,10 @@ examples:
             clocks = <&ref25m>;
             clock-names = "xin";
 
+            /* Set the SD/OE pin's settings */
+            idt,disable-shutdown;
+            idt,output-enable-active-low;
+
             OUT1 {
                 idt,drive-mode = <VC5_CMOSD>;
                 idt,voltage-microvolts = <1800000>;
-- 
2.25.1

Re: [PATCH v5 1/3] dt-bindings: clk: vc5: Add properties for configuring the SD/OE pin

[Rob Herring]

On Thu, Jul 22, 2021 at 03:09:16PM -0400, Sean Anderson wrote:
> These properties allow configuring the SD/OE pin as described in the
> datasheet.
> 
> Signed-off-by: Sean Anderson <sean.anderson@seco.com>
> ---
> This patch requires the dt-schema commit 25b1b49 ("meta-schemas: Drop
> restrictions on top level 'allOf'") to pass dt_binding_check.
> 
> Changes in v5:
> - Don't use dummy if's for oneOfs under allOfs
> 
> Changes in v4:
> - Specify that bindings should specify these properties, but don't make
>   any guarantees about the driver's behavior when they are not present.
> - Clarify description of idt,(en|dis)able-shutdown properties.
> - Make opposing properties mutually exclusive.
> - Add these properties to the example.
> 
> Changes in v3:
> - Add idt,disable-shutdown and idt,output-enable-active-low to allow for
>   a default of not changing the SP/SH bits at all.
> 
> Changes in v2:
> - Rename idt,sd-active-high to idt,output-enable-active-high
> - Add idt,enable-shutdown
> 
>  .../bindings/clock/idt,versaclock5.yaml       | 57 +++++++++++++++++++
>  1 file changed, 57 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml
> index 28675b0b80f1..1abf69e6b8e9 100644
> --- a/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml
> +++ b/Documentation/devicetree/bindings/clock/idt,versaclock5.yaml
> @@ -30,6 +30,21 @@ description: |
>      3 -- OUT3
>      4 -- OUT4
>  
> +  The idt,(en|dis)able-shutdown and idt,output-enable-active-(high|low)
> +  properties control the SH (en_global_shutdown) and SP bits of the
> +  Primary Source and Shutdown Register, respectively. Their behavior is
> +  summarized by the following table:
> +
> +  SH SP Output when the SD/OE pin is Low/High
> +  == == =====================================
> +   0  0 Active/Inactive
> +   0  1 Inactive/Active
> +   1  0 Active/Shutdown
> +   1  1 Inactive/Shutdown
> +
> +  One of idt,(en|dis)able-shutdown and one of
> +  idt,output-enable-active-(high|low) should be specified.
> +
>  maintainers:
>    - Luca Ceresoli <luca@lucaceresoli.net>
>  
> @@ -64,6 +79,34 @@ properties:
>      maximum: 22760
>      description: Optional load capacitor for XTAL1 and XTAL2
>  
> +  idt,enable-shutdown:
> +    $ref: /schemas/types.yaml#/definitions/flag
> +    description: |
> +      Enable the shutdown functionality. The chip will be shut down if
> +      the SD/OE pin is driven high. This corresponds to setting the SH
> +      bit of the Primary Source and Shutdown Register.
> +
> +  idt,disable-shutdown:
> +    $ref: /schemas/types.yaml#/definitions/flag
> +    description: |
> +      Disable the shutdown functionality. The chip will never be shut
> +      down based on the value of the SD/OE pin. This corresponds to
> +      clearing the SH bit of the Primary Source and Shutdown Register.

If these are mutually exclusive, better to do tristate. So 'idt,shutdown 
= 0|1' for disable/enable. Not present means use the default.

> +
> +  idt,output-enable-active-high:
> +    $ref: /schemas/types.yaml#/definitions/flag
> +    description: |
> +      This enables output when the SD/OE pin is high, and disables
> +      output when the SD/OE pin is low. This corresponds to setting the
> +      SP bit of the Primary Source and Shutdown Register.
> +
> +  idt,output-enable-active-low:
> +    $ref: /schemas/types.yaml#/definitions/flag
> +    description: |
> +      This disables output when the SD/OE pin is high, and enables
> +      output when the SD/OE pin is low. This corresponds to clearing the
> +      SP bit of the Primary Source and Shutdown Register.

And here 'idt,output-enable-active = 0|1'.

> +
>  patternProperties:
>    "^OUT[1-4]$":
>      type: object
> @@ -109,6 +152,16 @@ allOf:
>        required:
>          - clock-names
>          - clocks
> +  - oneOf:
> +      - required:
> +          - idt,enable-shutdown
> +      - required:
> +          - idt,disable-shutdown
> +  - oneOf:
> +      - required:
> +          - idt,output-enable-active-high
> +      - required:
> +          - idt,output-enable-active-low

Then you can drop all this.

>  
>  additionalProperties: false
>  
> @@ -138,6 +191,10 @@ examples:
>              clocks = <&ref25m>;
>              clock-names = "xin";
>  
> +            /* Set the SD/OE pin's settings */
> +            idt,disable-shutdown;
> +            idt,output-enable-active-low;
> +
>              OUT1 {
>                  idt,drive-mode = <VC5_CMOSD>;
>                  idt,voltage-microvolts = <1800000>;
> -- 
> 2.25.1
> 
>