From patchwork Thu Sep 13 07:01:26 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Walleij X-Patchwork-Id: 11385 Return-Path: X-Original-To: patchwork@peony.canonical.com Delivered-To: patchwork@peony.canonical.com Received: from fiordland.canonical.com (fiordland.canonical.com [91.189.94.145]) by peony.canonical.com (Postfix) with ESMTP id 2D86723F41 for ; Thu, 13 Sep 2012 07:02:01 +0000 (UTC) Received: from mail-ie0-f180.google.com (mail-ie0-f180.google.com [209.85.223.180]) by fiordland.canonical.com (Postfix) with ESMTP id 0047E34BB97E for ; Thu, 13 Sep 2012 07:01:59 +0000 (UTC) Received: by ieak11 with SMTP id k11so4236386iea.11 for ; Thu, 13 Sep 2012 00:01:59 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=x-forwarded-to:x-forwarded-for:delivered-to:received-spf:from:to:cc :subject:date:message-id:x-mailer:mime-version:content-type :x-gm-message-state; bh=cYMRNV0N49KvXyRxBpf81qSeVhy56qJ+h/2D+oGJ9E0=; b=dwyNsGqVEM4aT6QmZdOrzX0R3PSmuq3dmD2bZ8Kekd03Id8Y3Jq/REyhOErqfKi4gT ctRjWR0OG/S6Ez9b33uR/vfNdgvXoHgUOeZHKkeKBLJr21G6Jbd/Z8KQ1Mfe/6ANq4Gr /TpzuYyoTUzRP+2u/IHtvse9ti8Y4aHOL/KgmxC8/3ng4MLKfT5gN4PrPg9M3mOnSKX1 F0Yp2HDC361JJ0Wz7wf7j/QVDSTB15plaNnt7pfjtJnExo+H78yCWofN62zcazpNmdFn Tp8aPsRhR8dz3pmTu75Kxk/s4ZJl7RV79l1ewZFm8Pu3/rxrnQRP5NoSkgxH0K99YOnx W8RQ== Received: by 10.50.45.162 with SMTP id o2mr1151071igm.0.1347519719307; Thu, 13 Sep 2012 00:01:59 -0700 (PDT) X-Forwarded-To: linaro-patchwork@canonical.com X-Forwarded-For: patch@linaro.org linaro-patchwork@canonical.com Delivered-To: patches@linaro.org Received: by 10.50.184.232 with SMTP id ex8csp117222igc; Thu, 13 Sep 2012 00:01:58 -0700 (PDT) Received: by 10.14.213.137 with SMTP id a9mr1187013eep.38.1347519717412; Thu, 13 Sep 2012 00:01:57 -0700 (PDT) Received: from eu1sys200aog118.obsmtp.com (eu1sys200aog118.obsmtp.com [207.126.144.145]) by mx.google.com with SMTP id o42si17280768eep.83.2012.09.13.00.01.47 (version=TLSv1/SSLv3 cipher=OTHER); Thu, 13 Sep 2012 00:01:57 -0700 (PDT) Received-SPF: neutral (google.com: 207.126.144.145 is neither permitted nor denied by best guess record for domain of linus.walleij@stericsson.com) client-ip=207.126.144.145; Authentication-Results: mx.google.com; spf=neutral (google.com: 207.126.144.145 is neither permitted nor denied by best guess record for domain of linus.walleij@stericsson.com) smtp.mail=linus.walleij@stericsson.com Received: from beta.dmz-us.st.com ([167.4.1.35]) (using TLSv1) by eu1sys200aob118.postini.com ([207.126.147.11]) with SMTP ID DSNKUFGE24flr//KQKIGMBBVUjuhbTUsYxaL@postini.com; Thu, 13 Sep 2012 07:01:57 UTC Received: from zeta.dmz-us.st.com (ns4.st.com [167.4.16.71]) by beta.dmz-us.st.com (STMicroelectronics) with ESMTP id 7DB2147; Thu, 13 Sep 2012 07:01:03 +0000 (GMT) Received: from relay1.stm.gmessaging.net (unknown [10.230.100.17]) by zeta.dmz-us.st.com (STMicroelectronics) with ESMTP id DD83959; Thu, 13 Sep 2012 03:01:26 +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 D519E24C2F0; Thu, 13 Sep 2012 09:01:26 +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.83.0; Thu, 13 Sep 2012 09:01:30 +0200 From: Linus Walleij To: , Cc: Stephen Warren , Anmar Oueja , Linus Walleij Subject: [PATCH] pinctrl: document semantics vs GPIO Date: Thu, 13 Sep 2012 09:01:26 +0200 Message-ID: <1347519686-10170-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: ALoCoQmTmrsjM+PKkoAoYLd1exC9DoUyrrwDYRXGzY7HaIriGise1XzXr21D6O9Kujq8yji5BOUZ From: Linus Walleij The semantics of the interactions between GPIO and pinctrl may be unclear, e.g. which one do you request first? This amends the documentation to make this clear. Reported-by: Domenico Andreoli Signed-off-by: Linus Walleij --- This is an attempt to write up some of the unclarities that surfaced in recent discussions into the documentation proper. --- Documentation/pinctrl.txt | 52 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 50 insertions(+), 2 deletions(-) diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt index 1479aca..24c5995 100644 --- a/Documentation/pinctrl.txt +++ b/Documentation/pinctrl.txt @@ -289,6 +289,11 @@ Interaction with the GPIO subsystem The GPIO drivers may want to perform operations of various types on the same physical pins that are also registered as pin controller pins. +First and foremost, the two subsystems can be used as completely orthogonal, +see the section named "pin control requests from drivers" and +"drivers needing both pin control and GPIOs" below for details. But in some +situations a cross-subsystem mapping between pins and GPIOs is needed. + Since the pin controller subsystem have its pinspace local to the pin controller we need a mapping so that the pin control subsystem can figure out which pin controller handles control of a certain GPIO pin. Since a single @@ -359,6 +364,7 @@ will get an pin number into its handled number range. Further it is also passed the range ID value, so that the pin controller knows which range it should deal with. + PINMUX interfaces ================= @@ -960,8 +966,8 @@ all get selected, and they all get enabled and disable simultaneously by the pinmux core. -Pinmux requests from drivers -============================ +Pin control requests from drivers +================================= Generally it is discouraged to let individual drivers get and enable pin control. So if possible, handle the pin control in platform code or some other @@ -969,6 +975,11 @@ place where you have access to all the affected struct device * pointers. In some cases where a driver needs to e.g. switch between different mux mappings at runtime this is not possible. +A typical case is if a driver needs to switch bias of pins from normal +operation and going to sleep, moving from the PINCTRL_STATE_DEFAULT to +PINCTRL_STATE_SLEEP at runtime, re-biasing or even re-muxing pins to save +current in sleep mode. + A driver may request a certain control state to be activated, usually just the default state like this: @@ -1058,6 +1069,43 @@ 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. +Drivers needing both pin control and GPIOs +========================================== + +Again, it is discouraged to let drivers lookup and select pin control states +themselves, but again sometimes this is unavoidable. + +So say that your driver is fetching its resources like this: + +#include +#include + +struct pinctrl *pinctrl; +int gpio; + +pinctrl = devm_pinctrl_get_select_default(&dev); +gpio = devm_gpio_request(&dev, 14, "foo"); + +Here we first request a certain pin state and then request GPIO 14 to be +used. If you're using the subsystems orthogonally like this, always get +your pinctrl handle and select the desired pinctrl state BEFORE requesting +the GPIO. This is a semantic convention to avoid situations that can be +electrically unpleasant, you will certainly want to mux in and bias pins +in a certain way before the GPIO subsystems starts to deal with them. + +The above can be hidden: using pinctrl hogs, the driver may be setting +up the config and muxing for the pins when the pinctrl driver is probing, +nevertheless orthogonal to the GPIO subsystem. + +But there are also situations where it makes sense for the GPIO subsystem +to communicate directly with with the pinctrl subsystem, using the latter +as a back-end. This is when the GPIO driver may call out to the functions +described in the section "Pin control interaction with the GPIO subsystem" +above. This only involves per-pin multiplexing, and will be completely +hidden behind the gpio_*() function namespace. In this case, the driver +need not interact with the pin control subsystem at all. + + System pin control hogging ==========================