[deliverable/linux.git] / Documentation / devicetree / bindings / arm / psci.txt

* 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
Commit	Line	Data
65397edf WD	1	* Power State Coordination Interface (PSCI)
	2
	3	Firmware implementing the PSCI functions described in ARM document number
	4	ARM DEN 0022A ("Power State Coordination Interface System Software on ARM
	5	processors") can be used by Linux to initiate various CPU-centric power
	6	operations.
	7
	8	Issue A of the specification describes functions for CPU suspend, hotplug
	9	and migration of secure software.
	10
	11	Functions are invoked by trapping to the privilege level of the PSCI
	12	firmware (specified as part of the binding below) and passing arguments
	13	in a manner similar to that specified by AAPCS:
	14
	15	r0 => 32-bit Function ID / return value
	16	{r1 - r3} => Parameters
	17
	18	Note that the immediate field of the trapping instruction must be set
	19	to #0.
	20
	21
	22	Main node required properties:
	23
e1cd3b36 AC	24	- compatible : should contain at least one of:
e1cd3b36 AC	25
414ee536 GU	26	* "arm,psci" : For implementations complying to PSCI versions prior
	27	to 0.2.
	28	For these cases function IDs must be provided.
	29
	30	* "arm,psci-0.2" : For implementations complying to PSCI 0.2.
	31	Function IDs are not required and should be ignored by
	32	an OS with PSCI 0.2 support, but are permitted to be
	33	present for compatibility with existing software when
	34	"arm,psci" is later in the compatible list.
	35
	36	* "arm,psci-1.0" : For implementations complying to PSCI 1.0.
	37	PSCI 1.0 is backward compatible with PSCI 0.2 with
	38	minor specification updates, as defined in the PSCI
	39	specification[2].
0fc197c7	40
65397edf WD	41	- method : The method of calling the PSCI firmware. Permitted
	42	values are:
	43
	44	"smc" : SMC #0, with the register assignments specified
	45	in this binding.
	46
	47	"hvc" : HVC #0, with the register assignments specified
	48	in this binding.
	49
	50	Main node optional properties:
	51
	52	- cpu_suspend : Function ID for CPU_SUSPEND operation
	53
	54	- cpu_off : Function ID for CPU_OFF operation
	55
	56	- cpu_on : Function ID for CPU_ON operation
	57
	58	- migrate : Function ID for MIGRATE operation
	59
3f8161b2 LP	60	Device tree nodes that require usage of PSCI CPU_SUSPEND function (ie idle
	61	state nodes, as per bindings in [1]) must specify the following properties:
	62
	63	- arm,psci-suspend-param
	64	Usage: Required for state nodes[1] if the corresponding
	65	idle-states node entry-method property is set
	66	to "psci".
	67	Value type: <u32>
	68	Definition: power_state parameter to pass to the PSCI
	69	suspend call.
65397edf WD	70
	71	Example:
	72
e1cd3b36 AC	73	Case 1: PSCI v0.1 only.
e1cd3b36 AC	74
65397edf WD	75	psci {
	76	compatible = "arm,psci";
	77	method = "smc";
	78	cpu_suspend = <0x95c10000>;
	79	cpu_off = <0x95c10001>;
	80	cpu_on = <0x95c10002>;
	81	migrate = <0x95c10003>;
	82	};
e1cd3b36	83
e1cd3b36 AC	84	Case 2: PSCI v0.2 only
	85
	86	psci {
	87	compatible = "arm,psci-0.2";
	88	method = "smc";
	89	};
	90
	91	Case 3: PSCI v0.2 and PSCI v0.1.
	92
	93	A DTB may provide IDs for use by kernels without PSCI 0.2 support,
	94	enabling firmware and hypervisors to support existing and new kernels.
	95	These IDs will be ignored by kernels with PSCI 0.2 support, which will
	96	use the standard PSCI 0.2 IDs exclusively.
	97
	98	psci {
	99	compatible = "arm,psci-0.2", "arm,psci";
	100	method = "hvc";
	101
	102	cpu_on = < arbitrary value >;
	103	cpu_off = < arbitrary value >;
	104
	105	...
	106	};
3f8161b2 LP	107
	108	[1] Kernel documentation - ARM idle states bindings
	109	Documentation/devicetree/bindings/arm/idle-states.txt
0fc197c7 LP	110	[2] Power State Coordination Interface (PSCI) specification
0fc197c7 LP	111	http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf