From patchwork Tue Jun 11 19:59:09 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Walleij X-Patchwork-Id: 17802 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-vc0-f200.google.com (mail-vc0-f200.google.com [209.85.220.200]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id 5D2EB25DFB for ; Tue, 11 Jun 2013 19:59:51 +0000 (UTC) Received: by mail-vc0-f200.google.com with SMTP id kw10sf2168057vcb.11 for ; Tue, 11 Jun 2013 12:59:51 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=x-beenthere:x-forwarded-to:x-forwarded-for:delivered-to:from:to:cc :subject:date:message-id:x-mailer:mime-version:x-gm-message-state :x-original-sender:x-original-authentication-results:precedence :mailing-list:list-id:x-google-group-id:list-post:list-help :list-archive:list-unsubscribe:content-type; bh=38xjsk87Ckkkt4PI9tCRIoXZqvZN7prLIh4GuvyIH1w=; b=cBbj+5JcjHz/Ni8bOoxJ2rpiOQD4UIVsLEsmal7xNwfV5lSUf25jtuCJAIM3jI95Te HDvxNrE8VGtlPWT1MlScgXNTkouUQmKL0jnZBo9q78kABfFARtTluym++NJShh1wMCjH Dh7gRXA/2nGCRzjjdm/Wdc0t4d3uhIGuI9pKHuJ91SOphnMSqvU+FTYYNSMg5Ntqxfgu nyNQLE/FoZuEUajg8e8OYF1xZ90NGCSNpsB1zogb3uFYhjeShRv4mjHF4X9kCJ9EG+Pn /B28MXzb9YCJUY3ZuI3GmcPIIbMwLSBlz4hODgUnU2t7Dv+/TppwllxH+tlTs2r/Qoui sD4Q== X-Received: by 10.236.42.116 with SMTP id i80mr9137851yhb.26.1370980790739; Tue, 11 Jun 2013 12:59:50 -0700 (PDT) X-BeenThere: patchwork-forward@linaro.org Received: by 10.49.39.3 with SMTP id l3ls1089093qek.62.gmail; Tue, 11 Jun 2013 12:59:50 -0700 (PDT) X-Received: by 10.52.112.5 with SMTP id im5mr7308848vdb.4.1370980790348; Tue, 11 Jun 2013 12:59:50 -0700 (PDT) Received: from mail-ve0-x22f.google.com (mail-ve0-x22f.google.com [2607:f8b0:400c:c01::22f]) by mx.google.com with ESMTPS id tq4si7436326vdc.144.2013.06.11.12.59.50 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Tue, 11 Jun 2013 12:59:50 -0700 (PDT) Received-SPF: neutral (google.com: 2607:f8b0:400c:c01::22f is neither permitted nor denied by best guess record for domain of patch+caf_=patchwork-forward=linaro.org@linaro.org) client-ip=2607:f8b0:400c:c01::22f; Received: by mail-ve0-f175.google.com with SMTP id da11so6049477veb.20 for ; Tue, 11 Jun 2013 12:59:50 -0700 (PDT) X-Received: by 10.52.170.148 with SMTP id am20mr7307027vdc.75.1370980789962; Tue, 11 Jun 2013 12:59:49 -0700 (PDT) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patches@linaro.org Received: by 10.221.10.206 with SMTP id pb14csp123324vcb; Tue, 11 Jun 2013 12:59:48 -0700 (PDT) X-Received: by 10.14.100.2 with SMTP id y2mr5600647eef.75.1370980788020; Tue, 11 Jun 2013 12:59:48 -0700 (PDT) Received: from eu1sys200aog113.obsmtp.com (eu1sys200aog113.obsmtp.com [207.126.144.135]) by mx.google.com with SMTP id f5si12811392eep.128.2013.06.11.12.59.19 for (version=TLSv1 cipher=RC4-SHA bits=128/128); Tue, 11 Jun 2013 12:59:47 -0700 (PDT) Received-SPF: neutral (google.com: 207.126.144.135 is neither permitted nor denied by best guess record for domain of linus.walleij@stericsson.com) client-ip=207.126.144.135; Received: from beta.dmz-eu.st.com ([164.129.1.35]) (using TLSv1) by eu1sys200aob113.postini.com ([207.126.147.11]) with SMTP ID DSNKUbeBlsf00KHsoGBNPCkLAqnADAI+L+ER@postini.com; Tue, 11 Jun 2013 19:59:47 UTC Received: from zeta.dmz-eu.st.com (zeta.dmz-eu.st.com [164.129.230.9]) by beta.dmz-eu.st.com (STMicroelectronics) with ESMTP id 650EE168; Tue, 11 Jun 2013 19:59:16 +0000 (GMT) Received: from relay1.stm.gmessaging.net (unknown [10.230.100.17]) by zeta.dmz-eu.st.com (STMicroelectronics) with ESMTP id 4D32559C2; Tue, 11 Jun 2013 19:58:56 +0000 (GMT) Received: from exdcvycastm022.EQ1STM.local (alteon-source-exch [10.230.100.61]) (using TLSv1 with cipher RC4-MD5 (128/128 bits)) (Client CN "exdcvycastm022", Issuer "exdcvycastm022" (not verified)) by relay1.stm.gmessaging.net (Postfix) with ESMTPS id 5AEFC24C07C; Tue, 11 Jun 2013 21:59:05 +0200 (CEST) Received: from steludxu4075.lud.stericsson.com (10.230.100.153) by smtp.stericsson.com (10.230.100.30) with Microsoft SMTP Server (TLS) id 8.3.279.5; Tue, 11 Jun 2013 21:59:15 +0200 From: Linus Walleij To: Stephen Warren , Kevin Hilman , Tony Lindgren Cc: , , Linus Walleij , Ulf Hansson Subject: [PATCH] pinctrl: document the pinctrl PM states Date: Tue, 11 Jun 2013 21:59:09 +0200 Message-ID: <1370980749-15383-1-git-send-email-linus.walleij@stericsson.com> X-Mailer: git-send-email 1.7.11.3 MIME-Version: 1.0 X-Gm-Message-State: ALoCoQlRqDui8WnA4lo18fbJ2Fy7O7zhUNuXIgR5rGAgG40FGEInegwgq0N3f2WzZEU2x0iKFT9i X-Original-Sender: linus.walleij@stericsson.com X-Original-Authentication-Results: mx.google.com; spf=neutral (google.com: 2607:f8b0:400c:c01::22f is neither permitted nor denied by best guess record for domain of patch+caf_=patchwork-forward=linaro.org@linaro.org) smtp.mail=patch+caf_=patchwork-forward=linaro.org@linaro.org Precedence: list Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org List-ID: X-Google-Group-Id: 836684582541 List-Post: , List-Help: , List-Archive: List-Unsubscribe: , From: Linus Walleij This document snippet tries to be helpful and define the pin PM states and helpers, and how they should be used to create some kind of common ontology around this. Cc: Ulf Hansson Cc: Kevin Hilman Cc: Tony Lindgren Signed-off-by: Linus Walleij --- Documentation/pinctrl.txt | 118 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt index f6e664b..a34ea92 100644 --- a/Documentation/pinctrl.txt +++ b/Documentation/pinctrl.txt @@ -1196,6 +1196,124 @@ registered. Thus make sure that the error path in your driver gracefully cleans up and is ready to retry the probing later in the startup process. +Default and power management related states +=========================================== + +As mentioned earlier the device core will automatically try to obtain a +pinctrl handle and activate the "default" state on all drivers. + +However, for power management and power saving, it is sometimes necessary +to switch pin states at runtime. Electrically speaking this involves +for example reconfigure some pins to be grounded or pulled-down when the +system as a whole goes to sleep, or a pull-up could be turned off when pins +are idle, reducing leak current. + +To help out with this, if CONFIG_PM is selected in the Kconfig, three +additional states will also be obtained by the driver core and cached +there: + +"active" this is indended as an explicit active state, if the "default" + state is not synonymous with the active one. + +"idle" this is a state that is relaxing the pins when the system as a + whole is up and running, but these particular pins are unused. + +"sleep" this is a state that is used when the whole system goes to + suspend, becomes uninteractive, unresponsive to anything but + specific wake-up events. + +These correspond to the definitions found in +where the same strings are encoded. + +When CONFIG_PM is set, the following functions will simultaneously be made +available to switch between these power-related states: + +#include + +int pinctrl_pm_select_default_state(struct device *dev); +int pinctrl_pm_select_active_state(struct device *dev); +int pinctrl_pm_select_sleep_state(struct device *dev); +int pinctrl_pm_select_idle_state(struct device *dev); + +As the corresponding pinctrl handle and states are cached in the driver +core, nothing apart from these calls is needed to move the pins between +these states. + +For a typical runtime PM enabled (see Documentation/power/runtime_pm.txt) +driver the following outline could be followed: + +probe(): + pinctrl_pm_select_default_state() + +runtime_suspend(): + pinctrl_pm_select_idle_state() + +runtime_resume(): + pinctrl_pm_select_default_state() + +suspend: + pinctrl_pm_select_sleep_state() + +resume: + pinctrl_pm_select_idle_state() + +Some of the state selectors could be skipped if the driver is for a +certain system where e.g. the "active" state is not defined, instead +relying on the "default" state to make the pins active at all times. +For a driver only supporting suspend and resume, the "idle" state also +loose its meaning. + +A state-chart diagram would look like this: + + +---------+ +----------+ + probe() -> | default | -> runtime_suspend() -> | idle | + | | <- runtime_resume() <- | | + +---------+ +----------+ + | ^ + | | + suspend() resume() + | | + V | + +---------+ + | sleep | + +---------+ + +This reflects the runtime PM concept that we are always runtime +suspended when we go to suspend. + +A more complex example is a driver written for many different +hardware configurations, some which have only the default state, +some which have the default state and the sleep state, some that +have no idle state but indeed a default state and so on. Since +all states are basically optional (the core will not complain if +they are not found) we can write our state transitions like +this: + +probe(): + pinctrl_pm_select_default_state() + +runtime_suspend(): + pinctrl_pm_select_idle_state() + +runtime_resume(): + pinctrl_pm_select_default_state() + pinctrl_pm_select_active_state() + +suspend: + pinctrl_pm_select_sleep_state() + +resume: + pinctrl_pm_select_default_state() + pinctrl_pm_select_idle_state() + +Here runtime_resume() and resume() passes through the "default" +state to the "active" and "idle" states respectively since everything +but "default" is optional. For example it is OK to only supply the +"default" and "sleep" state pair with this code, and it will +transition the pins from "default" to "sleep" and leaving the rest +as no-ops. + + Drivers needing both pin control and GPIOs ==========================================