From patchwork Wed Jan 21 11:35:54 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sudeep Holla X-Patchwork-Id: 5676551 Return-Path: X-Original-To: patchwork-linux-arm@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id 4324E9F333 for ; Wed, 21 Jan 2015 11:38:02 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 3ADF5204D2 for ; Wed, 21 Jan 2015 11:38:01 +0000 (UTC) Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.9]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 3C655204D1 for ; Wed, 21 Jan 2015 11:38:00 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.80.1 #2 (Red Hat Linux)) id 1YDta2-0001pb-RU; Wed, 21 Jan 2015 11:36:14 +0000 Received: from foss-mx-na.foss.arm.com ([217.140.108.86]) by bombadil.infradead.org with esmtp (Exim 4.80.1 #2 (Red Hat Linux)) id 1YDtZg-0001hd-IV for linux-arm-kernel@lists.infradead.org; Wed, 21 Jan 2015 11:35:53 +0000 Received: from foss-smtp-na-1.foss.arm.com (unknown [10.80.61.8]) by foss-mx-na.foss.arm.com (Postfix) with ESMTP id CA15D27F; Wed, 21 Jan 2015 05:35:22 -0600 (CST) Received: from collaborate-mta1.arm.com (highbank-bc01-b06.austin.arm.com [10.112.81.134]) by foss-smtp-na-1.foss.arm.com (Postfix) with ESMTP id 6F7486045D; Wed, 21 Jan 2015 05:35:20 -0600 (CST) Received: from e103737-lin.cambridge.arm.com (e103737-lin.cambridge.arm.com [10.1.207.156]) by collaborate-mta1.arm.com (Postfix) with ESMTP id D229A13F824; Wed, 21 Jan 2015 05:35:18 -0600 (CST) From: Sudeep Holla To: linux-arm-kernel@lists.infradead.org, devicetree@vger.kernel.org Subject: [PATCH RFC 1/2] Documentation: arm: define DT bindings for system suspend Date: Wed, 21 Jan 2015 11:35:54 +0000 Message-Id: <1421840155-18990-2-git-send-email-sudeep.holla@arm.com> X-Mailer: git-send-email 1.9.1 In-Reply-To: <1421840155-18990-1-git-send-email-sudeep.holla@arm.com> References: <1421840155-18990-1-git-send-email-sudeep.holla@arm.com> X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20150121_033552_625799_91F17385 X-CRM114-Status: GOOD ( 15.71 ) X-Spam-Score: -0.0 (/) Cc: Mark Rutland , Jisheng Zhang , Jonghwa Lee , Lorenzo Pieralisi , Catalin Marinas , Leo Yan , Amit Daniel Kachhap , Rob Herring , Sudeep Holla X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+patchwork-linux-arm=patchwork.kernel.org@lists.infradead.org X-Spam-Status: No, score=-4.2 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_MED, T_RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP ARM based platforms implement unique ways to enter system suspend (i.e. Suspend to RAM). The mechanism and the parameters defining the system state vary on a per-platform basis forcing the OS to handle it in very platform specific way. Since ARM 32-bit systems had machine specific code, no attempts to standardize are being made as it provides easy way to implement suspend operations in a platform specific manner. However, this approach not only makes maintainance more difficult as the number of platforms supported increases but also not feasible for ARM64. This DT binding aims at standardizing the system suspend for ARM platforms. ARM64 platforms mandates entry-method property in DT for this system suspend node. On system implementing PSCI as an enable-method to enter system suspend, the PSCI CPU suspend method is used on versions upto v0.2 and requires the power_state parameter to be passed to the PSCI CPU suspend function. This parameter is platform specific, therefore must be provided by firmware to the OS in order to enable proper call sequence. This ARM system suspend DT bindings rely on a property (i.e. arm,psci-suspend-param) in the PSCI DT bindings that describes how the PSCI CPU suspend power_state parameter should be defined in DT. Signed-off-by: Sudeep Holla --- Documentation/devicetree/bindings/arm/psci.txt | 11 +++ .../devicetree/bindings/arm/system-suspend.txt | 93 ++++++++++++++++++++++ 2 files changed, 104 insertions(+) create mode 100644 Documentation/devicetree/bindings/arm/system-suspend.txt diff --git a/Documentation/devicetree/bindings/arm/psci.txt b/Documentation/devicetree/bindings/arm/psci.txt index 5aa40ede0e99..bd3977a2a333 100644 --- a/Documentation/devicetree/bindings/arm/psci.txt +++ b/Documentation/devicetree/bindings/arm/psci.txt @@ -61,6 +61,14 @@ Device tree nodes that require usage of PSCI CPU_SUSPEND function (ie idle Definition: power_state parameter to pass to the PSCI suspend call. +PSCI v0.2 and earlier versions don't have explicit operation for system +suspend. However, one can implement system suspend using CPU_SUSPEND by +ensuring every other core except the one executing the CPU_SUSPEND call +has called into PSCI through a CPU_OFF call. + +In such cases, device tree nodes representing system suspend as per the +bindings in [2] must specify the above "arm,psci-suspend-param" property. + Example: Case 1: PSCI v0.1 only. @@ -100,3 +108,6 @@ Case 3: PSCI v0.2 and PSCI v0.1. [1] Kernel documentation - ARM idle states bindings Documentation/devicetree/bindings/arm/idle-states.txt + +[2] Kernel documentation - ARM system suspend bindings + Documentation/devicetree/bindings/arm/system-suspend.txt diff --git a/Documentation/devicetree/bindings/arm/system-suspend.txt b/Documentation/devicetree/bindings/arm/system-suspend.txt new file mode 100644 index 000000000000..15cac4c7fe92 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/system-suspend.txt @@ -0,0 +1,93 @@ +========================================== +ARM system suspend binding description +========================================== + +========================================== +1 - Introduction +========================================== + +System Suspend(commonly known as Suspend to RAM) is a method to remove +power from most parts of the machine aside from the RAM, which is required +to restore the machine's state. Because of the large power savings, it is +widely used in mobile systems like laptops, tablets and smartphones. + +Usually most mobile systems enter system suspend state aggressively when +they are idle even for short time(in seconds) while others systems like +laptops automatically enter this mode when they running on batteries and +the lid is closed (and/or the user is inactive for some time(in minutes)). + +Most of the devices in the system are deactivated. Non-volatile memory +(like disk drives, flash, memory card), graphics chips and even the CPU +are usually deactivated. Only the RAM is powered to keep its contents. On +resume, only those individual devices/CPUs need to be reinitialized and +work continues relatively fast. + +It is highly hardware specific especially on ARM platforms. Hence we need +device tree binding definition for ARM system suspend state which is the +subject of this document in order to provide generic solution. + +=========================================== +2 - system suspend node +=========================================== + +The system suspend node represents the description of the mechanism to +enter system suspend state and must be defined as follows: + + - compatible + Usage: Required + Value type: + Definition: Must be "arm,system-suspend"; + + - entry-method + Value type: + Usage and definition depend on ARM architecture version. + # On ARM v8 64-bit this property is required and must + be one of: + - "arm,psci" (see bindings in [1]) + + - status: + Usage: Optional + Value type: + Definition: A standard device tree property [2] that indicates + the operational status of system suspend. + If present, it shall be: + "okay": to indicate it is operational. + "disabled": to indicate that it has been disabled + in firmware so it is not operational. + By default, it's always enabled if not explicitly + disabled. + + In addition to the properties listed above, it may require additional + properties specifics to the entry-method defined, please refer to the + corresponding entry-method bindings documentation for details. + In the below example using "arm,psci" entry method, + "arm,psci-suspend-param" is a PSCI specific property. + + The system suspend node's parent node must be the 'cpus' node. + +=========================================== +3 - Examples +=========================================== + +Example: +cpus { + /* cpu-map, cpu and idle-states nodes */ + .... + + system-suspend { + compatible = "arm,system-suspend"; + entry-method = "arm,psci"; + arm,psci-suspend-param = <0x1010000>; + }; + + .... +}; +=========================================== +4 - References +=========================================== + +[1] ARM Linux Kernel documentation - PSCI bindings + Documentation/devicetree/bindings/arm/psci.txt + +[2] ePAPR standard + https://www.power.org/documentation/epapr-version-1-1/