From: Matti Vaittinen A few of the ROHM PMICs have a state-machine corrsponding to the SOC power-states. Idea is that by changing the PMIC state, all power-outputs will be switched to a pre-defined state. As an example, the SOC may use a low-power state when system is suspended, and when transitioning from the normal operation to suspend, the PMIC can be told to go to SUSPEND-state - which will then switch outputs of all power-rails to pre-defined low-power state matching the SOC expectation for SUSPEND. In addition to the SUSPEND, there are a few other states as well. The voltage values & enable / disable -states matching the SOC expectations can be set for the PMIC states using rohm,dvs--voltage -properties. It all started with the BD71837 supporting this, but over the years these same properties have been used for a few other PMICs, and seems like this HW-state machine design is not going away. Copying the descriptions and types in each PMIC specific binding, and discussing them during the reviews is getting tedious for the reviewers and author(s) alike. Furthermore, having separate descriptions makes it very easy to add errors, or differing, and even contradicting documentation for properties with same name. Avoid these issues by using one common file for the common ROHM PMIC state-machine definitions and only referencing this from the individual PMIC bindings. Signed-off-by: Matti Vaittinen Suggested-by: Rob Herring --- This was discussed briefly here: https://lore.kernel.org/all/20260701192559.GA1313239-robh@kernel.org/ I will send this separately from the BD73900 -series to keep the series a bit smaller and to allow this to get merged independently. I can however send the further revisions in the BD73900 -series if that's preferred by reviewers. --- .../regulator/rohm,bd71815-regulator.yaml | 27 +++------ .../regulator/rohm,bd71828-regulator.yaml | 20 +------ .../regulator/rohm,bd71837-regulator.yaml | 16 +----- .../regulator/rohm,bd71847-regulator.yaml | 16 +----- .../regulator/rohm,bd72720-regulator.yaml | 40 ++----------- .../bindings/regulator/rohm,pmic-states.yaml | 57 +++++++++++++++++++ 6 files changed, 79 insertions(+), 97 deletions(-) create mode 100644 Documentation/devicetree/bindings/regulator/rohm,pmic-states.yaml diff --git a/Documentation/devicetree/bindings/regulator/rohm,bd71815-regulator.yaml b/Documentation/devicetree/bindings/regulator/rohm,bd71815-regulator.yaml index cc4ceb32e9d6..68b5e579e2d3 100644 --- a/Documentation/devicetree/bindings/regulator/rohm,bd71815-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/rohm,bd71815-regulator.yaml @@ -38,7 +38,9 @@ patternProperties: type: object description: Properties for single LDO/BUCK regulator. - $ref: regulator.yaml# + allOf: + - $ref: regulator.yaml# + - $ref: rohm,pmic-states.yaml# properties: regulator-name: @@ -51,15 +53,6 @@ patternProperties: description: GPIO used to control ldo4 state (when ldo4 is controlled by GPIO). - rohm,dvs-run-voltage: - description: - PMIC "RUN" state voltage in uV when PMIC HW states are used. See - comments below for bucks/LDOs which support this. 0 means - regulator should be disabled at RUN state. - $ref: /schemas/types.yaml#/definitions/uint32 - minimum: 0 - maximum: 3300000 - rohm,dvs-snvs-voltage: description: Whether to keep regulator enabled at "SNVS" state or not. @@ -71,21 +64,15 @@ patternProperties: minimum: 0 maximum: 3300000 + rohm,dvs-run-voltage: + minimum: 0 + maximum: 3300000 + rohm,dvs-suspend-voltage: - description: - PMIC "SUSPEND" state voltage in uV when PMIC HW states are used. See - comments below for bucks/LDOs which support this. 0 means - regulator should be disabled at SUSPEND state. - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 3300000 rohm,dvs-lpsr-voltage: - description: - PMIC "LPSR" state voltage in uV when PMIC HW states are used. See - comments below for bucks/LDOs which support this. 0 means - regulator should be disabled at LPSR state. - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 3300000 diff --git a/Documentation/devicetree/bindings/regulator/rohm,bd71828-regulator.yaml b/Documentation/devicetree/bindings/regulator/rohm,bd71828-regulator.yaml index d898800d6bca..8cba397678a6 100644 --- a/Documentation/devicetree/bindings/regulator/rohm,bd71828-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/rohm,bd71828-regulator.yaml @@ -40,7 +40,9 @@ patternProperties: type: object description: Properties for single BUCK regulator. - $ref: regulator.yaml# + allOf: + - $ref: regulator.yaml# + - $ref: rohm,pmic-states.yaml# properties: regulator-name: @@ -49,34 +51,18 @@ patternProperties: should be "buck1", ..., "buck7" rohm,dvs-run-voltage: - description: - PMIC default "RUN" state voltage in uV. See below table for - bucks which support this. 0 means disabled. - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 3300000 rohm,dvs-idle-voltage: - description: - PMIC default "IDLE" state voltage in uV. See below table for - bucks which support this. 0 means disabled. - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 3300000 rohm,dvs-suspend-voltage: - description: - PMIC default "SUSPEND" state voltage in uV. See below table for - bucks which support this. 0 means disabled. - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 3300000 rohm,dvs-lpsr-voltage: - description: - PMIC default "LPSR" state voltage in uV. See below table for - bucks which support this. 0 means disabled. - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 3300000 diff --git a/Documentation/devicetree/bindings/regulator/rohm,bd71837-regulator.yaml b/Documentation/devicetree/bindings/regulator/rohm,bd71837-regulator.yaml index 29b350a4f88a..efb38dd15145 100644 --- a/Documentation/devicetree/bindings/regulator/rohm,bd71837-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/rohm,bd71837-regulator.yaml @@ -44,7 +44,9 @@ patternProperties: "^BUCK[1-8]$": type: object - $ref: regulator.yaml# + allOf: + - $ref: regulator.yaml# + - $ref: rohm,pmic-states.yaml# description: Properties for single BUCK regulator. @@ -55,28 +57,16 @@ patternProperties: should be "buck1", ..., "buck8" rohm,dvs-run-voltage: - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 1300000 - description: - PMIC default "RUN" state voltage in uV. See below table for - bucks which support this. 0 means disabled. rohm,dvs-idle-voltage: - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 1300000 - description: - PMIC default "IDLE" state voltage in uV. See below table for - bucks which support this. 0 means disabled. rohm,dvs-suspend-voltage: - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 1300000 - description: - PMIC default "SUSPEND" state voltage in uV. See below table for - bucks which support this. 0 means disabled. # Supported default DVS states: # diff --git a/Documentation/devicetree/bindings/regulator/rohm,bd71847-regulator.yaml b/Documentation/devicetree/bindings/regulator/rohm,bd71847-regulator.yaml index 7ba4ccf723d8..ef6f69be24ae 100644 --- a/Documentation/devicetree/bindings/regulator/rohm,bd71847-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/rohm,bd71847-regulator.yaml @@ -43,7 +43,9 @@ patternProperties: "^BUCK[1-6]$": type: object - $ref: regulator.yaml# + allOf: + - $ref: regulator.yaml# + - $ref: rohm,pmic-states.yaml# description: Properties for single BUCK regulator. @@ -54,28 +56,16 @@ patternProperties: should be "buck1", ..., "buck6" rohm,dvs-run-voltage: - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 1300000 - description: - PMIC default "RUN" state voltage in uV. See below table for - bucks which support this. 0 means disabled. rohm,dvs-idle-voltage: - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 1300000 - description: - PMIC default "IDLE" state voltage in uV. See below table for - bucks which support this. 0 means disabled. rohm,dvs-suspend-voltage: - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 1300000 - description: - PMIC default "SUSPEND" state voltage in uV. See below table for - bucks which support this. 0 means disabled. # Supported default DVS states: # diff --git a/Documentation/devicetree/bindings/regulator/rohm,bd72720-regulator.yaml b/Documentation/devicetree/bindings/regulator/rohm,bd72720-regulator.yaml index 5518082129bd..76747bf2bbdd 100644 --- a/Documentation/devicetree/bindings/regulator/rohm,bd72720-regulator.yaml +++ b/Documentation/devicetree/bindings/regulator/rohm,bd72720-regulator.yaml @@ -26,41 +26,27 @@ patternProperties: type: object description: Properties for single LDO regulator. - $ref: regulator.yaml# + allOf: + - $ref: regulator.yaml# + - $ref: rohm,pmic-states.yaml# properties: regulator-name: pattern: "^ldo([1-9]|1[0-1])$" rohm,dvs-run-voltage: - description: - PMIC default "RUN" state voltage in uV. See below table for - LDOs which support this. 0 means disabled. - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 3300000 rohm,dvs-idle-voltage: - description: - PMIC default "IDLE" state voltage in uV. See below table for - LDOs which support this. 0 means disabled. - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 3300000 rohm,dvs-suspend-voltage: - description: - PMIC default "SUSPEND" state voltage in uV. See below table for - LDOs which support this. 0 means disabled. - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 3300000 rohm,dvs-lpsr-voltage: - description: - PMIC default "deep-idle" state voltage in uV. See below table for - LDOs which support this. 0 means disabled. - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 3300000 @@ -82,7 +68,9 @@ patternProperties: type: object description: Properties for single BUCK regulator. - $ref: regulator.yaml# + allOf: + - $ref: regulator.yaml# + - $ref: rohm,pmic-states.yaml# properties: regulator-name: @@ -97,34 +85,18 @@ patternProperties: maximum: 300000 rohm,dvs-run-voltage: - description: - PMIC default "RUN" state voltage in uV. See below table for - bucks which support this. 0 means disabled. - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 3300000 rohm,dvs-idle-voltage: - description: - PMIC default "IDLE" state voltage in uV. See below table for - bucks which support this. 0 means disabled. - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 3300000 rohm,dvs-suspend-voltage: - description: - PMIC default "SUSPEND" state voltage in uV. See below table for - bucks which support this. 0 means disabled. - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 3300000 rohm,dvs-lpsr-voltage: - description: - PMIC default "deep-idle" state voltage in uV. See below table for - bucks which support this. 0 means disabled. - $ref: /schemas/types.yaml#/definitions/uint32 minimum: 0 maximum: 3300000 diff --git a/Documentation/devicetree/bindings/regulator/rohm,pmic-states.yaml b/Documentation/devicetree/bindings/regulator/rohm,pmic-states.yaml new file mode 100644 index 000000000000..f09f021bdde4 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/rohm,pmic-states.yaml @@ -0,0 +1,57 @@ +# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/regulator/rohm,pmic-states.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: ROHM PMICs' hardware state machine descriptions + +maintainers: + - Matti Vaittinen + +description: + Many of the ROHM PMICs have internal state-machine designed to provide + correct voltages for different SOC states. In many cases the states and + transitions are SOC specific, but ones described here can be found from a + few of the different ROHM PMICs. + +properties: + rohm,dvs-run-voltage: + description: + PMIC "RUN" state voltage in uV when PMIC HW states are used. 0 means the + regulator should be disabled at RUN state. Some regulators do not support + setting HW state specific voltage but do support enable/disable control. + For them any positive value means the regulator should be enabled without + touching the voltage. + $ref: /schemas/types.yaml#/definitions/uint32 + + rohm,dvs-suspend-voltage: + description: + PMIC "SUSPEND" state voltage in uV when PMIC HW states are used. 0 means + the regulator should be disabled at SUSPEND state. Some regulators do not + support setting HW state specific voltage but do support enable/disable + control. For them any positive value means the regulator should be + enabled without touching the voltage. + $ref: /schemas/types.yaml#/definitions/uint32 + + rohm,dvs-idle-voltage: + description: + PMIC "IDLE" state voltage in uV. 0 means the regulator should be disabled + at IDLE state. Some regulators do not support setting HW state specific + voltage but do support enable/disable control. For them any positive + value means the regulator should be enabled without touching the voltage. + $ref: /schemas/types.yaml#/definitions/uint32 + + rohm,dvs-lpsr-voltage: + description: + PMIC "LPSR" state voltage in uV when PMIC HW states are used. 0 means the + regulator should be disabled at LPSR state. Some regulators do not + support setting HW state specific voltage but do support enable/disable + control. For them any positive value means the regulator should be + enabled without touching the voltage. Some PMICs' documentation may refer + to this state as a "deep-idle state". + $ref: /schemas/types.yaml#/definitions/uint32 + +# The schema is expected to be reference by PMIC schemas, which may introduce +# other properties that must be allowed. +additionalProperties: true base-commit: dc59e4fea9d83f03bad6bddf3fa2e52491777482 -- 2.54.0