RFC The Linux Kernel Thermal Framework Docbook
Get series with b4
b4 am [email protected]Versions newest first
- v1 RFC Latest12 patches 11 repliesIn review
Patches in v1 No applies recorded yet
| # | Subject and files | Size | Replies | Applied |
|---|---|---|---|---|
| 1/12 | Documentation: Introduce Linux Kernel Thermal Framework DocBookDocumentation/ Documentation/ | +90 | 3 replies | |
| 2/12 | Documentation: thermal docbook: add glossaryDocumentation/ | +128 | 7 replies | |
| 3/12 | thermal: cpu_cooling: remove duplicate documentation entriesinclude/ | +0 | 0 replies | |
| 4/12 | thermal: of-thermal: remove kernel doc warndrivers/ | +1 | 0 replies | |
| 5/12 | thermal: thermal.h: minor kernel doc fixinclude/ | +1 | 0 replies | |
| 6/12 | thermal: thermal_core: correct kernel doc wording on thermal_zone_get_tempdrivers/ | +1 | 0 replies | |
| 7/12 | Documentation: thermal docbook: introduce API reference chapterDocumentation/ | +9 | 0 replies | |
| 8/12 | thermal: fair share: fix kernel doc entrydrivers/ | +4 | 0 replies | |
| 9/12 | thermal: user space: fix kernel doc entrydrivers/ | +4 | 0 replies | |
| 10/12 | thermal: bang bang: fix kernel doc entrydrivers/ | +3 | 0 replies | |
| 11/12 | thermal: step wise: fix kernel doc entrydrivers/ | +19 | 0 replies | |
| 12/12 | Documentation: thermal docbook: introduce governor chapterDocumentation/ | +67 | 1 reply |
Reviews trailers per patch
No Reviewed-by, Acked-by or Tested-by trailers for v1 yet.
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