From patchwork Wed Mar 30 20:03:54 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Boris BREZILLON X-Patchwork-Id: 8858761 Return-Path: X-Original-To: patchwork-linux-rockchip@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork1.web.kernel.org (Postfix) with ESMTP id 877DD9F4F5 for ; Fri, 15 Apr 2016 20:58:57 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 92C282034A for ; Fri, 15 Apr 2016 20:58:56 +0000 (UTC) Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.9]) (using TLSv1.2 with cipher AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id AE8FA20295 for ; Fri, 15 Apr 2016 20:58:55 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.80.1 #2 (Red Hat Linux)) id 1arApL-0000ey-CR; Fri, 15 Apr 2016 20:58:55 +0000 Received: from down.free-electrons.com ([37.187.137.238] helo=mail.free-electrons.com) by bombadil.infradead.org with esmtp (Exim 4.80.1 #2 (Red Hat Linux)) id 1alMN0-0005AO-8m; Wed, 30 Mar 2016 20:05:40 +0000 Received: by mail.free-electrons.com (Postfix, from userid 110) id 60CFE1BBC; Wed, 30 Mar 2016 22:05:37 +0200 (CEST) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Spam-Level: X-Spam-Status: No, score=-5.2 required=5.0 tests=BAYES_00, RCVD_IN_DNSWL_MED, RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 Received: from localhost.localdomain (LFbn-1-2159-240.w90-76.abo.wanadoo.fr [90.76.216.240]) by mail.free-electrons.com (Postfix) with ESMTPSA id A31961853; Wed, 30 Mar 2016 22:05:12 +0200 (CEST) From: Boris Brezillon To: Thierry Reding , linux-pwm@vger.kernel.org Subject: [PATCH v5 31/46] pwm: update documentation Date: Wed, 30 Mar 2016 22:03:54 +0200 Message-Id: <1459368249-13241-32-git-send-email-boris.brezillon@free-electrons.com> X-Mailer: git-send-email 2.5.0 In-Reply-To: <1459368249-13241-1-git-send-email-boris.brezillon@free-electrons.com> References: <1459368249-13241-1-git-send-email-boris.brezillon@free-electrons.com> X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20160330_130538_818224_7BD6D7D1 X-CRM114-Status: GOOD ( 15.05 ) X-Spam-Score: -2.9 (--) X-Mailman-Approved-At: Fri, 15 Apr 2016 13:58:39 -0700 X-BeenThere: linux-rockchip@lists.infradead.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: Upstream kernel work for Rockchip platforms List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Milo Kim , Kamil Debski , Heiko Stuebner , linux-doc@vger.kernel.org, David Airlie , Mike Turquette , linux-fbdev@vger.kernel.org, dri-devel@lists.freedesktop.org, linux-kernel@vger.kernel.org, linux-sunxi@googlegroups.com, Alexandre Belloni , Daniel Vetter , Lee Jones , linux-clk@vger.kernel.org, linux-leds@vger.kernel.org, Boris Brezillon , Krzysztof Kozlowski , linux-samsung-soc@vger.kernel.org, Alexander Shiyan , Jonathan Corbet , Robert Jarzmik , lm-sensors@lm-sensors.org, linux-rockchip@lists.infradead.org, Chen-Yu Tsai , Tomi Valkeinen , linux-input@vger.kernel.org, Jean-Christophe Plagniol-Villard , intel-gfx@lists.freedesktop.org, Guenter Roeck , Jean Delvare , Joachim Eastwood , Bryan Wu , Jani Nikula , Mark Brown , Jacek Anaszewski , linux-arm-kernel@lists.infradead.org, Thomas Petazzoni , Ryan Mallon , Jingoo Han , Dmitry Torokhov , Stephen Boyd , Liam Girdwood , Hartley Sweeten , Richard Purdie , Kukjin Kim , Daniel Vetter , Maxime Ripard MIME-Version: 1.0 Sender: "Linux-rockchip" Errors-To: linux-rockchip-bounces+patchwork-linux-rockchip=patchwork.kernel.org@lists.infradead.org X-Virus-Scanned: ClamAV using ClamSMTP Update the PWM subsystem documentation to reflect the atomic PWM changes. Signed-off-by: Boris Brezillon --- Documentation/pwm.txt | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/Documentation/pwm.txt b/Documentation/pwm.txt index ca895fd..cb25fca 100644 --- a/Documentation/pwm.txt +++ b/Documentation/pwm.txt @@ -42,9 +42,23 @@ variants of these functions, devm_pwm_get() and devm_pwm_put(), also exist. After being requested, a PWM has to be configured using: -int pwm_config(struct pwm_device *pwm, int duty_ns, int period_ns); +int pwm_apply_state(struct pwm_device *pwm, struct pwm_state *pstate); -To start/stop toggling the PWM output use pwm_enable()/pwm_disable(). +This API controls both the PWM period/duty_cycle config and the +enable/disable state. + +The legacy pwm_config(), pwm_enable() and pwm_disable() are now deprecated, +and should be replaced by pwm_apply_state() calls. + +The PWM user API also allows one to query the PWM state with pwm_get_state(). + +In addition to the PWM state, the PWM API also exposes PWM arguments, which +are the reference PWM config one should use on this PWM. +PWM arguments are usually platform-specific and allows the PWM user to only +care about dutycycle relatively to the full period (like, duty = 50% of the +period). struct pwm_args contains 2 fields (period and polarity) and should +be used to set the initial PWM config (usually done in the probe function +of the PWM user). PWM arguments are retrieved with pwm_get_args(). Using PWMs with the sysfs interface ----------------------------------- @@ -105,6 +119,15 @@ goes low for the remainder of the period. Conversely, a signal with inversed polarity starts low for the duration of the duty cycle and goes high for the remainder of the period. +Drivers are encouraged to implement ->apply() instead of the legacy +->enable(), ->disable() and ->config() methods. Doing that should provide +atomicity in the PWM config workflow, which is required when the PWM controls +a critical device (like a regulator). + +The implementation of ->get_state() (a method used to retrieve initial PWM +state) is also encouraged for the same reason: letting the PWM user know +about the current PWM state would allow him to avoid glitches. + Locking -------