Debian Codegraph @

upstream/debian-trixie/man5/thinkfan.conf.5

raw
1 .TH THINKFAN.CONF 5 "December 2021" "thinkfan 1.3.1"
2 .SH NAME
3 thinkfan.conf \- YAML-formatted config for
4 .BR thinkfan (1)
5
6
7
8 .SH DESCRIPTION
9
10 YAML is a very powerful, yet concise notation for structured data.
11 Its full specification is available at https://yaml.org/spec/1.2/spec.html.
12 Thinkfan uses only a small subset of the full YAML syntax, so it may be helpful,
13 but not strictly necessary for users to take a look at the spec.
14
15 The most important thing to note is that indentation is syntactically relevant.
16 In particular, tabs should not be mixed with spaces.
17 We recommend using two spaces for indentation, like it is shown below.
18
19 The thinkfan config has three main sections:
20
21 .TP 11m
22 .B sensors:
23 Where temperatures should be read from. All
24 .BR hwmon -style
25 drivers are supported, as well as
26 .BR /proc/acpi/ibm/thermal ,
27 and, depending on the compile-time options,
28 .B libatasmart
29 (to read temperatures directly from hard disks) and
30 .B NVML
31 (via the proprietary nvidia driver).
32
33 .TP
34 .B fans:
35 Which fans should be used (currently only one allowed).
36 Support for multiple fans is currently in development and planned for a future
37 release.
38 Both
39 .BR hwmon -style
40 PWM controls and
41 .B /proc/acpi/ibm/fan
42 can be used.
43
44 .TP
45 .B levels:
46 Maps temperatures to fan speeds.
47 A \*(lqsimple mapping\*(rq just specifies one temperature as the lower and
48 upper bound (respectively) for a given fan speed.
49 In a \*(lqdetailed mapping\*(rq, the upper and lower bounds are specified for
50 each driver/sensor configured under
51 .BR sensors: .
52 This mode should be used when thinkfan is monitoring multiple devices that can
53 tolerate different amounts of heat.
54
55 .PP
56 Under each of these sections, there must be a list of key-value maps, each of
57 which configures a sensor driver, fan driver or fan speed mapping.
58
59
60
61 .SH SENSOR & FAN DRIVERS
62
63 For thinkfan to work, it first needs to know which temperature sensor drivers
64 and which fan drivers it should use.
65 The mapping between temperature readings and fan speeds is specified in a
66 separate config section (see the
67 .B FAN SPEEDS
68 section below).
69
70
71 .SS Sensor Syntax
72
73 The entries under the
74 .B sensors:
75 section can specify
76 .BR hwmon,
77 .BR thinkpad_acpi,
78 .BR NVML
79 or
80 .BR atasmart
81 drivers, where the latter two must be enabled at compile-time.
82 There can be any number (greater than zero) and combination of
83 .BR hwmon ,
84 .BR tpacpi ,
85 .BR nvml
86 and
87 .BR atasmart
88 entries.
89 However there may be at most one instance of the
90 .BR tpacpi
91 entry.
92
93 .nf
94 .B "sensors:"
95 .BI " \- hwmon: " hwmon-path
96 .BI " name: " hwmon-name
97 .BI " indices: " index-list
98 .BI " correction: " correction-list
99 .BI " optional: " bool-allow-errors
100
101 .B " \- tpacpi: /proc/acpi/ibm/thermal"
102 .BI " indices: " index-list
103 .BI " correction: " correction-list
104 .BI " optional: " bool-allow-errors
105
106 .BI " \- nvml: " nvml-bus-id
107 .BI " correction: " correction-list
108 .BI " optional: " bool-allow-errors
109
110 .BI " \- atasmart: " disk-device-file
111 .BI " correction: " correction-list
112 .BI " optional: " bool-allow-errors
113
114 .BR " \- " ...
115 .fi
116
117
118 .SS Fan Syntax
119
120 Currently, thinkfan supports only one fan, so there can be only one entry in the
121 list.
122 Support for multiple fans is currently in development and planned for a future
123 release.
124 The fan is either an
125 .B hwmon
126 fan:
127
128 .nf
129 .B "fans:"
130 .BI " \- hwmon: " hwmon-path
131 .BI " name: " hwmon-name
132 .BI " indices: " index-list
133 .fi
134
135 or a
136 .B tpacpi
137 fan:
138
139 .nf
140 .B "fans:"
141 .B " \- tpacpi: /proc/acpi/ibm/fan"
142 .fi
143
144
145 .SS Values
146
147 .TP 12m
148 .I hwmon-path
149 There are three ways of specifying hwmon fans or sensors:
150
151 .TP
152 \h'8m'1)
153 A full path of a \*(lqtemp*_input\*(rq or \*(lqpwm*\*(rq file, like
154 \*(lq/sys/class/hwmon/hwmon0/pwm1\*(rq or
155 \*(lq/sys/class/hwmon/hwmon0/temp1_input\*(rq.
156 In this case, the \*(lq\c
157 .BI indices: " index-list"\c
158 \*(rq and \*(lq\c
159 .BI name: " hwmon-name"\c
160 \*(rq entries are unnecessary since the path uniquely identifies a specific fan or
161 sensor.
162
163 Note that this method may lead to problems when the load order of the drivers
164 changes across bootups, because in the \*(lqhwmon\fIX\fR\*(rq folder name, the
165 .I X
166 actually corresponds to the load order.
167 Use method 2) or 3) to avoid this problem.
168
169 .TP
170 \h'8m'2)
171 A directory that contains a specific hwmon driver, for example
172 \*(lq/sys/devices/platform/nct6775.2592\*(rq.
173 Note that this path does not contain the load-order dependent
174 \*(lqhwmon\fIX\fR\*(rq folder.
175 As long as it contains only a single hwmon driver/interface it is sufficient to
176 specify the
177 \*(lq\c
178 .BI indices: " index-list"\c
179 \*(rq
180 entry to tell thinkfan which specific sensors to use from that interface.
181 The
182 \*(lq\c
183 .BI name: " hwmon-name"\c
184 \*(rq
185 entry is unnecessary.
186
187
188 .TP
189 \h'8m'3)
190 A directory that contains multiple or all of the hwmon drivers, for example
191 \*(lq/sys/class/hwmon\*(rq.
192 Here, both the \*(lq\c
193 .BI name: " hwmon-name"\c
194 \*(rq and \*(lq\c
195 .BI indices: " index-list"\c
196 \*(rq entries are required to tell thinkfan which interface to select below that
197 path, and which sensors or which fan to use from that interface.
198
199 .TP
200 .I hwmon-name
201 The name of a hwmon interface, typically found in a file called \*(lqname\*(rq.
202 This has to be specified if
203 .I hwmon-path
204 is a base path that contains multiple hwmons.
205 This method of specifying sensors is particularly useful if the full path to a
206 particular hwmon keeps changing between bootups, e.g. due to changing load order
207 of the driver modules.
208
209 .TP
210 .I index-list
211 A YAML list
212 .BI "[ " X1 ", " X2 ", " "\fR...\fB ]"
213 that specifies which sensors, resp. which fan to use from a given
214 interface.
215 Both
216 .B /proc/acpi/ibm/thermal
217 and also many hwmon interfaces contain multiple sensors, and not
218 all of them may be relevant for fan control.
219
220 .TP
221 \h'9m'\(bu
222 For
223 .B hwmon
224 entries, this is required if
225 .I hwmon-path
226 does not refer directly to a single \*(lqtemp\fIXi\fR_input\*(rq file, but to a folder
227 that contains one or more of them.
228 In this case,
229 .I index-list
230 specifies the
231 .I Xi
232 for the \*(lqtemp\fIXi\fR_input\*(rq files that should be used.
233 A hwmon interface may also contain multiple PWM controls for fans, so in that case,
234 .I index-list
235 must contain exactly one entry.
236
237 .TP
238 \h'9m'\(bu
239 For
240 .B tpacpi
241 sensors, this entry is optional.
242 If it is omitted, all temperatures found in
243 .B /proc/acpi/ibm/thermal
244 will be used.
245
246 .TP
247 .I nvml-bus-id
248 NOTE: only available if thinkfan was compiled with USE_NVML enabled.
249
250 The PCI bus ID of an nVidia graphics card that is run with the proprietary
251 nVidia driver. Can be obtained with e.g. \*(lqlspci | grep \-i vga\*(rq.
252 Usually, nVidia cards will use the open source
253 .B nouveau
254 driver, which should support hwmon sensors instead.
255
256 .TP
257 .I disk-device-file
258 NOTE: only available if thinkfan was compiled with USE_ATASMART enabled.
259
260 Full path to a device file for a hard disk that supports S.M.A.R.T.
261 See also the
262 .B \-d
263 option in
264 .BR thinkfan (1)
265 that prevents thinkfan from waking up sleeping (mechanical) disks to read their
266 temperature.
267
268 .TP
269 .IR correction-list " (always optional)"
270 A YAML list that specifies temperature offsets for each sensor in use by the
271 given driver. Use this if you want to use the \*(lqsimple\*(rq level syntax,
272 but need to compensate for devices with a lower heat tolerance.
273 Note however that the detailed level syntax is usually the better (i.e. more
274 fine-grained) choice.
275
276 .TP
277 .IR bool-allow-errors " (always optional, \fBfalse\fR by default)"
278 A truth value
279 .RB ( yes / no / true / false )
280 that specifies whether thinkfan should accept errors when reading from this
281 sensor.
282 Normally, thinkfan will exit with an error message if reading the temperature
283 from any configured sensor fails.
284 Marking a sensor as optional may be useful for removable hardware or devices
285 that may get switched off entirely to save power.
286
287
288
289 .SH FAN SPEEDS
290
291 The
292 .B levels:
293 section specifies a list of fan speeds with associated lower and upper
294 temperature bounds.
295 If temperature(s) drop below the lower bound, thinkfan switches to the previous
296 level, and if the upper bound is reached, thinkfan switches to the next level.
297
298 .SS Simple Syntax
299 In the simplified form, only one temperature is specified as an upper/lower
300 limit for a given fan speed.
301 In that case, the
302 .I lower-bound
303 and
304 .I upper-bound
305 are compared only to the highest temperature found among all configured sensors.
306 All other temperatures are ignored.
307 This mode is suitable for small systems (like laptops) where there is only one
308 device (e.g. the CPU) whose temperature needs to be controlled, or where the
309 required fan behaviour is similar enough for all heat-generating devices.
310
311 .nf
312 .B "levels:"
313 .BI " \- [ " fan-speed ", " lower-bound ", " upper-bound " ]"
314 .BR " \- " ...
315 .fi
316
317
318 .SS Detailed Syntax
319 This mode is suitable for more complex systems, with devices that have
320 different temperature ratings.
321 For example, many modern CPUs and GPUs can deal with temperatures above
322 80\[char176]C on a daily basis, whereas a hard disk will die quickly if it
323 reaches such temperatures.
324 In detailed mode, upper and lower temperature limits are specified for each
325 sensor individually:
326
327 .nf
328 .B "levels:"
329 .BI " \- speed: " fan-speed
330 .BI " lower_limit: [ " l1 ", " l2 ", " "\fR..." " ]"
331 .BI " upper_limit: [ " u1 ", " u2 ", " "\fR..." " ]"
332 .BR " \- " ...
333 .fi
334
335
336 .SS Values
337
338 .TP 12m
339 .I fan-speed
340 The possible speed values are different depending on which fan driver is used.
341
342 For a
343 .B hwmon
344 fan,
345 .I fan-speed
346 is a numeric value ranging from
347 .B 0
348 to
349 .BR 255 ,
350 corresponding to the PWM values accepted by the various kernel drivers.
351
352 For a
353 .B tpacpi
354 fan on Lenovo/IBM ThinkPads and some other Lenovo laptops (see \fBSENSORS & FAN
355 DRIVERS\fR above), numeric values and strings can be used.
356 The numeric values range from 0 to 7.
357 The string values take the form \fB"level \fIlvl-id\fB"\fR, where
358 .I lvl-id
359 may be a value from
360 .BR 0 " to " 7 ,
361 .BR auto ,
362 .B full-speed
363 or
364 .BR disengaged .
365 The numeric values
366 .BR 0 " to " 7
367 correspond to the regular fan speeds used by the firmware, although many
368 firmwares don't even use level \fB7\fR.
369 The value \fB"level auto"\fR gives control back to the firmware, which may be
370 useful if the fan behavior only needs to be changed for certain specific
371 temperature ranges (usually at the high and low end of the range).
372 The values \fB"level full-speed"\fR and \fB"level disengaged"\fR take the fan
373 speed control away from the firmware, causing the fan to slowly ramp up to an
374 absolute maximum that can be achieved within electrical limits.
375 Note that this will run the fan out of specification and cause increased wear,
376 though it may be helpful to combat thermal throttling.
377
378 .TP
379 .IB l1 ", " l2 ", " \fR...
380 .TP
381 .IB u1 ", " u2 ", " \fR...
382 The lower and upper limits refer to the sensors in the same order in which they
383 were found when processing the
384 .B sensors:
385 section (see
386 .B SENSOR & FAN DRIVERS
387 above).
388 For the first level entry, the
389 .B lower_limit
390 may be omitted, and for the last one, the
391 .B upper_limit
392 may be omitted.
393 For all levels in between, the lower limits must overlap with the upper limits
394 of the previous level, to make sure the entire temperature range is covered and
395 that there is some hysteresis between speed levels.
396
397
398 .SH SEE ALSO
399 .nf
400 The thinkfan manpage:
401 .BR thinkfan (1)
402
403 Example configs shipped with the source distribution, also available at:
404 .hy 0
405 https://github.com/vmatare/thinkfan/tree/master/examples
406
407 The Linux hwmon user interface documentation:
408 https://www.kernel.org/doc/html/latest/hwmon/sysfs\-interface.html
409
410 The thinkpad_acpi interface documentation:
411 https://www.kernel.org/doc/html/latest/admin\-guide/laptops/thinkpad\-acpi.html
412
413
414 .SH BUGS
415
416 .hy 0
417 .nf
418 Report bugs on the github issue tracker:
419 https://github.com/vmatare/thinkfan/issues
420