code:
Kernel driver max6642
=====================

Supported chips:

  * Maxim MAX6642

    Prefix: 'max6642'

    Addresses scanned: I2C 0x48-0x4f

    Datasheet: Publicly available at the Maxim website

	       http://datasheets.maxim-ic.com/en/ds/MAX6642.pdf

Authors:

	Per Dalen <per.dalen@appeartv.com>

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

The MAX6642 is a digital temperature sensor. It senses its own temperature as
well as the temperature on one external diode.

All temperature values are given in degrees Celsius. Resolution
is 0.25 degree for the local temperature and for the remote temperature.


code:
Kernel driver max6650
=====================

Supported chips:

  * Maxim MAX6650

    Prefix: 'max6650'

    Addresses scanned: none

    Datasheet: http://pdfserv.maxim-ic.com/en/ds/MAX6650-MAX6651.pdf

  * Maxim MAX6651

    Prefix: 'max6651'

    Addresses scanned: none

    Datasheet: http://pdfserv.maxim-ic.com/en/ds/MAX6650-MAX6651.pdf

Authors:
    - Hans J. Koch <hjk@hansjkoch.de>
    - John Morris <john.morris@spirentcom.com>
    - Claus Gindhart <claus.gindhart@kontron.com>

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

This driver implements support for the Maxim MAX6650 and MAX6651.

The 2 devices are very similar, but the MAX6550 has a reduced feature
set, e.g. only one fan-input, instead of 4 for the MAX6651.

The driver is not able to distinguish between the 2 devices.

The driver provides the following sensor accesses in sysfs:

=============== ======= =======================================================
fan1_input	ro	fan tachometer speed in RPM
fan2_input	ro	"
fan3_input	ro	"
fan4_input	ro	"
fan1_target	rw	desired fan speed in RPM (closed loop mode only)
pwm1_enable	rw	regulator mode, 0=full on, 1=open loop, 2=closed loop
			3=off
pwm1		rw	relative speed (0-255), 255=max. speed.
			Used in open loop mode only.
fan1_div	rw	sets the speed range the inputs can handle. Legal
			values are 1, 2, 4, and 8. Use lower values for
			faster fans.
=============== ======= =======================================================

Usage notes
-----------

This driver does not auto-detect devices. You will have to instantiate the
devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.

Module parameters
-----------------

If your board has a BIOS that initializes the MAX6650/6651 correctly, you can
simply load your module without parameters. It won't touch the configuration
registers then. If your board BIOS doesn't initialize the chip, or you want
different settings, you can set the following parameters:

voltage_12V: 5=5V fan, 12=12V fan, 0=don't change
prescaler: Possible values are 1,2,4,8,16, or 0 for don't change
clock: The clock frequency in Hz of the chip the driver should assume [254000]

Please have a look at the MAX6650/6651 data sheet and make sure that you fully
understand the meaning of these parameters before you attempt to change them.

repo_name: angery/linux


code:
Kernel driver max6697
=====================

Supported chips:

  * Maxim MAX6581

    Prefix: 'max6581'

    Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6581.pdf

  * Maxim MAX6602

    Prefix: 'max6602'

    Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6602.pdf

  * Maxim MAX6622

    Prefix: 'max6622'

    Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6622.pdf

  * Maxim MAX6636

    Prefix: 'max6636'

    Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6636.pdf

  * Maxim MAX6689

    Prefix: 'max6689'

    Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6689.pdf

  * Maxim MAX6693

    Prefix: 'max6693'

    Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6693.pdf

  * Maxim MAX6694

    Prefix: 'max6694'

    Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6694.pdf

  * Maxim MAX6697

    Prefix: 'max6697'

    Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6697.pdf

  * Maxim MAX6698

    Prefix: 'max6698'

    Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6698.pdf

  * Maxim MAX6699

    Prefix: 'max6699'

    Datasheet: http://datasheets.maximintegrated.com/en/ds/MAX6699.pdf

Author:

    Guenter Roeck <linux@roeck-us.net>

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

This driver implements support for several MAX6697 compatible temperature sensor
chips. The chips support one local temperature sensor plus four, six, or seven
remote temperature sensors. Remote temperature sensors are diode-connected
thermal transitors, except for MAX6698 which supports three diode-connected
thermal transistors plus three thermistors in addition to the local temperature
sensor.

The driver provides the following sysfs attributes. temp1 is the local (chip)
temperature, temp[2..n] are remote temperatures. The actually supported
per-channel attributes are chip type and channel dependent.

================ == ==========================================================
tempX_input      RO temperature
tempX_max        RW temperature maximum threshold
tempX_max_alarm  RO temperature maximum threshold alarm
tempX_crit       RW temperature critical threshold
tempX_crit_alarm RO temperature critical threshold alarm
tempX_fault      RO temperature diode fault (remote sensors only)
================ == ==========================================================


code:
Kernel driver max8688
=====================

Supported chips:

  * Maxim MAX8688

    Prefix: 'max8688'

    Addresses scanned: -

    Datasheet: http://datasheets.maxim-ic.com/en/ds/MAX8688.pdf

Author: Guenter Roeck <linux@roeck-us.net>

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

This driver supports hardware monitoring for Maxim MAX8688 Digital Power-Supply
Controller/Monitor with PMBus Interface.

The driver is a client driver to the core PMBus driver. Please see
Documentation/hwmon/pmbus.rst for details on PMBus client drivers.

Usage Notes
-----------

This driver does not auto-detect devices. You will have to instantiate the
devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.

Platform data support
---------------------

The driver supports standard PMBus driver platform data.

Sysfs entries
-------------

The following attributes are supported. Limits are read-write; all other
attributes are read-only.

======================= ========================================================
in1_label		"vout1"
in1_input		Measured voltage. From READ_VOUT register.
in1_min			Minimum Voltage. From VOUT_UV_WARN_LIMIT register.
in1_max			Maximum voltage. From VOUT_OV_WARN_LIMIT register.
in1_lcrit		Critical minimum Voltage. VOUT_UV_FAULT_LIMIT register.
in1_crit		Critical maximum voltage. From VOUT_OV_FAULT_LIMIT
			register.
in1_min_alarm		Voltage low alarm. From VOLTAGE_UV_WARNING status.
in1_max_alarm		Voltage high alarm. From VOLTAGE_OV_WARNING status.
in1_lcrit_alarm		Voltage critical low alarm. From VOLTAGE_UV_FAULT
			status.
in1_crit_alarm		Voltage critical high alarm. From VOLTAGE_OV_FAULT
			status.
in1_highest		Historical maximum voltage.
in1_reset_history	Write any value to reset history.

curr1_label		"iout1"
curr1_input		Measured current. From READ_IOUT register.
curr1_max		Maximum current. From IOUT_OC_WARN_LIMIT register.
curr1_crit		Critical maximum current. From IOUT_OC_FAULT_LIMIT
			register.
curr1_max_alarm		Current high alarm. From IOUT_OC_WARN_LIMIT register.
curr1_crit_alarm	Current critical high alarm. From IOUT_OC_FAULT status.
curr1_highest		Historical maximum current.
curr1_reset_history	Write any value to reset history.

temp1_input		Measured temperature. From READ_TEMPERATURE_1 register.
temp1_max		Maximum temperature. From OT_WARN_LIMIT register.
temp1_crit		Critical high temperature. From OT_FAULT_LIMIT register.
temp1_max_alarm		Chip temperature high alarm. Set by comparing
			READ_TEMPERATURE_1 with OT_WARN_LIMIT if TEMP_OT_WARNING
			status is set.
temp1_crit_alarm	Chip temperature critical high alarm. Set by comparing
			READ_TEMPERATURE_1 with OT_FAULT_LIMIT if TEMP_OT_FAULT
			status is set.
temp1_highest		Historical maximum temperature.
temp1_reset_history	Write any value to reset history.
======================= ========================================================


code:
Kernel driver mc13783-adc
=========================

Supported chips:

  * Freescale MC13783

    Prefix: 'mc13783'

    Datasheet: https://www.nxp.com/docs/en/data-sheet/MC13783.pdf

  * Freescale MC13892

    Prefix: 'mc13892'

    Datasheet: https://www.nxp.com/docs/en/data-sheet/MC13892.pdf

Authors:

   - Sascha Hauer <s.hauer@pengutronix.de>
   - Luotao Fu <l.fu@pengutronix.de>

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

The Freescale MC13783 and MC13892 are Power Management and Audio Circuits.
Among other things they contain a 10-bit A/D converter. The converter has 16
(MC13783) resp. 12 (MC13892) channels which can be used in different modes. The
A/D converter has a resolution of 2.25mV.

Some channels can be used as General Purpose inputs or in a dedicated mode with
a chip internal scaling applied .

Currently the driver only supports the Application Supply channel (BP / BPSNS),
the General Purpose inputs and touchscreen.

See the following tables for the meaning of the different channels and their
chip internal scaling:

- MC13783:

======= =============================================== =============== =======
Channel	Signal						Input Range	Scaling
======= =============================================== =============== =======
0	Battery Voltage (BATT)				2.50 - 4.65V	-2.40V
1	Battery Current (BATT - BATTISNS)		-50 - 50 mV	x20
2	Application Supply (BP)				2.50 - 4.65V	-2.40V
3	Charger Voltage (CHRGRAW)			0 - 10V /	/5
							0 - 20V		/10
4	Charger Current (CHRGISNSP-CHRGISNSN)		-0.25 - 0.25V	x4
5	General Purpose ADIN5 / Battery Pack Thermistor	0 - 2.30V	No
6	General Purpose ADIN6 / Backup Voltage (LICELL)	0 - 2.30V /	No /
							1.50 - 3.50V	-1.20V
7	General Purpose ADIN7 / UID / Die Temperature	0 - 2.30V /	No /
							0 - 2.55V /	x0.9 / No
8	General Purpose ADIN8				0 - 2.30V	No
9	General Purpose ADIN9				0 - 2.30V	No
10	General Purpose ADIN10				0 - 2.30V	No
11	General Purpose ADIN11				0 - 2.30V	No
12	General Purpose TSX1 / Touchscreen X-plate 1	0 - 2.30V	No
13	General Purpose TSX2 / Touchscreen X-plate 2	0 - 2.30V	No
14	General Purpose TSY1 / Touchscreen Y-plate 1	0 - 2.30V	No
15	General Purpose TSY2 / Touchscreen Y-plate 2	0 - 2.30V	No
======= =============================================== =============== =======

- MC13892:

======= =============================================== =============== =======
Channel	Signal						Input Range	Scaling
======= =============================================== =============== =======
0	Battery Voltage (BATT)				0 - 4.8V	/2
1	Battery Current (BATT - BATTISNSCC)		-60 - 60 mV	x20
2	Application Supply (BPSNS)			0 - 4.8V	/2
3	Charger Voltage (CHRGRAW)			0 - 12V /	/5
							0 - 20V		/10
4	Charger Current (CHRGISNS-BPSNS) /		-0.3 - 0.3V /	x4 /
	Touchscreen X-plate 1				0 - 2.4V	No
5	General Purpose ADIN5 /	Battery Pack Thermistor	0 - 2.4V	No
6	General Purpose ADIN6 / Backup Voltage (LICELL)	0 - 2.4V /	No
	Backup Voltage (LICELL)                        	0 - 3.6V	x2/3
7	General Purpose ADIN7 / UID / Die Temperature	0 - 2.4V /	No /
							0 - 4.8V	/2
12	General Purpose TSX1 / Touchscreen X-plate 1	0 - 2.4V	No
13	General Purpose TSX2 / Touchscreen X-plate 2	0 - 2.4V	No
14	General Purpose TSY1 / Touchscreen Y-plate 1	0 - 2.4V	No
15	General Purpose TSY2 / Touchscreen Y-plate 2	0 - 2.4V	No
======= =============================================== =============== =======


code:
Kernel driver MCP3021
=====================

Supported chips:

  * Microchip Technology MCP3021

    Prefix: 'mcp3021'

    Datasheet: http://ww1.microchip.com/downloads/en/DeviceDoc/21805a.pdf

  * Microchip Technology MCP3221

    Prefix: 'mcp3221'

    Datasheet: http://ww1.microchip.com/downloads/en/DeviceDoc/21732c.pdf

Authors:

   - Mingkai Hu
   - Sven Schuchmann <schuchmann@schleissheimer.de>

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

This driver implements support for the Microchip Technology MCP3021 and
MCP3221 chip.

The Microchip Technology Inc. MCP3021 is a successive approximation A/D
converter (ADC) with 10-bit resolution. The MCP3221 has 12-bit resolution.

These devices provide one single-ended input with very low power consumption.
Communication to the MCP3021/MCP3221  is performed using a 2-wire I2C
compatible interface. Standard (100 kHz) and Fast (400 kHz) I2C modes are
available. The default I2C device address is 0x4d (contact the Microchip
factory for additional address options).


code:
Kernel driver menf21bmc_hwmon
=============================

Supported chips:

	* MEN 14F021P00

	  Prefix: 'menf21bmc_hwmon'

	  Adresses scanned: -

Author: Andreas Werner <andreas.werner@men.de>

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

The menf21bmc is a Board Management Controller (BMC) which provides an I2C
interface to the host to access the features implemented in the BMC.

This driver gives access to the voltage monitoring feature of the main
voltages of the board.
The voltage sensors are connected to the ADC inputs of the BMC which is
a PIC16F917 Mikrocontroller.

Usage Notes
-----------

This driver is part of the MFD driver named "menf21bmc" and does
not auto-detect devices.
You will have to instantiate the MFD driver explicitly.
Please see Documentation/i2c/instantiating-devices.rst for
details.

Sysfs entries
-------------

The following attributes are supported. All attributes are read only
The Limits are read once by the driver.

=============== ==========================
in0_input	+3.3V input voltage
in1_input	+5.0V input voltage
in2_input	+12.0V input voltage
in3_input	+5V Standby input voltage
in4_input	VBAT (on board battery)

in[0-4]_min	Minimum voltage limit
in[0-4]_max	Maximum voltage limit

in0_label	"MON_3_3V"
in1_label	"MON_5V"
in2_label	"MON_12V"
in3_label	"5V_STANDBY"
in4_label	"VBAT"
=============== ==========================


code:
Kernel driver mlxreg-fan
========================

Provides FAN control for the next Mellanox systems:

- QMB700, equipped with 40x200GbE InfiniBand ports;
- MSN3700, equipped with 32x200GbE or 16x400GbE Ethernet ports;
- MSN3410, equipped with 6x400GbE plus 48x50GbE Ethernet ports;
- MSN3800, equipped with 64x1000GbE Ethernet ports;

Author: Vadim Pasternak <vadimp@mellanox.com>

These are the Top of the Rack systems, equipped with Mellanox switch
board with Mellanox Quantum or Spectrume-2 devices.
FAN controller is implemented by the programmable device logic.

The default registers offsets set within the programmable device is as
following:

======================= ====
pwm1			0xe3
fan1 (tacho1)		0xe4
fan2 (tacho2)		0xe5
fan3 (tacho3)		0xe6
fan4 (tacho4)		0xe7
fan5 (tacho5)		0xe8
fan6 (tacho6)		0xe9
fan7 (tacho7)		0xea
fan8 (tacho8)		0xeb
fan9 (tacho9)		0xec
fan10 (tacho10)		0xed
fan11 (tacho11)		0xee
fan12 (tacho12)		0xef
======================= ====

This setup can be re-programmed with other registers.

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

The driver implements a simple interface for driving a fan connected to
a PWM output and tachometer inputs.
This driver obtains PWM and tachometers registers location according to
the system configuration and creates FAN/PWM hwmon objects and a cooling
device. PWM and tachometers are sensed through the on-board programmable
device, which exports its register map. This device could be attached to
any bus type, for which register mapping is supported.
Single instance is created with one PWM control, up to 12 tachometers and
one cooling device. It could be as many instances as programmable device
supports.
The driver exposes the fan to the user space through the hwmon's and
thermal's sysfs interfaces.

/sys files in hwmon subsystem
-----------------------------

================= == ===================================================
fan[1-12]_fault   RO files for tachometers TACH1-TACH12 fault indication
fan[1-12]_input   RO files for tachometers TACH1-TACH12 input (in RPM)
pwm1		  RW file for fan[1-12] target duty cycle (0..255)
================= == ===================================================

/sys files in thermal subsystem
-------------------------------

================= == ====================================================
cur_state	  RW file for current cooling state of the cooling device
		     (0..max_state)
max_state	  RO file for maximum cooling state of the cooling device
================= == ====================================================


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

Kernel driver mp2888
====================

Supported chips:

  * MPS MP12254

    Prefix: 'mp2888'

Author:

	Vadim Pasternak <vadimp@nvidia.com>

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

This driver implements support for Monolithic Power Systems, Inc. (MPS)
vendor dual-loop, digital, multi-phase controller MP2888.

This device: supports:

- One power rail.
- Programmable Multi-Phase up to 10 Phases.
- PWM-VID Interface
- One pages 0 for telemetry.
- Programmable pins for PMBus Address.
- Built-In EEPROM to Store Custom Configurations.

Device complaint with:

- PMBus rev 1.3 interface.

Device supports direct format for reading output current, output voltage,
input and output power and temperature.
Device supports linear format for reading input voltage and input power.

The driver provides the next attributes for the current:

- for current out input and maximum alarm;
- for phase current: input and label.

The driver exports the following attributes via the 'sysfs' files, where:

- 'n' is number of configured phases (from 1 to 10);
- index 1 for "iout";
- indexes 2 ... 1 + n for phases.

**curr[1-{1+n}]_input**

**curr[1-{1+n}]_label**

**curr1_max**

**curr1_max_alarm**

The driver provides the next attributes for the voltage:

- for voltage in: input, low and high critical thresholds, low and high
  critical alarms;
- for voltage out: input and high alarm;

The driver exports the following attributes via the 'sysfs' files, where

**in1_crit**

**in1_crit_alarm**

**in1_input**

**in1_label**

**in1_min**

**in1_min_alarm**

**in2_alarm**

**in2_input**

**in2_label**

The driver provides the next attributes for the power:

- for power in alarm and input.
- for power out: cap, cap alarm an input.

The driver exports the following attributes via the 'sysfs' files, where
- indexes 1 for "pin";
- indexes 2 for "pout";

**power1_alarm**

**power1_input**

**power1_label**

**power2_input**

**power2_label**

**power2_max**

**power2_max_alarm**

The driver provides the next attributes for the temperature:

**temp1_input**

**temp1_max**

**temp1_max_alarm**


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

Kernel driver mp2975
====================

Supported chips:

  * MPS MP12254

    Prefix: 'mp2975'

Author:

	Vadim Pasternak <vadimp@nvidia.com>

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

This driver implements support for Monolithic Power Systems, Inc. (MPS)
vendor dual-loop, digital, multi-phase controller MP2975.

This device:

- Supports up to two power rail.
- Provides 8 pulse-width modulations (PWMs), and can be configured up
  to 8-phase operation for rail 1 and up to 4-phase operation for rail
  2.
- Supports two pages 0 and 1 for telemetry and also pages 2 and 3 for
  configuration.
- Can configured VOUT readout in direct or VID format and allows
  setting of different formats on rails 1 and 2. For VID the following
  protocols are available: VR13 mode with 5-mV DAC; VR13 mode with
  10-mV DAC, IMVP9 mode with 5-mV DAC.

Device supports:

- SVID interface.
- AVSBus interface.

Device complaint with:

- PMBus rev 1.3 interface.

Device supports direct format for reading output current, output voltage,
input and output power and temperature.
Device supports linear format for reading input voltage and input power.
Device supports VID and direct formats for reading output voltage.
The below VID modes are supported: VR12, VR13, IMVP9.

The driver provides the next attributes for the current:

- for current in: input, maximum alarm;
- for current out input, maximum alarm and highest values;
- for phase current: input and label.
  attributes.

The driver exports the following attributes via the 'sysfs' files, where

- 'n' is number of telemetry pages (from 1 to 2);
- 'k' is number of configured phases (from 1 to 8);
- indexes 1, 1*n for "iin";
- indexes n+1, n+2 for "iout";
- indexes 2*n+1 ... 2*n + k for phases.

**curr[1-{2n}]_alarm**

**curr[{n+1}-{n+2}]_highest**

**curr[1-{2n+k}]_input**

**curr[1-{2n+k}]_label**

The driver provides the next attributes for the voltage:

- for voltage in: input, high critical threshold, high critical alarm, all only
  from page 0;
- for voltage out: input, low and high critical thresholds, low and high
  critical alarms, from pages 0 and 1;

The driver exports the following attributes via the 'sysfs' files, where

- 'n' is number of telemetry pages (from 1 to 2);
- indexes 1 for "iin";
- indexes n+1, n+2 for "vout";

**in[1-{2n+1}]_crit**

**in[1-{2n+1}]_crit_alarm**

**in[1-{2n+1}]_input**

**in[1-{2n+1}]_label**

**in[2-{n+1}]_lcrit**

**in[2-{n+1}1_lcrit_alarm**

The driver provides the next attributes for the power:

- for power in alarm and input.
- for power out: highest and input.

The driver exports the following attributes via the 'sysfs' files, where

- 'n' is number of telemetry pages (from 1 to 2);
- indexes 1 for "pin";
- indexes n+1, n+2 for "pout";

**power1_alarm**

**power[2-{n+1}]_highest**

**power[1-{2n+1}]_input**

**power[1-{2n+1}]_label**

The driver provides the next attributes for the temperature (only from page 0):

**temp1_crit**

**temp1_crit_alarm**

**temp1_input**

**temp1_max**

**temp1_max_alarm**


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

Kernel driver mp5023
====================

Supported chips:

  * MPS MP5023

    Prefix: 'mp5023'

  * Datasheet

    Publicly available at the MPS website : https://www.monolithicpower.com/en/mp5023.html

Author:

	Howard Chiu <howard.chiu@quantatw.com>

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

This driver implements support for Monolithic Power Systems, Inc. (MPS)
MP5023 Hot-Swap Controller.

Device complaint with:

- PMBus rev 1.3 interface.

Device supports direct format for reading input voltage, output voltage,
output current, input power and temperature.

The driver exports the following attributes via the 'sysfs' files
for input voltage:

**in1_input**

**in1_label**

**in1_max**

**in1_max_alarm**

**in1_min**

**in1_min_alarm**

The driver provides the following attributes for output voltage:

**in2_input**

**in2_label**

**in2_alarm**

The driver provides the following attributes for output current:

**curr1_input**

**curr1_label**

**curr1_alarm**

**curr1_max**

The driver provides the following attributes for input power:

**power1_input**

**power1_label**

**power1_alarm**

The driver provides the following attributes for temperature:

**temp1_input**

**temp1_max**

**temp1_max_alarm**

**temp1_crit**

**temp1_crit_alarm**


code:
Kernel driver nct6683
=====================

Supported chips:

  * Nuvoton NCT6683D/NCT6687D

    Prefix: 'nct6683'

    Addresses scanned: ISA address retrieved from Super I/O registers

    Datasheet: Available from Nuvoton upon request

Authors:

	Guenter Roeck <linux@roeck-us.net>

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

This driver implements support for the Nuvoton NCT6683D eSIO chip.

The chips implement up to shared 32 temperature and voltage sensors.
It supports up to 16 fan rotation sensors and up to 8 fan control engines.

Temperatures are measured in degrees Celsius. Measurement resolution is
0.5 degrees C.

Voltage sensors (also known as IN sensors) report their values in millivolts.

Fan rotation speeds are reported in RPM (rotations per minute).

Usage Note
----------

Limit register locations on Intel boards with EC firmware version 1.0
build date 04/03/13 do not match the register locations in the Nuvoton
datasheet. Nuvoton confirms that Intel uses a special firmware version
with different register addresses. The specification describing the Intel
firmware is held under NDA by Nuvoton and Intel and not available
to the public.

Some of the register locations can be reverse engineered; others are too
well hidden. Given this, writing any values from the operating system is
considered too risky with this firmware and has been disabled. All limits
must all be written from the BIOS.

The driver has only been tested with the Intel firmware, and by default
only instantiates on Intel boards. To enable it on non-Intel boards,
set the 'force' module parameter to 1.

Tested Boards and Firmware Versions
-----------------------------------

The driver has been reported to work with the following boards and
firmware versions.

=============== ===============================================
Board		Firmware version
=============== ===============================================
Intel DH87RL	NCT6683D EC firmware version 1.0 build 04/03/13
Intel DH87MC	NCT6683D EC firmware version 1.0 build 04/03/13
Intel DB85FL	NCT6683D EC firmware version 1.0 build 04/03/13
ASRock X570	NCT6683D EC firmware version 1.0 build 06/28/19
MSI B550	NCT6687D EC firmware version 1.0 build 05/07/20
=============== ===============================================


code:
Kernel driver NCT6775
=====================

.. note::

    This driver supersedes the NCT6775F and NCT6776F support in the W83627EHF
    driver.

Supported chips:

  * Nuvoton NCT6102D/NCT6104D/NCT6106D

    Prefix: 'nct6106'

    Addresses scanned: ISA address retrieved from Super I/O registers

    Datasheet: Available from the Nuvoton web site

  * Nuvoton NCT5572D/NCT6771F/NCT6772F/NCT6775F/W83677HG-I

    Prefix: 'nct6775'

    Addresses scanned: ISA address retrieved from Super I/O registers

    Datasheet: Available from Nuvoton upon request

  * Nuvoton NCT5573D/NCT5577D/NCT6776D/NCT6776F

    Prefix: 'nct6776'

    Addresses scanned: ISA address retrieved from Super I/O registers

    Datasheet: Available from Nuvoton upon request

  * Nuvoton NCT5532D/NCT6779D

    Prefix: 'nct6779'

    Addresses scanned: ISA address retrieved from Super I/O registers

    Datasheet: Available from Nuvoton upon request

  * Nuvoton NCT6791D

    Prefix: 'nct6791'

    Addresses scanned: ISA address retrieved from Super I/O registers

    Datasheet: Available from Nuvoton upon request

  * Nuvoton NCT6792D

    Prefix: 'nct6792'

    Addresses scanned: ISA address retrieved from Super I/O registers

    Datasheet: Available from Nuvoton upon request

  * Nuvoton NCT6793D

    Prefix: 'nct6793'

    Addresses scanned: ISA address retrieved from Super I/O registers

    Datasheet: Available from Nuvoton upon request

  * Nuvoton NCT6795D

    Prefix: 'nct6795'

    Addresses scanned: ISA address retrieved from Super I/O registers

    Datasheet: Available from Nuvoton upon request

  * Nuvoton NCT6796D

    Prefix: 'nct6796'

    Addresses scanned: ISA address retrieved from Super I/O registers

    Datasheet: Available from Nuvoton upon request

Authors:

	Guenter Roeck <linux@roeck-us.net>

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

This driver implements support for the Nuvoton NCT6775F, NCT6776F, and NCT6779D
and compatible super I/O chips.

The chips support up to 25 temperature monitoring sources. Up to 6 of those are
direct temperature sensor inputs, the others are special sources such as PECI,
PCH, and SMBUS. Depending on the chip type, 2 to 6 of the temperature sources
can be monitored and compared against minimum, maximum, and critical
temperatures. The driver reports up to 10 of the temperatures to the user.
There are 4 to 5 fan rotation speed sensors, 8 to 15 analog voltage sensors,
one VID, alarms with beep warnings (control unimplemented), and some automatic
fan regulation strategies (plus manual fan control mode).

The temperature sensor sources on all chips are configurable. The configured
source for each of the temperature sensors is provided in tempX_label.

Temperatures are measured in degrees Celsius and measurement resolution is
either 1 degC or 0.5 degC, depending on the temperature source and
configuration. An alarm is triggered when the temperature gets higher than
the high limit; it stays on until the temperature falls below the hysteresis
value. Alarms are only supported for temp1 to temp6, depending on the chip type.

Fan rotation speeds are reported in RPM (rotations per minute). An alarm is
triggered if the rotation speed has dropped below a programmable limit. On
NCT6775F, fan readings can be divided by a programmable divider (1, 2, 4, 8,
16, 32, 64 or 128) to give the readings more range or accuracy; the other chips
do not have a fan speed divider. The driver sets the most suitable fan divisor
itself; specifically, it increases the divider value each time a fan speed
reading returns an invalid value, and it reduces it if the fan speed reading
is lower than optimal. Some fans might not be present because they share pins
with other functions.

Voltage sensors (also known as IN sensors) report their values in millivolts.
An alarm is triggered if the voltage has crossed a programmable minimum
or maximum limit.

The driver supports automatic fan control mode known as Thermal Cruise.
In this mode, the chip attempts to keep the measured temperature in a
predefined temperature range. If the temperature goes out of range, fan
is driven slower/faster to reach the predefined range again.

The mode works for fan1-fan5.

sysfs attributes
----------------

pwm[1-7]
    - this file stores PWM duty cycle or DC value (fan speed) in range:

	   0 (lowest speed) to 255 (full)

pwm[1-7]_enable
    - this file controls mode of fan/temperature control:

	* 0 Fan control disabled (fans set to maximum speed)
	* 1 Manual mode, write to pwm[0-5] any value 0-255
	* 2 "Thermal Cruise" mode
	* 3 "Fan Speed Cruise" mode
	* 4 "Smart Fan III" mode (NCT6775F only)
	* 5 "Smart Fan IV" mode

pwm[1-7]_mode
    - controls if output is PWM or DC level

	* 0 DC output
	* 1 PWM output

Common fan control attributes
-----------------------------

pwm[1-7]_temp_sel
			Temperature source. Value is temperature sensor index.
			For example, select '1' for temp1_input.

pwm[1-7]_weight_temp_sel
			Secondary temperature source. Value is temperature
			sensor index. For example, select '1' for temp1_input.
			Set to 0 to disable secondary temperature control.

If secondary temperature functionality is enabled, it is controlled with the
following attributes.

pwm[1-7]_weight_duty_step
			Duty step size.

pwm[1-7]_weight_temp_step
			Temperature step size. With each step over
			temp_step_base, the value of weight_duty_step is added
			to the current pwm value.

pwm[1-7]_weight_temp_step_base
			Temperature at which secondary temperature control kicks
			in.

pwm[1-7]_weight_temp_step_tol
			Temperature step tolerance.

Thermal Cruise mode (2)
-----------------------

If the temperature is in the range defined by:

pwm[1-7]_target_temp
			Target temperature, unit millidegree Celsius
			(range 0 - 127000)

pwm[1-7]_temp_tolerance
			Target temperature tolerance, unit millidegree Celsius

There are no changes to fan speed. Once the temperature leaves the interval, fan
speed increases (if temperature is higher that desired) or decreases (if
temperature is lower than desired), using the following limits and time
intervals.

pwm[1-7]_start
			fan pwm start value (range 1 - 255), to start fan
			when the temperature is above defined range.

pwm[1-7]_floor
			lowest fan pwm (range 0 - 255) if temperature is below
			the defined range. If set to 0, the fan is expected to
			stop if the temperature is below the defined range.

pwm[1-7]_step_up_time
			milliseconds before fan speed is increased

pwm[1-7]_step_down_time
			milliseconds before fan speed is decreased

pwm[1-7]_stop_time
			how many milliseconds must elapse to switch
			corresponding fan off (when the temperature was below
			defined range).

Speed Cruise mode (3)
---------------------

This modes tries to keep the fan speed constant.

fan[1-7]_target
			Target fan speed

fan[1-7]_tolerance
			Target speed tolerance

Untested; use at your own risk.

Smart Fan IV mode (5)
---------------------

This mode offers multiple slopes to control the fan speed. The slopes can be
controlled by setting the pwm and temperature attributes. When the temperature
rises, the chip will calculate the DC/PWM output based on the current slope.
There are up to seven data points depending on the chip type. Subsequent data
points should be set to higher temperatures and higher pwm values to achieve
higher fan speeds with increasing temperature. The last data point reflects
critical temperature mode, in which the fans should run at full speed.

pwm[1-7]_auto_point[1-7]_pwm
			pwm value to be set if temperature reaches matching
			temperature range.

pwm[1-7]_auto_point[1-7]_temp
			Temperature over which the matching pwm is enabled.

pwm[1-7]_temp_tolerance
			Temperature tolerance, unit millidegree Celsius

pwm[1-7]_crit_temp_tolerance
			Temperature tolerance for critical temperature,
			unit millidegree Celsius

pwm[1-7]_step_up_time
			milliseconds before fan speed is increased

pwm[1-7]_step_down_time
			milliseconds before fan speed is decreased

Usage Notes
-----------

On various ASUS boards with NCT6776F, it appears that CPUTIN is not really
connected to anything and floats, or that it is connected to some non-standard
temperature measurement device. As a result, the temperature reported on CPUTIN
will not reflect a usable value. It often reports unreasonably high
temperatures, and in some cases the reported temperature declines if the actual
temperature increases (similar to the raw PECI temperature value - see PECI
specification for details). CPUTIN should therefore be ignored on ASUS
boards. The CPU temperature on ASUS boards is reported from PECI 0.


code:
Kernel driver nct7802
=====================

Supported chips:

  * Nuvoton NCT7802Y

    Prefix: 'nct7802'

    Addresses scanned: I2C 0x28..0x2f

    Datasheet: Available from Nuvoton web site

Authors:

	Guenter Roeck <linux@roeck-us.net>

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

This driver implements support for the Nuvoton NCT7802Y hardware monitoring
chip. NCT7802Y supports 6 temperature sensors, 5 voltage sensors, and 3 fan
speed sensors.

Smart Fan™ speed control is available via pwmX_auto_point attributes.

Tested Boards and BIOS Versions
-------------------------------

The driver has been reported to work with the following boards and
BIOS versions.

======================= ===============================================
Board			BIOS version
======================= ===============================================
Kontron COMe-bSC2	CHR2E934.001.GGO
Kontron COMe-bIP2	CCR2E212
======================= ===============================================


code:
Kernel driver nct7904
=====================

Supported chip:

  * Nuvoton NCT7904D

    Prefix: nct7904

    Addresses: I2C 0x2d, 0x2e

    Datasheet: Publicly available at Nuvoton website

	http://www.nuvoton.com/

Author: Vadim V. Vlasov <vvlasov@dev.rtsoft.ru>

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

The NCT7904D is a hardware monitor supporting up to 20 voltage sensors,
internal temperature sensor, Intel PECI and AMD SB-TSI CPU temperature
interface, up to 12 fan tachometer inputs, up to 4 fan control channels
with SmartFan.

Sysfs entries
-------------

Currently, the driver supports only the following features:

======================= =======================================================
in[1-20]_input		Input voltage measurements (mV)

fan[1-12]_input		Fan tachometer measurements (rpm)

temp1_input		Local temperature (1/1000 degree,
			0.125 degree resolution)

temp[2-9]_input		CPU temperatures (1/1000 degree,
			0.125 degree resolution)

pwm[1-4]_enable		R/W, 1/2 for manual or SmartFan mode
			Setting SmartFan mode is supported only if it has been
			previously configured by BIOS (or configuration EEPROM)

pwm[1-4]		R/O in SmartFan mode, R/W in manual control mode
======================= =======================================================

The driver checks sensor control registers and does not export the sensors
that are not enabled. Anyway, a sensor that is enabled may actually be not
connected and thus provide zero readings.

Limitations
-----------

The following features are not supported in current version:

 - SmartFan control
 - Watchdog
 - GPIO
 - external temperature sensors
 - SMI
 - min/max values
 - many other...


code:
Kernel driver npcm750-pwm-fan
=============================

Supported chips:

	NUVOTON NPCM750/730/715/705

Authors:

	<tomer.maimon@nuvoton.com>

Description:
------------
This driver implements support for NUVOTON NPCM7XX PWM and Fan Tacho
controller. The PWM controller supports up to 8 PWM outputs. The Fan tacho
controller supports up to 16 tachometer inputs.

The driver provides the following sensor accesses in sysfs:

=============== ======= =====================================================
fanX_input	ro	provide current fan rotation value in RPM as reported
			by the fan to the device.

pwmX		rw	get or set PWM fan control value. This is an integer
			value between 0(off) and 255(full speed).
=============== ======= =====================================================


code:
Kernel driver nsa320_hwmon
==========================

Supported chips:

  * Holtek HT46R065 microcontroller with onboard firmware that configures

	it to act as a hardware monitor.

    Prefix: 'nsa320'

    Addresses scanned: none

    Datasheet: Not available, driver was reverse engineered based upon the

	Zyxel kernel source

Author:

  Adam Baker <linux@baker-net.org.uk>

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

This chip is known to be used in the Zyxel NSA320 and NSA325 NAS Units and
also in some variants of the NSA310 but the driver has only been tested
on the NSA320. In all of these devices it is connected to the same 3 GPIO
lines which are used to provide chip select, clock and data lines. The
interface behaves similarly to SPI but at much lower speeds than are normally
used for SPI.

Following each chip select pulse the chip will generate a single 32 bit word
that contains 0x55 as a marker to indicate that data is being read correctly,
followed by an 8 bit fan speed in 100s of RPM and a 16 bit temperature in
tenths of a degree.

sysfs-Interface
---------------

============= =================
temp1_input   temperature input
fan1_input    fan speed
============= =================

Notes
-----

The access timings used in the driver are the same as used in the Zyxel
provided kernel. Testing has shown that if the delay between chip select and
the first clock pulse is reduced from 100 ms to just under 10ms then the chip
will not produce any output. If the duration of either phase of the clock
is reduced from 100 us to less than 15 us then data pulses are likely to be
read twice corrupting the output. The above analysis is based upon a sample
of one unit but suggests that the Zyxel provided delay values include a
reasonable tolerance.

The driver incorporates a limit that it will not check for updated values
faster than once a second. This is because the hardware takes a relatively long
time to read the data from the device and when it does it reads both temp and
fan speed. As the most likely case for two accesses in quick succession is
to read both of these values avoiding a second read delay is desirable.


code:
Kernel driver ntc_thermistor
============================

Supported thermistors from Murata:

* Murata NTC Thermistors NCP15WB473, NCP18WB473, NCP21WB473, NCP03WB473,
  NCP15WL333, NCP03WF104, NCP15XH103

  Prefixes: 'ncp15wb473', 'ncp18wb473', 'ncp21wb473', 'ncp03wb473',
  'ncp15wl333', 'ncp03wf104', 'ncp15xh103'

  Datasheet: Publicly available at Murata

Supported thermistors from EPCOS:

* EPCOS NTC Thermistors B57330V2103

  Prefixes: b57330v2103

  Datasheet: Publicly available at EPCOS

Other NTC thermistors can be supported simply by adding compensation
tables; e.g., NCP15WL333 support is added by the table ncpXXwl333.

Authors:

	MyungJoo Ham <myungjoo.ham@samsung.com>

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

The NTC (Negative Temperature Coefficient) thermistor is a simple thermistor
that requires users to provide the resistance and lookup the corresponding
compensation table to get the temperature input.

The NTC driver provides lookup tables with a linear approximation function
and four circuit models with an option not to use any of the four models.

Using the following convention::

   $	resistor
   [TH]	the thermistor

The four circuit models provided are:

1. connect = NTC_CONNECTED_POSITIVE, pullup_ohm > 0::

     [pullup_uV]
	 |    |
	[TH]  $ (pullup_ohm)
	 |    |
	 +----+-----------------------[read_uV]
	 |
	 $ (pulldown_ohm)
	 |
	-+- (ground)

2. connect = NTC_CONNECTED_POSITIVE, pullup_ohm = 0 (not-connected)::

     [pullup_uV]
	 |
	[TH]
	 |
	 +----------------------------[read_uV]
	 |
	 $ (pulldown_ohm)
	 |
	-+- (ground)

3. connect = NTC_CONNECTED_GROUND, pulldown_ohm > 0::

     [pullup_uV]
	 |
	 $ (pullup_ohm)
	 |
	 +----+-----------------------[read_uV]
	 |    |
	[TH]  $ (pulldown_ohm)
	 |    |
	-+----+- (ground)

4. connect = NTC_CONNECTED_GROUND, pulldown_ohm = 0 (not-connected)::

     [pullup_uV]
	 |
	 $ (pullup_ohm)
	 |
	 +----------------------------[read_uV]
	 |
	[TH]
	 |
	-+- (ground)

When one of the four circuit models is used, read_uV, pullup_uV, pullup_ohm,
pulldown_ohm, and connect should be provided. When none of the four models
are suitable or the user can get the resistance directly, the user should
provide read_ohm and _not_ provide the others.

Sysfs Interface
---------------

=============== == =============================================================
name		   the mandatory global attribute, the thermistor name.
=============== == =============================================================
temp1_type	RO always 4 (thermistor)

temp1_input	RO measure the temperature and provide the measured value.
		   (reading this file initiates the reading procedure.)
=============== == =============================================================

Note that each NTC thermistor has only _one_ thermistor; thus, only temp1 exists.


code:
.. SPDX-License-Identifier: GPL-2.0-or-later

Kernel driver nzxt-kraken2
==========================

Supported devices:

* NZXT Kraken X42
* NZXT Kraken X52
* NZXT Kraken X62
* NZXT Kraken X72

Author: Jonas Malaco

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

This driver enables hardware monitoring support for NZXT Kraken X42/X52/X62/X72
all-in-one CPU liquid coolers.  Three sensors are available: fan speed, pump
speed and coolant temperature.

Fan and pump control, while supported by the firmware, are not currently
exposed.  The addressable RGB LEDs, present in the integrated CPU water block
and pump head, are not supported either.  But both features can be found in
existing user-space tools (e.g. `liquidctl`_).

.. _liquidctl: https://github.com/liquidctl/liquidctl

Usage Notes
-----------

As these are USB HIDs, the driver can be loaded automatically by the kernel and
supports hot swapping.

Sysfs entries
-------------

=======================	========================================================
fan1_input		Fan speed (in rpm)
fan2_input		Pump speed (in rpm)
temp1_input		Coolant temperature (in millidegrees Celsius)
=======================	========================================================


code:
.. SPDX-License-Identifier: GPL-2.0-or-later

Kernel driver nzxt-smart2
=========================

Supported devices:

- NZXT RGB & Fan controller
- NZXT Smart Device v2

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

This driver implements monitoring and control of fans plugged into the device.
Besides typical speed monitoring and PWM duty cycle control, voltage and current
is reported for every fan.

The device also has two connectors for RGB LEDs; support for them isn't
implemented (mainly because there is no standardized sysfs interface).

Also, the device has a noise sensor, but the sensor seems to be completely
useless (and very imprecise), so support for it isn't implemented too.

Usage Notes
-----------

The device should be autodetected, and the driver should load automatically.

If fans are plugged in/unplugged while the system is powered on, the driver
must be reloaded to detect configuration changes; otherwise, new fans can't
be controlled (`pwm*` changes will be ignored). It is necessary because the
device has a dedicated "detect fans" command, and currently, it is executed only
during initialization. Speed, voltage, current monitoring will work even without
reload. As an alternative to reloading the module, a userspace tool (like
`liquidctl`_) can be used to run "detect fans" command through hidraw interface.

The driver coexists with userspace tools that access the device through hidraw
interface with no known issues.

.. _liquidctl: https://github.com/liquidctl/liquidctl

Sysfs entries
-------------

=======================	========================================================
fan[1-3]_input		Fan speed monitoring (in rpm).
curr[1-3]_input		Current supplied to the fan (in milliamperes).
in[0-2]_input		Voltage supplied to the fan (in millivolts).
pwm[1-3]		Controls fan speed: PWM duty cycle for PWM-controlled
			fans, voltage for other fans. Voltage can be changed in
			9-12 V range, but the value of the sysfs attribute is
			always in 0-255 range (1 = 9V, 255 = 12V). Setting the
			attribute to 0 turns off the fan completely.
pwm[1-3]_enable		1 if the fan can be controlled by writing to the
			corresponding pwm* attribute, 0 otherwise. The device
			can control only the fans it detected itself, so the
			attribute is read-only.
pwm[1-3]_mode		Read-only, 1 for PWM-controlled fans, 0 for other fans
			(or if no fan connected).
update_interval		The interval at which all inputs are updated (in
			milliseconds). The default is 1000ms. Minimum is 250ms.
=======================	========================================================


code:
Kernel driver occ-hwmon
=======================

Supported chips:

  * POWER8
  * POWER9

Author: Eddie James <eajames@linux.ibm.com>

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

This driver supports hardware monitoring for the On-Chip Controller (OCC)
embedded on POWER processors. The OCC is a device that collects and aggregates
sensor data from the processor and the system. The OCC can provide the raw
sensor data as well as perform thermal and power management on the system.

The P8 version of this driver is a client driver of I2C. It may be probed
manually if an "ibm,p8-occ-hwmon" compatible device is found under the
appropriate I2C bus node in the device-tree.

The P9 version of this driver is a client driver of the FSI-based OCC driver.
It will be probed automatically by the FSI-based OCC driver.

Sysfs entries
-------------

The following attributes are supported. All attributes are read-only unless
specified.

The OCC sensor ID is an integer that represents the unique identifier of the
sensor with respect to the OCC. For example, a temperature sensor for the third
DIMM slot in the system may have a sensor ID of 7. This mapping is unavailable
to the device driver, which must therefore export the sensor ID as-is.

Some entries are only present with certain OCC sensor versions or only on
certain OCCs in the system. The version number is not exported to the user
but can be inferred.

temp[1-n]_label
	OCC sensor ID.

[with temperature sensor version 1]

    temp[1-n]_input
			Measured temperature of the component in millidegrees
			Celsius.

[with temperature sensor version >= 2]

    temp[1-n]_type
				The FRU (Field Replaceable Unit) type
				(represented by an integer) for the component
				that this sensor measures.
    temp[1-n]_fault
				Temperature sensor fault boolean; 1 to indicate
				that a fault is present or 0 to indicate that
				no fault is present.

    [with type == 3 (FRU type is VRM)]

	temp[1-n]_alarm
				VRM temperature alarm boolean; 1 to indicate
				alarm, 0 to indicate no alarm

    [else]

	temp[1-n]_input
				Measured temperature of the component in
				millidegrees Celsius.

freq[1-n]_label
			OCC sensor ID.
freq[1-n]_input
			Measured frequency of the component in MHz.
power[1-n]_input
			Latest measured power reading of the component in
			microwatts.
power[1-n]_average
			Average power of the component in microwatts.
power[1-n]_average_interval
				The amount of time over which the power average
				was taken in microseconds.

[with power sensor version < 2]

    power[1-n]_label
			OCC sensor ID.

[with power sensor version >= 2]

    power[1-n]_label
			OCC sensor ID + function ID + channel in the form
			of a string, delimited by underscores, i.e. "0_15_1".
			Both the function ID and channel are integers that
			further identify the power sensor.

[with power sensor version 0xa0]

    power[1-n]_label
			OCC sensor ID + sensor type in the form of a string,
			delimited by an underscore, i.e. "0_system". Sensor
			type will be one of "system", "proc", "vdd" or "vdn".
			For this sensor version, OCC sensor ID will be the same
			for all power sensors.

[present only on "master" OCC; represents the whole system power; only one of
this type of power sensor will be present]

    power[1-n]_label
				"system"
    power[1-n]_input
				Latest system output power in microwatts.
    power[1-n]_cap
				Current system power cap in microwatts.
    power[1-n]_cap_not_redundant
				System power cap in microwatts when
				there is not redundant power.
    power[1-n]_cap_max
				Maximum power cap that the OCC can enforce in
				microwatts.
    power[1-n]_cap_min		Minimum power cap that the OCC can enforce in
				microwatts.
    power[1-n]_cap_user		The power cap set by the user, in microwatts.
				This attribute will return 0 if no user power
				cap has been set. This attribute is read-write,
				but writing any precision below watts will be
				ignored, i.e. requesting a power cap of
				500900000 microwatts will result in a power cap
				request of 500 watts.

    [with caps sensor version > 1]

	power[1-n]_cap_user_source
					Indicates how the user power cap was
					set. This is an integer that maps to
					system or firmware components that can
					set the user power cap.

The following "extn" sensors are exported as a way for the OCC to provide data
that doesn't fit anywhere else. The meaning of these sensors is entirely
dependent on their data, and cannot be statically defined.

extn[1-n]_label
			ASCII ID or OCC sensor ID.
extn[1-n]_flags
			This is one byte hexadecimal value. Bit 7 indicates the
			type of the label attribute; 1 for sensor ID, 0 for
			ASCII ID. Other bits are reserved.
extn[1-n]_input
			6 bytes of hexadecimal data, with a meaning defined by
			the sensor ID.


code:
.. SPDX-License-Identifier: GPL-2.0-or-later

Kernel driver oxp-sensors
=========================

Author:
    - Joaquín Ignacio Aramendía <samsagax@gmail.com>

Description:
------------

One X Player devices from One Netbook provide fan readings and fan control
through its Embedded Controller.

Currently only supports AMD boards from the One X Player and AOK ZOE lineup.
Intel boards could be supported if we could figure out the EC registers and
values to write to since the EC layout and model is different.

Supported devices
-----------------

Currently the driver supports the following handhelds:

 - AOK ZOE A1
 - OneXPlayer AMD
 - OneXPlayer mini AMD
 - OneXPlayer mini AMD PRO

Sysfs entries
-------------

The following attributes are supported:

fan1_input
  Read Only. Reads current fan RMP.

pwm1_enable
  Read Write. Enable manual fan control. Write "1" to set to manual, write "0"
  to let the EC control de fan speed. Read this attribute to see current status.

pwm1
  Read Write. Read this attribute to see current duty cycle in the range [0-255].
  When pwm1_enable is set to "1" (manual) write any value in the range [0-255]
  to set fan speed.


code:
Kernel driver pc87360
=====================

Supported chips:

  * National Semiconductor PC87360, PC87363, PC87364, PC87365 and PC87366

    Prefixes: 'pc87360', 'pc87363', 'pc87364', 'pc87365', 'pc87366'

    Addresses scanned: none, address read from Super I/O config space

    Datasheets: No longer available

Authors: Jean Delvare <jdelvare@suse.de>

Thanks to Sandeep Mehta, Tonko de Rooy and Daniel Ceregatti for testing.

Thanks to Rudolf Marek for helping me investigate conversion issues.

Module Parameters
-----------------

* init int
    Chip initialization level:

    - 0: None
    - **1**: Forcibly enable internal voltage and temperature channels,
      except in9
    - 2: Forcibly enable all voltage and temperature channels, except in9
    - 3: Forcibly enable all voltage and temperature channels, including in9

Note that this parameter has no effect for the PC87360, PC87363 and PC87364
chips.

Also note that for the PC87366, initialization levels 2 and 3 don't enable
all temperature channels, because some of them share pins with each other,
so they can't be used at the same time.

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

The National Semiconductor PC87360 Super I/O chip contains monitoring and
PWM control circuitry for two fans. The PC87363 chip is similar, and the
PC87364 chip has monitoring and PWM control for a third fan.

The National Semiconductor PC87365 and PC87366 Super I/O chips are complete
hardware monitoring chipsets, not only controlling and monitoring three fans,
but also monitoring eleven voltage inputs and two (PC87365) or up to four
(PC87366) temperatures.

  =========== ======= ======= ======= ======= =====
  Chip        #vin    #fan    #pwm    #temp   devid
  =========== ======= ======= ======= ======= =====
  PC87360     -       2       2       -       0xE1
  PC87363     -       2       2       -       0xE8
  PC87364     -       3       3       -       0xE4
  PC87365     11      3       3       2       0xE5
  PC87366     11      3       3       3-4     0xE9
  =========== ======= ======= ======= ======= =====

The driver assumes that no more than one chip is present, and one of the
standard Super I/O addresses is used (0x2E/0x2F or 0x4E/0x4F)

Fan Monitoring
--------------

Fan rotation speeds are reported in RPM (revolutions per minute). An alarm
is triggered if the rotation speed has dropped below a programmable limit.
A different alarm is triggered if the fan speed is too low to be measured.

Fan readings are affected by a programmable clock divider, giving the
readings more range or accuracy. Usually, users have to learn how it works,
but this driver implements dynamic clock divider selection, so you don't
have to care no more.

For reference, here are a few values about clock dividers:

    =========== =============== =============== ===========
		slowest         accuracy        highest
		measurable      around 3000     accurate
    divider     speed (RPM)     RPM (RPM)       speed (RPM)
    =========== =============== =============== ===========
	 1        1882              18           6928
	 2         941              37           4898
	 4         470              74           3464
	 8         235             150           2449
    =========== =============== =============== ===========

For the curious, here is how the values above were computed:

 * slowest measurable speed: clock/(255*divider)
 * accuracy around 3000 RPM: 3000^2/clock
 * highest accurate speed: sqrt(clock*100)

The clock speed for the PC87360 family is 480 kHz. I arbitrarily chose 100
RPM as the lowest acceptable accuracy.

As mentioned above, you don't have to care about this no more.

Note that not all RPM values can be represented, even when the best clock
divider is selected. This is not only true for the measured speeds, but
also for the programmable low limits, so don't be surprised if you try to
set, say, fan1_min to 2900 and it finally reads 2909.

Fan Control
-----------

PWM (pulse width modulation) values range from 0 to 255, with 0 meaning
that the fan is stopped, and 255 meaning that the fan goes at full speed.

Be extremely careful when changing PWM values. Low PWM values, even
non-zero, can stop the fan, which may cause irreversible damage to your
hardware if temperature increases too much. When changing PWM values, go
step by step and keep an eye on temperatures.

One user reported problems with PWM. Changing PWM values would break fan
speed readings. No explanation nor fix could be found.

Temperature Monitoring
----------------------

Temperatures are reported in degrees Celsius. Each temperature measured has
associated low, high and overtemperature limits, each of which triggers an
alarm when crossed.

The first two temperature channels are external. The third one (PC87366
only) is internal.

The PC87366 has three additional temperature channels, based on
thermistors (as opposed to thermal diodes for the first three temperature
channels). For technical reasons, these channels are held by the VLM
(voltage level monitor) logical device, not the TMS (temperature
measurement) one. As a consequence, these temperatures are exported as
voltages, and converted into temperatures in user-space.

Note that these three additional channels share their pins with the
external thermal diode channels, so you (physically) can't use them all at
the same time. Although it should be possible to mix the two sensor types,
the documents from National Semiconductor suggest that motherboard
manufacturers should choose one type and stick to it. So you will more
likely have either channels 1 to 3 (thermal diodes) or 3 to 6 (internal
thermal diode, and thermistors).

Voltage Monitoring
------------------

Voltages are reported relatively to a reference voltage, either internal or
external. Some of them (in7:Vsb, in8:Vdd and in10:AVdd) are divided by two
internally, you will have to compensate in sensors.conf. Others (in0 to in6)
are likely to be divided externally. The meaning of each of these inputs as
well as the values of the resistors used for division is left to the
motherboard manufacturers, so you will have to document yourself and edit
sensors.conf accordingly. National Semiconductor has a document with
recommended resistor values for some voltages, but this still leaves much
room for per motherboard specificities, unfortunately. Even worse,
motherboard manufacturers don't seem to care about National Semiconductor's
recommendations.

Each voltage measured has associated low and high limits, each of which
triggers an alarm when crossed.

When available, VID inputs are used to provide the nominal CPU Core voltage.
The driver will default to VRM 9.0, but this can be changed from user-space.
The chipsets can handle two sets of VID inputs (on dual-CPU systems), but
the driver will only export one for now. This may change later if there is
a need.

General Remarks
---------------

If an alarm triggers, it will remain triggered until the hardware register
is read at least once. This means that the cause for the alarm may already
have disappeared! Note that all hardware registers are read whenever any
data is read (unless it is less than 2 seconds since the last update, in
which case cached values are returned instead). As a consequence, when
a once-only alarm triggers, it may take 2 seconds for it to show, and 2
more seconds for it to disappear.

Monitoring of in9 isn't enabled at lower init levels (<3) because that
channel measures the battery voltage (Vbat). It is a known fact that
repeatedly sampling the battery voltage reduces its lifetime. National
Semiconductor smartly designed their chipset so that in9 is sampled only
once every 1024 sampling cycles (that is every 34 minutes at the default
sampling rate), so the effect is attenuated, but still present.

Limitations
-----------

The datasheets suggests that some values (fan mins, fan dividers)
shouldn't be changed once the monitoring has started, but we ignore that
recommendation. We'll reconsider if it actually causes trouble.


code:
Kernel driver pc87427
=====================

Supported chips:

  * National Semiconductor PC87427

    Prefix: 'pc87427'

    Addresses scanned: none, address read from Super I/O config space

    Datasheet: No longer available

Author: Jean Delvare <jdelvare@suse.de>

Thanks to Amir Habibi at Candelis for setting up a test system, and to
Michael Kress for testing several iterations of this driver.

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

The National Semiconductor Super I/O chip includes complete hardware
monitoring capabilities. It can monitor up to 18 voltages, 8 fans and
6 temperature sensors. Only the fans and temperatures are supported at
the moment, voltages aren't.

This chip also has fan controlling features (up to 4 PWM outputs),
which are partly supported by this driver.

The driver assumes that no more than one chip is present, which seems
reasonable.

Fan Monitoring
--------------

Fan rotation speeds are reported as 14-bit values from a gated clock
signal. Speeds down to 83 RPM can be measured.

An alarm is triggered if the rotation speed drops below a programmable
limit. Another alarm is triggered if the speed is too low to be measured
(including stalled or missing fan).

Fan Speed Control
-----------------

Fan speed can be controlled by PWM outputs. There are 4 possible modes:
always off, always on, manual and automatic. The latter isn't supported
by the driver: you can only return to that mode if it was the original
setting, and the configuration interface is missing.

Temperature Monitoring
----------------------

The PC87427 relies on external sensors (following the SensorPath
standard), so the resolution and range depend on the type of sensor
connected. The integer part can be 8-bit or 9-bit, and can be signed or
not. I couldn't find a way to figure out the external sensor data
temperature format, so user-space adjustment (typically by a factor 2)
may be required.


code:
Kernel driver pcf8591
=====================

Supported chips:

  * Philips/NXP PCF8591

    Prefix: 'pcf8591'

    Addresses scanned: none

    Datasheet: Publicly available at the NXP website

	       http://www.nxp.com/pip/PCF8591_6.html

Authors:
      - Aurelien Jarno <aurelien@aurel32.net>
      - valuable contributions by Jan M. Sendler <sendler@sendler.de>,
      - Jean Delvare <jdelvare@suse.de>

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

The PCF8591 is an 8-bit A/D and D/A converter (4 analog inputs and one
analog output) for the I2C bus produced by Philips Semiconductors (now NXP).
It is designed to provide a byte I2C interface to up to 4 separate devices.

The PCF8591 has 4 analog inputs programmable as single-ended or
differential inputs:

- mode 0 : four single ended inputs
	Pins AIN0 to AIN3 are single ended inputs for channels 0 to 3

- mode 1 : three differential inputs
	Pins AIN3 is the common negative differential input
	Pins AIN0 to AIN2 are positive differential inputs for channels 0 to 2

- mode 2 : single ended and differential mixed
	Pins AIN0 and AIN1 are single ended inputs for channels 0 and 1
	Pins AIN2 is the positive differential input for channel 3
	Pins AIN3 is the negative differential input for channel 3

- mode 3 : two differential inputs
	Pins AIN0 is the positive differential input for channel 0
	Pins AIN1 is the negative differential input for channel 0
	Pins AIN2 is the positive differential input for channel 1
	Pins AIN3 is the negative differential input for channel 1

See the datasheet for details.

Module parameters
-----------------

* input_mode int

    Analog input mode:

	 - 0 = four single ended inputs
	 - 1 = three differential inputs
	 - 2 = single ended and differential mixed
	 - 3 = two differential inputs

Accessing PCF8591 via /sys interface
-------------------------------------

The PCF8591 is plainly impossible to detect! Thus the driver won't even
try. You have to explicitly instantiate the device at the relevant
address (in the interval [0x48..0x4f]) either through platform data, or
using the sysfs interface. See Documentation/i2c/instantiating-devices.rst
for details.

Directories are being created for each instantiated PCF8591:

/sys/bus/i2c/devices/<0>-<1>/
   where <0> is the bus the chip is connected to (e. g. i2c-0)
   and <1> the chip address ([48..4f])

Inside these directories, there are such files:

   in0_input, in1_input, in2_input, in3_input, out0_enable, out0_output, name

Name contains chip name.

The in0_input, in1_input, in2_input and in3_input files are RO. Reading gives
the value of the corresponding channel. Depending on the current analog inputs
configuration, files in2_input and in3_input may not exist. Values range
from 0 to 255 for single ended inputs and -128 to +127 for differential inputs
(8-bit ADC).

The out0_enable file is RW. Reading gives "1" for analog output enabled and
"0" for analog output disabled. Writing accepts "0" and "1" accordingly.

The out0_output file is RW. Writing a number between 0 and 255 (8-bit DAC), send
the value to the digital-to-analog converter. Note that a voltage will
only appears on AOUT pin if aout0_enable equals 1. Reading returns the last
value written.


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

Kernel driver peci-cputemp
==========================

Supported chips:
	One of Intel server CPUs listed below which is connected to a PECI bus.
		* Intel Xeon E5/E7 v3 server processors
			Intel Xeon E5-14xx v3 family
			Intel Xeon E5-24xx v3 family
			Intel Xeon E5-16xx v3 family
			Intel Xeon E5-26xx v3 family
			Intel Xeon E5-46xx v3 family
			Intel Xeon E7-48xx v3 family
			Intel Xeon E7-88xx v3 family
		* Intel Xeon E5/E7 v4 server processors
			Intel Xeon E5-16xx v4 family
			Intel Xeon E5-26xx v4 family
			Intel Xeon E5-46xx v4 family
			Intel Xeon E7-48xx v4 family
			Intel Xeon E7-88xx v4 family
		* Intel Xeon Scalable server processors
			Intel Xeon D family
			Intel Xeon Bronze family
			Intel Xeon Silver family
			Intel Xeon Gold family
			Intel Xeon Platinum family

	Datasheet: Available from http://www.intel.com/design/literature.htm

Author: Jae Hyun Yoo <jae.hyun.yoo@linux.intel.com>

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

This driver implements a generic PECI hwmon feature which provides Digital
Thermal Sensor (DTS) thermal readings of the CPU package and CPU cores that are
accessible via the processor PECI interface.

All temperature values are given in millidegree Celsius and will be measurable
only when the target CPU is powered on.

Sysfs interface
-------------------

======================= =======================================================
temp1_label		"Die"
temp1_input		Provides current die temperature of the CPU package.
temp1_max		Provides thermal control temperature of the CPU package
			which is also known as Tcontrol.
temp1_crit		Provides shutdown temperature of the CPU package which
			is also known as the maximum processor junction
			temperature, Tjmax or Tprochot.
temp1_crit_hyst		Provides the hysteresis value from Tcontrol to Tjmax of
			the CPU package.

temp2_label		"DTS"
temp2_input		Provides current temperature of the CPU package scaled
			to match DTS thermal profile.
temp2_max		Provides thermal control temperature of the CPU package
			which is also known as Tcontrol.
temp2_crit		Provides shutdown temperature of the CPU package which
			is also known as the maximum processor junction
			temperature, Tjmax or Tprochot.
temp2_crit_hyst		Provides the hysteresis value from Tcontrol to Tjmax of
			the CPU package.

temp3_label		"Tcontrol"
temp3_input		Provides current Tcontrol temperature of the CPU
			package which is also known as Fan Temperature target.
			Indicates the relative value from thermal monitor trip
			temperature at which fans should be engaged.
temp3_crit		Provides Tcontrol critical value of the CPU package
			which is same to Tjmax.

temp4_label		"Tthrottle"
temp4_input		Provides current Tthrottle temperature of the CPU
			package. Used for throttling temperature. If this value
			is allowed and lower than Tjmax - the throttle will
			occur and reported at lower than Tjmax.

temp5_label		"Tjmax"
temp5_input		Provides the maximum junction temperature, Tjmax of the
			CPU package.

temp[6-N]_label		Provides string "Core X", where X is resolved core
			number.
temp[6-N]_input		Provides current temperature of each core.

======================= =======================================================


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

Kernel driver peci-dimmtemp
===========================

Supported chips:
	One of Intel server CPUs listed below which is connected to a PECI bus.
		* Intel Xeon E5/E7 v3 server processors
			Intel Xeon E5-14xx v3 family
			Intel Xeon E5-24xx v3 family
			Intel Xeon E5-16xx v3 family
			Intel Xeon E5-26xx v3 family
			Intel Xeon E5-46xx v3 family
			Intel Xeon E7-48xx v3 family
			Intel Xeon E7-88xx v3 family
		* Intel Xeon E5/E7 v4 server processors
			Intel Xeon E5-16xx v4 family
			Intel Xeon E5-26xx v4 family
			Intel Xeon E5-46xx v4 family
			Intel Xeon E7-48xx v4 family
			Intel Xeon E7-88xx v4 family
		* Intel Xeon Scalable server processors
			Intel Xeon D family
			Intel Xeon Bronze family
			Intel Xeon Silver family
			Intel Xeon Gold family
			Intel Xeon Platinum family

	Datasheet: Available from http://www.intel.com/design/literature.htm

Author: Jae Hyun Yoo <jae.hyun.yoo@linux.intel.com>

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

This driver implements a generic PECI hwmon feature which provides
Temperature sensor on DIMM readings that are accessible via the processor PECI interface.

All temperature values are given in millidegree Celsius and will be measurable
only when the target CPU is powered on.

Sysfs interface
-------------------

======================= =======================================================

temp[N]_label		Provides string "DIMM CI", where C is DIMM channel and
			I is DIMM index of the populated DIMM.
temp[N]_input		Provides current temperature of the populated DIMM.
temp[N]_max		Provides thermal control temperature of the DIMM.
temp[N]_crit		Provides shutdown temperature of the DIMM.

======================= =======================================================

Note:
	DIMM temperature attributes will appear when the client CPU's BIOS
	completes memory training and testing.


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

Kernel driver pim4328
=====================

Supported chips:

  * Flex PIM4328

    Prefix: 'pim4328', 'bmr455'

    Addresses scanned: -

    Datasheet:

https://flexpowermodules.com/resources/fpm-techspec-pim4328

  * Flex PIM4820

    Prefixes: 'pim4820'

    Addresses scanned: -

    Datasheet: https://flexpowermodules.com/resources/fpm-techspec-pim4820

  * Flex PIM4006, PIM4106, PIM4206, PIM4306, PIM4406

    Prefixes: 'pim4006', 'pim4106', 'pim4206', 'pim4306', 'pim4406'

    Addresses scanned: -

    Datasheet: https://flexpowermodules.com/resources/fpm-techspec-pim4006

Author: Erik Rosen <erik.rosen@metormote.com>

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

This driver supports hardware monitoring for Flex PIM4328 and
compatible digital power interface modules.

The driver is a client driver to the core PMBus driver. Please see
Documentation/hwmon/pmbus.rst and Documentation.hwmon/pmbus-core for details
on PMBus client drivers.

Usage Notes
-----------

This driver does not auto-detect devices. You will have to instantiate the
devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
details.

Platform data support
---------------------

The driver supports standard PMBus driver platform data.

Sysfs entries
-------------

The following attributes are supported. All attributes are read-only.

======================= ========================================================
in1_label		"vin"
in1_input		Measured input voltage.
in1_alarm		Input voltage alarm.

in2_label		"vin.0"
in2_input		Measured input voltage on input A.

			PIM4328 and PIM4X06

in3_label		"vin.1"
in3_input		Measured input voltage on input B.

			PIM4328 and PIM4X06

in4_label		"vcap"
in4_input		Measured voltage on holdup capacitor.

			PIM4328

curr1_label		"iin.0"
curr1_input		Measured input current on input A.

			PIM4X06

curr2_label		"iin.1"
curr2_input		Measured input current on input B.

			PIM4X06

currX_label		"iout1"
currX_input		Measured output current.
currX_alarm		Output current alarm.

			X is 1 for PIM4820, 3 otherwise.

temp1_input		Measured temperature.
temp1_alarm		High temperature alarm.
======================= ========================================================


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

Kernel driver pli1209bc
=======================

Supported chips:

  * Digital Supervisor PLI1209BC

    Prefix: 'pli1209bc'

    Addresses scanned: 0x50 - 0x5F

    Datasheet: https://www.vicorpower.com/documents/datasheets/ds-PLI1209BCxyzz-VICOR.pdf

Authors:
    - Marcello Sylvester Bauer <sylv@sylv.io>

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

The Vicor PLI1209BC is an isolated digital power system supervisor that provides
a communication interface between a host processor and one Bus Converter Module
(BCM). The PLI communicates with a system controller via a PMBus compatible
interface over an isolated UART interface. Through the PLI, the host processor
can configure, set protection limits, and monitor the BCM.

Sysfs entries
-------------

======================= ========================================================
in1_label		"vin2"
in1_input		Input voltage.
in1_rated_min		Minimum rated input voltage.
in1_rated_max		Maximum rated input voltage.
in1_max			Maximum input voltage.
in1_max_alarm		Input voltage high alarm.
in1_crit		Critical input voltage.
in1_crit_alarm		Input voltage critical alarm.

in2_label		"vout2"
in2_input		Output voltage.
in2_rated_min		Minimum rated output voltage.
in2_rated_max		Maximum rated output voltage.
in2_alarm		Output voltage alarm

curr1_label		"iin2"
curr1_input		Input current.
curr1_max		Maximum input current.
curr1_max_alarm		Maximum input current high alarm.
curr1_crit		Critical input current.
curr1_crit_alarm	Input current critical alarm.

curr2_label		"iout2"
curr2_input		Output current.
curr2_crit		Critical output current.
curr2_crit_alarm	Output current critical alarm.
curr2_max		Maximum output current.
curr2_max_alarm		Output current high alarm.

power1_label		"pin2"
power1_input		Input power.
power1_alarm		Input power alarm.

power2_label		"pout2"
power2_input		Output power.
power2_rated_max	Maximum rated output power.

temp1_input		Die temperature.
temp1_alarm		Die temperature alarm.
temp1_max		Maximum die temperature.
temp1_max_alarm		Die temperature high alarm.
temp1_crit		Critical die temperature.
temp1_crit_alarm	Die temperature critical alarm.
======================= ========================================================


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

Kernel driver pm6764tr
======================

Supported chips:

  * ST PM6764TR

    Prefix: 'pm6764tr'

    Addresses scanned: -

    Datasheet: http://www.st.com/resource/en/data_brief/pm6764.pdf

Authors:
	<hsu.yungteng@gmail.com>

Description:
------------

This driver supports the STMicroelectronics PM6764TR chip. The PM6764TR is a high
performance digital controller designed to power Intel's VR12.5 processors and memories.

The device utilizes digital technology to implement all control and power management
functions to provide maximum flexibility and performance. The NVM is embedded to store
custom configurations. The PM6764TR device features up to 4-phase programmable operation.

The PM6764TR supports power state transitions featuring VFDE, and programmable DPM
maintaining the best efficiency over all loading conditions without compromising transient
response. The device assures fast and independent protection against load overcurrent,
under/overvoltage and feedback disconnections.


code:
==================================
PMBus core driver and internal API
==================================

Introduction
============

[from pmbus.org] The Power Management Bus (PMBus) is an open standard
power-management protocol with a fully defined command language that facilitates
communication with power converters and other devices in a power system. The
protocol is implemented over the industry-standard SMBus serial interface and
enables programming, control, and real-time monitoring of compliant power
conversion products. This flexible and highly versatile standard allows for
communication between devices based on both analog and digital technologies, and
provides true interoperability which will reduce design complexity and shorten
time to market for power system designers. Pioneered by leading power supply and
semiconductor companies, this open power system standard is maintained and
promoted by the PMBus Implementers Forum (PMBus-IF), comprising 30+ adopters
with the objective to provide support to, and facilitate adoption among, users.

Unfortunately, while PMBus commands are standardized, there are no mandatory
commands, and manufacturers can add as many non-standard commands as they like.
Also, different PMBUs devices act differently if non-supported commands are
executed. Some devices return an error, some devices return 0xff or 0xffff and
set a status error flag, and some devices may simply hang up.

Despite all those difficulties, a generic PMBus device driver is still useful
and supported since kernel version 2.6.39. However, it was necessary to support
device specific extensions in addition to the core PMBus driver, since it is
simply unknown what new device specific functionality PMBus device developers
come up with next.

To make device specific extensions as scalable as possible, and to avoid having
to modify the core PMBus driver repeatedly for new devices, the PMBus driver was
split into core, generic, and device specific code. The core code (in
pmbus_core.c) provides generic functionality. The generic code (in pmbus.c)
provides support for generic PMBus devices. Device specific code is responsible
for device specific initialization and, if needed, maps device specific
functionality into generic functionality. This is to some degree comparable
to PCI code, where generic code is augmented as needed with quirks for all kinds
of devices.

PMBus device capabilities auto-detection
========================================

For generic PMBus devices, code in pmbus.c attempts to auto-detect all supported
PMBus commands. Auto-detection is somewhat limited, since there are simply too
many variables to consider. For example, it is almost impossible to autodetect
which PMBus commands are paged and which commands are replicated across all
pages (see the PMBus specification for details on multi-page PMBus devices).

For this reason, it often makes sense to provide a device specific driver if not
all commands can be auto-detected. The data structures in this driver can be
used to inform the core driver about functionality supported by individual
chips.

Some commands are always auto-detected. This applies to all limit commands
(lcrit, min, max, and crit attributes) as well as associated alarm attributes.
Limits and alarm attributes are auto-detected because there are simply too many
possible combinations to provide a manual configuration interface.

PMBus internal API
==================

The API between core and device specific PMBus code is defined in
drivers/hwmon/pmbus/pmbus.h. In addition to the internal API, pmbus.h defines
standard PMBus commands and virtual PMBus commands.

Standard PMBus commands
-----------------------

Standard PMBus commands (commands values 0x00 to 0xff) are defined in the PMBUs
specification.

Virtual PMBus commands
----------------------

Virtual PMBus commands are provided to enable support for non-standard
functionality which has been implemented by several chip vendors and is thus
desirable to support.

Virtual PMBus commands start with command value 0x100 and can thus easily be
distinguished from standard PMBus commands (which can not have values larger
than 0xff). Support for virtual PMBus commands is device specific and thus has
to be implemented in device specific code.

Virtual commands are named PMBUS_VIRT_xxx and start with PMBUS_VIRT_BASE. All
virtual commands are word sized.

There are currently two types of virtual commands.

- READ commands are read-only; writes are either ignored or return an error.
- RESET commands are read/write. Reading reset registers returns zero
  (used for detection), writing any value causes the associated history to be
  reset.

Virtual commands have to be handled in device specific driver code. Chip driver
code returns non-negative values if a virtual command is supported, or a
negative error code if not. The chip driver may return -ENODATA or any other
Linux error code in this case, though an error code other than -ENODATA is
handled more efficiently and thus preferred. Either case, the calling PMBus
core code will abort if the chip driver returns an error code when reading
or writing virtual registers (in other words, the PMBus core code will never
send a virtual command to a chip).

PMBus driver information
------------------------

PMBus driver information, defined in struct pmbus_driver_info, is the main means
for device specific drivers to pass information to the core PMBus driver.
Specifically, it provides the following information.

- For devices supporting its data in Direct Data Format, it provides coefficients
  for converting register values into normalized data. This data is usually
  provided by chip manufacturers in device datasheets.
- Supported chip functionality can be provided to the core driver. This may be
  necessary for chips which react badly if non-supported commands are executed,
  and/or to speed up device detection and initialization.
- Several function entry points are provided to support overriding and/or
  augmenting generic command execution. This functionality can be used to map
  non-standard PMBus commands to standard commands, or to augment standard
  command return values with device specific information.

PEC Support
===========

Many PMBus devices support SMBus PEC (Packet Error Checking). If supported
by both the I2C adapter and by the PMBus chip, it is by default enabled.
If PEC is supported, the PMBus core driver adds an attribute named 'pec' to
the I2C device. This attribute can be used to control PEC support in the
communication with the PMBus chip.

API functions
=============

Functions provided by chip driver
---------------------------------

All functions return the command return value (read) or zero (write) if
successful. A return value of -ENODATA indicates that there is no manufacturer
specific command, but that a standard PMBus command may exist. Any other
negative return value indicates that the commands does not exist for this
chip, and that no attempt should be made to read or write the standard
command.

As mentioned above, an exception to this rule applies to virtual commands,
which *must* be handled in driver specific code. See "Virtual PMBus Commands"
above for more details.

Command execution in the core PMBus driver code is as follows::

	if (chip_access_function) {
		status = chip_access_function();
		if (status != -ENODATA)
			return status;
	}
	if (command >= PMBUS_VIRT_BASE)	/* For word commands/registers only */
		return -EINVAL;
	return generic_access();

Chip drivers may provide pointers to the following functions in struct
pmbus_driver_info. All functions are optional.

::

  int (*read_byte_data)(struct i2c_client *client, int page, int reg);

Read byte from page <page>, register <reg>.
<page> may be -1, which means "current page".

::

  int (*read_word_data)(struct i2c_client *client, int page, int phase,
                        int reg);

Read word from page <page>, phase <pase>, register <reg>. If the chip does not
support multiple phases, the phase parameter can be ignored. If the chip
supports multiple phases, a phase value of 0xff indicates all phases.

::

  int (*write_word_data)(struct i2c_client *client, int page, int reg,
			 u16 word);

Write word to page <page>, register <reg>.

::

  int (*write_byte)(struct i2c_client *client, int page, u8 value);

Write byte to page <page>, register <reg>.
<page> may be -1, which means "current page".

::

  int (*identify)(struct i2c_client *client, struct pmbus_driver_info *info);

Determine supported PMBus functionality. This function is only necessary
if a chip driver supports multiple chips, and the chip functionality is not
pre-determined. It is currently only used by the generic pmbus driver
(pmbus.c).

Functions exported by core driver
---------------------------------

Chip drivers are expected to use the following functions to read or write
PMBus registers. Chip drivers may also use direct I2C commands. If direct I2C
commands are used, the chip driver code must not directly modify the current
page, since the selected page is cached in the core driver and the core driver
will assume that it is selected. Using pmbus_set_page() to select a new page
is mandatory.

::

  int pmbus_set_page(struct i2c_client *client, u8 page, u8 phase);

Set PMBus page register to <page> and <phase> for subsequent commands.
If the chip does not support multiple phases, the phase parameter is
ignored. Otherwise, a phase value of 0xff selects all phases.

::

  int pmbus_read_word_data(struct i2c_client *client, u8 page, u8 phase,
                           u8 reg);

Read word data from <page>, <phase>, <reg>. Similar to
i2c_smbus_read_word_data(), but selects page and phase first. If the chip does
not support multiple phases, the phase parameter is ignored. Otherwise, a phase
value of 0xff selects all phases.

::

  int pmbus_write_word_data(struct i2c_client *client, u8 page, u8 reg,
			    u16 word);

Write word data to <page>, <reg>. Similar to i2c_smbus_write_word_data(), but
selects page first.

::

  int pmbus_read_byte_data(struct i2c_client *client, int page, u8 reg);

Read byte data from <page>, <reg>. Similar to i2c_smbus_read_byte_data(), but
selects page first. <page> may be -1, which means "current page".

::

  int pmbus_write_byte(struct i2c_client *client, int page, u8 value);

Write byte data to <page>, <reg>. Similar to i2c_smbus_write_byte(), but
selects page first. <page> may be -1, which means "current page".

::

  void pmbus_clear_faults(struct i2c_client *client);

Execute PMBus "Clear Fault" command on all chip pages.
This function calls the device specific write_byte function if defined.
Therefore, it must _not_ be called from that function.

::

  bool pmbus_check_byte_register(struct i2c_client *client, int page, int reg);

Check if byte register exists. Return true if the register exists, false
otherwise.
This function calls the device specific write_byte function if defined to
obtain the chip status. Therefore, it must _not_ be called from that function.

::

  bool pmbus_check_word_register(struct i2c_client *client, int page, int reg);

Check if word register exists. Return true if the register exists, false
otherwise.
This function calls the device specific write_byte function if defined to
obtain the chip status. Therefore, it must _not_ be called from that function.

::

  int pmbus_do_probe(struct i2c_client *client, struct pmbus_driver_info *info);

Execute probe function. Similar to standard probe function for other drivers,
with the pointer to struct pmbus_driver_info as additional argument. Calls
identify function if supported. Must only be called from device probe
function.

::

  const struct pmbus_driver_info
	*pmbus_get_driver_info(struct i2c_client *client);

Return pointer to struct pmbus_driver_info as passed to pmbus_do_probe().

PMBus driver platform data
==========================

PMBus platform data is defined in include/linux/pmbus.h. Platform data
currently provides a flags field with four bits used::

	#define PMBUS_SKIP_STATUS_CHECK			BIT(0)

	#define PMBUS_WRITE_PROTECTED			BIT(1)

	#define PMBUS_NO_CAPABILITY			BIT(2)

	#define PMBUS_READ_STATUS_AFTER_FAILED_CHECK	BIT(3)

	struct pmbus_platform_data {
		u32 flags;              /* Device specific flags */

		/* regulator support */
		int num_regulators;
		struct regulator_init_data *reg_init_data;
	};

Flags
-----

PMBUS_SKIP_STATUS_CHECK

During register detection, skip checking the status register for
communication or command errors.

Some PMBus chips respond with valid data when trying to read an unsupported
register. For such chips, checking the status register is mandatory when
trying to determine if a chip register exists or not.
Other PMBus chips don't support the STATUS_CML register, or report
communication errors for no explicable reason. For such chips, checking the
status register must be disabled.

Some i2c controllers do not support single-byte commands (write commands with
no data, i2c_smbus_write_byte()). With such controllers, clearing the status
register is impossible, and the PMBUS_SKIP_STATUS_CHECK flag must be set.

PMBUS_WRITE_PROTECTED

Set if the chip is write protected and write protection is not determined
by the standard WRITE_PROTECT command.

PMBUS_NO_CAPABILITY

Some PMBus chips don't respond with valid data when reading the CAPABILITY
register. For such chips, this flag should be set so that the PMBus core
driver doesn't use CAPABILITY to determine it's behavior.

PMBUS_READ_STATUS_AFTER_FAILED_CHECK

Read the STATUS register after each failed register check.

Some PMBus chips end up in an undefined state when trying to read an
unsupported register. For such chips, it is necessary to reset the
chip pmbus controller to a known state after a failed register check.
This can be done by reading a known register. By setting this flag the
driver will try to read the STATUS register after each failed
register check. This read may fail, but it will put the chip into a
known state.


code:
Kernel driver pmbus
===================

Supported chips:

  * Flex BMR310, BMR453, BMR454, BMR456, BMR457, BMR458, BMR480,
    BMR490, BMR491, BMR492

    Prefixes: 'bmr310', 'bmr453', 'bmr454', 'bmr456', 'bmr457', 'bmr458', 'bmr480',
    'bmr490', 'bmr491', 'bmr492'

    Addresses scanned: -

    Datasheets:

	https://flexpowermodules.com/products

  * ON Semiconductor ADP4000, NCP4200, NCP4208

    Prefixes: 'adp4000', 'ncp4200', 'ncp4208'

    Addresses scanned: -

    Datasheets:

	https://www.onsemi.com/pub_link/Collateral/ADP4000-D.PDF

	https://www.onsemi.com/pub_link/Collateral/NCP4200-D.PDF

	https://www.onsemi.com/pub_link/Collateral/JUNE%202009-%20REV.%200.PDF

  * Lineage Power

    Prefixes: 'mdt040', 'pdt003', 'pdt006', 'pdt012', 'udt020'

    Addresses scanned: -

    Datasheets:

	http://www.lineagepower.com/oem/pdf/PDT003A0X.pdf

	http://www.lineagepower.com/oem/pdf/PDT006A0X.pdf

	http://www.lineagepower.com/oem/pdf/PDT012A0X.pdf

	http://www.lineagepower.com/oem/pdf/UDT020A0X.pdf

	http://www.lineagepower.com/oem/pdf/MDT040A0X.pdf

  * Texas Instruments TPS40400, TPS544B20, TPS544B25, TPS544C20, TPS544C25

    Prefixes: 'tps40400', 'tps544b20', 'tps544b25', 'tps544c20', 'tps544c25'

    Addresses scanned: -

    Datasheets:

	https://www.ti.com/lit/gpn/tps40400

	https://www.ti.com/lit/gpn/tps544b20

	https://www.ti.com/lit/gpn/tps544b25

	https://www.ti.com/lit/gpn/tps544c20

	https://www.ti.com/lit/gpn/tps544c25

  * Maxim MAX20796

    Prefix: 'max20796'

    Addresses scanned: -

    Datasheet:

	Not published

  * Generic PMBus devices

    Prefix: 'pmbus'

    Addresses scanned: -

    Datasheet: n.a.

Author: Guenter Roeck <linux@roeck-us.net>

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

This driver supports hardware monitoring for various PMBus compliant devices.
It supports voltage, current, power, and temperature sensors as supported
by the device.

Each monitored channel has its own high and low limits, plus a critical
limit.

Fan support will be added in a later version of this driver.

Usage Notes
-----------

This driver does not probe for PMBus devices, since there is no register
which can be safely used to identify the chip (The MFG_ID register is not
supported by all chips), and since there is no well defined address range for
PMBus devices. You will have to instantiate the devices explicitly.

Example: the following will load the driver for an LTC2978 at address 0x60
on I2C bus #1::

	$ modprobe pmbus
	$ echo ltc2978 0x60 > /sys/bus/i2c/devices/i2c-1/new_device

Platform data support
---------------------

Support for additional PMBus chips can be added by defining chip parameters in
a new chip specific driver file. For example, (untested) code to add support for
Emerson DS1200 power modules might look as follows::

  static struct pmbus_driver_info ds1200_info = {
	.pages = 1,
	/* Note: All other sensors are in linear mode */
	.direct[PSC_VOLTAGE_OUT] = true,
	.direct[PSC_TEMPERATURE] = true,
	.direct[PSC_CURRENT_OUT] = true,
	.m[PSC_VOLTAGE_IN] = 1,
	.b[PSC_VOLTAGE_IN] = 0,
	.R[PSC_VOLTAGE_IN] = 3,
	.m[PSC_VOLTAGE_OUT] = 1,
	.b[PSC_VOLTAGE_OUT] = 0,
	.R[PSC_VOLTAGE_OUT] = 3,
	.m[PSC_TEMPERATURE] = 1,
	.b[PSC_TEMPERATURE] = 0,
	.R[PSC_TEMPERATURE] = 3,
	.func[0] = PMBUS_HAVE_VIN | PMBUS_HAVE_IIN | PMBUS_HAVE_STATUS_INPUT
		   | PMBUS_HAVE_VOUT | PMBUS_HAVE_STATUS_VOUT
		   | PMBUS_HAVE_IOUT | PMBUS_HAVE_STATUS_IOUT
		   | PMBUS_HAVE_PIN | PMBUS_HAVE_POUT
		   | PMBUS_HAVE_TEMP | PMBUS_HAVE_STATUS_TEMP
		   | PMBUS_HAVE_FAN12 | PMBUS_HAVE_STATUS_FAN12,
  };

  static int ds1200_probe(struct i2c_client *client)
  {
	return pmbus_do_probe(client, &ds1200_info);
  }

  static const struct i2c_device_id ds1200_id[] = {
	{"ds1200", 0},
	{}
  };

  MODULE_DEVICE_TABLE(i2c, ds1200_id);

  /* This is the driver that will be inserted */
  static struct i2c_driver ds1200_driver = {
	.driver = {
		   .name = "ds1200",
		   },
	.probe_new = ds1200_probe,
	.id_table = ds1200_id,
  };

  static int __init ds1200_init(void)
  {
	return i2c_add_driver(&ds1200_driver);
  }

  static void __exit ds1200_exit(void)
  {
	i2c_del_driver(&ds1200_driver);
  }

Sysfs entries
-------------

When probing the chip, the driver identifies which PMBus registers are
supported, and determines available sensors from this information.
Attribute files only exist if respective sensors are supported by the chip.
Labels are provided to inform the user about the sensor associated with
a given sysfs entry.

The following attributes are supported. Limits are read-write; all other
attributes are read-only.

======================= ========================================================
inX_input		Measured voltage. From READ_VIN or READ_VOUT register.
inX_min			Minimum Voltage.
			From VIN_UV_WARN_LIMIT or VOUT_UV_WARN_LIMIT register.
inX_max			Maximum voltage.
			From VIN_OV_WARN_LIMIT or VOUT_OV_WARN_LIMIT register.
inX_lcrit		Critical minimum Voltage.
			From VIN_UV_FAULT_LIMIT or VOUT_UV_FAULT_LIMIT register.
inX_crit		Critical maximum voltage.
			From VIN_OV_FAULT_LIMIT or VOUT_OV_FAULT_LIMIT register.
inX_min_alarm		Voltage low alarm. From VOLTAGE_UV_WARNING status.
inX_max_alarm		Voltage high alarm. From VOLTAGE_OV_WARNING status.
inX_lcrit_alarm		Voltage critical low alarm.
			From VOLTAGE_UV_FAULT status.
inX_crit_alarm		Voltage critical high alarm.
			From VOLTAGE_OV_FAULT status.
inX_label		"vin", "vcap", or "voutY"
inX_rated_min		Minimum rated voltage.
			From MFR_VIN_MIN or MFR_VOUT_MIN register.
inX_rated_max		Maximum rated voltage.
			From MFR_VIN_MAX or MFR_VOUT_MAX register.

currX_input		Measured current. From READ_IIN or READ_IOUT register.
currX_max		Maximum current.
			From IIN_OC_WARN_LIMIT or IOUT_OC_WARN_LIMIT register.
currX_lcrit		Critical minimum output current.
			From IOUT_UC_FAULT_LIMIT register.
currX_crit		Critical maximum current.
			From IIN_OC_FAULT_LIMIT or IOUT_OC_FAULT_LIMIT register.
currX_alarm		Current high alarm.
			From IIN_OC_WARNING or IOUT_OC_WARNING status.
currX_max_alarm		Current high alarm.
			From IIN_OC_WARN_LIMIT or IOUT_OC_WARN_LIMIT status.
currX_lcrit_alarm	Output current critical low alarm.
			From IOUT_UC_FAULT status.
currX_crit_alarm	Current critical high alarm.
			From IIN_OC_FAULT or IOUT_OC_FAULT status.
currX_label		"iin", "iinY", "iinY.Z", "ioutY", or "ioutY.Z",
			where Y reflects the page number and Z reflects the
			phase.
currX_rated_max		Maximum rated current.
			From MFR_IIN_MAX or MFR_IOUT_MAX register.

powerX_input		Measured power. From READ_PIN or READ_POUT register.
powerX_cap		Output power cap. From POUT_MAX register.
powerX_max		Power limit. From PIN_OP_WARN_LIMIT or
			POUT_OP_WARN_LIMIT register.
powerX_crit		Critical output power limit.
			From POUT_OP_FAULT_LIMIT register.
powerX_alarm		Power high alarm.
			From PIN_OP_WARNING or POUT_OP_WARNING status.
powerX_crit_alarm	Output power critical high alarm.
			From POUT_OP_FAULT status.
powerX_label		"pin", "pinY", "pinY.Z", "poutY", or "poutY.Z",
			where Y reflects the page number and Z reflects the
			phase.
powerX_rated_max	Maximum rated power.
			From MFR_PIN_MAX or MFR_POUT_MAX register.

tempX_input		Measured temperature.
			From READ_TEMPERATURE_X register.
tempX_min		Minimum temperature. From UT_WARN_LIMIT register.
tempX_max		Maximum temperature. From OT_WARN_LIMIT register.
tempX_lcrit		Critical low temperature.
			From UT_FAULT_LIMIT register.
tempX_crit		Critical high temperature.
			From OT_FAULT_LIMIT register.
tempX_min_alarm		Chip temperature low alarm. Set by comparing
			READ_TEMPERATURE_X with UT_WARN_LIMIT if
			TEMP_UT_WARNING status is set.
tempX_max_alarm		Chip temperature high alarm. Set by comparing
			READ_TEMPERATURE_X with OT_WARN_LIMIT if
			TEMP_OT_WARNING status is set.
tempX_lcrit_alarm	Chip temperature critical low alarm. Set by comparing
			READ_TEMPERATURE_X with UT_FAULT_LIMIT if
			TEMP_UT_FAULT status is set.
tempX_crit_alarm	Chip temperature critical high alarm. Set by comparing
			READ_TEMPERATURE_X with OT_FAULT_LIMIT if
			TEMP_OT_FAULT status is set.
tempX_rated_min		Minimum rated temperature.
			From MFR_TAMBIENT_MIN register.
tempX_rated_max		Maximum rated temperature.
			From MFR_TAMBIENT_MAX, MFR_MAX_TEMP_1, MFR_MAX_TEMP_2 or
			MFR_MAX_TEMP_3 register.
======================= ========================================================


code:
Kernel driver powr1220
======================

Supported chips:

  * Lattice POWR1220AT8

    Prefix: 'powr1220'

    Addresses scanned: none

    Datasheet: Publicly available at the Lattice website

	       http://www.latticesemi.com/

Author: Scott Kanowitz <scott.kanowitz@gmail.com>

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

This driver supports the Lattice POWR1220AT8 chip. The POWR1220
includes voltage monitoring for 14 inputs as well as trim settings
for output voltages and GPIOs. This driver implements the voltage
monitoring portion of the chip.

Voltages are sampled by a 12-bit ADC with a step size of 2 mV.
An in-line attenuator allows measurements from 0 to 6 V. The
attenuator is enabled or disabled depending on the setting of the
input's max value. The driver will enable the attenuator for any
value over the low measurement range maximum of 2 V.

The input naming convention is as follows:

============== ========
driver name    pin name
============== ========
in0            VMON1
in1            VMON2
in2            VMON3
in2            VMON4
in4            VMON5
in5            VMON6
in6            VMON7
in7            VMON8
in8            VMON9
in9            VMON10
in10           VMON11
in11           VMON12
in12           VCCA
in13           VCCINP
============== ========

The ADC readings are updated on request with a minimum period of 1s.