[PATCH v7 1/3] Documentation: common clk API

[Paul Walmsley]

Hello Arnd,

On Sat, 17 Mar 2012, Arnd Bergmann wrote:

> I think it's rather pointless, because the option is not going to
> be user selectable but will get selected by the platform unless I'm
> mistaken. The platform maintainers that care already know the state
> of the framework.

This is where we have differing views, I think.  Clearly, Sascha, 
Saravana, Rob, and I have at least slightly different opinions on the 
durability of the existing API and code.  So it seems reasonable to assume 
that others who have not followed the development of the common clock code 
might mistake the implementation or API as being stable and well-defined.

It sounds like the primary objection is to the use of CONFIG_EXPERIMENTAL.  
So here is a patch to simply note the status of this code in its Kconfig 
text.


- Paul

From: Paul Walmsley <paul at pwsan.com>
Date: Tue, 20 Mar 2012 17:19:06 -0600
Subject: [PATCH] clk: note that the common clk code is still subject to
 significant change

Indicate that the common clk code and API is still likely to require
significant change.  The API is not well-defined and both it and the
underlying mechanics are likely to need significant changes to support
non-trivial uses of the rate changing code, such as DVFS with external
I/O devices.  So any platforms that switch their implementation over
to this may need to revise much of their driver code and revalidate
their implementations until the behavior of the code is
better-defined.

A good time for removing this help text would be after at least two
platforms that do DVFS on groups of external I/O devices have ported
their clock implementations over to the common clk code.

Signed-off-by: Paul Walmsley <paul at pwsan.com>
Cc: Mike Turquette <mturquette at ti.com>
---
 drivers/clk/Kconfig |    5 +++++
 1 files changed, 5 insertions(+), 0 deletions(-)

diff --git a/drivers/clk/Kconfig b/drivers/clk/Kconfig
index 2eaf17e..dd2d528 100644
--- a/drivers/clk/Kconfig
+++ b/drivers/clk/Kconfig
@@ -21,6 +21,11 @@ menuconfig COMMON_CLK
 	  this option for loadable modules requiring the common clock
 	  framework.
 
+	  The API and implementation enabled by this option is still
+	  incomplete.  The API and implementation is expected to be
+	  fluid and subject to change at any time, potentially
+	  breaking existing users.
+
 	  If in doubt, say "N".
 
 if COMMON_CLK
-- 
1.7.9.1