Re: [PATCH RFC 02/12] Documentation: thermal docbook: add glossary

From: Eduardo Valentin
Date: Wed Feb 18 2015 - 15:48:36 EST


On Wed, Feb 18, 2015 at 08:58:18AM -0800, Srinivas Pandruvada wrote:
> On Wed, 2015-02-18 at 11:52 +0000, Javi Merino wrote:
> > Hi Eduardo,
> >
> > On Mon, Feb 09, 2015 at 09:34:03PM +0000, Eduardo Valentin wrote:
> > > This change introduces a section in the Introduction Chapter to
> > > list concepts used by the Thermal Framework.
> > >
> > > Signed-off-by: Eduardo Valentin <edubezval@xxxxxxxxx>
> > > ---
> > > Documentation/DocBook/thermal.tmpl | 129 ++++++++++++++++++++++++++++++++++++-
> > > 1 file changed, 128 insertions(+), 1 deletion(-)
> > >
> > > diff --git a/Documentation/DocBook/thermal.tmpl b/Documentation/DocBook/thermal.tmpl
> > > index f8fb8a2..66efed3 100644
> > > --- a/Documentation/DocBook/thermal.tmpl
> > > +++ b/Documentation/DocBook/thermal.tmpl
> > > @@ -84,5 +84,132 @@
> > > devices.
> > > </para>
> > >
> > > - </chapter>
> > > + <sect1 id="glossary">
> > > + <title>Glossary</title>
> > > + <para>The Linux Kernel Thermal Framework uses a
> > > + specific terminology to represent the entities involved
> > > + in thermal constrained environments. This section
> > > + summaries the terminology as dictionary. These terms are
> > > + in use within the present document and in the source
> > > + code of the Linux Kernel Thermal Framework.
> > > + </para>
> > > + <glossary>
> > > + <glossentry>
> > > + <glossterm>Thermal Zone</glossterm>
> > > + <glossdef>
> > > + <para>Thermal zones represent
> > > + what is the current status of a
> > > + thermal constrained zone in the
> > > + hardware. The zone usually is a
> > > + device or component. The status
> > > + of a thermal zone is mainly with
> > > + respect to temperature.
> > > + Currently, the Linux Kernel
> > > + Thermal Framework represents
> > > + temperature in miliCelsius. The
> > > + current abstraction covers for
> > > + non negative temperatures and
> > > + constraints.
> > > + </para>
> >
> > Shall we point out that a thermal zone doesn't necessarily imply a
> > thermal sensor? I find it very common to assume that if you have 10
> > sensors, you should have 10 thermal zones. From my point of view, a
> > thermal zone is an area that has similar thermal characteristics.
> > Therefore, the temperature of the thermal zone doesn't necessarily
> > have to come from on sensor, and can be defined as a combination of
> > the input from multiple thermal sensors.

Yes, I agree that here we should mention that we are talking about an
area/zone in hardware.

>
> Currently since you can have one temperature input per zone
> (irrespective of whether the temperature is combination of many sensors
> or virtual sensor), so separating thermal sensor and zone can be more
> confusing IMO from a user space perspective.

I believe we should make it clear in the documentation what is the
relation between each entity. I will add a section about the relations,
clarifying from concept perspective, implementation wise, and from
userspace perspective.

>
> This was a feature proposed and submitted for thermal sysfs 2.0 (or next
> version), where sensors and zones are separated. I think there was some
> plan to adopt this. Rui Zhang can comment more.

Yes, I agree. However, the sysfs 2.0 never made upstream. The current
documentation project targets what is in the kernel tree.

>
> Thanks,
> Srinivas
>
>
> >
> > I don't know how to put this in proper words for the documentation,
> > but I think it's worth hinting it here.
> >
> > Cheers,
> > Javi
>
>

Attachment: signature.asc
Description: Digital signature