Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 5025ef8b authored by Rob Herring's avatar Rob Herring
Browse files

dt-bindings: arm: Convert PSCI binding to json-schema 



Convert the PSCI binding to use DT schema format.

Cc: Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>
Cc: Will Deacon <will@kernel.org>
Signed-off-by: default avatarRob Herring <robh@kernel.org>
parent c875a3f8

Documentation/arm64/booting.txt

+1 −1
Original line number Diff line number Diff line
@@ -257,7 +257,7 @@ following manner: 
  processors") to bring CPUs into the kernel.



  The device tree should contain a 'psci' node, as described in

  Documentation/devicetree/bindings/arm/psci.txt.

  Documentation/devicetree/bindings/arm/psci.yaml.



- Secondary CPU general-purpose register settings

  x0 = 0 (reserved for future use)

Documentation/devicetree/bindings/arm/arm-boards

+1 −1
Original line number Diff line number Diff line
@@ -197,7 +197,7 @@ Required nodes: 
The description for the board must include:

   - a "psci" node describing the boot method used for the secondary CPUs.

     A detailed description of the bindings used for "psci" nodes is present

     in the psci.txt file.

     in the psci.yaml file.

   - a "cpus" node describing the available cores and their associated

     "enable-method"s. For more details see cpus.txt file.

Documentation/devicetree/bindings/arm/idle-states.txt

+1 −1
Original line number Diff line number Diff line
@@ -691,7 +691,7 @@ cpus { 
    Documentation/devicetree/bindings/arm/cpus.yaml



[2] ARM Linux Kernel documentation - PSCI bindings

    Documentation/devicetree/bindings/arm/psci.txt

    Documentation/devicetree/bindings/arm/psci.yaml



[3] ARM Server Base System Architecture (SBSA)

    http://infocenter.arm.com/help/index.jsp

Documentation/devicetree/bindings/arm/psci.txt

deleted100644 → 0
+0 −111
Original line number Diff line number Diff line 
* Power State Coordination Interface (PSCI)



Firmware implementing the PSCI functions described in ARM document number

ARM DEN 0022A ("Power State Coordination Interface System Software on ARM

processors") can be used by Linux to initiate various CPU-centric power

operations.



Issue A of the specification describes functions for CPU suspend, hotplug

and migration of secure software.



Functions are invoked by trapping to the privilege level of the PSCI

firmware (specified as part of the binding below) and passing arguments

in a manner similar to that specified by AAPCS:



	 r0		=> 32-bit Function ID / return value

	{r1 - r3}	=> Parameters



Note that the immediate field of the trapping instruction must be set

to #0.





Main node required properties:



 - compatible    : should contain at least one of:



     * "arm,psci"     : For implementations complying to PSCI versions prior

			to 0.2.

			For these cases function IDs must be provided.



     * "arm,psci-0.2" : For implementations complying to PSCI 0.2.

			Function IDs are not required and should be ignored by

			an OS with PSCI 0.2 support, but are permitted to be

			present for compatibility with existing software when

			"arm,psci" is later in the compatible list.



     * "arm,psci-1.0" : For implementations complying to PSCI 1.0.

			PSCI 1.0 is backward compatible with PSCI 0.2 with

			minor specification updates, as defined in the PSCI

			specification[2].



 - method        : The method of calling the PSCI firmware. Permitted

                   values are:



                   "smc" : SMC #0, with the register assignments specified

		           in this binding.



                   "hvc" : HVC #0, with the register assignments specified

		           in this binding.



Main node optional properties:



 - cpu_suspend   : Function ID for CPU_SUSPEND operation



 - cpu_off       : Function ID for CPU_OFF operation



 - cpu_on        : Function ID for CPU_ON operation



 - migrate       : Function ID for MIGRATE operation



Device tree nodes that require usage of PSCI CPU_SUSPEND function (ie idle

state nodes, as per bindings in [1]) must specify the following properties:



- arm,psci-suspend-param

		Usage: Required for state nodes[1] if the corresponding

                       idle-states node entry-method property is set

                       to "psci".

		Value type: <u32>

		Definition: power_state parameter to pass to the PSCI

			    suspend call.



Example:



Case 1: PSCI v0.1 only.



	psci {

		compatible	= "arm,psci";

		method		= "smc";

		cpu_suspend	= <0x95c10000>;

		cpu_off		= <0x95c10001>;

		cpu_on		= <0x95c10002>;

		migrate		= <0x95c10003>;

	};



Case 2: PSCI v0.2 only



	psci {

		compatible	= "arm,psci-0.2";

		method		= "smc";

	};



Case 3: PSCI v0.2 and PSCI v0.1.



	A DTB may provide IDs for use by kernels without PSCI 0.2 support,

	enabling firmware and hypervisors to support existing and new kernels.

	These IDs will be ignored by kernels with PSCI 0.2 support, which will

	use the standard PSCI 0.2 IDs exclusively.



	psci {

		compatible = "arm,psci-0.2", "arm,psci";

		method = "hvc";



		cpu_on = < arbitrary value >;

		cpu_off = < arbitrary value >;



		...

	};



[1] Kernel documentation - ARM idle states bindings

    Documentation/devicetree/bindings/arm/idle-states.txt

[2] Power State Coordination Interface (PSCI) specification

    http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf

Documentation/devicetree/bindings/arm/psci.yaml

0 → 100644
+163 −0
Original line number Diff line number Diff line 
# SPDX-License-Identifier: GPL-2.0

%YAML 1.2

---

$id: http://devicetree.org/schemas/arm/psci.yaml#

$schema: http://devicetree.org/meta-schemas/core.yaml#



title: Power State Coordination Interface (PSCI)



maintainers:

  - Lorenzo Pieralisi <lorenzo.pieralisi@arm.com>



description: |+

  Firmware implementing the PSCI functions described in ARM document number

  ARM DEN 0022A ("Power State Coordination Interface System Software on ARM

  processors") can be used by Linux to initiate various CPU-centric power

  operations.



  Issue A of the specification describes functions for CPU suspend, hotplug

  and migration of secure software.



  Functions are invoked by trapping to the privilege level of the PSCI

  firmware (specified as part of the binding below) and passing arguments

  in a manner similar to that specified by AAPCS:



     r0       => 32-bit Function ID / return value

    {r1 - r3}	=> Parameters



  Note that the immediate field of the trapping instruction must be set

  to #0.



  [2] Power State Coordination Interface (PSCI) specification

    http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf



properties:

  compatible:

    oneOf:

      - description:

          For implementations complying to PSCI versions prior to 0.2.

        const: arm,psci



      - description:

          For implementations complying to PSCI 0.2.

        const: arm,psci-0.2



      - description:

          For implementations complying to PSCI 0.2.

          Function IDs are not required and should be ignored by an OS with

          PSCI 0.2 support, but are permitted to be present for compatibility

          with existing software when "arm,psci" is later in the compatible

          list.

        items:

          - const: arm,psci-0.2

          - const: arm,psci



      - description:

          For implementations complying to PSCI 1.0.

        const: arm,psci-1.0



      - description:

          For implementations complying to PSCI 1.0.

          PSCI 1.0 is backward compatible with PSCI 0.2 with minor

          specification updates, as defined in the PSCI specification[2].

        items:

          - const: arm,psci-1.0

          - const: arm,psci-0.2



  method:

    description: The method of calling the PSCI firmware.

    allOf:

      - $ref: /schemas/types.yaml#/definitions/string-array

      - enum:

          # SMC #0, with the register assignments specified in this binding.

          - smc

          # HVC #0, with the register assignments specified in this binding.

          - hvc



  cpu_suspend:

    $ref: /schemas/types.yaml#/definitions/uint32

    description: Function ID for CPU_SUSPEND operation



  cpu_off:

    $ref: /schemas/types.yaml#/definitions/uint32

    description: Function ID for CPU_OFF operation



  cpu_on:

    $ref: /schemas/types.yaml#/definitions/uint32

    description: Function ID for CPU_ON operation



  migrate:

    $ref: /schemas/types.yaml#/definitions/uint32

    description: Function ID for MIGRATE operation



  arm,psci-suspend-param:

    $ref: /schemas/types.yaml#/definitions/uint32

    description: |

      power_state parameter to pass to the PSCI suspend call.



      Device tree nodes that require usage of PSCI CPU_SUSPEND function (ie

      idle state nodes with entry-method property is set to "psci", as per

      bindings in [1]) must specify this property.



      [1] Kernel documentation - ARM idle states bindings

        Documentation/devicetree/bindings/arm/idle-states.txt





required:

  - compatible

  - method



allOf:

  - if:

      properties:

        compatible:

          contains:

            const: arm,psci

    then:

      required:

        - cpu_off

        - cpu_on



examples:

  - |+



    // Case 1: PSCI v0.1 only.



    psci {

      compatible      = "arm,psci";

      method          = "smc";

      cpu_suspend     = <0x95c10000>;

      cpu_off         = <0x95c10001>;

      cpu_on          = <0x95c10002>;

      migrate         = <0x95c10003>;

    };



  - |+



    // Case 2: PSCI v0.2 only



    psci {

      compatible      = "arm,psci-0.2";

      method          = "smc";

    };





  - |+



    // Case 3: PSCI v0.2 and PSCI v0.1.



    /*

     * A DTB may provide IDs for use by kernels without PSCI 0.2 support,

     * enabling firmware and hypervisors to support existing and new kernels.

     * These IDs will be ignored by kernels with PSCI 0.2 support, which will

     * use the standard PSCI 0.2 IDs exclusively.

     */



    psci {

      compatible = "arm,psci-0.2", "arm,psci";

      method = "hvc";



      cpu_on = <0x95c10002>;

      cpu_off = <0x95c10001>;

    };

...