Skip to content

RFC The Linux Kernel Thermal Framework Docbook

Eduardo Valentin linux-pm lkml 1 version In review

Get series with b4
b4 am [email protected]

Versions newest first

  1. v1 RFC Latest12 patches 11 repliesIn review

Patches in v1 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/12Documentation: Introduce Linux Kernel Thermal Framework DocBookDocumentation/DocBook/Makefile Documentation/DocBook/thermal.tmpl+90 -13 replies
2/12Documentation: thermal docbook: add glossaryDocumentation/DocBook/thermal.tmpl+128 -17 replies
3/12thermal: cpu_cooling: remove duplicate documentation entriesinclude/linux/cpu_cooling.h+0 -130 replies
4/12thermal: of-thermal: remove kernel doc warndrivers/thermal/of-thermal.c+1 -10 replies
5/12thermal: thermal.h: minor kernel doc fixinclude/linux/thermal.h+1 -10 replies
6/12thermal: thermal_core: correct kernel doc wording on thermal_zone_get_tempdrivers/thermal/thermal_core.c+1 -10 replies
7/12Documentation: thermal docbook: introduce API reference chapterDocumentation/DocBook/thermal.tmpl+9 -00 replies
8/12thermal: fair share: fix kernel doc entrydrivers/thermal/fair_share.c+4 -10 replies
9/12thermal: user space: fix kernel doc entrydrivers/thermal/user_space.c+4 -10 replies
10/12thermal: bang bang: fix kernel doc entrydrivers/thermal/gov_bang_bang.c+3 -20 replies
11/12thermal: step wise: fix kernel doc entrydrivers/thermal/step_wise.c+19 -60 replies
12/12Documentation: thermal docbook: introduce governor chapterDocumentation/DocBook/thermal.tmpl+67 -01 reply

Reviews trailers per patch

No Reviewed-by, Acked-by or Tested-by trailers for v1 yet.

Read the v1 thread

Cover letter [PATCH RFC 00/12] The Linux Kernel Thermal Framework Docbook

(sorry if you got this duplicated, this time I am copying the mailing lists)

Hello Rui, linux-pm,

It's been some time that I have started this documentation project. The target is to organize the thermal code documentation, using the kernel docbook format. In other words, the Linux kernel Documentation would be earning a new Docbook, a thermal Docbook.

The work is in progress. I started a few chapters, but never got the chance to finish what I initially intended. However, I decided to share already with you because I would like to hear what people would like to see in the Docbook.

The whole idea is to consolidate what we have currently spread under Documentation, in a single place, the new Docbook. So, we would be moving the Documentation/thermal/sysfs-api.txt content to this Docbook (not done yet).

The overall content organization that I am envisioning is organized in the following Chapters:
1 - Introduction: Overall thermal problem statement and the Linux Kernel solution. In here we should also give an overview of the framework design strategies and decisions. Under sysfs-api.txt we have something talking about it, but I believe it got dated already. In this chapter, we also include a small dictionary. Current status: In progress
2 - Governors: In here we would document all the existing governors and their implemented policies. Also, I would like to have a simple example on how to write your own thermal governor.
Current status: In progress.
3 - Cooling Devices: I believe here we should include the documentation of the existing cooling devices in the kernel tree. Also, we should include an example on how to implement a cooling device. 4 - Thermal zone drivers: An example on a simple thermal zone device driver code. Discussion on the multiple ways of implementing one: standard, of-thermal support, etc.
5 - Generic code: Documentation of the design decision of our generic drivers: cpu cooling, clock cooling, of-thermal, etc.
6 - User space ABI: Documentation of what we expose to userland.
7 - API Reference: A chapter with the documentation coming from in code comments.

The current code needs a couple of fixes to achieve Chapter 6, API Reference, though. I am sending in this series a couple of examples of what needs to be fixed.

The content of Chapter 6 and Chapter 7 is more or less an overlap of what we have mostly inside sysfs-api.txt. I believe it is easier to maintain code comments than maintaining a separate file to talk about code documentation. Therefore the motivation to write the Docbook. Besides, within this Docbook we should cover a better overview of the framework, that we currently lack.

I am not sure if we need to have specific thermal zone driver documentation. Probably not. But driver authors, rise your voice if you would like to have one.

Comments are welcome.

BR,

Eduardo Valentin (12):
Documentation: Introduce Linux Kernel Thermal Framework DocBook
Documentation: thermal docbook: add glossary
thermal: cpu_cooling: remove duplicate documentation entries
thermal: of-thermal: remove kernel doc warn
thermal: thermal.h: minor kernel doc fix
thermal: thermal_core: correct kernel doc wording on
thermal_zone_get_temp
Documentation: thermal docbook: introduce API reference chapter
thermal: fair share: fix kernel doc entry
thermal: user space: fix kernel doc entry
thermal: bang bang: fix kernel doc entry
thermal: step wise: fix kernel doc entry
Documentation: thermal docbook: introduce governor chapter

 Documentation/DocBook/Makefile     |   3 +-
 Documentation/DocBook/thermal.tmpl | 291 +++++++++++++++++++++++++++++++++++++
 drivers/thermal/fair_share.c       |   5 +-
 drivers/thermal/gov_bang_bang.c    |   5 +-
 drivers/thermal/of-thermal.c       |   2 +-
 drivers/thermal/step_wise.c        |  25 +++-
 drivers/thermal/thermal_core.c     |   2 +-
 drivers/thermal/user_space.c       |   5 +-
 include/linux/cpu_cooling.h        |  13 --
 include/linux/thermal.h            |   2 +-
 10 files changed, 326 insertions(+), 27 deletions(-)
 create mode 100644 Documentation/DocBook/thermal.tmpl
Signature · 1 line
2.1.3