[PATCH] PM / OPP: improve introductory documentation

[PATCH] PM / OPP: improve introductory documentation

[Nishanth Menon]

Make Operating Performance Points (OPP) library introductory chapter
a little more reader-friendly. Split the chapter into two sections
and highlight the definition with an example.

Reported-by: Linus Torvalds <torvalds@linux-foundation.org>
Cc: "Rafael J. Wysocki" <rjw@sisk.pl>
Cc: linux-pm@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
Signed-off-by: Nishanth Menon <nm@ti.com>
---
based on v3.8 tag
 Documentation/power/opp.txt |   23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/Documentation/power/opp.txt b/Documentation/power/opp.txt
index 3035d00..b4f1870 100644
--- a/Documentation/power/opp.txt
+++ b/Documentation/power/opp.txt
@@ -1,6 +1,5 @@
-*=============*
-* OPP Library *
-*=============*
+Operating Performance Points (OPP) Library
+==========================================
 
 (C) 2009-2010 Nishanth Menon <nm@ti.com>, Texas Instruments Incorporated
 
@@ -16,15 +15,31 @@ Contents
 
 1. Introduction
 ===============
+1.1 What is an Operating Performance Point (OPP)?
+
 Complex SoCs of today consists of a multiple sub-modules working in conjunction.
 In an operational system executing varied use cases, not all modules in the SoC
 need to function at their highest performing frequency all the time. To
 facilitate this, sub-modules in a SoC are grouped into domains, allowing some
 domains to run at lower voltage and frequency while other domains are loaded
-more. The set of discrete tuples consisting of frequency and voltage pairs that
+more.
+
+The set of discrete tuples consisting of frequency and voltage pairs that
 the device will support per domain are called Operating Performance Points or
 OPPs.
 
+As an example:
+Let us consider an MPU device which supports the following:
+{300MHz at minimum voltage of 1V}, {800MHz at minimum voltage of 1.2V},
+{1GHz at minimum voltage of 1.3V}
+
+We can represent these as three OPPs as the following {Hz, uV} tuples:
+{300000000, 1000000}
+{600000000, 1200000}
+{100000000, 1300000}
+
+1.2 Operating Performance Points Library
+
 OPP library provides a set of helper functions to organize and query the OPP
 information. The library is located in drivers/base/power/opp.c and the header
 is located in include/linux/opp.h. OPP library can be enabled by enabling
-- 
1.7.9.5

Re: [PATCH] PM / OPP: improve introductory documentation

[Randy Dunlap]

On 02/26/13 09:37, Nishanth Menon wrote:
> Make Operating Performance Points (OPP) library introductory chapter
> a little more reader-friendly. Split the chapter into two sections
> and highlight the definition with an example.
> 
> Reported-by: Linus Torvalds <torvalds@linux-foundation.org>
> Cc: "Rafael J. Wysocki" <rjw@sisk.pl>
> Cc: linux-pm@vger.kernel.org
> Cc: linux-doc@vger.kernel.org
> Cc: linux-kernel@vger.kernel.org
> Signed-off-by: Nishanth Menon <nm@ti.com>
> ---
> based on v3.8 tag
>  Documentation/power/opp.txt |   23 +++++++++++++++++++----
>  1 file changed, 19 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/power/opp.txt b/Documentation/power/opp.txt
> index 3035d00..b4f1870 100644
> --- a/Documentation/power/opp.txt
> +++ b/Documentation/power/opp.txt
> @@ -1,6 +1,5 @@
> -*=============*
> -* OPP Library *
> -*=============*
> +Operating Performance Points (OPP) Library
> +==========================================
>  
>  (C) 2009-2010 Nishanth Menon <nm@ti.com>, Texas Instruments Incorporated
>  
> @@ -16,15 +15,31 @@ Contents
>  
>  1. Introduction
>  ===============
> +1.1 What is an Operating Performance Point (OPP)?
> +
>  Complex SoCs of today consists of a multiple sub-modules working in conjunction.
>  In an operational system executing varied use cases, not all modules in the SoC
>  need to function at their highest performing frequency all the time. To
>  facilitate this, sub-modules in a SoC are grouped into domains, allowing some
>  domains to run at lower voltage and frequency while other domains are loaded
> -more. The set of discrete tuples consisting of frequency and voltage pairs that
> +more.

huh???

> +
> +The set of discrete tuples consisting of frequency and voltage pairs that
>  the device will support per domain are called Operating Performance Points or
>  OPPs.
>  
> +As an example:
> +Let us consider an MPU device which supports the following:
> +{300MHz at minimum voltage of 1V}, {800MHz at minimum voltage of 1.2V},
> +{1GHz at minimum voltage of 1.3V}
> +
> +We can represent these as three OPPs as the following {Hz, uV} tuples:
> +{300000000, 1000000}
> +{600000000, 1200000}
    800000000

> +{100000000, 1300000}
    1000000000 ??

> +
> +1.2 Operating Performance Points Library
> +
>  OPP library provides a set of helper functions to organize and query the OPP
>  information. The library is located in drivers/base/power/opp.c and the header
>  is located in include/linux/opp.h. OPP library can be enabled by enabling
> 


-- 
~Randy

Re: [PATCH] PM / OPP: improve introductory documentation

[Nishanth Menon]

On 14:43-20130226, Randy Dunlap wrote:
> On 02/26/13 09:37, Nishanth Menon wrote:
[..]
> >  
> >  1. Introduction
> >  ===============
> > +1.1 What is an Operating Performance Point (OPP)?
> > +
> >  Complex SoCs of today consists of a multiple sub-modules working in conjunction.
> >  In an operational system executing varied use cases, not all modules in the SoC
> >  need to function at their highest performing frequency all the time. To
> >  facilitate this, sub-modules in a SoC are grouped into domains, allowing some
> >  domains to run at lower voltage and frequency while other domains are loaded
> > -more. The set of discrete tuples consisting of frequency and voltage pairs that
> > +more.
> 
> huh???
I split the definition line to it's own paragraph below. But, I think
you intend to say we could improve better the remaining paragraph.
Could you elaborate your thoughts?
> 
> > +
> > +The set of discrete tuples consisting of frequency and voltage pairs that
> >  the device will support per domain are called Operating Performance Points or
> >  OPPs.
> >  
> > +As an example:
> > +Let us consider an MPU device which supports the following:
> > +{300MHz at minimum voltage of 1V}, {800MHz at minimum voltage of 1.2V},
> > +{1GHz at minimum voltage of 1.3V}
> > +
> > +We can represent these as three OPPs as the following {Hz, uV} tuples:
> > +{300000000, 1000000}
> > +{600000000, 1200000}
>     800000000
> 
> > +{100000000, 1300000}
>     1000000000 ??
Thanks for catching it. will fix it in next rev.

-- 
Regards,
Nishanth Menon

Re: [PATCH] PM / OPP: improve introductory documentation

[Randy Dunlap]

On 02/26/13 15:10, Nishanth Menon wrote:
> On 14:43-20130226, Randy Dunlap wrote:
>> On 02/26/13 09:37, Nishanth Menon wrote:
> [..]
>>>  
>>>  1. Introduction
>>>  ===============
>>> +1.1 What is an Operating Performance Point (OPP)?
>>> +
>>>  Complex SoCs of today consists of a multiple sub-modules working in conjunction.
>>>  In an operational system executing varied use cases, not all modules in the SoC
>>>  need to function at their highest performing frequency all the time. To
>>>  facilitate this, sub-modules in a SoC are grouped into domains, allowing some
>>>  domains to run at lower voltage and frequency while other domains are loaded
>>> -more. The set of discrete tuples consisting of frequency and voltage pairs that
>>> +more.
>>
>> huh???
> I split the definition line to it's own paragraph below. But, I think
> you intend to say we could improve better the remaining paragraph.
> Could you elaborate your thoughts?

"while other domains are loaded more."  Some people probably understand
that OK; I dunno.  I would rather see it written out more verbosely, e.g.:

"while other domains run at voltage/frequency pairs that are higher."

but partly I was confused by the diff(1) lines.  my bad :(


>>> +
>>> +The set of discrete tuples consisting of frequency and voltage pairs that
>>>  the device will support per domain are called Operating Performance Points or
>>>  OPPs.
>>>  
>>> +As an example:
>>> +Let us consider an MPU device which supports the following:
>>> +{300MHz at minimum voltage of 1V}, {800MHz at minimum voltage of 1.2V},
>>> +{1GHz at minimum voltage of 1.3V}
>>> +
>>> +We can represent these as three OPPs as the following {Hz, uV} tuples:
>>> +{300000000, 1000000}
>>> +{600000000, 1200000}
>>     800000000
>>
>>> +{100000000, 1300000}
>>     1000000000 ??
> Thanks for catching it. will fix it in next rev.
> 


-- 
~Randy

Re: [PATCH] PM / OPP: improve introductory documentation

[Nishanth Menon]

On 15:39-20130226, Randy Dunlap wrote:
> On 02/26/13 15:10, Nishanth Menon wrote:
> > On 14:43-20130226, Randy Dunlap wrote:
> >> On 02/26/13 09:37, Nishanth Menon wrote:
> > [..]
> >>>  
> >>>  1. Introduction
> >>>  ===============
> >>> +1.1 What is an Operating Performance Point (OPP)?
> >>> +
> >>>  Complex SoCs of today consists of a multiple sub-modules working in conjunction.
> >>>  In an operational system executing varied use cases, not all modules in the SoC
> >>>  need to function at their highest performing frequency all the time. To
> >>>  facilitate this, sub-modules in a SoC are grouped into domains, allowing some
> >>>  domains to run at lower voltage and frequency while other domains are loaded
> >>> -more. The set of discrete tuples consisting of frequency and voltage pairs that
> >>> +more.
> >>
> >> huh???
> > I split the definition line to it's own paragraph below. But, I think
> > you intend to say we could improve better the remaining paragraph.
> > Could you elaborate your thoughts?
> 
> "while other domains are loaded more."  Some people probably understand
> that OK; I dunno.  I would rather see it written out more verbosely, e.g.:
> 
> "while other domains run at voltage/frequency pairs that are higher."
You are right, being verbose here makes sense. I will pick up your wording
here in v2. Thanks for reviewing and helping improve.
> 
> but partly I was confused by the diff(1) lines.  my bad :(
no worries.

-- 
Regards,
Nishanth Menon