From patchwork Wed Jan 22 14:03:10 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Walleij X-Patchwork-Id: 23524 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-ie0-f199.google.com (mail-ie0-f199.google.com [209.85.223.199]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id DFD18218CB for ; Wed, 22 Jan 2014 14:03:21 +0000 (UTC) Received: by mail-ie0-f199.google.com with SMTP id x13sf37873925ief.2 for ; Wed, 22 Jan 2014 06:03:21 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:delivered-to:from:to:cc:subject :date:message-id:x-original-sender:x-original-authentication-results :precedence:mailing-list:list-id:list-post:list-help:list-archive :list-unsubscribe; bh=xIdscNzw/E93RBSyDc3+99KO84fhZwaRXtqHAdWxc1c=; b=dCCWYWFYmixnrHoNnwxXQcavTIfRRWJe9FVh3/mSIHYgNq4UXmOv1M+2hCQ/rONUh+ 8j1mRTx0hzCD/ocU/mfFIv3ZjavUOkaROnfBIhh5p6qxZ6OhNCZSAvohvm5PcS4a+k7Q KPt8/lZ7b9wNJzUKIwxRcmG/Nd7V3dDmbrG+SNi/Zr1Oy/Cm7NStwUc9DQwXlgsgbShk q+K8fD+p2vDAmhcRkc7jJlvzLMlxzv2E8EZTwEG4mZyhPImWZh1Ro4JT1rFRhf0xHQIC Sc4bG2N3d03bS4Pxso3T6o5MxRy13gx5MaqR3We+PNtKjxQtH+aRK6wh0Im4Bjz0PFFe G2QQ== X-Gm-Message-State: ALoCoQl5Tx5imDW89dpKGmjRABFTdUzbmhIhNSsZjY+WG5JKcwcaHq6t96vjAPSKkvr4cZde4+19 X-Received: by 10.50.92.3 with SMTP id ci3mr5576171igb.5.1390399401204; Wed, 22 Jan 2014 06:03:21 -0800 (PST) MIME-Version: 1.0 X-BeenThere: patchwork-forward@linaro.org Received: by 10.49.15.42 with SMTP id u10ls54823qec.96.gmail; Wed, 22 Jan 2014 06:03:21 -0800 (PST) X-Received: by 10.58.85.133 with SMTP id h5mr1056504vez.4.1390399401087; Wed, 22 Jan 2014 06:03:21 -0800 (PST) Received: from mail-vc0-f175.google.com (mail-vc0-f175.google.com [209.85.220.175]) by mx.google.com with ESMTPS id dd4si4584614vcb.145.2014.01.22.06.03.20 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 22 Jan 2014 06:03:20 -0800 (PST) Received-SPF: neutral (google.com: 209.85.220.175 is neither permitted nor denied by best guess record for domain of patch+caf_=patchwork-forward=linaro.org@linaro.org) client-ip=209.85.220.175; Received: by mail-vc0-f175.google.com with SMTP id ij19so233340vcb.34 for ; Wed, 22 Jan 2014 06:03:20 -0800 (PST) X-Received: by 10.220.193.132 with SMTP id du4mr180471vcb.39.1390399400868; Wed, 22 Jan 2014 06:03:20 -0800 (PST) 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.220.174.196 with SMTP id u4csp186553vcz; Wed, 22 Jan 2014 06:03:20 -0800 (PST) X-Received: by 10.181.5.65 with SMTP id ck1mr8204936wid.57.1390399398419; Wed, 22 Jan 2014 06:03:18 -0800 (PST) Received: from mail-we0-f176.google.com (mail-we0-f176.google.com [74.125.82.176]) by mx.google.com with ESMTPS id eo15si6904805wid.26.2014.01.22.06.03.18 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 22 Jan 2014 06:03:18 -0800 (PST) Received-SPF: neutral (google.com: 74.125.82.176 is neither permitted nor denied by best guess record for domain of linus.walleij@linaro.org) client-ip=74.125.82.176; Received: by mail-we0-f176.google.com with SMTP id t61so335934wes.21 for ; Wed, 22 Jan 2014 06:03:18 -0800 (PST) X-Received: by 10.194.133.135 with SMTP id pc7mr1877878wjb.51.1390399396480; Wed, 22 Jan 2014 06:03:16 -0800 (PST) Received: from localhost.localdomain ([85.235.11.236]) by mx.google.com with ESMTPSA id jw4sm15066090wjc.20.2014.01.22.06.03.14 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 22 Jan 2014 06:03:15 -0800 (PST) From: Linus Walleij To: linux-gpio@vger.kernel.org Cc: Alexandre Courbot , Linus Walleij , Thomas Gleixner Subject: [PATCH] gpio: document how to make combined GPIO+irqchip drivers Date: Wed, 22 Jan 2014 15:03:10 +0100 Message-Id: <1390399390-9414-1-git-send-email-linus.walleij@linaro.org> X-Mailer: git-send-email 1.8.4.2 X-Removed-Original-Auth: Dkim didn't pass. X-Original-Sender: linus.walleij@linaro.org X-Original-Authentication-Results: mx.google.com; spf=neutral (google.com: 209.85.220.175 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: , Write a few words on how GPIO drivers supplying an irqchip should be written. Cc: Thomas Gleixner Signed-off-by: Linus Walleij --- Documentation/gpio/driver.txt | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt index 9da0bfa74781..9818b2055197 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/gpio/driver.txt @@ -62,6 +62,36 @@ Any debugfs dump method should normally ignore signals which haven't been requested as GPIOs. They can use gpiochip_is_requested(), which returns either NULL or the label associated with that GPIO when it was requested. +GPIO drivers providing IRQs +--------------------------- +It is custom that GPIO drivers (GPIO chips) are also providing interrupts, +most often cascaded off a parent interrupt controller, and in some special +cases the GPIO logic is melded with a SoC:s primary interrupt controller. + +The IRQ portions of the GPIO block are implemented using an irqchip, using +the header . So basically such a driver is utilizing two sub- +systems simultaneously: gpio and irq. + +It is legal for any IRQ consumer to request an IRQ from any irqchip no matter +if that is a combined GPIO+IRQ driver. The basic premise is that gpio_chip and +irq_chip are orthogonal, and offering their services independent of each +other. + +gpiod_to_irq() is just a convenience function to figure out the IRQ for a +certain GPIO line and should not be relied upon to have been called before +the IRQ is used. + +So always prepare the hardware and make it ready for action in respective +callbacks from the GPIO and irqchip APIs. Do not rely on gpio_to_irq() having +been called first. + +This orthogonality leads to ambiguities that we need to solve: if there is +competition inside the subsystem which side is using the resource (a certain +GPIO line and register for example) it needs to deny certain operations and +keep track of usage inside of the gpiolib subsystem. This is why the API +below exists. + + Locking IRQ usage ----------------- Input GPIOs can be used as IRQ signals. When this happens, a driver is requested @@ -73,3 +103,7 @@ This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock is released: void gpiod_unlock_as_irq(struct gpio_desc *desc) + +When implementing an irqchip inside a GPIO driver, these two functions should +typically be called in the .startup() and .shutdown() callbacks from the +irqchip.