[mirror_ubuntu-focal-kernel.git] / Documentation / hwmon / lm85.rst

Kernel driver lm85
==================

Supported chips:

  * National Semiconductor LM85 (B and C versions)

    Prefix: 'lm85b' or 'lm85c'

    Addresses scanned: I2C 0x2c, 0x2d, 0x2e

    Datasheet: http://www.national.com/pf/LM/LM85.html

  * Texas Instruments LM96000

    Prefix: 'lm9600'

    Addresses scanned: I2C 0x2c, 0x2d, 0x2e

    Datasheet: http://www.ti.com/lit/ds/symlink/lm96000.pdf

  * Analog Devices ADM1027

    Prefix: 'adm1027'

    Addresses scanned: I2C 0x2c, 0x2d, 0x2e

    Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADM1027

  * Analog Devices ADT7463

    Prefix: 'adt7463'

    Addresses scanned: I2C 0x2c, 0x2d, 0x2e

    Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADT7463

  * Analog Devices ADT7468

    Prefix: 'adt7468'

    Addresses scanned: I2C 0x2c, 0x2d, 0x2e

    Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADT7468

  * SMSC EMC6D100, SMSC EMC6D101

    Prefix: 'emc6d100'

    Addresses scanned: I2C 0x2c, 0x2d, 0x2e

    Datasheet: http://www.smsc.com/media/Downloads_Public/discontinued/6d100.pdf

  * SMSC EMC6D102

    Prefix: 'emc6d102'

    Addresses scanned: I2C 0x2c, 0x2d, 0x2e

    Datasheet: http://www.smsc.com/main/catalog/emc6d102.html

  * SMSC EMC6D103

    Prefix: 'emc6d103'

    Addresses scanned: I2C 0x2c, 0x2d, 0x2e

    Datasheet: http://www.smsc.com/main/catalog/emc6d103.html

  * SMSC EMC6D103S

    Prefix: 'emc6d103s'

    Addresses scanned: I2C 0x2c, 0x2d, 0x2e

    Datasheet: http://www.smsc.com/main/catalog/emc6d103s.html

Authors:
       - Philip Pokorny <ppokorny@penguincomputing.com>,
       - Frodo Looijaard <frodol@dds.nl>,
       - Richard Barrington <rich_b_nz@clear.net.nz>,
       - Margit Schubert-While <margitsw@t-online.de>,
       - Justin Thiessen <jthiessen@penguincomputing.com>

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

This driver implements support for the National Semiconductor LM85 and
compatible chips including the Analog Devices ADM1027, ADT7463, ADT7468 and
SMSC EMC6D10x chips family.

The LM85 uses the 2-wire interface compatible with the SMBUS 2.0
specification. Using an analog to digital converter it measures three (3)
temperatures and five (5) voltages. It has four (4) 16-bit counters for
measuring fan speed. Five (5) digital inputs are provided for sampling the
VID signals from the processor to the VRM. Lastly, there are three (3) PWM
outputs that can be used to control fan speed.

The voltage inputs have internal scaling resistors so that the following
voltage can be measured without external resistors:

  2.5V, 3.3V, 5V, 12V, and CPU core voltage (2.25V)

The temperatures measured are one internal diode, and two remote diodes.
Remote 1 is generally the CPU temperature. These inputs are designed to
measure a thermal diode like the one in a Pentium 4 processor in a socket
423 or socket 478 package. They can also measure temperature using a
transistor like the 2N3904.

A sophisticated control system for the PWM outputs is designed into the
LM85 that allows fan speed to be adjusted automatically based on any of the
three temperature sensors. Each PWM output is individually adjustable and
programmable. Once configured, the LM85 will adjust the PWM outputs in
response to the measured temperatures without further host intervention.
This feature can also be disabled for manual control of the PWM's.

Each of the measured inputs (voltage, temperature, fan speed) has
corresponding high/low limit values. The LM85 will signal an ALARM if any
measured value exceeds either limit.

The LM85 samples all inputs continuously. The lm85 driver will not read
the registers more often than once a second. Further, configuration data is
only read once each 5 minutes. There is twice as much config data as
measurements, so this would seem to be a worthwhile optimization.

Special Features
----------------

The LM85 has four fan speed monitoring modes. The ADM1027 has only two.
Both have special circuitry to compensate for PWM interactions with the
TACH signal from the fans. The ADM1027 can be configured to measure the
speed of a two wire fan, but the input conditioning circuitry is different
for 3-wire and 2-wire mode. For this reason, the 2-wire fan modes are not
exposed to user control. The BIOS should initialize them to the correct
mode. If you've designed your own ADM1027, you'll have to modify the
init_client function and add an insmod parameter to set this up.

To smooth the response of fans to changes in temperature, the LM85 has an
optional filter for smoothing temperatures. The ADM1027 has the same
config option but uses it to rate limit the changes to fan speed instead.

The ADM1027, ADT7463 and ADT7468 have a 10-bit ADC and can therefore
measure temperatures with 0.25 degC resolution. They also provide an offset
to the temperature readings that is automatically applied during
measurement. This offset can be used to zero out any errors due to traces
and placement. The documentation says that the offset is in 0.25 degC
steps, but in initial testing of the ADM1027 it was 1.00 degC steps. Analog
Devices has confirmed this "bug". The ADT7463 is reported to work as
described in the documentation. The current lm85 driver does not show the
offset register.

The ADT7468 has a high-frequency PWM mode, where all PWM outputs are
driven by a 22.5 kHz clock. This is a global mode, not per-PWM output,
which means that setting any PWM frequency above 11.3 kHz will switch
all 3 PWM outputs to a 22.5 kHz frequency. Conversely, setting any PWM
frequency below 11.3 kHz will switch all 3 PWM outputs to a frequency
between 10 and 100 Hz, which can then be tuned separately.

See the vendor datasheets for more information. There is application note
from National (AN-1260) with some additional information about the LM85.
The Analog Devices datasheet is very detailed and describes a procedure for
determining an optimal configuration for the automatic PWM control.

The SMSC EMC6D100 & EMC6D101 monitor external voltages, temperatures, and
fan speeds. They use this monitoring capability to alert the system to out
of limit conditions and can automatically control the speeds of multiple
fans in a PC or embedded system. The EMC6D101, available in a 24-pin SSOP
package, and the EMC6D100, available in a 28-pin SSOP package, are designed
to be register compatible. The EMC6D100 offers all the features of the
EMC6D101 plus additional voltage monitoring and system control features.
Unfortunately it is not possible to distinguish between the package
versions on register level so these additional voltage inputs may read
zero. EMC6D102 and EMC6D103 feature additional ADC bits thus extending precision
of voltage and temperature channels.

SMSC EMC6D103S is similar to EMC6D103, but does not support pwm#_auto_pwm_minctl
and temp#_auto_temp_off.

The LM96000 supports additional high frequency PWM modes (22.5 kHz, 24 kHz,
25.7 kHz, 27.7 kHz and 30 kHz), which can be configured on a per-PWM basis.

Hardware Configurations
-----------------------

The LM85 can be jumpered for 3 different SMBus addresses. There are
no other hardware configuration options for the LM85.

The lm85 driver detects both LM85B and LM85C revisions of the chip. See the
datasheet for a complete description of the differences. Other than
identifying the chip, the driver behaves no differently with regard to
these two chips. The LM85B is recommended for new designs.

The ADM1027, ADT7463 and ADT7468 chips have an optional SMBALERT output
that can be used to signal the chipset in case a limit is exceeded or the
temperature sensors fail. Individual sensor interrupts can be masked so
they won't trigger SMBALERT. The SMBALERT output if configured replaces one
of the other functions (PWM2 or IN0). This functionality is not implemented
in current driver.

The ADT7463 and ADT7468 also have an optional THERM output/input which can
be connected to the processor PROC_HOT output. If available, the autofan
control dynamic Tmin feature can be enabled to keep the system temperature
within spec (just?!) with the least possible fan noise.

Configuration Notes
-------------------

Besides standard interfaces driver adds following:

* Temperatures and Zones

Each temperature sensor is associated with a Zone. There are three
sensors and therefore three zones (# 1, 2 and 3). Each zone has the following
temperature configuration points:

* temp#_auto_temp_off
	- temperature below which fans should be off or spinning very low.
* temp#_auto_temp_min
	- temperature over which fans start to spin.
* temp#_auto_temp_max
	- temperature when fans spin at full speed.
* temp#_auto_temp_crit
	- temperature when all fans will run full speed.

PWM Control
^^^^^^^^^^^

There are three PWM outputs. The LM85 datasheet suggests that the
pwm3 output control both fan3 and fan4. Each PWM can be individually
configured and assigned to a zone for its control value. Each PWM can be
configured individually according to the following options.

* pwm#_auto_pwm_min
	- this specifies the PWM value for temp#_auto_temp_off
	  temperature. (PWM value from 0 to 255)

* pwm#_auto_pwm_minctl
	- this flags selects for temp#_auto_temp_off temperature
	  the behaviour of fans. Write 1 to let fans spinning at
	  pwm#_auto_pwm_min or write 0 to let them off.

.. note::

	It has been reported that there is a bug in the LM85 that causes
	the flag to be associated with the zones not the PWMs. This
	contradicts all the published documentation. Setting pwm#_min_ctl
	in this case actually affects all PWMs controlled by zone '#'.

PWM Controlling Zone selection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* pwm#_auto_channels
	- controls zone that is associated with PWM

Configuration choices:

========== =============================================
Value      Meaning
========== =============================================
      1    Controlled by Zone 1
      2    Controlled by Zone 2
      3    Controlled by Zone 3
     23    Controlled by higher temp of Zone 2 or 3
    123    Controlled by highest temp of Zone 1, 2 or 3
      0    PWM always 0%  (off)
     -1    PWM always 100%  (full on)
     -2    Manual control (write to 'pwm#' to set)
========== =============================================

The National LM85's have two vendor specific configuration
features. Tach. mode and Spinup Control. For more details on these,
see the LM85 datasheet or Application Note AN-1260. These features
are not currently supported by the lm85 driver.

The Analog Devices ADM1027 has several vendor specific enhancements.
The number of pulses-per-rev of the fans can be set, Tach monitoring
can be optimized for PWM operation, and an offset can be applied to
the temperatures to compensate for systemic errors in the
measurements. These features are not currently supported by the lm85
driver.

In addition to the ADM1027 features, the ADT7463 and ADT7468 also have
Tmin control and THERM asserted counts. Automatic Tmin control acts to
adjust the Tmin value to maintain the measured temperature sensor at a
specified temperature. There isn't much documentation on this feature in
the ADT7463 data sheet. This is not supported by current driver.
Commit	Line	Data
	1	Kernel driver lm85
	2	==================
	3
	4	Supported chips:
	5
	6	* National Semiconductor LM85 (B and C versions)
	7
	8	Prefix: 'lm85b' or 'lm85c'
	9
	10	Addresses scanned: I2C 0x2c, 0x2d, 0x2e
	11
	12	Datasheet: http://www.national.com/pf/LM/LM85.html
	13
	14	* Texas Instruments LM96000
	15
	16	Prefix: 'lm9600'
	17
	18	Addresses scanned: I2C 0x2c, 0x2d, 0x2e
	19
	20	Datasheet: http://www.ti.com/lit/ds/symlink/lm96000.pdf
	21
	22	* Analog Devices ADM1027
	23
	24	Prefix: 'adm1027'
	25
	26	Addresses scanned: I2C 0x2c, 0x2d, 0x2e
	27
	28	Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADM1027
	29
	30	* Analog Devices ADT7463
	31
	32	Prefix: 'adt7463'
	33
	34	Addresses scanned: I2C 0x2c, 0x2d, 0x2e
	35
	36	Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADT7463
	37
	38	* Analog Devices ADT7468
	39
	40	Prefix: 'adt7468'
	41
	42	Addresses scanned: I2C 0x2c, 0x2d, 0x2e
	43
	44	Datasheet: http://www.onsemi.com/PowerSolutions/product.do?id=ADT7468
	45
	46	* SMSC EMC6D100, SMSC EMC6D101
	47
	48	Prefix: 'emc6d100'
	49
	50	Addresses scanned: I2C 0x2c, 0x2d, 0x2e
	51
	52	Datasheet: http://www.smsc.com/media/Downloads_Public/discontinued/6d100.pdf
	53
	54	* SMSC EMC6D102
	55
	56	Prefix: 'emc6d102'
	57
	58	Addresses scanned: I2C 0x2c, 0x2d, 0x2e
	59
	60	Datasheet: http://www.smsc.com/main/catalog/emc6d102.html
	61
	62	* SMSC EMC6D103
	63
	64	Prefix: 'emc6d103'
	65
	66	Addresses scanned: I2C 0x2c, 0x2d, 0x2e
	67
	68	Datasheet: http://www.smsc.com/main/catalog/emc6d103.html
	69
	70	* SMSC EMC6D103S
	71
	72	Prefix: 'emc6d103s'
	73
	74	Addresses scanned: I2C 0x2c, 0x2d, 0x2e
	75
	76	Datasheet: http://www.smsc.com/main/catalog/emc6d103s.html
	77
	78	Authors:
	79	- Philip Pokorny <ppokorny@penguincomputing.com>,
	80	- Frodo Looijaard <frodol@dds.nl>,
	81	- Richard Barrington <rich_b_nz@clear.net.nz>,
	82	- Margit Schubert-While <margitsw@t-online.de>,
	83	- Justin Thiessen <jthiessen@penguincomputing.com>
	84
	85	Description
	86	-----------
	87
	88	This driver implements support for the National Semiconductor LM85 and
	89	compatible chips including the Analog Devices ADM1027, ADT7463, ADT7468 and
	90	SMSC EMC6D10x chips family.
	91
	92	The LM85 uses the 2-wire interface compatible with the SMBUS 2.0
	93	specification. Using an analog to digital converter it measures three (3)
	94	temperatures and five (5) voltages. It has four (4) 16-bit counters for
	95	measuring fan speed. Five (5) digital inputs are provided for sampling the
	96	VID signals from the processor to the VRM. Lastly, there are three (3) PWM
	97	outputs that can be used to control fan speed.
	98
	99	The voltage inputs have internal scaling resistors so that the following
	100	voltage can be measured without external resistors:
	101
	102	2.5V, 3.3V, 5V, 12V, and CPU core voltage (2.25V)
	103
	104	The temperatures measured are one internal diode, and two remote diodes.
	105	Remote 1 is generally the CPU temperature. These inputs are designed to
	106	measure a thermal diode like the one in a Pentium 4 processor in a socket
	107	423 or socket 478 package. They can also measure temperature using a
	108	transistor like the 2N3904.
	109
	110	A sophisticated control system for the PWM outputs is designed into the
	111	LM85 that allows fan speed to be adjusted automatically based on any of the
	112	three temperature sensors. Each PWM output is individually adjustable and
	113	programmable. Once configured, the LM85 will adjust the PWM outputs in
	114	response to the measured temperatures without further host intervention.
	115	This feature can also be disabled for manual control of the PWM's.
	116
	117	Each of the measured inputs (voltage, temperature, fan speed) has
	118	corresponding high/low limit values. The LM85 will signal an ALARM if any
	119	measured value exceeds either limit.
	120
	121	The LM85 samples all inputs continuously. The lm85 driver will not read
	122	the registers more often than once a second. Further, configuration data is
	123	only read once each 5 minutes. There is twice as much config data as
	124	measurements, so this would seem to be a worthwhile optimization.
	125
	126	Special Features
	127	----------------
	128
	129	The LM85 has four fan speed monitoring modes. The ADM1027 has only two.
	130	Both have special circuitry to compensate for PWM interactions with the
	131	TACH signal from the fans. The ADM1027 can be configured to measure the
	132	speed of a two wire fan, but the input conditioning circuitry is different
	133	for 3-wire and 2-wire mode. For this reason, the 2-wire fan modes are not
	134	exposed to user control. The BIOS should initialize them to the correct
	135	mode. If you've designed your own ADM1027, you'll have to modify the
	136	init_client function and add an insmod parameter to set this up.
	137
	138	To smooth the response of fans to changes in temperature, the LM85 has an
	139	optional filter for smoothing temperatures. The ADM1027 has the same
	140	config option but uses it to rate limit the changes to fan speed instead.
	141
	142	The ADM1027, ADT7463 and ADT7468 have a 10-bit ADC and can therefore
	143	measure temperatures with 0.25 degC resolution. They also provide an offset
	144	to the temperature readings that is automatically applied during
	145	measurement. This offset can be used to zero out any errors due to traces
	146	and placement. The documentation says that the offset is in 0.25 degC
	147	steps, but in initial testing of the ADM1027 it was 1.00 degC steps. Analog
	148	Devices has confirmed this "bug". The ADT7463 is reported to work as
	149	described in the documentation. The current lm85 driver does not show the
	150	offset register.
	151
	152	The ADT7468 has a high-frequency PWM mode, where all PWM outputs are
	153	driven by a 22.5 kHz clock. This is a global mode, not per-PWM output,
	154	which means that setting any PWM frequency above 11.3 kHz will switch
	155	all 3 PWM outputs to a 22.5 kHz frequency. Conversely, setting any PWM
	156	frequency below 11.3 kHz will switch all 3 PWM outputs to a frequency
	157	between 10 and 100 Hz, which can then be tuned separately.
	158
	159	See the vendor datasheets for more information. There is application note
	160	from National (AN-1260) with some additional information about the LM85.
	161	The Analog Devices datasheet is very detailed and describes a procedure for
	162	determining an optimal configuration for the automatic PWM control.
	163
	164	The SMSC EMC6D100 & EMC6D101 monitor external voltages, temperatures, and
	165	fan speeds. They use this monitoring capability to alert the system to out
	166	of limit conditions and can automatically control the speeds of multiple
	167	fans in a PC or embedded system. The EMC6D101, available in a 24-pin SSOP
	168	package, and the EMC6D100, available in a 28-pin SSOP package, are designed
	169	to be register compatible. The EMC6D100 offers all the features of the
	170	EMC6D101 plus additional voltage monitoring and system control features.
	171	Unfortunately it is not possible to distinguish between the package
	172	versions on register level so these additional voltage inputs may read
	173	zero. EMC6D102 and EMC6D103 feature additional ADC bits thus extending precision
	174	of voltage and temperature channels.
	175
	176	SMSC EMC6D103S is similar to EMC6D103, but does not support pwm#_auto_pwm_minctl
	177	and temp#_auto_temp_off.
	178
	179	The LM96000 supports additional high frequency PWM modes (22.5 kHz, 24 kHz,
	180	25.7 kHz, 27.7 kHz and 30 kHz), which can be configured on a per-PWM basis.
	181
	182	Hardware Configurations
	183	-----------------------
	184
	185	The LM85 can be jumpered for 3 different SMBus addresses. There are
	186	no other hardware configuration options for the LM85.
	187
	188	The lm85 driver detects both LM85B and LM85C revisions of the chip. See the
	189	datasheet for a complete description of the differences. Other than
	190	identifying the chip, the driver behaves no differently with regard to
	191	these two chips. The LM85B is recommended for new designs.
	192
	193	The ADM1027, ADT7463 and ADT7468 chips have an optional SMBALERT output
	194	that can be used to signal the chipset in case a limit is exceeded or the
	195	temperature sensors fail. Individual sensor interrupts can be masked so
	196	they won't trigger SMBALERT. The SMBALERT output if configured replaces one
	197	of the other functions (PWM2 or IN0). This functionality is not implemented
	198	in current driver.
	199
	200	The ADT7463 and ADT7468 also have an optional THERM output/input which can
	201	be connected to the processor PROC_HOT output. If available, the autofan
	202	control dynamic Tmin feature can be enabled to keep the system temperature
	203	within spec (just?!) with the least possible fan noise.
	204
	205	Configuration Notes
	206	-------------------
	207
	208	Besides standard interfaces driver adds following:
	209
	210	* Temperatures and Zones
	211
	212	Each temperature sensor is associated with a Zone. There are three
	213	sensors and therefore three zones (# 1, 2 and 3). Each zone has the following
	214	temperature configuration points:
	215
	216	* temp#_auto_temp_off
	217	- temperature below which fans should be off or spinning very low.
	218	* temp#_auto_temp_min
	219	- temperature over which fans start to spin.
	220	* temp#_auto_temp_max
	221	- temperature when fans spin at full speed.
	222	* temp#_auto_temp_crit
	223	- temperature when all fans will run full speed.
	224
	225	PWM Control
	226	^^^^^^^^^^^
	227
	228	There are three PWM outputs. The LM85 datasheet suggests that the
	229	pwm3 output control both fan3 and fan4. Each PWM can be individually
	230	configured and assigned to a zone for its control value. Each PWM can be
	231	configured individually according to the following options.
	232
	233	* pwm#_auto_pwm_min
	234	- this specifies the PWM value for temp#_auto_temp_off
	235	temperature. (PWM value from 0 to 255)
	236
	237	* pwm#_auto_pwm_minctl
	238	- this flags selects for temp#_auto_temp_off temperature
	239	the behaviour of fans. Write 1 to let fans spinning at
	240	pwm#_auto_pwm_min or write 0 to let them off.
	241
	242	.. note::
	243
	244	It has been reported that there is a bug in the LM85 that causes
	245	the flag to be associated with the zones not the PWMs. This
	246	contradicts all the published documentation. Setting pwm#_min_ctl
	247	in this case actually affects all PWMs controlled by zone '#'.
	248
	249	PWM Controlling Zone selection
	250	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
	251
	252	* pwm#_auto_channels
	253	- controls zone that is associated with PWM
	254
	255	Configuration choices:
	256
	257	========== =============================================
	258	Value Meaning
	259	========== =============================================
	260	1 Controlled by Zone 1
	261	2 Controlled by Zone 2
	262	3 Controlled by Zone 3
	263	23 Controlled by higher temp of Zone 2 or 3
	264	123 Controlled by highest temp of Zone 1, 2 or 3
	265	0 PWM always 0% (off)
	266	-1 PWM always 100% (full on)
	267	-2 Manual control (write to 'pwm#' to set)
	268	========== =============================================
	269
	270	The National LM85's have two vendor specific configuration
	271	features. Tach. mode and Spinup Control. For more details on these,
	272	see the LM85 datasheet or Application Note AN-1260. These features
	273	are not currently supported by the lm85 driver.
	274
	275	The Analog Devices ADM1027 has several vendor specific enhancements.
	276	The number of pulses-per-rev of the fans can be set, Tach monitoring
	277	can be optimized for PWM operation, and an offset can be applied to
	278	the temperatures to compensate for systemic errors in the
	279	measurements. These features are not currently supported by the lm85
	280	driver.
	281
	282	In addition to the ADM1027 features, the ADT7463 and ADT7468 also have
	283	Tmin control and THERM asserted counts. Automatic Tmin control acts to
	284	adjust the Tmin value to maintain the measured temperature sensor at a
	285	specified temperature. There isn't much documentation on this feature in
	286	the ADT7463 data sheet. This is not supported by current driver.