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

[Paul Walmsley]

Hello Nico,

On Tue, 20 Mar 2012, Nicolas Pitre wrote:

> This common clk API has been under development for over *two* years 
> already, with several attempts to merge it.  And each previous merge 
> attempt aborted because someone came along at the last minute to do 
> exactly what you are doing i.e. underline all the flaws and call for a 
> redesign.  This is becoming a bad joke.

There is a misunderstanding.  I am not calling for a redesign.  I am 
simply stating that the current maturity level of the API and code should 
be documented in the Kconfig dependencies or description text before the 
code goes upstream.  The objectives are to make future changes easier, set 
expectations, and clearly disclose the extent to which the API and code 
will need to change.

> The code will be easier to change once it is in mainline, simply due to 
> the fact that you can also change all its users at once.  And it is well 
> possible that most users won't have to deal with the same magnitude of 
> complexity as yours, again reducing the scope for resistance to changes.

I hope you are right.  To me, these conclusions seem unlikely.  It seems 
equally likely that these rationales will make it much more difficult to 
change the code once it's upstream and platforms are depending on it.  
Particularly given the ongoing sensitivity to reducing "churn" of mainline 
code, so publicly discussed.  So it seems like a good idea to attempt to 
address these potential roadblocks and criticisms to major clock framework 
changes early.

> And APIs in the Linux kernel do change all the time.  There is no stable 
> API in the kernel.  Extensions will come about eventually, and existing 
> users (simple ones by definition if the current API already meets their 
> needs) should be converted over easily.

Yes, simple extensions should be straightforward.  Of greater concern are 
changes to the existing interface that will probably be required.  These 
could involve significant changes to driver or platform code.  It seems 
likely that there will be strong inertia to making these changes after 
platforms and drivers are converted.

However, if we clearly state that these API changes are likely until the 
API is well-defined, we will hopefully reduce some angst by disclosing
what some of us know.

...

One last comment to address which is orthogonal to the technical content 
of this discussion.

> Otherwise one might ask where were you during those development years if 
> you claim that the behavior and/or API of the common clock code still 
> need to change significantly?

One might ask this.  If one were to ask this, another might briefly 
outline the participation in public and private clock discussions at 
Linaro Connect in Budapest and Redwood Shores, at LPC in Santa Rosa, at 
ELCE/KS in Prague, at ELC in Redwood Shores, in conference calls, IRC 
sessions, and private E-mails with many of the people included in the 
header of this message, not to mention the list posts.

None of the concerns that have been described are new.  There has been an 
endeavour to discuss them with anyone who seemed even remotely interested.

Of course it is a personal source of regret that the participation could 
not have been greater, but this regret is hardly limited to the common 
clock project.


regards,

- Paul