From patchwork Thu Dec 18 13:44:17 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: kamlakant.patel@linaro.org X-Patchwork-Id: 42453 Return-Path: X-Original-To: linaro@patches.linaro.org Delivered-To: linaro@patches.linaro.org Received: from mail-lb0-f200.google.com (mail-lb0-f200.google.com [209.85.217.200]) by ip-10-151-82-157.ec2.internal (Postfix) with ESMTPS id DDAB726C6B for ; Thu, 18 Dec 2014 13:44:32 +0000 (UTC) Received: by mail-lb0-f200.google.com with SMTP id f15sf779359lbj.7 for ; Thu, 18 Dec 2014 05:44:31 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:delivered-to:date:from:to:cc:subject:message-id :references:mime-version:content-type:content-disposition :in-reply-to:user-agent:sender:precedence:list-id:x-original-sender :x-original-authentication-results:mailing-list:list-post:list-help :list-archive:list-unsubscribe; bh=36+eiVqODGf/GAwXCBw9V8mRciC9Ke5Qw8UZLOdW//o=; b=H9dDQxaOMB/QYvS1rkEdgFEzFcSOIdnMFapCs+u39XAnEo2FftChTPssqSWzV/DRLr PYD3iS/J5Tc62MGGXrMt1HKg/NggbSIm/DVa7wHWHIgHMx69OL2CtK1Px2UOjBOz3FjC rMjBixbdVZyOWlg7maKwam1Hcr+0FdtTCT+2IdYHblog+TgR/DLh9Er9lLkXdCN8BJ30 yEnIQhaRELTX0nrs2X6nvZUkkxv3NRoqQ1lvT46Q6+OawZsvJeN8wH+bvT/wv2DTyqA6 IEch1D+xKCqu1loBV3YqLd4ZP6n0WiSu8Ttfjas6q366LoFfTngP0F3PxVYvXhyJyb3l AJkQ== X-Gm-Message-State: ALoCoQlFzBSuX8N7nVd925JnPnlqETXJxSOLXiTc34Yq/R9VpLsO7+tq0PmxCjwJjW3SlH3HyLNe X-Received: by 10.112.159.199 with SMTP id xe7mr82786lbb.21.1418910271886; Thu, 18 Dec 2014 05:44:31 -0800 (PST) X-BeenThere: patchwork-forward@linaro.org Received: by 10.152.234.228 with SMTP id uh4ls1215303lac.108.gmail; Thu, 18 Dec 2014 05:44:31 -0800 (PST) X-Received: by 10.152.36.100 with SMTP id p4mr2343053laj.11.1418910271732; Thu, 18 Dec 2014 05:44:31 -0800 (PST) Received: from mail-la0-f51.google.com (mail-la0-f51.google.com. [209.85.215.51]) by mx.google.com with ESMTPS id s4si6874135las.118.2014.12.18.05.44.31 for (version=TLSv1 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Thu, 18 Dec 2014 05:44:31 -0800 (PST) Received-SPF: pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.51 as permitted sender) client-ip=209.85.215.51; Received: by mail-la0-f51.google.com with SMTP id ms9so1010906lab.10 for ; Thu, 18 Dec 2014 05:44:31 -0800 (PST) X-Received: by 10.152.7.229 with SMTP id m5mr2379142laa.80.1418910271580; Thu, 18 Dec 2014 05:44:31 -0800 (PST) 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.112.142.69 with SMTP id ru5csp1710025lbb; Thu, 18 Dec 2014 05:44:30 -0800 (PST) X-Received: by 10.68.249.130 with SMTP id yu2mr3483527pbc.69.1418910269476; Thu, 18 Dec 2014 05:44:29 -0800 (PST) Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id uu7si10295732pbc.19.2014.12.18.05.44.28 for ; Thu, 18 Dec 2014 05:44:29 -0800 (PST) Received-SPF: none (google.com: linux-gpio-owner@vger.kernel.org does not designate permitted sender hosts) client-ip=209.132.180.67; Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752044AbaLRNo2 (ORCPT ); Thu, 18 Dec 2014 08:44:28 -0500 Received: from mail-pa0-f51.google.com ([209.85.220.51]:57916 "EHLO mail-pa0-f51.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752370AbaLRNo1 (ORCPT ); Thu, 18 Dec 2014 08:44:27 -0500 Received: by mail-pa0-f51.google.com with SMTP id ey11so1433398pad.38 for ; Thu, 18 Dec 2014 05:44:26 -0800 (PST) X-Received: by 10.70.15.68 with SMTP id v4mr3472001pdc.21.1418910266412; Thu, 18 Dec 2014 05:44:26 -0800 (PST) Received: from linaro ([202.140.36.34]) by mx.google.com with ESMTPSA id fs1sm6942543pdb.16.2014.12.18.05.44.23 (version=TLSv1.2 cipher=RC4-SHA bits=128/128); Thu, 18 Dec 2014 05:44:25 -0800 (PST) Date: Thu, 18 Dec 2014 19:14:17 +0530 From: Kamlakant Patel To: Alexandre Courbot Cc: Linus Walleij , "linux-gpio@vger.kernel.org" , "linux-doc@vger.kernel.org" Subject: Re: [PATCH v1 5/5] gpio: document basic mmio gpio library Message-ID: <20141218134417.GB2518@linaro> References: <1417435778-21879-1-git-send-email-kamlakant.patel@linaro.org> <1417435778-21879-6-git-send-email-kamlakant.patel@linaro.org> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.5.21 (2010-09-15) 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: kamlakant.patel@linaro.org X-Original-Authentication-Results: mx.google.com; spf=pass (google.com: domain of patch+caf_=patchwork-forward=linaro.org@linaro.org designates 209.85.215.51 as permitted sender) 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: , On Thu, Dec 04, 2014 at 05:52:24PM +0530, Kamlakant Patel wrote: > On 4 December 2014 at 14:42, Alexandre Courbot wrote: > > On Mon, Dec 1, 2014 at 9:09 PM, wrote: > >> From: Kamlakant Patel > >> > >> This is a brief documentation on how to use GPIO Generic > >> library for memory-mapped GPIO controllers. > >> > >> Signed-off-by: Kamlakant Patel > >> --- > >> Documentation/gpio/driver.txt | 50 +++++++++++++++++++++++++++++++++++++++++++ > >> 1 file changed, 50 insertions(+) > > > > Yum, more doc! > > > >> > >> diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt > >> index 31e0b5d..563abea 100644 > >> --- a/Documentation/gpio/driver.txt > >> +++ b/Documentation/gpio/driver.txt > >> @@ -190,3 +190,53 @@ gpiochip_free_own_desc(). > >> These functions must be used with care since they do not affect module use > >> count. Do not use the functions to request gpio descriptors not owned by the > >> calling driver. > >> + > >> + > >> +Generic driver for memory-mapped GPIO controllers > >> +------------------------------------------------- > >> +The GPIO generic library provides support for basic platform_device > >> +memory-mapped GPIO controllers, which can be accessed by selecting Kconfig > >> +symbol GPIO_GENERIC and using library functions provided by GPIO generic > >> +driver (see drivers/gpio/gpio-generic.c). > >> +The simplest form of a GPIO controller that the driver support is just a > > > > s/support/supports > > > >> +single "data" register, where GPIO state can be read and/or written. > >> + > >> +The driver can be registered using "basic-mmio-gpio" or for big-endian > >> +notation support use "basic-mmio-gpio-be". The code will configure gpio_chip > > > > Using where? You should say that this is for the platform device name. > > > >> +and issue gpiochip_add(). > > > >> + > >> +The driver supports: > >> +- 8/16/32/64 bits registers. The number of GPIOs is determined by the width of > >> + the registers. > >> +- GPIO controllers with clear/set registers. > >> +- GPIO controllers with a single "data" register. > >> +- Big endian bits/GPIOs ordering. > > > > Maybe add a sentence indicating that these settings are defined in the > > drivers using named memory resources. > > > >> + > >> +For setting GPIO's there are three supported configurations: > >> +- single input/output register resource (named "dat"). > > > > This resource seems to be mandatory - please make sure you mention this fact. > > > >> +- set/clear pair (named "set" and "clr"). > >> +- single output register resource and single input resource ("set" and dat"). > >> + > >> +For setting the GPIO direction, there are three supported configurations: > >> +- simple bidirection GPIO that requires no configuration. > > > > s/bidirection/bidirectional maybe? > > > >> +- an output direction register (named "dirout") where a 1 bit indicates the > >> + GPIO is an output. > >> +- an input direction register (named "dirin") where a 1 bit indicates the GPIO > >> + is an input. > >> + > >> +It is possible to use only parts of GPIO generic library. Each GPIO controller > >> +using GPIO generic library needs to include the following header. > >> + > >> + #include > >> + > >> +Use bgpio_init to configure gpio_chip and bgpio_remove to remove the controller. > >> +int bgpio_init(struct bgpio_chip *bgc, struct device *dev, > >> + unsigned long sz, void __iomem *dat, void __iomem *set, > >> + void __iomem *clr, void __iomem *dirout, void __iomem *dirin, > >> + unsigned long flags); > > > > If you put the prototype for bgpio_init(), please also put the one of > > bgpio_remove()... > > > >> + > >> +The "flag" parameter can be following depending on controller configuration: > >> +BGPIOF_BIG_ENDIAN BIT(0) > >> +BGPIOF_UNREADABLE_REG_SET BIT(1) /* reg_set is unreadable */ > >> +BGPIOF_UNREADABLE_REG_DIR BIT(2) /* reg_dir is unreadable */ > >> +BGPIOF_BIG_ENDIAN_BYTE_ORDER BIT(3) > > > > Right now this documentation is a little bit confusing. Basically > > there are two ways to use this driver: > > > > 1) Name your platform device ""basic-mmio-gpio" or > > "basic-mmio-gpio-be", set the right named memory resources to specify > > the desired configuration, and let bgpio_pdev_probe() do all the work. > > > > 2) Allocate a bgpio_chip yourself, call bgpio_init() on it and its > > resources, and finally invoke gpiochip_add() yourself. > > > > These two different ways of doing kind of seem to be mixed together. > > Can you try to highlight the fact that these are alternatives? > This is an updated version of previous patch. Please review. diff --git a/Documentation/gpio/driver.txt b/Documentation/gpio/driver.txt index 31e0b5d..f6b617a 100644 --- a/Documentation/gpio/driver.txt +++ b/Documentation/gpio/driver.txt @@ -190,3 +190,45 @@ gpiochip_free_own_desc(). These functions must be used with care since they do not affect module use count. Do not use the functions to request gpio descriptors not owned by the calling driver. + + +Generic driver for memory-mapped GPIO controllers +------------------------------------------------- +The GPIO generic library provides support for basic platform_device +memory-mapped GPIO controllers, which can be accessed by selecting Kconfig +symbol GPIO_GENERIC and using library functions provided by GPIO generic +driver (see drivers/gpio/gpio-generic.c). + +The driver supports registers of the sizes of 8/16/32/64 bits and the number +of GPIOs are determined by the width of the registers. A set of named memory +resources should be defined in the drivers (e.g "dat", "set", "clr", "dirout" +and "dirin"), where "dat" is a mandatory resource. + +Each GPIO controller using GPIO generic library needs to include the following +header. + #include + +There are two ways to use this driver: +1. Using basic GPIO MMIO Generic driver directly: + Name your platform device "basic-mmio-gpio" or "basic-mmio-gpio-be", set the + right named memory resources to specify the desired configuration, and let + bgpio_pdev_probe do all the work. + +2. Using basic GPIO MMIO Generic library in your driver: + Allocate a bgpio_chip yourself in your GPIO driver, call bgpio_init() on it + and its resources, and finally invoke gpiochip_add yourself. It is possible + to use only parts of the driver, you can overwrite functions and variables + in your driver, if necessary. + You can call bgpio_remove() to unregister a gpio_chip. + +For setting up GPIO's there are three supported configurations: +- single input/output register resource (named "dat"). +- set/clear pair (named "set" and "clr"). +- single output register resource and single input resource ("set" and "dat"). + +For setting the GPIO direction, there are three supported configurations: +- simple bidirectional GPIO that requires no configuration. +- an output direction register (named "dirout") where a 1 bit indicates the + GPIO is an output. +- an input direction register (named "dirin") where a 1 bit indicates the GPIO + is an input.