[mirror_ubuntu-jammy-kernel.git] / Documentation / hwmon / adm9240.rst

Kernel driver adm9240
=====================

Supported chips:

  * Analog Devices ADM9240

    Prefix: 'adm9240'

    Addresses scanned: I2C 0x2c - 0x2f

    Datasheet: Publicly available at the Analog Devices website

	http://www.analog.com/UploadedFiles/Data_Sheets/79857778ADM9240_0.pdf

  * Dallas Semiconductor DS1780

    Prefix: 'ds1780'

    Addresses scanned: I2C 0x2c - 0x2f

    Datasheet: Publicly available at the Dallas Semiconductor (Maxim) website

	http://pdfserv.maxim-ic.com/en/ds/DS1780.pdf

  * National Semiconductor LM81

    Prefix: 'lm81'

    Addresses scanned: I2C 0x2c - 0x2f

    Datasheet: Publicly available at the National Semiconductor website

	http://www.national.com/ds.cgi/LM/LM81.pdf

Authors:
    - Frodo Looijaard <frodol@dds.nl>,
    - Philip Edelbrock <phil@netroedge.com>,
    - Michiel Rook <michiel@grendelproject.nl>,
    - Grant Coady <gcoady.lk@gmail.com> with guidance
      from Jean Delvare <jdelvare@suse.de>

Interface
---------
The I2C addresses listed above assume BIOS has not changed the
chip MSB 5-bit address. Each chip reports a unique manufacturer
identification code as well as the chip revision/stepping level.

Description
-----------
[From ADM9240] The ADM9240 is a complete system hardware monitor for
microprocessor-based systems, providing measurement and limit comparison
of up to four power supplies and two processor core voltages, plus
temperature, two fan speeds and chassis intrusion. Measured values can
be read out via an I2C-compatible serial System Management Bus, and values
for limit comparisons can be programmed in over the same serial bus. The
high speed successive approximation ADC allows frequent sampling of all
analog channels to ensure a fast interrupt response to any out-of-limit
measurement.

The ADM9240, DS1780 and LM81 are register compatible, the following
details are common to the three chips. Chip differences are described
after this section.


Measurements
------------
The measurement cycle

The adm9240 driver will take a measurement reading no faster than once
each two seconds. User-space may read sysfs interface faster than the
measurement update rate and will receive cached data from the most
recent measurement.

ADM9240 has a very fast 320us temperature and voltage measurement cycle
with independent fan speed measurement cycles counting alternating rising
edges of the fan tacho inputs.

DS1780 measurement cycle is about once per second including fan speed.

LM81 measurement cycle is about once per 400ms including fan speed.
The LM81 12-bit extended temperature measurement mode is not supported.

Temperature
-----------
On chip temperature is reported as degrees Celsius as 9-bit signed data
with resolution of 0.5 degrees Celsius. High and low temperature limits
are 8-bit signed data with resolution of one degree Celsius.

Temperature alarm is asserted once the temperature exceeds the high limit,
and is cleared when the temperature falls below the temp1_max_hyst value.

Fan Speed
---------
Two fan tacho inputs are provided, the ADM9240 gates an internal 22.5kHz
clock via a divider to an 8-bit counter. Fan speed (rpm) is calculated by:

rpm = (22500 * 60) / (count * divider)

Automatic fan clock divider

  * User sets 0 to fan_min limit

    - low speed alarm is disabled
    - fan clock divider not changed
    - auto fan clock adjuster enabled for valid fan speed reading

  * User sets fan_min limit too low

    - low speed alarm is enabled
    - fan clock divider set to max
    - fan_min set to register value 254 which corresponds
      to 664 rpm on adm9240
    - low speed alarm will be asserted if fan speed is
      less than minimum measurable speed
    - auto fan clock adjuster disabled

  * User sets reasonable fan speed

    - low speed alarm is enabled
    - fan clock divider set to suit fan_min
    - auto fan clock adjuster enabled: adjusts fan_min

  * User sets unreasonably high low fan speed limit

    - resolution of the low speed limit may be reduced
    - alarm will be asserted
    - auto fan clock adjuster enabled: adjusts fan_min

  * fan speed may be displayed as zero until the auto fan clock divider
    adjuster brings fan speed clock divider back into chip measurement
    range, this will occur within a few measurement cycles.

Analog Output
-------------
An analog output provides a 0 to 1.25 volt signal intended for an external
fan speed amplifier circuit. The analog output is set to maximum value on
power up or reset. This doesn't do much on the test Intel SE440BX-2.

Voltage Monitor

^^^^^^^^^^^^^^^

Voltage (IN) measurement is internally scaled:

    === =========== =========== ========= ==========
    nr  label       nominal     maximum   resolution
		      mV          mV         mV
    === =========== =========== ========= ==========
    0   +2.5V        2500        3320       13.0
    1   Vccp1        2700        3600       14.1
    2   +3.3V        3300        4380       17.2
    3     +5V        5000        6640       26.0
    4    +12V       12000       15940       62.5
    5   Vccp2        2700        3600       14.1
    === =========== =========== ========= ==========

The reading is an unsigned 8-bit value, nominal voltage measurement is
represented by a reading of 192, being 3/4 of the measurement range.

An alarm is asserted for any voltage going below or above the set limits.

The driver reports and accepts voltage limits scaled to the above table.

VID Monitor
-----------
The chip has five inputs to read the 5-bit VID and reports the mV value
based on detected CPU type.

Chassis Intrusion
-----------------
An alarm is asserted when the CI pin goes active high. The ADM9240
Datasheet has an example of an external temperature sensor driving
this pin. On an Intel SE440BX-2 the Chassis Intrusion header is
connected to a normally open switch.

The ADM9240 provides an internal open drain on this line, and may output
a 20 ms active low pulse to reset an external Chassis Intrusion latch.

Clear the CI latch by writing value 0 to the sysfs intrusion0_alarm file.

Alarm flags reported as 16-bit word

    ===     =============       ==========================
    bit     label               comment
    ===     =============       ==========================
     0      +2.5 V_Error        high or low limit exceeded
     1      VCCP_Error          high or low limit exceeded
     2      +3.3 V_Error        high or low limit exceeded
     3      +5 V_Error          high or low limit exceeded
     4      Temp_Error          temperature error
     6      FAN1_Error          fan low limit exceeded
     7      FAN2_Error          fan low limit exceeded
     8      +12 V_Error         high or low limit exceeded
     9      VCCP2_Error         high or low limit exceeded
    12      Chassis_Error       CI pin went high
    ===     =============       ==========================

Remaining bits are reserved and thus undefined. It is important to note
that alarm bits may be cleared on read, user-space may latch alarms and
provide the end-user with a method to clear alarm memory.
Commit	Line	Data
a0ef1483 GC	1	Kernel driver adm9240
	2	=====================
	3
	4	Supported chips:
b04f2f7d	5
a0ef1483	6	* Analog Devices ADM9240
b04f2f7d	7
a0ef1483	8	Prefix: 'adm9240'
b04f2f7d	9
a0ef1483	10	Addresses scanned: I2C 0x2c - 0x2f
b04f2f7d	11
a0ef1483	12	Datasheet: Publicly available at the Analog Devices website
b04f2f7d MCC	13
b04f2f7d MCC	14	http://www.analog.com/UploadedFiles/Data_Sheets/79857778ADM9240_0.pdf
a0ef1483 GC	15
a0ef1483 GC	16	* Dallas Semiconductor DS1780
b04f2f7d	17
a0ef1483	18	Prefix: 'ds1780'
b04f2f7d	19
a0ef1483	20	Addresses scanned: I2C 0x2c - 0x2f
b04f2f7d	21
a0ef1483	22	Datasheet: Publicly available at the Dallas Semiconductor (Maxim) website
b04f2f7d MCC	23
b04f2f7d MCC	24	http://pdfserv.maxim-ic.com/en/ds/DS1780.pdf
a0ef1483 GC	25
a0ef1483 GC	26	* National Semiconductor LM81
b04f2f7d	27
a0ef1483	28	Prefix: 'lm81'
b04f2f7d	29
a0ef1483	30	Addresses scanned: I2C 0x2c - 0x2f
b04f2f7d	31
a0ef1483	32	Datasheet: Publicly available at the National Semiconductor website
b04f2f7d MCC	33
b04f2f7d MCC	34	http://www.national.com/ds.cgi/LM/LM81.pdf
a0ef1483 GC	35
a0ef1483 GC	36	Authors:
b04f2f7d MCC	37	- Frodo Looijaard <frodol@dds.nl>,
	38	- Philip Edelbrock <phil@netroedge.com>,
	39	- Michiel Rook <michiel@grendelproject.nl>,
	40	- Grant Coady <gcoady.lk@gmail.com> with guidance
	41	from Jean Delvare <jdelvare@suse.de>
a0ef1483 GC	42
	43	Interface
	44	---------
	45	The I2C addresses listed above assume BIOS has not changed the
	46	chip MSB 5-bit address. Each chip reports a unique manufacturer
	47	identification code as well as the chip revision/stepping level.
	48
	49	Description
	50	-----------
	51	[From ADM9240] The ADM9240 is a complete system hardware monitor for
	52	microprocessor-based systems, providing measurement and limit comparison
	53	of up to four power supplies and two processor core voltages, plus
	54	temperature, two fan speeds and chassis intrusion. Measured values can
	55	be read out via an I2C-compatible serial System Management Bus, and values
	56	for limit comparisons can be programmed in over the same serial bus. The
	57	high speed successive approximation ADC allows frequent sampling of all
	58	analog channels to ensure a fast interrupt response to any out-of-limit
	59	measurement.
	60
	61	The ADM9240, DS1780 and LM81 are register compatible, the following
	62	details are common to the three chips. Chip differences are described
	63	after this section.
	64
	65
	66	Measurements
	67	------------
	68	The measurement cycle
	69
	70	The adm9240 driver will take a measurement reading no faster than once
	71	each two seconds. User-space may read sysfs interface faster than the
	72	measurement update rate and will receive cached data from the most
	73	recent measurement.
	74
	75	ADM9240 has a very fast 320us temperature and voltage measurement cycle
	76	with independent fan speed measurement cycles counting alternating rising
	77	edges of the fan tacho inputs.
	78
	79	DS1780 measurement cycle is about once per second including fan speed.
	80
	81	LM81 measurement cycle is about once per 400ms including fan speed.
	82	The LM81 12-bit extended temperature measurement mode is not supported.
	83
	84	Temperature
	85	-----------
	86	On chip temperature is reported as degrees Celsius as 9-bit signed data
	87	with resolution of 0.5 degrees Celsius. High and low temperature limits
	88	are 8-bit signed data with resolution of one degree Celsius.
	89
	90	Temperature alarm is asserted once the temperature exceeds the high limit,
	91	and is cleared when the temperature falls below the temp1_max_hyst value.
	92
	93	Fan Speed
	94	---------
	95	Two fan tacho inputs are provided, the ADM9240 gates an internal 22.5kHz
	96	clock via a divider to an 8-bit counter. Fan speed (rpm) is calculated by:
	97
	98	rpm = (22500 * 60) / (count * divider)
	99
	100	Automatic fan clock divider
	101
	102	* User sets 0 to fan_min limit
b04f2f7d	103
a0ef1483 GC	104	- low speed alarm is disabled
	105	- fan clock divider not changed
	106	- auto fan clock adjuster enabled for valid fan speed reading
	107
	108	* User sets fan_min limit too low
b04f2f7d	109
a0ef1483 GC	110	- low speed alarm is enabled
	111	- fan clock divider set to max
	112	- fan_min set to register value 254 which corresponds
	113	to 664 rpm on adm9240
	114	- low speed alarm will be asserted if fan speed is
	115	less than minimum measurable speed
	116	- auto fan clock adjuster disabled
	117
	118	* User sets reasonable fan speed
b04f2f7d	119
a0ef1483 GC	120	- low speed alarm is enabled
	121	- fan clock divider set to suit fan_min
	122	- auto fan clock adjuster enabled: adjusts fan_min
	123
	124	* User sets unreasonably high low fan speed limit
b04f2f7d	125
a0ef1483 GC	126	- resolution of the low speed limit may be reduced
	127	- alarm will be asserted
	128	- auto fan clock adjuster enabled: adjusts fan_min
	129
b04f2f7d MCC	130	* fan speed may be displayed as zero until the auto fan clock divider
	131	adjuster brings fan speed clock divider back into chip measurement
	132	range, this will occur within a few measurement cycles.
a0ef1483 GC	133
	134	Analog Output
	135	-------------
	136	An analog output provides a 0 to 1.25 volt signal intended for an external
	137	fan speed amplifier circuit. The analog output is set to maximum value on
	138	power up or reset. This doesn't do much on the test Intel SE440BX-2.
	139
	140	Voltage Monitor
	141
b04f2f7d MCC	142	^^^^^^^^^^^^^^^
b04f2f7d MCC	143
a0ef1483 GC	144	Voltage (IN) measurement is internally scaled:
a0ef1483 GC	145
b04f2f7d	146	=== =========== =========== ========= ==========
a0ef1483	147	nr label nominal maximum resolution
b04f2f7d MCC	148	mV mV mV
b04f2f7d MCC	149	=== =========== =========== ========= ==========
a0ef1483 GC	150	0 +2.5V 2500 3320 13.0
	151	1 Vccp1 2700 3600 14.1
	152	2 +3.3V 3300 4380 17.2
	153	3 +5V 5000 6640 26.0
	154	4 +12V 12000 15940 62.5
	155	5 Vccp2 2700 3600 14.1
b04f2f7d	156	=== =========== =========== ========= ==========
a0ef1483 GC	157
	158	The reading is an unsigned 8-bit value, nominal voltage measurement is
	159	represented by a reading of 192, being 3/4 of the measurement range.
	160
	161	An alarm is asserted for any voltage going below or above the set limits.
	162
	163	The driver reports and accepts voltage limits scaled to the above table.
	164
	165	VID Monitor
	166	-----------
	167	The chip has five inputs to read the 5-bit VID and reports the mV value
	168	based on detected CPU type.
	169
	170	Chassis Intrusion
	171	-----------------
	172	An alarm is asserted when the CI pin goes active high. The ADM9240
	173	Datasheet has an example of an external temperature sensor driving
	174	this pin. On an Intel SE440BX-2 the Chassis Intrusion header is
	175	connected to a normally open switch.
	176
	177	The ADM9240 provides an internal open drain on this line, and may output
	178	a 20 ms active low pulse to reset an external Chassis Intrusion latch.
	179
0de2b244	180	Clear the CI latch by writing value 0 to the sysfs intrusion0_alarm file.
a0ef1483 GC	181
	182	Alarm flags reported as 16-bit word
	183
b04f2f7d	184	=== ============= ==========================
a0ef1483	185	bit label comment
b04f2f7d	186	=== ============= ==========================
a0ef1483 GC	187	0 +2.5 V_Error high or low limit exceeded
	188	1 VCCP_Error high or low limit exceeded
	189	2 +3.3 V_Error high or low limit exceeded
	190	3 +5 V_Error high or low limit exceeded
	191	4 Temp_Error temperature error
	192	6 FAN1_Error fan low limit exceeded
	193	7 FAN2_Error fan low limit exceeded
	194	8 +12 V_Error high or low limit exceeded
	195	9 VCCP2_Error high or low limit exceeded
	196	12 Chassis_Error CI pin went high
b04f2f7d	197	=== ============= ==========================
a0ef1483 GC	198
	199	Remaining bits are reserved and thus undefined. It is important to note
	200	that alarm bits may be cleared on read, user-space may latch alarms and
	201	provide the end-user with a method to clear alarm memory.