The Linux Hardware Monitoring kernel API

Linux hwmon 커널 API 개요와 선언

Guenter Roeck가 작성한 이 문서는 하드웨어 모니터링 프레임워크를 사용하는 hwmon 드라이버용 커널 API를 설명합니다. hwmon 드라이버나 장치의 개념, 사용자 공간이 장치와 통신하는 인터페이스는 이 문서의 범위가 아닙니다. 그 내용은 `Documentation/hwmon/sysfs-interface.rst`를, 드라이버 작성과 개선 지침은 `Documentation/hwmon/submitting-patches.rst`를 읽어야 합니다.

모든 하드웨어 모니터링 드라이버는 `<linux/hwmon.h>`를 포함해야 하며, 경우에 따라 `<linux/hwmon-sysfs.h>`도 포함합니다. `linux/hwmon.h`는 `hwmon_device_register_with_info()`, 장치 관리형인 `devm_hwmon_device_register_with_info()`, `hwmon_device_unregister()`를 선언합니다.

같은 헤더는 이름을 정규화하는 `hwmon_sanitize_name()`과 `devm_hwmon_sanitize_name()`, hwmon 코어의 직렬화 잠금을 공유하는 `hwmon_lock()`과 `hwmon_unlock()`도 선언합니다. 각 함수의 원형, 인수 타입, `const` 한정자, 반환 타입은 아래 원문 코드 블록과 동일하게 보존됩니다.

The Linux Hardware Monitoring kernel API
========================================

Guenter Roeck

Introduction
------------

This document describes the API that can be used by hardware monitoring
drivers that want to use the hardware monitoring framework.

This document does not describe what a hardware monitoring (hwmon) Driver or
Device is. It also does not describe the API which can be used by user space
to communicate with a hardware monitoring device. If you want to know this
then please read the following file: Documentation/hwmon/sysfs-interface.rst.

For additional guidelines on how to write and improve hwmon drivers, please
also read Documentation/hwmon/submitting-patches.rst.

The API
-------
Each hardware monitoring driver must #include <linux/hwmon.h> and, in some
cases, <linux/hwmon-sysfs.h>. linux/hwmon.h declares the following
register/unregister functions::

  struct device *
  hwmon_device_register_with_info(struct device *dev,
                                  const char *name, void *drvdata,
                                  const struct hwmon_chip_info *info,
                                  const struct attribute_group **extra_groups);

  struct device *
  devm_hwmon_device_register_with_info(struct device *dev,
                                       const char *name,
                                       void *drvdata,
                                       const struct hwmon_chip_info *info,
                                       const struct attribute_group **extra_groups);

  void hwmon_device_unregister(struct device *dev);

  char *hwmon_sanitize_name(const char *name);

  char *devm_hwmon_sanitize_name(struct device *dev, const char *name);

  void hwmon_lock(struct device *dev);
  void hwmon_unlock(struct device *dev);

장치 등록, 이름, 잠금의 수명 주기

`hwmon_device_register_with_info()`는 하드웨어 모니터링 장치를 등록하고 hwmon 코어 안에 표준 sysfs 속성을 만듭니다. 덕분에 드라이버는 sysfs 속성 구현보다 칩에서 값을 읽고 쓰는 일에 집중할 수 있습니다. 부모 장치 인수와 칩 정보 인수는 `NULL`이면 안 됩니다.

`devm_hwmon_device_register_with_info()`는 같은 등록 작업을 장치 관리형으로 수행하므로 드라이버의 제거 함수가 hwmon 장치를 직접 제거할 필요가 없습니다. 그 밖의 hwmon 장치 등록 함수는 모두 폐기 예정이므로 새 드라이버에서 사용하면 안 됩니다.

수동 등록 함수를 사용했다면 드라이버 제거 함수에서 `hwmon_device_unregister()`를 호출해야 합니다. 이 함수에는 등록 과정에서 반환된 하드웨어 모니터링 장치 구조체 포인터를 넘깁니다.

지원되는 등록 함수는 유효한 장치 이름만 허용합니다. 공백, `*`, `-`가 들어간 이름은 거부됩니다. 이름 인수로 `NULL`을 전달하면 부모 장치 이름에서 hwmon 장치 이름을 만듭니다. `dev_name()`처럼 정적 이름을 쓰지 않아 문자를 보장할 수 없다면 `hwmon_sanitize_name()`으로 문자열을 복제하고 잘못된 문자를 밑줄로 바꿀 수 있습니다. 이때 생긴 메모리는 호출자가 장치 제거 시 해제해야 합니다. `devm_hwmon_sanitize_name()`은 그 메모리를 자동으로 해제하는 장치 관리형 버전입니다.

`[devm_]hwmon_device_register_with_info()`와 연결된 접근 함수는 hwmon 코어가 직렬화합니다. 인터럽트 처리기나 드라이버가 완전히 구현한 별도 속성처럼 다른 경로에도 같은 직렬화가 필요하면 `hwmon_lock()`과 `hwmon_unlock()`으로 해당 호출들을 보호할 수 있습니다.

hwmon_device_register_with_info registers a hardware monitoring device.
It creates the standard sysfs attributes in the hardware monitoring core,
letting the driver focus on reading from and writing to the chip instead
of having to bother with sysfs attributes. The parent device parameter
as well as the chip parameter must not be NULL. Its parameters are described
in more detail below.

devm_hwmon_device_register_with_info is similar to
hwmon_device_register_with_info. However, it is device managed, meaning the
hwmon device does not have to be removed explicitly by the removal function.

All other hardware monitoring device registration functions are deprecated
and must not be used in new drivers.

hwmon_device_unregister deregisters a registered hardware monitoring device.
The parameter of this function is the pointer to the registered hardware
monitoring device structure. This function must be called from the driver
remove function if the hardware monitoring device was registered with
hwmon_device_register_with_info.

All supported hwmon device registration functions only accept valid device
names. Device names including invalid characters (whitespace, '*', or '-')
will be rejected. If NULL is passed as name parameter, the hardware monitoring
device name will be derived from the parent device name.

If the driver doesn't use a static device name (for example it uses
dev_name()), and therefore cannot make sure the name only contains valid
characters, hwmon_sanitize_name can be used. This convenience function
will duplicate the string and replace any invalid characters with an
underscore. It will allocate memory for the new string and it is the
responsibility of the caller to release the memory when the device is
removed.

devm_hwmon_sanitize_name is the resource managed version of
hwmon_sanitize_name; the memory will be freed automatically on device
removal.

When using ``[devm_]hwmon_device_register_with_info()`` to register the
hardware monitoring device, accesses using the associated access functions
are serialised by the hardware monitoring core. If a driver needs locking
for other functions such as interrupt handlers or for attributes which are
fully implemented in the driver, hwmon_lock() and hwmon_unlock() can be used
to ensure that calls to those functions are serialized.

등록 인수와 hwmon_chip_info 연산

`hwmon_device_register_with_info()`에 전달하는 인수는 부모 장치 포인터 `dev`, 장치 이름 `name`, 드라이버 전용 데이터 `drvdata`, 칩 설명 `info`, 그리고 비표준 sysfs 속성 그룹의 `NULL` 종료 목록 `extra_groups`입니다. 성공하면 생성된 hwmon 장치 포인터를 반환하고, 실패하면 음수 오류 코드를 반환합니다.

`struct hwmon_chip_info`는 장치 연산을 가리키는 `ops`와 장치 채널 설명자의 `NULL` 종료 목록을 가리키는 `info`로 구성됩니다. 이 두 필드가 드라이버의 동작 계약과 센서 구성을 코어에 연결합니다.

`struct hwmon_ops`의 `is_visible` 콜백은 지원하는 각 속성의 파일 모드를 반환하며 필수입니다. `read`는 칩에서 값을 읽는 선택 콜백이지만 읽을 수 있는 속성이 하나라도 있으면 반드시 제공해야 합니다. `write`도 선택 콜백이지만 쓸 수 있는 속성이 존재하면 반드시 제공해야 합니다.

Using devm_hwmon_device_register_with_info()
--------------------------------------------

hwmon_device_register_with_info() registers a hardware monitoring device.
The parameters to this function are

=============================================== ===============================================
`struct device *dev`                                Pointer to parent device
`const char *name`                                Device name
`void *drvdata`                                        Driver private data
`const struct hwmon_chip_info *info`                Pointer to chip description.
`const struct attribute_group **extra_groups`         Null-terminated list of additional non-standard
                                                sysfs attribute groups.
=============================================== ===============================================

This function returns a pointer to the created hardware monitoring device
on success and a negative error code for failure.

The hwmon_chip_info structure looks as follows::

        struct hwmon_chip_info {
                const struct hwmon_ops *ops;
                const struct hwmon_channel_info * const *info;
        };

It contains the following fields:

* ops:
        Pointer to device operations.
* info:
        NULL-terminated list of device channel descriptors.

The list of hwmon operations is defined as::

  struct hwmon_ops {
        umode_t (*is_visible)(const void *, enum hwmon_sensor_types type,
                              u32 attr, int);
        int (*read)(struct device *, enum hwmon_sensor_types type,
                    u32 attr, int, long *);
        int (*write)(struct device *, enum hwmon_sensor_types type,
                     u32 attr, int, long);
  };

It defines the following operations.

* is_visible:
    Pointer to a function to return the file mode for each supported
    attribute. This function is mandatory.

* read:
    Pointer to a function for reading a value from the chip. This function
    is optional, but must be provided if any readable attributes exist.

* write:
    Pointer to a function for writing a value to the chip. This function is
    optional, but must be provided if any writeable attributes exist.

센서 채널 형식과 구성 비트

각 센서 채널은 `struct hwmon_channel_info`로 설명합니다. `type`은 하드웨어 모니터링 센서 형식이고, `config`는 해당 형식의 각 센서가 지원하는 속성을 나타내는 구성값의 포인터입니다.

지원 형식에는 특정 입출력에 묶이지 않은 칩 속성을 위한 가상 형식 `hwmon_chip`, 온도 `hwmon_temp`, 전압 `hwmon_in`, 전류 `hwmon_curr`, 전력 `hwmon_power`, 에너지 `hwmon_energy`, 64비트 부호 있는 값으로 보고하는 에너지 `hwmon_energy64`, 습도 `hwmon_humidity`, 팬 속도 `hwmon_fan`, PWM 제어 `hwmon_pwm`가 있습니다.

`config`는 주어진 형식의 센서별 구성값을 나열하고 마지막을 0으로 끝냅니다. 각 값은 단일 센서가 제공하는 속성을 나타내는 비트값들의 조합입니다. 원문에서 `attributes supposed by a single sensor`라고 적힌 부분은 문맥상 단일 센서가 지원하도록 지정된 속성을 뜻합니다.

Each sensor channel is described with struct hwmon_channel_info, which is
defined as follows::

        struct hwmon_channel_info {
                enum hwmon_sensor_types type;
                u32 *config;
        };

It contains following fields:

* type:
    The hardware monitoring sensor type.

    Supported sensor types are

     ================== ==================================================
     hwmon_chip                A virtual sensor type, used to describe attributes
                        which are not bound to a specific input or output
     hwmon_temp                Temperature sensor
     hwmon_in                Voltage sensor
     hwmon_curr                Current sensor
     hwmon_power                Power sensor
     hwmon_energy        Energy sensor
     hwmon_energy64        Energy sensor, reported as 64-bit signed value
     hwmon_humidity        Humidity sensor
     hwmon_fan                Fan speed sensor
     hwmon_pwm                PWM control
     ================== ==================================================

* config:
    Pointer to a 0-terminated list of configuration values for each
    sensor of the given type. Each value is a combination of bit values
    describing the attributes supposed by a single sensor.

LM75 구성 예제와 속성 접두사

LM75 호환 칩은 온도 센서 하나를 가진 예제로 제시됩니다. 드라이버는 `HWMON_C_REGISTER_TZ`로 thermal 하위 시스템에 등록하고 `HWMON_C_UPDATE_INTERVAL` 속성을 지원합니다. 온도 센서는 `HWMON_T_INPUT`으로 현재 온도를 읽고, `HWMON_T_MAX` 최대 온도 레지스터와 `HWMON_T_MAX_HYST` 최대 온도 히스테리시스 레지스터를 제공합니다.

긴 형식에서는 `lm75_chip_config`와 `lm75_temp_config`를 각각 0으로 끝내고, 이를 `hwmon_chip` 및 `hwmon_temp` 형식의 `struct hwmon_channel_info`에 연결합니다. `lm75_info`는 두 채널 설명자 포인터 뒤에 `NULL`을 둡니다.

가능하면 `HWMON_CHANNEL_INFO()` 매크로를 사용해야 합니다. 이 매크로는 별도의 구성 배열과 채널 구조체를 간결한 채널 선언으로 바꿉니다. 이후 `lm75_hwmon_ops`에 `lm75_is_visible`, `lm75_read`, `lm75_write`를 연결하고, `lm75_chip_info`에 연산과 채널 목록을 지정합니다.

개별 속성 지원 비트의 전체 목록은 `include/linux/hwmon.h`에 있습니다. 칩과 전류 속성이 모두 `HWMON_C_xxxx` 접두사를 사용하므로 형식 문맥을 구분해야 합니다. 나머지는 온도 `HWMON_T_xxxx`, 전압 `HWMON_I_xxxx`, 전력 `HWMON_P_xxxx`, 에너지 `HWMON_E_xxxx`, 습도 `HWMON_H_xxxx`, 팬 `HWMON_F_xxxx`, PWM `HWMON_PWM_xxxx`입니다.

As an example, here is the complete description file for a LM75 compatible
sensor chip. The chip has a single temperature sensor. The driver wants to
register with the thermal subsystem (HWMON_C_REGISTER_TZ), and it supports
the update_interval attribute (HWMON_C_UPDATE_INTERVAL). The chip supports
reading the temperature (HWMON_T_INPUT), it has a maximum temperature
register (HWMON_T_MAX) as well as a maximum temperature hysteresis register
(HWMON_T_MAX_HYST)::

        static const u32 lm75_chip_config[] = {
                HWMON_C_REGISTER_TZ | HWMON_C_UPDATE_INTERVAL,
                0
        };

        static const struct hwmon_channel_info lm75_chip = {
                .type = hwmon_chip,
                .config = lm75_chip_config,
        };

        static const u32 lm75_temp_config[] = {
                HWMON_T_INPUT | HWMON_T_MAX | HWMON_T_MAX_HYST,
                0
        };

        static const struct hwmon_channel_info lm75_temp = {
                .type = hwmon_temp,
                .config = lm75_temp_config,
        };

        static const struct hwmon_channel_info * const lm75_info[] = {
                &lm75_chip,
                &lm75_temp,
                NULL
        };

        The HWMON_CHANNEL_INFO() macro can and should be used when possible.
        With this macro, the above example can be simplified to

        static const struct hwmon_channel_info * const lm75_info[] = {
                HWMON_CHANNEL_INFO(chip,
                                HWMON_C_REGISTER_TZ | HWMON_C_UPDATE_INTERVAL),
                HWMON_CHANNEL_INFO(temp,
                                HWMON_T_INPUT | HWMON_T_MAX | HWMON_T_MAX_HYST),
                NULL
        };

        The remaining declarations are as follows.

        static const struct hwmon_ops lm75_hwmon_ops = {
                .is_visible = lm75_is_visible,
                .read = lm75_read,
                .write = lm75_write,
        };

        static const struct hwmon_chip_info lm75_chip_info = {
                .ops = &lm75_hwmon_ops,
                .info = lm75_info,
        };

A complete list of bit values indicating individual attribute support
is defined in include/linux/hwmon.h. Definition prefixes are as follows.

=============== =================================================
HWMON_C_xxxx        Chip attributes, for use with hwmon_chip.
HWMON_T_xxxx        Temperature attributes, for use with hwmon_temp.
HWMON_I_xxxx        Voltage attributes, for use with hwmon_in.
HWMON_C_xxxx        Current attributes, for use with hwmon_curr.
                Notice the prefix overlap with chip attributes.
HWMON_P_xxxx        Power attributes, for use with hwmon_power.
HWMON_E_xxxx        Energy attributes, for use with hwmon_energy.
HWMON_H_xxxx        Humidity attributes, for use with hwmon_humidity.
HWMON_F_xxxx        Fan speed attributes, for use with hwmon_fan.
HWMON_PWM_xxxx        PWM control attributes, for use with hwmon_pwm.
=============== =================================================

드라이버 콜백의 인수와 반환값

각 드라이버는 `is_visible`, `read`, `write` 함수를 제공합니다. `is_visible_func()`의 `data`는 장치 전용 데이터 구조체 포인터, `type`은 센서 형식, `attr`은 특정 속성의 식별자, `channel`은 센서 채널 번호입니다. 예를 들어 `HWMON_T_INPUT` 비트에 대응하는 속성값은 `hwmon_temp_input`이며 전체 매핑은 `include/linux/hwmon.h`에 있습니다.

`is_visible_func()`는 해당 속성의 파일 모드를 반환합니다. 일반적으로 0이면 속성을 만들지 않고, `0444`이면 읽기 전용, `0644`이면 소유자 쓰기와 전체 읽기를 허용합니다.

`read_func()`에는 hwmon 장치 포인터 `dev`, 센서 형식 `type`, 속성 식별자 `attr`, 채널 번호 `channel`, 값을 돌려줄 `long *val`을 전달합니다. `hwmon_energy64`에서는 `val`이 `long *`로 전달되지만 `s64 *`로 형변환해야 합니다. 성공 시 0, 실패 시 음수 오류 번호를 반환합니다.

`write_func()`는 같은 장치, 형식, 속성, 채널 인수와 칩에 기록할 `long val`을 받습니다. 이 함수도 성공하면 0, 실패하면 음수 오류 번호를 반환합니다.

Driver callback functions
-------------------------

Each driver provides is_visible, read, and write functions. Parameters
and return values for those functions are as follows::

  umode_t is_visible_func(const void *data, enum hwmon_sensor_types type,
                          u32 attr, int channel)

Parameters:
        data:
                Pointer to device private data structure.
        type:
                The sensor type.
        attr:
                Attribute identifier associated with a specific attribute.
                For example, the attribute value for HWMON_T_INPUT would be
                hwmon_temp_input. For complete mappings of bit fields to
                attribute values please see include/linux/hwmon.h.
        channel:
                The sensor channel number.

Return value:
        The file mode for this attribute. Typically, this will be 0 (the
        attribute will not be created), 0444, or 0644.

::

        int read_func(struct device *dev, enum hwmon_sensor_types type,
                      u32 attr, int channel, long *val)

Parameters:
        dev:
                Pointer to the hardware monitoring device.
        type:
                The sensor type.
        attr:
                Attribute identifier associated with a specific attribute.
                For example, the attribute value for HWMON_T_INPUT would be
                hwmon_temp_input. For complete mappings please see
                include/linux/hwmon.h.
        channel:
                The sensor channel number.
        val:
                Pointer to attribute value.
                For hwmon_energy64, `'val`' is passed as `long *` but needs
                a typecast to `s64 *`.

Return value:
        0 on success, a negative error number otherwise.

::

        int write_func(struct device *dev, enum hwmon_sensor_types type,
                       u32 attr, int channel, long val)

Parameters:
        dev:
                Pointer to the hardware monitoring device.
        type:
                The sensor type.
        attr:
                Attribute identifier associated with a specific attribute.
                For example, the attribute value for HWMON_T_INPUT would be
                hwmon_temp_input. For complete mappings please see
                include/linux/hwmon.h.
        channel:
                The sensor channel number.
        val:
                The value to write to the chip.

Return value:
        0 on success, a negative error number otherwise.

드라이버 제공 추가 sysfs 속성

대부분의 경우 hwmon 코어가 표준 sysfs 속성을 내부에서 만들기 때문에 드라이버가 직접 속성을 제공할 필요가 없습니다. 드라이버가 추가해야 하는 것은 비표준 sysfs 속성뿐입니다. `<linux/hwmon-sysfs.h>`는 이런 속성을 선언하고 사용하는 여러 매크로를 제공합니다.

추가 문맥이 없는 속성은 기존 `DEVICE_ATTR` 또는 `DEVICE_ATTR_{RW,RO,WO}` 변형으로 선언할 수 있습니다. 하지만 센서 인덱스처럼 sysfs 처리 함수에 넘겨야 할 정보가 있으면 `SENSOR_DEVICE_ATTR` 또는 `SENSOR_DEVICE_ATTR_2`를 사용합니다. 전자는 추가 인수 하나, 후자는 두 개를 전달합니다.

표준 권한과 함수 이름을 사용할 수 있다면 단순화된 변형을 사용해야 합니다. `SENSOR_DEVICE_ATTR[_2]_RW`의 표준 권한은 `0644`, `SENSOR_DEVICE_ATTR[_2]_RO`는 `0444`, `SENSOR_DEVICE_ATTR[_2]_WO`는 `0200`입니다. `DEVICE_ATTR_{RW,RO,WO}`와 비슷하게 제공한 함수 이름 뒤에 `_show`와 `_store`가 붙어 표준 함수 이름이 됩니다.

`SENSOR_DEVICE_ATTR` 계열은 `struct device_attribute dev_attr`과 `int index`를 가진 `struct sensor_device_attribute` 변수를 정의합니다. 속성 읽기·쓰기 함수에서 속성이 붙은 장치를 `to_sensor_dev_attr()`에 전달하면 이 구조체 포인터를 얻습니다.

`SENSOR_DEVICE_ATTR_2` 계열은 `struct device_attribute dev_attr`, `u8 index`, `u8 nr`을 가진 `struct sensor_device_attribute_2` 변수를 정의합니다. `to_sensor_dev_attr_2()`에 속성이 붙은 장치를 전달하면 이 구조체 포인터를 얻습니다.

Driver-provided sysfs attributes
--------------------------------

In most situations it should not be necessary for a driver to provide sysfs
attributes since the hardware monitoring core creates those internally.
Only additional non-standard sysfs attributes need to be provided.

The header file linux/hwmon-sysfs.h provides a number of useful macros to
declare and use hardware monitoring sysfs attributes.

In many cases, you can use the existing define DEVICE_ATTR or its variants
DEVICE_ATTR_{RW,RO,WO} to declare such attributes. This is feasible if an
attribute has no additional context. However, in many cases there will be
additional information such as a sensor index which will need to be passed
to the sysfs attribute handling function.

SENSOR_DEVICE_ATTR and SENSOR_DEVICE_ATTR_2 can be used to define attributes
which need such additional context information. SENSOR_DEVICE_ATTR requires
one additional argument, SENSOR_DEVICE_ATTR_2 requires two.

Simplified variants of SENSOR_DEVICE_ATTR and SENSOR_DEVICE_ATTR_2 are available
and should be used if standard attribute permissions and function names are
feasible. Standard permissions are 0644 for SENSOR_DEVICE_ATTR[_2]_RW,
0444 for SENSOR_DEVICE_ATTR[_2]_RO, and 0200 for SENSOR_DEVICE_ATTR[_2]_WO.
Standard functions, similar to DEVICE_ATTR_{RW,RO,WO}, have _show and _store
appended to the provided function name.

SENSOR_DEVICE_ATTR and its variants define a struct sensor_device_attribute
variable. This structure has the following fields::

        struct sensor_device_attribute {
                struct device_attribute dev_attr;
                int index;
        };

You can use to_sensor_dev_attr to get the pointer to this structure from the
attribute read or write function. Its parameter is the device to which the
attribute is attached.

SENSOR_DEVICE_ATTR_2 and its variants define a struct sensor_device_attribute_2
variable, which is defined as follows::

        struct sensor_device_attribute_2 {
                struct device_attribute dev_attr;
                u8 index;
                u8 nr;
        };

Use to_sensor_dev_attr_2 to get the pointer to this structure. Its parameter
is the device to which the attribute is attached.