Kernel driver ina2xx

INA2xx 계열 지원 칩

`ina2xx` 드라이버는 Texas Instruments INA219, INA220, INA226, INA230, INA231, INA260과 Silergy SY24655를 지원합니다. 모든 칩은 I2C 주소 `0x40`부터 `0x4f`를 사용합니다. 접두사는 각각 `ina219`, `ina220`, `ina226`, `ina230`, `ina231`, `ina260`, `sy24655`입니다.

TI 칩의 데이터시트는 `https://www.ti.com/`, SY24655 데이터시트는 `https://us1.silergy.com/`에서 공개됩니다. 문서에 기재된 작성자는 Lothar Felten입니다.

Kernel driver ina2xx
====================

Supported chips:

  * Texas Instruments INA219


    Prefix: 'ina219'
    Addresses: I2C 0x40 - 0x4f

    Datasheet: Publicly available at the Texas Instruments website

               https://www.ti.com/

  * Texas Instruments INA220

    Prefix: 'ina220'

    Addresses: I2C 0x40 - 0x4f

    Datasheet: Publicly available at the Texas Instruments website

               https://www.ti.com/

  * Texas Instruments INA226

    Prefix: 'ina226'

    Addresses: I2C 0x40 - 0x4f

    Datasheet: Publicly available at the Texas Instruments website

               https://www.ti.com/

  * Texas Instruments INA230

    Prefix: 'ina230'

    Addresses: I2C 0x40 - 0x4f

    Datasheet: Publicly available at the Texas Instruments website

               https://www.ti.com/

  * Texas Instruments INA231

    Prefix: 'ina231'

    Addresses: I2C 0x40 - 0x4f

    Datasheet: Publicly available at the Texas Instruments website

               https://www.ti.com/

  * Texas Instruments INA260

    Prefix: 'ina260'

    Addresses: I2C 0x40 - 0x4f

    Datasheet: Publicly available at the Texas Instruments website

               https://www.ti.com/

  * Silergy SY24655

    Prefix: 'sy24655'

    Addresses: I2C 0x40 - 0x4f

    Datasheet: Publicly available at the Silergy website

               https://us1.silergy.com/


Author: Lothar Felten <lothar.felten@gmail.com>

계열별 측정 기능과 shunt 설정

INA219는 I2C 기반 high-side 전류 shunt·전력 모니터이며 shunt 전압 강하와 전원 전압을 감시하고 변환 시간과 필터링을 프로그래밍할 수 있습니다. INA220은 high-side 또는 low-side에서 shunt 강하와 전원 전압을 감시합니다.

INA226은 I2C 전류 shunt·전력 모니터로 shunt 전압 강하와 bus 전원 전압을 감시합니다. INA230과 INA231도 high-side 또는 low-side에서 같은 두 전압을 감시합니다. INA260은 shunt 저항을 내장한 high-side 또는 low-side 전류·전력 모니터입니다.

SY24655는 I2C 기반 high-side·low-side 전류 shunt·전력 모니터입니다. Shunt 강하와 전원 전압을 지원하고 보정값과 변환 시간을 프로그래밍할 수 있으며, 에너지 변환에 사용할 평균 전력도 계산합니다.

Micro-ohms 단위 shunt 값은 컴파일 시 플랫폼 데이터나 장치 트리로 설정하거나, 실행 중 sysfs의 `shunt_resistor` 속성으로 설정할 수 있습니다. 장치 트리 binding은 `Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml`에 있습니다.

INA226은 `Documentation/hwmon/sysfs-interface.rst`의 `update_interval`도 지원합니다. 내부 interval은 bus 전압 변환 시간과 shunt 전압 변환 시간의 합에 평균 횟수를 곱한 값입니다. 드라이버는 변환 시간은 건드리지 않고 평균 횟수만 바꿉니다. 범위는 2ms부터 2253ms이며 실제 설정값은 요청값과 다를 수 있습니다.

Description
-----------

The INA219 is a high-side current shunt and power monitor with an I2C
interface. The INA219 monitors both shunt drop and supply voltage, with
programmable conversion times and filtering.

The INA220 is a high or low side current shunt and power monitor with an I2C
interface. The INA220 monitors both shunt drop and supply voltage.

The INA226 is a current shunt and power monitor with an I2C interface.
The INA226 monitors both a shunt voltage drop and bus supply voltage.

INA230 and INA231 are high or low side current shunt and power monitors
with an I2C interface. The chips monitor both a shunt voltage drop and
bus supply voltage.

INA260 is a high or low side current and power monitor with integrated shunt
resistor.

The SY24655 is a high- and low-side current shunt and power monitor with an I2C
interface. The SY24655 supports both shunt drop and supply voltage, with
programmable calibration value and conversion times. The SY24655 can also
calculate average power for use in energy conversion.

The shunt value in micro-ohms can be set via platform data or device tree at
compile-time or via the shunt_resistor attribute in sysfs at run-time. Please
refer to the Documentation/devicetree/bindings/hwmon/ti,ina2xx.yaml for bindings
if the device tree is used.

Additionally ina226 supports update_interval attribute as described in
Documentation/hwmon/sysfs-interface.rst. Internally the interval is the sum of
bus and shunt voltage conversion times multiplied by the averaging rate. We
don't touch the conversion times and only modify the number of averages. The
lower limit of the update_interval is 2 ms, the upper limit is 2253 ms.
The actual programmed interval may vary from the desired value.

공통·추가 sysfs 속성

모든 지원 칩의 공통 속성은 mV 단위 shunt 전압 `in0_input`, mV 단위 bus 전압 `in1_input`, mA 단위 전류 `curr1_input`, uW 단위 전력 `power1_input`입니다. `shunt_resistor`는 uOhm 단위 shunt 저항이며 shunt가 내장된 INA260에서는 제공하지 않습니다.

INA226, INA230, INA231, INA260, SY24655에는 임계 하한·상한 전류와 경보, 임계 하한·상한 shunt 전압과 경보, 임계 하한·상한 bus 전압과 경보, 임계 상한 전력과 경보가 추가됩니다. `update_interval`은 shunt와 bus 전압 결과를 평균하는 샘플 수에 영향을 주는 데이터 변환 시간입니다.

General sysfs entries
---------------------

======================= ===============================================
in0_input                Shunt voltage(mV) channel
in1_input                Bus voltage(mV) channel
curr1_input                Current(mA) measurement channel
power1_input                Power(uW) measurement channel
shunt_resistor                Shunt resistance(uOhm) channel (not for ina260)
======================= ===============================================

Additional sysfs entries for ina226, ina230, ina231, ina260, and sy24655
------------------------------------------------------------------------

======================= ====================================================
curr1_lcrit                Critical low current
curr1_crit                Critical high current
curr1_lcrit_alarm        Current critical low alarm
curr1_crit_alarm        Current critical high alarm
in0_lcrit                Critical low shunt voltage
in0_crit                Critical high shunt voltage
in0_lcrit_alarm                Shunt voltage critical low alarm
in0_crit_alarm                Shunt voltage critical high alarm
in1_lcrit                Critical low bus voltage
in1_crit                Critical high bus voltage
in1_lcrit_alarm                Bus voltage critical low alarm
in1_crit_alarm                Bus voltage critical high alarm
power1_crit                Critical high power
power1_crit_alarm        Power critical high alarm
update_interval                data conversion time; affects number of samples used
                        to average results for shunt and bus voltages.
======================= ====================================================

SY24655 평균 전력과 임계 설정 제약

SY24655 전용 `power1_average`는 직전 읽기 시점부터 현재까지의 평균 전력을 제공합니다.

`power1_crit`는 설정된 `shunt_resistor`를 바탕으로 계산되므로 `power1_crit`보다 먼저 `shunt_resistor`를 구성해야 합니다.

하위 레지스터 구현 제약 때문에 한 번에 하나의 `*crit` 설정과 그 경보만 활성화할 수 있습니다. 하나의 `*crit`에 값을 쓰면 다른 모든 `*crit` 설정과 경보가 지워지고, 어느 `*crit`에든 0을 쓰면 모든 임계 설정과 경보가 지워집니다.

Sysfs entries for sy24655 only
------------------------------

======================= ====================================================
power1_average                average power from last reading to the present.
======================= ====================================================

.. note::

   - Configure `shunt_resistor` before configure `power1_crit`, because power
     value is calculated based on `shunt_resistor` set.
   - Because of the underlying register implementation, only one `*crit` setting
     and its `alarm` can be active. Writing to one `*crit` setting clears other
     `*crit` settings and alarms. Writing 0 to any `*crit` setting clears all
     `*crit` settings and alarms.