From patchwork Wed Apr 9 12:37:27 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Walleij X-Patchwork-Id: 28088 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-qg0-f71.google.com (mail-qg0-f71.google.com [209.85.192.71]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id 9BEFA202DD for ; Wed, 9 Apr 2014 12:37:58 +0000 (UTC) Received: by mail-qg0-f71.google.com with SMTP id j5sf4350980qga.2 for ; Wed, 09 Apr 2014 05:37:58 -0700 (PDT) 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:sender:precedence:list-id:x-original-sender :x-original-authentication-results:mailing-list:list-post:list-help :list-archive:list-unsubscribe; bh=/RBGmxOf+eXE2Il8iZ7KJHcMW8MjaSwUUv9jSjjKwC8=; b=M3YsLfWrOHTDEjVn4s8mWDFqvMxac9HeJQDYBCSE/qsJOfC6APWHi9tBHiJUbHEOY0 g10feW0r77MmlXIp3dXS9iVUkFWumLssbRN+AM3fEMvLz1VJMv2edkZ4MXo/GJopqTsc xg9LEO0yPyPWelsX7GqLygFj3LsRV2PTmLcroDjloSqaQFjMCWjrn3Wvy/awhj5sGZsj Hd2P830/B4lyPNCAnLTk8lZ2V2V5BWc4g0FxlJOTUGlt/UX69bsq9Jr4YbqyoMZRpdWx 6tvQCEcLqSHvBSwSy5WFOerWDB0B4XywXmD1prBZqMIB30GPTL1WB55NlIL1TX7ccj0S OYMw== X-Gm-Message-State: ALoCoQlL/OMcylvwQMSqE9DUS1HcSFuWBa4Np2SHxSrplO19Bvq40ushqvDUPpzjjbmCkwvqKQ9X X-Received: by 10.58.168.137 with SMTP id zw9mr4927933veb.15.1397047078302; Wed, 09 Apr 2014 05:37:58 -0700 (PDT) MIME-Version: 1.0 X-BeenThere: patchwork-forward@linaro.org Received: by 10.140.104.116 with SMTP id z107ls688889qge.37.gmail; Wed, 09 Apr 2014 05:37:58 -0700 (PDT) X-Received: by 10.52.240.140 with SMTP id wa12mr253090vdc.52.1397047078161; Wed, 09 Apr 2014 05:37:58 -0700 (PDT) Received: from mail-vc0-f175.google.com (mail-vc0-f175.google.com [209.85.220.175]) by mx.google.com with ESMTPS id h11si113447veh.104.2014.04.09.05.37.58 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Wed, 09 Apr 2014 05:37:58 -0700 (PDT) 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 lh14so1960606vcb.6 for ; Wed, 09 Apr 2014 05:37:58 -0700 (PDT) X-Received: by 10.220.113.207 with SMTP id b15mr146901vcq.55.1397047078013; Wed, 09 Apr 2014 05:37:58 -0700 (PDT) X-Forwarded-To: patchwork-forward@linaro.org X-Forwarded-For: patch@linaro.org patchwork-forward@linaro.org Delivered-To: patch@linaro.org Received: by 10.220.12.8 with SMTP id v8csp326424vcv; Wed, 9 Apr 2014 05:37:57 -0700 (PDT) X-Received: by 10.68.236.41 with SMTP id ur9mr11624670pbc.101.1397047075516; Wed, 09 Apr 2014 05:37:55 -0700 (PDT) Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id sf3si433613pac.124.2014.04.09.05.37.53; Wed, 09 Apr 2014 05:37:53 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-gpio-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S933129AbaDIMhw (ORCPT + 1 other); Wed, 9 Apr 2014 08:37:52 -0400 Received: from mail-wi0-f169.google.com ([209.85.212.169]:46138 "EHLO mail-wi0-f169.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S933124AbaDIMhe (ORCPT ); Wed, 9 Apr 2014 08:37:34 -0400 Received: by mail-wi0-f169.google.com with SMTP id hm4so9449100wib.0 for ; Wed, 09 Apr 2014 05:37:32 -0700 (PDT) X-Received: by 10.180.11.36 with SMTP id n4mr9866307wib.4.1397047052695; Wed, 09 Apr 2014 05:37:32 -0700 (PDT) Received: from localhost.localdomain ([85.235.11.236]) by mx.google.com with ESMTPSA id jd2sm4144601wic.9.2014.04.09.05.37.30 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 09 Apr 2014 05:37:31 -0700 (PDT) From: Linus Walleij To: linux-gpio@vger.kernel.org Cc: Alexandre Courbot , Linus Walleij Subject: [PATCH] gpio: document gpio irqchips a bit more, describe helpers Date: Wed, 9 Apr 2014 14:37:27 +0200 Message-Id: <1397047047-20870-1-git-send-email-linus.walleij@linaro.org> X-Mailer: git-send-email 1.9.0 Sender: linux-gpio-owner@vger.kernel.org Precedence: list List-ID: X-Mailing-List: linux-gpio@vger.kernel.org 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 Mailing-list: list patchwork-forward@linaro.org; contact patchwork-forward+owners@linaro.org X-Google-Group-Id: 836684582541 List-Post: , List-Help: , List-Archive: List-Unsubscribe: , This adds some documentation about the GPIO irqchips, what types exist etc. Signed-off-by: Linus Walleij Acked-by: Alexandre Courbot --- Documentation/gpio/driver.txt | 59 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt index f73cc7b5dc85..fa9a0a8b3734 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/gpio/driver.txt @@ -73,6 +73,65 @@ 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. +GPIO irqchips usually fall in one of two categories: + +* CHAINED GPIO irqchips: these are usually the type that is embedded on + an SoC. This means that there is a fast IRQ handler for the GPIOs that + gets called in a chain from the parent IRQ handler, most typically the + system interrupt controller. This means the GPIO irqchip is registered + using irq_set_chained_handler() or the corresponding + gpiochip_set_chained_irqchip() helper function, and the GPIO irqchip + handler will be called immediately from the parent irqchip, while + holding the IRQs disabled. The GPIO irqchip will then end up calling + something like this sequence in its interrupt handler: + + static irqreturn_t tc3589x_gpio_irq(int irq, void *data) + chained_irq_enter(...); + generic_handle_irq(...); + chained_irq_exit(...); + + Chained GPIO irqchips typically can NOT set the .can_sleep flag on + struct gpio_chip, as everything happens directly in the callbacks. + +* NESTED THREADED GPIO irqchips: these are off-chip GPIO expanders and any + other GPIO irqchip residing on the other side of a sleeping bus. Of course + such drivers that need slow bus traffic to read out IRQ status and similar, + traffic which may in turn incur other IRQs to happen, cannot be handled + in a quick IRQ handler with IRQs disabled. Instead they need to spawn a + thread and then mask the parent IRQ line until the interrupt is handled + by the driver. The hallmark of this driver is to call something like + this in its interrupt handler: + + static irqreturn_t tc3589x_gpio_irq(int irq, void *data) + ... + handle_nested_irq(irq); + + The hallmark of threaded GPIO irqchips is that they set the .can_sleep + flag on struct gpio_chip to true, indicating that this chip may sleep + when accessing the GPIOs. + +To help out in handling the set-up and management of GPIO irqchips and the +associated irqdomain and resource allocation callbacks, the gpiolib has +some helpers that can be enabled by selecting the GPIOLIB_IRQCHIP Kconfig +symbol: + +* gpiochip_irqchip_add(): adds an irqchip to a gpiochip. It will pass + the struct gpio_chip* for the chip to all IRQ callbacks, so the callbacks + need to embed the gpio_chip in its state container and obtain a pointer + to the container using container_of(). + (See Documentation/driver-model/design-patterns.txt) + +* gpiochip_set_chained_irqchip(): sets up a chained irq handler for a + gpio_chip from a parent IRQ and passes the struct gpio_chip* as handler + data. (Notice handler data, since the irqchip data is likely used by the + parent irqchip!) This is for the chained type of chip. + +To use the helpers please keep the following in mind: + +- Make sure to assign all relevant members of the struct gpio_chip so that + the irqchip can initialize. E.g. .dev and .can_sleep shall be set up + properly. + 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