From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-qc0-f171.google.com (mail-qc0-f171.google.com [209.85.216.171]) (using TLSv1 with cipher ECDHE-RSA-RC4-SHA (128/128 bits)) (Client CN "smtp.gmail.com", Issuer "Google Internet Authority" (not verified)) by ozlabs.org (Postfix) with ESMTPS id CB46B2C0098 for ; Fri, 19 Jul 2013 03:47:27 +1000 (EST) Received: by mail-qc0-f171.google.com with SMTP id n1so1859727qcw.16 for ; Thu, 18 Jul 2013 10:47:24 -0700 (PDT) Date: Thu, 18 Jul 2013 13:47:22 -0400 (EDT) From: Nicolas Pitre To: Russell King - ARM Linux Subject: Re: [PATCH v1 05/24] clk: wrap I/O access for improved portability In-Reply-To: <20130718091735.GW24642@n2100.arm.linux.org.uk> Message-ID: References: <1373914074-20889-1-git-send-email-gsi@denx.de> <1373914074-20889-6-git-send-email-gsi@denx.de> <20130715193829.GS14452@pengutronix.de> <20130718070402.GO7080@book.gsilab.sittig.org> <20130718091735.GW24642@n2100.arm.linux.org.uk> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Cc: Mike Turquette , Detlev Zundel , Wolfram Sang , devicetree-discuss@lists.ozlabs.org, Greg Kroah-Hartman , Gerhard Sittig , linuxppc-dev@lists.ozlabs.org, Rob Herring , Mark Brown , Marc Kleine-Budde , Wolfgang Grandegger , David Woodhouse , Sascha Hauer , linux-arm-kernel@lists.infradead.org, Mauro Carvalho Chehab List-Id: Linux on PowerPC Developers Mail List List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , On Thu, 18 Jul 2013, Russell King - ARM Linux wrote: > 1. clk_get() and clk_put() are NOT part of the common clock API. > They're separate - they're part of the clk API, and the infrastructure > behind that is clkdev, which is a separately owned thing (by me.) > > 2. The "contract" of the clk API is defined by the clk API, not by some > random implementation like the common clock API. The clk API is > maintained by myself, and is described in include/linux/clk.h > > 3. clk_prepare() and clk_unprepare() are functions MUST only be called > from contexts where sleeping is permitted. These functions MAY sleep > for whatever reason they require to, and as long as they require to. > (This is the whole reason these two functions were created in the > first place.) > > 4. clk_enable() and clk_disable() MAY be called from any context, but > MUST never sleep. If you need to talk over a non-atomic bus for these, > then these functions should be no-ops, and the code which does that > must be executed from the clk_prepare()/clk_unprepare() operations. Could the above be included in some form in Documentation/clk.txt (this is likely one of the first location people look for information) and elsewhere if appropriate please? A *lot* of people are confused by the prepare-enable-disable-unprepare sequence and when I try to find some rational for the prepare/enable split I can only direct them to mail archive posts since this is nowhere to be found in the kernel. The comments in include/linux/clk.h, while correct, are very terse and don't provide any insight to the reason why there is a split in the API. The content of Documentation/clk.txt does refer to prepare and enable (and their counterparts) but again doesn't provide any clue about the reason for their existence. Since there've been several good posts with usage example now buried into list archives, I think this would go a long way helping people get it right if those were part of the kernel documentation as well. Nicolas