| Kernel driver lm93 | |
| ================== | |
| Supported chips: | |
| * National Semiconductor LM93 | |
| Prefix 'lm93' | |
| Addresses scanned: I2C 0x2c-0x2e | |
| Datasheet: http://www.national.com/ds.cgi/LM/LM93.pdf | |
| Authors: | |
| Mark M. Hoffman <mhoffman@lightlink.com> | |
| Ported to 2.6 by Eric J. Bowersox <ericb@aspsys.com> | |
| Adapted to 2.6.20 by Carsten Emde <ce@osadl.org> | |
| Modified for mainline integration by Hans J. Koch <hjk@hansjkoch.de> | |
| Module Parameters | |
| ----------------- | |
| * 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" | |
| 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". | |
| 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. | |
| User Interface | |
| -------------- | |
| #PROCHOT: | |
| 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 (in seconds): | |
| #PROCHOT intervals: 0.73, 1.46, 2.9, 5.8, 11.7, 23.3, 46.6, 93.2, 186, 372 | |
| 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 | |
| integers 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 | |
| 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 | |
| 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 (in Hz): 12, 36, 48, 60, 72, 84, 96, 22500 (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 | |
| #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 | |
| ----------------------- | |
| file description | |
| ------------------------------------------------------------- | |
| prochot<n> current #PROCHOT % | |
| prochot<n>_avg moving average #PROCHOT % | |
| prochot<n>_max limit #PROCHOT % | |
| prochot_short enable or disable logical #PROCHOT pin short | |
| 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 | |
| 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 | |