.. SPDX-License-Identifier: GPL-2.0-only

Kernel drivers ltc4282
==========================================

Supported chips:

  * Analog Devices LTC4282

    Prefix: 'ltc4282'

    Addresses scanned: - I2C 0x40 - 0x5A (7-bit)
    Addresses scanned: - I2C 0x80 - 0xB4 with a step of 2 (8-bit)

    Datasheet:

        https://www.analog.com/media/en/technical-documentation/data-sheets/ltc4282.pdf

Author: Nuno Sá <nuno.sa@analog.com>

Description
___________

The LTC4282 hot swap controller allows a board to be safely inserted and removed
from a live backplane. Using one or more external N-channel pass transistors,
board supply voltage and inrush current are ramped up at an adjustable rate. An
I2C interface and onboard ADC allows for monitoring of board current, voltage,
power, energy and fault status. The device features analog foldback current
limiting and supply monitoring for applications from 2.9V to 33V. Dual 12V gate
drive allows high power applications to either share safe operating area across
parallel MOSFETs or support a 2-stage start-up that first charges the load
capacitance followed by enabling a low on-resistance path to the load. The
LTC4282 is well suited to high power applications because the precise monitoring
capability and accurate current limiting reduce the extremes in which both loads
and power supplies must safely operate. Non-volatile configuration allows for
flexibility in the autonomous generation of alerts and response to faults.

Sysfs entries
_____________

The following attributes are supported. Limits are read-write and all the other
attributes are read-only. Note that in0 and in1 are mutually exclusive. Enabling
one disables the other and disabling one enables the other.

======================= ==========================================
in0_input		Output voltage (mV).
in0_min			Undervoltage threshold
in0_max                 Overvoltage threshold
in0_lowest		Lowest measured voltage
in0_highest		Highest measured voltage
in0_reset_history	Write 1 to reset in0 history.
			Also clears fet bad and short fault logs.
in0_min_alarm		Undervoltage alarm
in0_max_alarm           Overvoltage alarm
in0_enable		Enable/Disable VSOURCE monitoring
in0_fault		Failure in the MOSFETs. Either bad or shorted FET.
in0_label		Channel label (VSOURCE)

in1_input		Input voltage (mV).
in1_min			Undervoltage threshold
in1_max                 Overvoltage threshold
in1_lowest		Lowest measured voltage
in1_highest		Highest measured voltage
in1_reset_history	Write 1 to reset in1 history.
			Also clears over/undervoltage fault logs.
in1_min_alarm		Undervoltage alarm
in1_max_alarm           Overvoltage alarm
in1_lcrit_alarm         Critical Undervoltage alarm
in1_crit_alarm          Critical Overvoltage alarm
in1_enable		Enable/Disable VDD monitoring
in1_label		Channel label (VDD)

in2_input		GPIO voltage (mV)
in2_min			Undervoltage threshold
in2_max			Overvoltage threshold
in2_lowest		Lowest measured voltage
in2_highest		Highest measured voltage
in2_reset_history	Write 1 to reset in2 history
in2_min_alarm		Undervoltage alarm
in2_max_alarm		Overvoltage alarm
in2_label		Channel label (VGPIO)

curr1_input		Sense current (mA)
curr1_min		Undercurrent threshold
curr1_max		Overcurrent threshold
curr1_lowest		Lowest measured current
curr1_highest		Highest measured current
curr1_reset_history	Write 1 to reset curr1 history.
			Also clears overcurrent fault logs.
curr1_min_alarm		Undercurrent alarm
curr1_max_alarm		Overcurrent alarm
curr1_crit_alarm        Critical Overcurrent alarm
curr1_label		Channel label (ISENSE)

power1_input		Power (in uW)
power1_min		Low power threshold
power1_max		High power threshold
power1_input_lowest	Historical minimum power use
power1_input_highest	Historical maximum power use
power1_reset_history	Write 1 to reset power1 history.
			Also clears power bad fault logs.
power1_min_alarm	Low power alarm
power1_max_alarm	High power alarm
power1_label		Channel label (Power)

energy1_input		Measured energy over time (in microJoule)
energy1_enable		Enable/Disable Energy accumulation
======================= ==========================================

DebugFs entries
_______________

The chip also has a fault log register where failures can be logged. Hence,
as these are logging events, we give access to them in debugfs. Note that
even if some failure is detected in these logs, it does necessarily mean
that the failure is still present. As mentioned in the proper Sysfs entries,
these logs can be cleared by writing in the proper reset_history attribute.

.. warning:: The debugfs interface is subject to change without notice
             and is only available when the kernel is compiled with
             ``CONFIG_DEBUG_FS`` defined.

``/sys/kernel/debug/ltc4282-hwmon[X]/``
contains the following attributes:

=======================  ==========================================
power1_bad_fault_log     Set to 1 by a power1 bad fault occurring.
in0_fet_short_fault_log	 Set to 1 when the ADC detects a FET-short fault.
in0_fet_bad_fault_log    Set to 1 when a FET-BAD fault occurs.
in1_crit_fault_log       Set to 1 by a VDD overvoltage fault occurring.
in1_lcrit_fault_log      Set to 1 by a VDD undervoltage fault occurring.
curr1_crit_fault_log	 Set to 1 by an overcurrent fault occurring.
=======================  ==========================================