[lm-sensors] [PATCH] lm93 driver for 2.6, second try

[r.marek@sh.cvut.cz (Rudolf Marek)]

Hi,

I'm on holiday so I was able to go through documentation (limited time). Here is what I have done so far.

> 
> diff -Naur linux-2.6.13-rc3-mm3-original/Documentation/hwmon/lm93 linux-2.6.13-rc3-mm3/Documentation/hwmon/lm93
> --- linux-2.6.13-rc3-mm3-original/Documentation/hwmon/lm93	1970-01-01 00:00:00.000000000 +0000
> +++ linux-2.6.13-rc3-mm3/Documentation/hwmon/lm93	2005-08-01 18:12:12.000000000 +0000
> @@ -0,0 +1,410 @@
> +Kernel driver lm93
> +=========
> +
> +Supported chips:
> +  * National Semiconductor LM93
> +    Prefix 'lm93'

Should be > +    Prefix: 'lm93'

> +    Addresses scanned: I2C 0x2c-0x2e
> +    Datasheet: http://www.national.com/ds.cgi/LM/LM93.pdf
We like the html page with all the stuff more.
> +
> +Author:
> +	Mark M. Hoffman <mhoffman@lightlink.com>
> +	Ported to 2.6 by Eric J. Bowersox <ericb@aspsys.com>

Also we do not use tabs in this text files.

> +Module Parameters
> +-----------------
> +
> +(specific to LM93)
> +* init: integer
> +  Set to non-zero to force some initializations (default is 0).
> +* disable_block: integer
> +  A "0" allows SMBus block data transactions if the host supports them.  A "1"

Please avoid double spaces. Please fix it where is necessary.

> +  disables SMBus block data transactions.  The default is 0.
> +* vccp_limit_type: integer array (2)
> +  Configures in7 and in8 limit type, where 0 means absolute and non-zero
> +  means relative.  "Relative" here refers to "Dynamic Vccp Monitoring using
> +  VID" from the datasheet.  It greatly simplifies the interface to allow
> +  only one set of limits (absolute or relative) to be in operation at a
> +  time (even though the hardware is capable of enabling both).  There's
> +  not a compelling use case for enabling both at once, anyway.  The default
> +  is "0,0".
> +* vid_agtl: integer
> +  A "0" configures the VID pins for V(ih) = 2.1V min, V(il) = 0.8V max.
> +  A "1" configures the VID pins for V(ih) = 0.8V min, V(il) = 0.4V max.
> +  (The latter setting is referred to as AGTL+ Compatible in the datasheet.)
> +  I.e. this parameter controls the VID pin input thresholds; if your VID
> +  inputs are not working, try changing this.  The default value is "0".
> +

The rest here is not presented - because it is common,
> +(common among sensor drivers)
> +* force: short array (min = 1, max = 48)
> +  List of adapter,address pairs to assume to be present.  Autodetection
> +  of the target device will still be attempted.  Use one of the more
> +  specific force directives below if this doesn't detect the device.
> +* force_lm93: short array (min = 1, max = 48)
> +  List of adapter,address pairs which are unquestionably assumed to contain
> +  a 'lm93' chip
> +* ignore: short array (min = 1, max = 48)
> +  List of adapter,address pairs not to scan
> +* ignore_range: short array (min = 1, max = 48)
> +  List of adapter,start-addr,end-addr triples not to scan
> +* probe: short array (min = 1, max = 48)
> +  List of adapter,address pairs to scan additionally
> +* probe_range: short array (min = 1, max = 48)
> +  List of adapter,start-addr,end-addr triples to scan additionally

Please remove.

> +
> +Hardware Description
> +--------------------
> +
> +(from the datasheet)
> +
> +The LM93, hardware monitor, has a two wire digital interface compatible with
> +SMBus 2.0. Using an 8-bit ADC, the LM93 measures the temperature of two remote
> +diode connected transistors as well as its own die and 16 power supply
> +voltages. To set fan speed, the LM93 has two PWM outputs that are each
> +controlled by up to four temperature zones. The fancontrol algorithm is lookup
> +table based. The LM93 includes a digital filter that can be invoked to smooth
> +temperature readings for better control of fan speed. The LM93 has four
> +tachometer inputs to measure fan speed. Limit and status registers for all
> +measured values are included. The LM93 builds upon the functionality of
> +previous motherboard management ASICs and uses some of the LM85 s features
> +(i.e. smart tachometer mode). It also adds measurement and control support
> +for dynamic Vccp monitoring and PROCHOT. It is designed to monitor a dual
> +processor Xeon class motherboard with a minimum of external components.
> +
> +
> +Driver Description
> +------------------
> +
> +This driver implements support for the National Semiconductor LM93.
> +
> +
> +User Interface
> +--------------
> +
> +#PROCHOT:
> +
Can you please describe whatfor is this signal?

> +The LM93 can monitor two #PROCHOT signals.  The results are found in the
> +sysfs files prochot1, prochot2, prochot1_avg, prochot2_avg, prochot1_max,
> +and prochot2_max.  prochot1_max and prochot2_max contain the user limits
> +for #PROCHOT1 and #PROCHOT2, respectively.  prochot1 and prochot2 contain
> +the current readings for the most recent complete time interval.  The
> +value of prochot1_avg and prochot2_avg is something like a 2 period
> +exponential moving average (but not quite - check the datasheet). Note
> +that this third value is calculated by the chip itself.  All values range
> +from 0-255 where 0 indicates no throttling, and 255 indicates > 99.6%.
> +
> +The monitoring intervals for the two #PROCHOT signals is also configurable.
> +These intervals can be found in the sysfs files prochot1_interval and
> +prochot2_interval.  The values in these files specify the intervals for
> +#P1_PROCHOT and #P2_PROCHOT, respectively.  Selecting a value not in this
> +list will cause the driver to use the next largest interval.  The available
> +intervals are:
> +
> +#PROCHOT intervals: 0.73, 1.46, 2.9, 5.8, 11.7, 23.3, 46.6, 93.2, 186, 372
> +

What unit?

> +It is possible to configure the LM93 to logically short the two #PROCHOT
> +signals.  I.e. when #P1_PROCHOT is asserted, the LM93 will automatically
> +assert #P2_PROCHOT, and vice-versa.  This mode is enabled by writing a 
> +non-zero integer to the sysfs file prochot_short.
> +
> +The LM93 can also override the #PROCHOT pins by driving a PWM signal onto
> +one or both of them.  When overridden, the signal has a period of 3.56 mS,
> +a minimum pulse width of 5 clocks (at 22.5kHz => 6.25% duty cycle), and
> +a maximum pulse width of 80 clocks (at 22.5kHz => 99.88% duty cycle).
> +
> +The sysfs files prochot1_override and prochot2_override contain boolean
> +intgers which enable or disable the override function for #P1_PROCHOT and
> +#P2_PROCHOT, respectively.  The sysfs file prochot_override_duty_cycle
> +contains a value controlling the duty cycle for the PWM signal used when
> +the override function is enabled.  This value ranges from 0 to 15, with 0
> +indicating minimum duty cycle and 15 indicating maximum.
> +
> +#VRD_HOT:
> +
> +The LM93 can monitor two #VRD_HOT signals. The results are found in the

Also here why is noice to have it monitored.

> +sysfs files vrdhot1 and vrdhot2. There is one value per file: a boolean for
> +which 1 indicates #VRD_HOT is asserted and 0 indicates it is negated. These
> +files are read-only.
> +
> +Smart Tach Mode:
> +
> +(from the datasheet)
> +
> +	If a fan is driven using a low-side drive PWM, the tachometer
> +	output of the fan is corrupted. The LM93 includes smart tachometer
> +	circuitry that allows an accurate tachometer reading to be
> +	achieved despite the signal corruption.  In smart tach mode all
> +	four signals are measured within 4 seconds.
> +
> +Smart tach mode is enabled by the driver by writing 1 or 2 (associating the
> +the fan tachometer with a pwm) to the sysfs file fan<n>_smart_tach.  A zero
> +will disable the function for that fan.  Note that Smart tach mode cannot be
> +enabled if the PWM output frequency is 22500 Hz (see below).
> +
> +Manual PWM:
> +
> +The LM93 has a fixed or override mode for the two PWM outputs (although, there
> +are still some conditions that will override even this mode - see section
> +15.10.6 of the datasheet for details.)  The sysfs files pwm1_override
> +and pwm2_override are used to enable this mode; each is a boolean integer
> +where 0 disables and 1 enables the manual control mode.  The sysfs files pwm1
> +and pwm2 are used to set the manual duty cycle; each is an integer (0-255)
> +where 0 is 0% duty cycle, and 255 is 100%.  Note that the duty cycle values

Not everyone knows what is duty cycle can you add something like fan is stopped and fan goes
fullspeed? Tnx

> +are constrained by the hardware. Selecting a value which is not available
> +will cause the driver to use the next largest value.  Also note: when manual
> +PWM mode is disabled, the value of pwm1 and pwm2 indicates the current duty
> +cycle chosen by the h/w.
> +
> +PWM Output Frequency:
> +
> +The LM93 supports several different frequencies for the PWM output channels.
> +The sysfs files pwm1_freq and pwm2_freq are used to select the frequency. The
> +frequency values are constrained by the hardware.  Selecting a value which is
> +not available will cause the driver to use the next largest value.  Also note
> +that this parameter has implications for the Smart Tach Mode (see above).
> +
> +PWM Output Frequencies: 12, 36, 48, 60, 72, 84, 96, 22500 (h/w default)
> +
> +Automatic PWM:
> +
> +The LM93 is capable of complex automatic fan control, with many different
> +points of configuration.  To start, each PWM output can be bound to any 
> +combination of eight control sources.  The final PWM is the largest of all
> +individual control sources to which the PWM output is bound.
> +
> +The eight control sources are: temp1-temp4 (aka "zones" in the datasheet),
> +#PROCHOT 1 & 2, and #VRDHOT 1 & 2.  The bindings are expressed as a bitmask
> +in the sysfs files pwm<n>_auto_channels, where a "1" enables the binding, and
> + a "0" disables it. The h/w default is 0x0f (all temperatures bound).
> +
> +	0x01 - Temp 1
> +	0x02 - Temp 2
> +	0x04 - Temp 3
> +	0x08 - Temp 4
> +	0x10 - #PROCHOT 1
> +	0x20 - #PROCHOT 2
> +	0x40 - #VRDHOT 1
> +	0x80 - #VRDHOT 2
> +
> +The function y = f(x) takes a source temperature x to a PWM output y.  This
> +function of the LM93 is derived from a base temperature and a table of 12
> +temperature offsets.  The base temperature is expressed in degrees C in the
> +sysfs files temp<n>_auto_base.  The offsets are expressed in cumulative
> +degrees C, with the value of offset <i> for temperature value <n> being
> +contained in the file temp<n>_auto_offset<i>.  E.g. if the base temperature
> +is 40C:
> +
> +     offset #	temp<n>_auto_offset<i>	range		pwm
> +	 1		0		-		 25.00%
> +	 2		0		-		 28.57%
> +	 3		1		40C - 41C	 32.14%
> +	 4		1		41C - 42C	 35.71%
> +	 5		2		42C - 44C	 39.29%
> +	 6		2		44C - 46C	 42.86%
> +	 7		2		48C - 50C	 46.43%
> +	 8		2		50C - 52C	 50.00%
> +	 9		2		52C - 54C	 53.57%
> +	10		2		54C - 56C	 57.14%
> +	11		2		56C - 58C	 71.43%
> +	12		2		58C - 60C	 85.71%
> +					> 60C		100.00%
> +	
> +Valid offsets are in the range 0C <= x <= 7.5C in 0.5C increments.
> +
> +There is an independent base temperature for each temperature channel. Note,
> +however, there are only two tables of offsets: one each for temp[12] and
> +temp[34].  Therefore, any change to e.g. temp1_auto_offset<i> will also
> +affect temp2_auto_offset<i>.
> +
> +The LM93 can also apply hysteresis to the offset table, to prevent unwanted
> +oscillation between two steps in the offsets table.  These values are found in
> +the sysfs files temp<n>_auto_offset_hyst.  The value in this file has the
> +same representation as in temp<n>_auto_offset<i>.
> +
> +If a temperature reading falls below the base value for that channel, the LM93
> +will use the minimum PWM value.  These values are found in the sysfs files
> +temp<n>_auto_pwm_min.  Note, there are only two minimums: one each for temp[12]
> +and temp[34].  Therefore, any change to e.g. temp1_auto_pwm_min will also
> +affect temp2_auto_pwm_min.
> +
> +PWM Spin-Up Cycle:
> +
> +A spin-up cycle occurs when a PWM output is commanded from 0% duty cycle to
> +some value > 0%.  The LM93 supports a minimum duty cycle during spin-up.  These
> +values are found in the sysfs files pwm<n>_auto_spinup_min. The value in this
> +file has the same representation as other PWM duty cycle values. The
> +duration of the spin-up cycle is also configurable.  These values are found in
> +the sysfs files pwm<n>_auto_spinup_time. The value in this file is
> +the spin-up time in seconds.  The available spin-up times are constrained by
> +the hardware.  Selecting a value which is not available will cause the driver
> +to use the next largest value.
> +
> +Spin-up Durations: 0 (disabled, h/w default), 0.1, 0.25, 0.4, 0.7, 1.0,
> +		   2.0, 4.0
> +

what unit?

> +#PROCHOT and #VRDHOT PWM Ramping:
> +
> +If the #PROCHOT or #VRDHOT signals are asserted while bound to a PWM output
> +channel, the LM93 will ramp the PWM output up to 100% duty cycle in discrete
> +steps. The duration of each step is configurable. There are two files, with
> +one value each in seconds: pwm_auto_prochot_ramp and pwm_auto_vrdhot_ramp.
> +The available ramp times are constrained by the hardware.  Selecting a value
> +which is not available will cause the driver to use the next largest value.
> +
> +Ramp Times: 0 (disabled, h/w default) to 0.75 in 0.05 second intervals
> +
> +Fan Boost:
> +
> +For each temperature channel, there is a boost temperature: if the channel
> +exceeds this limit, the LM93 will immediately drive both PWM outputs to 100%.
> +This limit is expressed in degrees C in the sysfs files temp<n>_auto_boost.
> +There is also a hysteresis temperature for this function: after the boost
> +limit is reached, the temperature channel must drop below this value before
> +the boost function is disabled.  This temperature is also expressed in degrees
> +C in the sysfs files temp<n>_auto_boost_hyst.
> +
> +GPIO Pins:
> +
> +The LM93 can monitor the logic level of four dedicated GPIO pins as well as the
> +four tach input pins.  GPIO0-GPIO3 correspond to (fan) tach 1-4, respectively.
> +All eight GPIOs are read by reading the bitmask in the sysfs file gpio.  The
> +LSB is GPIO0, and the MSB is GPIO7.
> +
> +
> +LM93 Unique sysfs Files
> +-----------------------

Please look to other files how is this section done. (like in my w8792d patch recently)
http://www.google.com/url?sa=t&ct=res&cd=1&url=http%3A//lists.lm-sensors.org/pipermail/lm-sensors/2005-May/012391.html&ei=WVDzQrHNPL_WRPnspMQC

> +
> +	file			description
> +	-------------------------------------------------------------
> +
> +	prochot<n>		current #PROCHOT %, 

what value can be read written? What does it do?

We use [1-x] to dentote multiple files see rest documentation for and example.

> +
> +	prochot<n>_avg		moving average #PROCHOT %

What unit? if procents plese write it at least for first  time in words.

> +
> +	prochot<n>_max		limit #PROCHOT %
> +
> +	prochot_short		enable or disable logical #PROCHOT pin short

Please add something like 0, 1 to enable/disable.

> +
> +	prochot<n>_override	force #PROCHOT assertion as PWM
> +
> +	prochot_override_duty_cycle
> +				duty cycle for the PWM signal used when
> +				#PROCHOT is overridden
> +
> +	prochot<n>_interval	#PROCHOT PWM sampling interval
> +
> +	vrdhot<n>		0 means negated, 1 means asserted
> +
> +	fan<n>_smart_tach	enable or disable smart tach mode
> +
> +	pwm<n>_auto_channels	select control sources for PWM outputs
> +
> +	pwm<n>_auto_spinup_min	minimum duty cycle during spin-up
> +
> +	pwm<n>_auto_spinup_time	duration of spin-up
> +
> +	pwm_auto_prochot_ramp	ramp time per step when #PROCHOT asserted
> +
> +	pwm_auto_vrdhot_ramp	ramp time per step when #VRDHOT asserted
> +
> +	temp<n>_auto_base	temperature channel base
> +
> +	temp<n>_auto_offset[1-12]
> +				temperature channel offsets
> +
> +	temp<n>_auto_offset_hyst
> +				temperature channel offset hysteresis

Again in what units it is? Celsius? Is decimal dot allowed?
> +
> +	temp<n>_auto_boost	temperature channel boost (PWMs to 100%) limit
> +
> +	temp<n>_auto_boost_hyst	temperature channel boost hysteresis
> +
> +	gpio			input state of 8 GPIO pins; read-only
> +
> +
> +Sample Configuration File
> +-------------------------
> +
> +Here is a sample LM93 chip config for sensors.conf:
> +

DO we have it in lm_sensors package?

> +---------- cut here ----------
> +chip "lm93-*"
> +
> +# VOLTAGE INPUTS
> +
> +	# labels and scaling based on datasheet recommendations
> +	label in1	"+12V1"
> +	compute in1	@ * 12.945, @ / 12.945
> +	set in1_min	12 * 0.90
> +	set in1_max	12 * 1.10
> +
> +	label in2	"+12V2"
> +	compute in2	@ * 12.945, @ / 12.945
> +	set in2_min	12 * 0.90
> +	set in2_max	12 * 1.10
> +
> +	label in3	"+12V3"
> +	compute in3	@ * 12.945, @ / 12.945
> +	set in3_min	12 * 0.90
> +	set in3_max	12 * 1.10
> +
> +	label in4	"FSB_Vtt"
> +
> +	label in5	"3GIO"
> +
> +	label in6	"ICH_Core"
> +
> +	label in7	"Vccp1"
> +
> +	label in8	"Vccp2"
> +
> +	label in9	"+3.3V"
> +	set in9_min	3.3 * 0.90
> +	set in9_max	3.3 * 1.10
> +
> +	label in10	"+5V"
> +	set in10_min	5.0 * 0.90
> +	set in10_max	5.0 * 1.10
> +
> +	label in11	"SCSI_Core"
> +
> +	label in12	"Mem_Core"
> +
> +	label in13	"Mem_Vtt"
> +
> +	label in14	"Gbit_Core"
> +
> +	# Assuming R1/R2 = 4.1143, and 3.3V reference
> +	# -12V = (4.1143 + 1) * (@ - 3.3) + 3.3
> +	label in15	"-12V"
> +	compute in15 @ * 5.1143 - 13.57719, (@ + 13.57719) / 5.1143
> +	set in15_min	-12 * 0.90
> +	set in15_max	-12 * 1.10
> +
> +	label in16	"+3.3VSB"
> +	set in16_min	3.3 * 0.90
> +	set in16_max	3.3 * 1.10
> +
> +# TEMPERATURE INPUTS
> +
> +	label temp1	"CPU1"
> +	label temp2	"CPU2"
> +	label temp3	"LM93"
> +
> +# TACHOMETER INPUTS
> +
> +	label fan1	"Fan1"
> +	set fan1_min	3000
> +	label fan2	"Fan2"
> +	set fan2_min	3000
> +	label fan3	"Fan3"
> +	set fan3_min	3000
> +	label fan4	"Fan4"
> +	set fan4_min	3000
> +
> +# PWM OUTPUTS
> +
> +	label pwm1	"CPU1"
> +	label pwm2	"CPU2"
> +
> diff -Naur linux-2.6.13-rc3-mm3-original/drivers/hwmon/Kconfig linux-2.6.13-rc3-mm3/drivers/hwmon/Kconfig