Generic Thermal Sysfs Driver

Generic thermal sysfs 소개

이 문서는 Sujith Thomas와 Zhang Rui가 작성한 Generic Thermal Sysfs driver 사용 안내서이며 Copyright는 2008 Intel Corporation에 있습니다.

Generic thermal sysfs는 thermal zone device(sensor)와 thermal cooling device(fan, processor 등)가 thermal management solution에 등록되어 참여할 수 있는 interface를 제공합니다.

이 안내서는 새 thermal zone과 cooling device를 thermal management에 참여시키는 방법에 초점을 둡니다. Infrastructure는 platform-independent이므로 어떤 유형의 thermal zone과 cooling device도 사용할 수 있어야 합니다.

Thermal sysfs driver의 주된 일은 thermal zone 및 cooling device attribute를 user space에 노출하는 것입니다. Intelligent thermal application은 current temperature와 trip point temperature를 읽어 적절한 device를 throttle할 수 있습니다.

표기에서 `[0-*]`는 0부터 시작하는 임의의 양수 번호를, `[1-*]`는 1부터 시작하는 임의의 양수 번호를 뜻합니다.

===================================
Generic Thermal Sysfs driver How To
===================================

Written by Sujith Thomas <sujith.thomas@intel.com>, Zhang Rui <rui.zhang@intel.com>

Copyright (c)  2008 Intel Corporation


0. Introduction
===============

The generic thermal sysfs provides a set of interfaces for thermal zone
devices (sensors) and thermal cooling devices (fan, processor...) to register
with the thermal management solution and to be a part of it.

This how-to focuses on enabling new thermal zone and cooling devices to
participate in thermal management.
This solution is platform independent and any type of thermal zone devices
and cooling devices should be able to make use of the infrastructure.

The main task of the thermal sysfs driver is to expose thermal zone attributes
as well as cooling device attributes to the user space.
An intelligent thermal management application can make decisions based on
inputs from thermal zone attributes (the current temperature and trip point
temperature) and throttle appropriate devices.

- `[0-*]`        denotes any positive number starting from 0
- `[1-*]`        denotes any positive number starting from 1

Thermal zone device 등록과 해제

`thermal_zone_device_register_with_trips()`는 새 thermal zone device(sensor)를 `/sys/class/thermal/thermal_zone[0-*]`로 추가하고, 동시에 등록된 모든 thermal cooling device를 bind하려고 시도합니다.

`type`은 thermal zone type, `trips`는 trip point table, `devdata`는 device private data, `ops`는 thermal zone callback, `tzp`는 platform parameter입니다. `passive_delay`는 passive cooling poll 사이의 millisecond, `polling_delay`는 trip crossing 확인 poll 사이의 millisecond이며 interrupt-driven system에서는 0입니다.

`.should_bind`는 cooling device를 특정 trip point에 bind할지 검사하고, `.get_temp`는 current temperature를 얻습니다. `.set_trips`는 current temperature 바로 아래와 위의 trip point를 찾아 trip window를 설정합니다.

`.change_mode`는 zone의 enabled/disabled mode를 바꾸고, `.set_trip_temp`는 특정 trip point temperature를 설정하며, `.get_crit_temp`는 critical temperature를 얻습니다.

`.set_emul_temp`는 threshold debugging용 emulation temperature를 설정하고, `.get_trend`는 최근 zone temperature 변화 추세를 얻습니다. `.hot`과 `.critical`은 각각 해당 trip point crossing handler입니다.

`thermal_zone_device_unregister()`는 thermal zone device를 제거하고 `/sys/class/thermal` entry를 삭제하며 사용하던 모든 cooling device의 binding을 해제합니다.

1. thermal sysfs driver interface functions
===========================================

1.1 thermal zone device interface
---------------------------------

    ::

        struct thermal_zone_device *
        thermal_zone_device_register_with_trips(const char *type,
                                        const struct thermal_trip *trips,
                                        int num_trips, void *devdata,
                                        const struct thermal_zone_device_ops *ops,
                                        const struct thermal_zone_params *tzp,
                                        unsigned int passive_delay,
                                        unsigned int polling_delay)

    This interface function adds a new thermal zone device (sensor) to the
    /sys/class/thermal folder as `thermal_zone[0-*]`. It tries to bind all the
    thermal cooling devices registered to it at the same time.

    type:
        the thermal zone type.
    trips:
        the table of trip points for this thermal zone.
    devdata:
        device private data
    ops:
        thermal zone device call-backs.

        .should_bind:
                check whether or not a given cooling device should be bound to
                a given trip point in this thermal zone.
        .get_temp:
                get the current temperature of the thermal zone.
        .set_trips:
                set the trip points window. Whenever the current temperature
                is updated, the trip points immediately below and above the
                current temperature are found.
        .change_mode:
                change the mode (enabled/disabled) of the thermal zone.
        .set_trip_temp:
                set the temperature of a given trip point.
        .get_crit_temp:
                get the critical temperature for this thermal zone.
        .set_emul_temp:
                set the emulation temperature which helps in debugging
                different threshold temperature points.
        .get_trend:
                get the trend of most recent zone temperature changes.
        .hot:
                hot trip point crossing handler.
        .critical:
                critical trip point crossing handler.
    tzp:
        thermal zone platform parameters.
    passive_delay:
        number of milliseconds to wait between polls when performing passive
        cooling.
    polling_delay:
        number of milliseconds to wait between polls when checking
        whether trip points have been crossed (0 for interrupt driven systems).

    ::

        void thermal_zone_device_unregister(struct thermal_zone_device *tz)

    This interface function removes the thermal zone device.
    It deletes the corresponding entry from /sys/class/thermal folder and
    unbinds all the thermal cooling devices it uses.

Device Tree thermal sensor 등록

`thermal_zone_of_sensor_register()`는 새 sensor를 DT thermal zone에 추가합니다. Device tree에 기술된 thermal zone 목록에서 `dev->of_node`가 temperature provider로 참조되는 zone을 찾아 sensor를 해당 DT thermal zone device에 연결합니다.

`dev`는 유효한 `dev->of_node` pointer를 가진 sensor device node입니다. `sensor_id`는 sensor IP에 sensor가 여러 개 있을 때 쓰는 identifier입니다. `data`는 caller 소유 private pointer이며 temperature reading callback에 다시 전달됩니다. `ops`는 `struct thermal_zone_of_device_ops *`입니다.

필수 callback `get_temp`는 sensor temperature를 읽습니다. `set_trips`는 temperature window를 설정하고, window를 벗어나면 driver가 `thermal_zone_device_update`로 thermal core에 알려야 합니다.

선택 callback `get_trend`는 sensor temperature trend를 읽고 `set_emul_temp`는 emulated temperature를 설정합니다. Thermal zone temperature는 `thermal_zone_of_device_ops.get_temp()`로 제공되며 호출 시 private `@data`가 돌아옵니다.

실패하면 error pointer, 성공하면 유효한 thermal zone device handle을 반환합니다. Caller는 `IS_ERR()`로 성공 여부를 검사해야 합니다.

::

   struct thermal_zone_device
   *thermal_zone_of_sensor_register(struct device *dev, int sensor_id,
                        void *data,
                        const struct thermal_zone_of_device_ops *ops)

This interface adds a new sensor to a DT thermal zone.
This function will search the list of thermal zones described in
device tree and look for the zone that refer to the sensor device
pointed by dev->of_node as temperature providers. For the zone
pointing to the sensor node, the sensor will be added to the DT
thermal zone device.

The parameters for this interface are:

dev:
                Device node of sensor containing valid node pointer in
                dev->of_node.
sensor_id:
                a sensor identifier, in case the sensor IP has more
                than one sensors
data:
                a private pointer (owned by the caller) that will be
                passed back, when a temperature reading is needed.
ops:
                `struct thermal_zone_of_device_ops *`.

                ==============  =======================================
                get_temp        a pointer to a function that reads the
                                sensor temperature. This is mandatory
                                callback provided by sensor driver.
                set_trips        a pointer to a function that sets a
                                temperature window. When this window is
                                left the driver must inform the thermal
                                core via thermal_zone_device_update.
                get_trend         a pointer to a function that reads the
                                sensor temperature trend.
                set_emul_temp        a pointer to a function that sets
                                sensor emulated temperature.
                ==============  =======================================

The thermal zone temperature is provided by the get_temp() function
pointer of thermal_zone_of_device_ops. When called, it will
have the private pointer @data back.

It returns error pointer if fails otherwise valid thermal zone device
handle. Caller should check the return handle with IS_ERR() for finding
whether success or not.

DT sensor 해제, devm 등록과 slope·offset

`thermal_zone_of_sensor_unregister()`는 `thermal_zone_of_sensor_register()`로 추가한 sensor를 DT thermal zone에서 해제합니다. Sensor callback과 private data를 제거하고 `.get_temp()` 및 `get_trend()` callback을 제거해 zone을 비활성 상태로 만듭니다.

`devm_thermal_zone_of_sensor_register()`는 register function의 resource-managed version입니다. Error path나 driver unbinding에서 `thermal_zone_of_sensor_unregister()`를 명시적으로 호출할 필요가 없고 driver resource manager가 처리합니다.

`devm_thermal_zone_of_sensor_unregister()`는 unregister function의 resource-managed version입니다. 일반적으로 직접 호출할 필요 없이 resource management code가 해제를 보장합니다.

`thermal_zone_get_slope()`와 `thermal_zone_get_offset()`은 thermal zone의 slope 및 offset attribute를 읽습니다. Platform driver가 temperature 계산에 사용할 수 있습니다.

::

    void thermal_zone_of_sensor_unregister(struct device *dev,
                                           struct thermal_zone_device *tzd)

This interface unregisters a sensor from a DT thermal zone which was
successfully added by interface thermal_zone_of_sensor_register().
This function removes the sensor callbacks and private data from the
thermal zone device registered with thermal_zone_of_sensor_register()
interface. It will also silent the zone by remove the .get_temp() and
get_trend() thermal zone device callbacks.

::

  struct thermal_zone_device
  *devm_thermal_zone_of_sensor_register(struct device *dev,
                        int sensor_id,
                        void *data,
                        const struct thermal_zone_of_device_ops *ops)

This interface is resource managed version of
thermal_zone_of_sensor_register().

All details of thermal_zone_of_sensor_register() described in
section 1.1.3 is applicable here.

The benefit of using this interface to register sensor is that it
is not require to explicitly call thermal_zone_of_sensor_unregister()
in error path or during driver unbinding as this is done by driver
resource manager.

::

        void devm_thermal_zone_of_sensor_unregister(struct device *dev,
                                        struct thermal_zone_device *tzd)

This interface is resource managed version of
thermal_zone_of_sensor_unregister().
All details of thermal_zone_of_sensor_unregister() described in
section 1.1.4 is applicable here.
Normally this function will not need to be called and the resource
management code will ensure that the resource is freed.

::

        int thermal_zone_get_slope(struct thermal_zone_device *tz)

This interface is used to read the slope attribute value
for the thermal zone device, which might be useful for platform
drivers for temperature calculations.

::

        int thermal_zone_get_offset(struct thermal_zone_device *tz)

This interface is used to read the offset attribute value
for the thermal zone device, which might be useful for platform
drivers for temperature calculations.

Thermal cooling device interface

`thermal_cooling_device_register()`는 새 thermal cooling device(fan, processor 등)를 `/sys/class/thermal/cooling_device[0-*]`로 추가하고 동시에 등록된 모든 thermal zone device에 자신을 bind하려고 시도합니다.

`name`은 cooling device name, `devdata`는 private data, `ops`는 callback입니다. `.get_max_state`는 maximum throttle state, `.get_cur_state`는 현재 요청된 throttle state를 얻고 `.set_cur_state`는 current throttle state를 설정합니다.

`thermal_cooling_device_unregister()`는 cooling device를 제거하고 `/sys/class/thermal` entry를 삭제하며 이를 사용하는 모든 thermal zone에서 binding을 해제합니다.

1.2 thermal cooling device interface
------------------------------------


    ::

        struct thermal_cooling_device
        *thermal_cooling_device_register(char *name,
                        void *devdata, struct thermal_cooling_device_ops *)

    This interface function adds a new thermal cooling device (fan/processor/...)
    to /sys/class/thermal/ folder as `cooling_device[0-*]`. It tries to bind itself
    to all the thermal zone devices registered at the same time.

    name:
        the cooling device name.
    devdata:
        device private data.
    ops:
        thermal cooling devices call-backs.

        .get_max_state:
                get the Maximum throttle state of the cooling device.
        .get_cur_state:
                get the Currently requested throttle state of the
                cooling device.
        .set_cur_state:
                set the Current throttle state of the cooling device.

    ::

        void thermal_cooling_device_unregister(struct thermal_cooling_device *cdev)

    This interface function removes the thermal cooling device.
    It deletes the corresponding entry from /sys/class/thermal folder and
    unbinds itself from all the thermal zone devices using it.

Thermal Zone Parameters

`struct thermal_zone_params`는 thermal zone의 platform-level parameter를 정의합니다. 각 zone의 data는 platform layer에서 와야 하지만 optional이므로 제공하지 않는 platform도 있습니다.

`.governor_name`은 이 zone에서 사용하는 thermal governor 이름입니다.

`.no_hwmon`은 thermal-to-hwmon sysfs interface 생성 여부입니다. `false`면 hwmon interface를 만들고 `true`면 만들지 않습니다. `thermal_zone_params`가 `NULL`이면 backward compatibility를 위해 hwmon interface를 생성합니다.

1.4 Thermal Zone Parameters
---------------------------

    ::

        struct thermal_zone_params

    This structure defines the platform level parameters for a thermal zone.
    This data, for each thermal zone should come from the platform layer.
    This is an optional feature where some platforms can choose not to
    provide this data.

    .governor_name:
               Name of the thermal governor used for this zone
    .no_hwmon:
               a boolean to indicate if the thermal to hwmon sysfs interface
               is required. when no_hwmon == false, a hwmon sysfs interface
               will be created. when no_hwmon == true, nothing will be done.
               In case the thermal_zone_params is NULL, the hwmon interface
               will be created (for backward compatibility).

Thermal zone과 cooling device sysfs tree

속성 권한 표기에서 `RO`는 read-only, `WO`는 write-only, `RW`는 read/write입니다. Thermal sysfs attribute는 `/sys/class/thermal` 아래에 있고, hwmon이 built-in 또는 module로 compile되면 `/sys/class/hwmon`에도 확장 interface가 있습니다.

등록된 thermal zone에는 type, current temperature, mode, policy, available policy와 각 trip point의 temperature·type·hysteresis가 생성됩니다. `emul_temp`는 emulated temperature 설정 node입니다.

Power allocator 관련 `sustainable_power`, `k_po`, `k_pu`, `k_i`, `k_d`, `integral_cutoff`와 linear extrapolation용 `slope`, `offset`도 thermal zone attribute로 제공됩니다.

등록된 cooling device에는 type, maximum/current state와 statistics directory가 있습니다. Statistics는 reset, state별 체류 시간(ms), total transition count, transition table을 제공합니다.

2. sysfs attributes structure
=============================

==        ================
RO        read only value
WO        write only value
RW        read/write value
==        ================

Thermal sysfs attributes will be represented under /sys/class/thermal.
Hwmon sysfs I/F extension is also available under /sys/class/hwmon
if hwmon is compiled in or built as a module.

Thermal zone device sys I/F, created once it's registered::

  /sys/class/thermal/thermal_zone[0-*]:
    |---type:                        Type of the thermal zone
    |---temp:                        Current temperature
    |---mode:                        Working mode of the thermal zone
    |---policy:                        Thermal governor used for this zone
    |---available_policies:        Available thermal governors for this zone
    |---trip_point_[0-*]_temp:        Trip point temperature
    |---trip_point_[0-*]_type:        Trip point type
    |---trip_point_[0-*]_hyst:        Hysteresis value for this trip point
    |---emul_temp:                Emulated temperature set node
    |---sustainable_power:      Sustainable dissipatable power
    |---k_po:                   Proportional term during temperature overshoot
    |---k_pu:                   Proportional term during temperature undershoot
    |---k_i:                    PID's integral term in the power allocator gov
    |---k_d:                    PID's derivative term in the power allocator
    |---integral_cutoff:        Offset above which errors are accumulated
    |---slope:                  Slope constant applied as linear extrapolation
    |---offset:                 Offset constant applied as linear extrapolation

Thermal cooling device sys I/F, created once it's registered::

  /sys/class/thermal/cooling_device[0-*]:
    |---type:                        Type of the cooling device(processor/fan/...)
    |---max_state:                Maximum cooling state of the cooling device
    |---cur_state:                Current cooling state of the cooling device
    |---stats:                        Directory containing cooling device's statistics
    |---stats/reset:                Writing any value resets the statistics
    |---stats/time_in_state_ms:        Time (msec) spent in various cooling states
    |---stats/total_trans:        Total number of times cooling state is changed
    |---stats/trans_table:        Cooling state transition table

Zone·cooling 관계와 hwmon interface

두 dynamic attribute는 pair로 생성·제거되며 thermal zone과 연결된 cooling device의 관계를 표현합니다. `cdev[0-*]`는 현재 zone의 cooling device, `cdev[0-*]_trip_point`는 연결된 trip point, `cdev[0-*]_weight`는 이 zone에서의 영향도입니다.

Generic thermal driver는 thermal zone device 및 cooling device sysfs 외에도 thermal zone device의 각 `_type_`별 hwmon interface를 만듭니다. 예를 들어 등록된 모든 ACPI thermal zone을 위해 hwmon class device 하나와 관련 sysfs interface를 구성합니다.

Hwmon tree의 `name`은 thermal zone type, `temp[1-*]_input`은 current temperature, `temp[1-*]_critical`은 critical trip point입니다. 자세한 thermal attribute는 `Documentation/ABI/testing/sysfs-class-thermal`, hwmon 정보는 `Documentation/hwmon/sysfs-interface.rst`를 참조합니다.

Then next two dynamic attributes are created/removed in pairs. They represent
the relationship between a thermal zone and its associated cooling device.

::

  /sys/class/thermal/thermal_zone[0-*]:
    |---cdev[0-*]:                [0-*]th cooling device in current thermal zone
    |---cdev[0-*]_trip_point:        Trip point that cdev[0-*] is associated with
    |---cdev[0-*]_weight:       Influence of the cooling device in
                                this thermal zone

Besides the thermal zone device sysfs I/F and cooling device sysfs I/F,
the generic thermal driver also creates a hwmon sysfs I/F for each _type_
of thermal zone device. E.g. the generic thermal driver registers one hwmon
class device and build the associated hwmon sysfs I/F for all the registered
ACPI thermal zones.

Please read Documentation/ABI/testing/sysfs-class-thermal for thermal
zone and cooling device attribute details.

::

  /sys/class/hwmon/hwmon[0-*]:
    |---name:                        The type of the thermal zone devices
    |---temp[1-*]_input:        The current temperature of thermal zone [1-*]
    |---temp[1-*]_critical:        The critical trip point of thermal zone [1-*]

Please read Documentation/hwmon/sysfs-interface.rst for additional information.

ACPI thermal zone 구현 예

ACPI thermal zone은 critical, hot, passive, active 같은 여러 trip point를 지원할 수 있습니다. 예제 zone은 critical, passive, active[0], active[1]을 지원해 4개 trip point의 `thermal_zone1`로 등록됩니다.

Processor 하나와 fan 하나가 각각 `thermal_cooling_device`로 등록되며 zone 냉각 효과는 동일하다고 간주합니다. Processor가 `_PSL` method에, fan이 `_AL0` method에 나열된 구성입니다.

예제 `thermal_zone1`은 `acpitz`, 37000 milli degree, enabled, `step_wise` policy입니다. Critical 100000, passive 80000, active0 70000, active1 60000의 trip point를 가집니다.

`cdev0` processor는 passive trip point 1에 weight 1024로 연결되고, `cdev1` fan은 active[0] trip point 2에 weight 1024로 연결됩니다. Processor maximum state는 8, fan maximum state는 2이며 둘의 current state는 0입니다.

같은 zone은 `/sys/class/hwmon/hwmon0`에서 name `acpitz`, `temp1_input` 37000, `temp1_crit` 100000으로 나타납니다.

3. A simple implementation
==========================

ACPI thermal zone may support multiple trip points like critical, hot,
passive, active. If an ACPI thermal zone supports critical, passive,
active[0] and active[1] at the same time, it may register itself as a
thermal_zone_device (thermal_zone1) with 4 trip points in all.
It has one processor and one fan, which are both registered as
thermal_cooling_device. Both are considered to have the same
effectiveness in cooling the thermal zone.

If the processor is listed in _PSL method, and the fan is listed in _AL0
method, the sys I/F structure will be built like this::

 /sys/class/thermal:
  |thermal_zone1:
    |---type:                        acpitz
    |---temp:                        37000
    |---mode:                        enabled
    |---policy:                        step_wise
    |---available_policies:        step_wise fair_share
    |---trip_point_0_temp:        100000
    |---trip_point_0_type:        critical
    |---trip_point_1_temp:        80000
    |---trip_point_1_type:        passive
    |---trip_point_2_temp:        70000
    |---trip_point_2_type:        active0
    |---trip_point_3_temp:        60000
    |---trip_point_3_type:        active1
    |---cdev0:                        --->/sys/class/thermal/cooling_device0
    |---cdev0_trip_point:        1        /* cdev0 can be used for passive */
    |---cdev0_weight:           1024
    |---cdev1:                        --->/sys/class/thermal/cooling_device3
    |---cdev1_trip_point:        2        /* cdev1 can be used for active[0]*/
    |---cdev1_weight:           1024

  |cooling_device0:
    |---type:                        Processor
    |---max_state:                8
    |---cur_state:                0

  |cooling_device3:
    |---type:                        Fan
    |---max_state:                2
    |---cur_state:                0

 /sys/class/hwmon:
  |hwmon0:
    |---name:                        acpitz
    |---temp1_input:                37000
    |---temp1_crit:                100000

Export Symbol API

`get_tz_trend`는 thermal zone temperature의 변화율인 trend를 반환합니다. 이상적으로 thermal sensor driver가 callback을 구현해야 하지만, 구현하지 않으면 thermal framework가 previous와 current temperature를 비교해 trend를 계산합니다.

`thermal_cdev_update`는 cooling device state를 설정하는 arbitrator입니다. 가능하면 cooling device를 가장 깊은 cooling state로 설정합니다.

4. Export Symbol APIs
=====================

4.1. get_tz_trend
-----------------

This function returns the trend of a thermal zone, i.e the rate of change
of temperature of the thermal zone. Ideally, the thermal sensor drivers
are supposed to implement the callback. If they don't, the thermal
framework calculated the trend by comparing the previous and the current
temperature values.

4.2. thermal_cdev_update
------------------------

This function serves as an arbitrator to set the state of a cooling
device. It sets the cooling device to the deepest cooling state if
possible.

Critical event와 emergency action

Critical trip temperature를 넘으면 thermal framework는 configuration에 따라 hardware protection power-off(shutdown) 또는 reboot를 trigger합니다.

Kernel은 먼저 orderly power-off 또는 reboot를 시도하고, 설정된 delay 후 각각 forced power-off 또는 reboot를 수행합니다. 이것도 실패하면 최후 수단으로 `emergency_restart()`를 호출합니다.

Delay는 orderly action에 충분한 시간을 주도록 신중하게 측정해야 합니다. Delay가 0이면 emergency action이 지원되지 않으므로, emergency action을 trigger하려면 검증한 0보다 큰 값을 반드시 설정해야 합니다.

5. Critical Events
==================

On an event of critical trip temperature crossing, the thermal framework
will trigger a hardware protection power-off (shutdown) or reboot,
depending on configuration.

At first, the kernel will attempt an orderly power-off or reboot, but
accepts a delay after which it proceeds to do a forced power-off or
reboot, respectively. If this fails, ``emergency_restart()`` is invoked
as last resort.

The delay should be carefully profiled so as to give adequate time for
orderly power-off or reboot.

If the delay is set to 0, the emergency action will not be supported. So a
carefully profiled non-zero positive value is a must for the emergency
action to be triggered.