Re: [PATCH] More i2c driver changes for 2.5.66

[Greg KH <greg@kroah.com>]

ChangeSet 1.1010, 2003/04/02 15:39:28-08:00, greg@kroah.com

i2c: remove old proc documentation and add sysfs file documentation


 Documentation/i2c/proc-interface  |   53 -----------
 Documentation/i2c/sysfs-interface |  177 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 177 insertions(+), 53 deletions(-)


diff -Nru a/Documentation/i2c/proc-interface b/Documentation/i2c/proc-interface
--- a/Documentation/i2c/proc-interface	Wed Apr  2 16:00:02 2003
+++ /dev/null	Wed Dec 31 16:00:00 1969
@@ -1,53 +0,0 @@
-i2c-core is the core i2c module (surprise!) which offers general routines on
-which other modules build. You will find that all i2c-related modules depend
-on this module, so it will (need to) be loaded whenever another i2c-related 
-module is loaded. Seen from the outside, the most interesting is the /proc 
-interface. Note that there is no corresponding sysctl interface!
-
-/proc/bus/i2c
-=============
-
-Whenever i2c-core is loaded, you will find a file /proc/bus/i2c, which lists
-all currently registered I2C adapters. Each line contains exactly one
-I2C adapter. Each line has the following format: "i2c-%d\t%9s\t%-32s't%-32s\n",
-which works out to four columns separated by tabs. Note that the file
-will be empty, if no adapters are registered at all.
-
-Adapters are numbered from 0 upwards. The first column contains the number
-of the adapter, for example "i2c-4" for adapter 4. The name listed is also
-the name of the /proc file which lists all devices attached to it, and
-of the /dev file which corresponds to this adapter.
-
-The second column documents what kind of adapter this is. Some adapters
-understand the full I2C protocol, others only a subset called SMBus,
-and yet others are some kind of pseudo-adapters that do not understand
-i2c at all. Possible values in here are "i2c", "smbus", "i2c/smbus"
-and "dummy". Because the SMBus protocol can be fully emulated by i2c
-adapters, if you see "i2c" here, SMBus is supported too. There may
-be some future adapters which support both specific SMBus commands and
-general I2C, and they will display "i2c/smbus".
-
-The third and fourth column are respectively the algorithm and adapter
-name of this adapter. Each adapter is associated with an algorithm,
-and several adapters can share the same algorithm. The combination of
-algorithm name and adapter name should be unique for an adapter, but
-you can't really count on that yet.
-
-
-/proc/bus/i2c-*
-===============
-
-Each registered adapter gets its own file in /proc/bus/, which lists
-the devices registered to the adapter. Each line in such a file contains
-one registered device. Each line has the following format:
-"%02x\t%-32s\t%-32s\n", which works out to three columns separated by
-tabs. Note that this file can be empty, if no devices are found on 
-the adapter.
-
-The first column contains the (hexadecimal) address of the client. As 
-only 7-bit addresses are supported at this moment, two digits are
-enough. 
-
-The second and third column are respectively the client name and the
-driver name of this client. Each client is associated with a driver,
-and several clients can share the same driver.
diff -Nru a/Documentation/i2c/sysfs-interface b/Documentation/i2c/sysfs-interface
--- /dev/null	Wed Dec 31 16:00:00 1969
+++ b/Documentation/i2c/sysfs-interface	Wed Apr  2 16:00:02 2003
@@ -0,0 +1,177 @@
+Naming and data format standards for sysfs files
+------------------------------------------------
+
+The libsensors library offers an interface to the raw sensors data
+through the sysfs interface. See libsensors documentation and source for
+more further information.
+
+An alternative method that some programs use is to access the sysfs
+files directly. This document briefly describes the standards that the
+drivers follow, so that an application program can scan for entries and
+access this data in a simple and consistent way.
+
+If you are developing a userspace application please send us feedback on
+this standard.
+
+Note that motherboards vary widely in the connections to sensor chips.
+There is no standard that ensures, for example, that the second
+temperature sensor is connected to the CPU, or that the second fan is on
+the CPU. Therefore, programs must provide a facility for the user to
+label or bind /proc entries for display.  Sensor chips often have unused
+inputs that should be ignored by user programs.
+
+Each chip gets its own directory in the sysfs /sys/devices tree.  To
+find all sensor chips, it is easier to follow the symlinks from
+/sys/i2c/devices/
+
+All sysfs values are fixed point numbers.  To get the true value of some
+of the values, you should divide by the specified value.
+
+There is only one value per file, unlike the older /proc specification.
+
+Alarms are direct indications read from the chips. The drivers do NOT
+make comparisons of readings to thresholds. This allows violations
+between readings to be caught and alarmed. The exact definition of an
+alarm (for example, whether a threshold must be met or must be exceeded
+to cause an alarm) is chip-dependent.
+
+
+-------------------------------------------------------------------------
+
+sysfs entries are as follows:
+
+
+Entry		Function
+-----		--------
+alarms		Alarm bitmask.
+		Read only.
+		Integer representation of one to four bytes.
+		A '1' bit means an alarm.
+		Chips should be programmed for 'comparator' mode so that
+		the alarm will 'come back' after you read the register
+		if it is still valid.
+		Generally a direct representation of a chip's internal
+		alarm registers; there is no standard for the position
+		of individual bits.
+		Bits are defined in kernel/include/sensors.h.
+
+beep_enable	Beep/interrupt enable
+		0 to disable.
+		1 to enable.
+		Read/Write
+
+beep_mask	Bitmask for beep.
+		Same format as 'alarms' with the same bit locations.
+		Read only.
+
+curr_max[1-n]	Current max value
+		Fixed point XXXXX, divide by 1000 to get Amps.
+		Read/Write.
+
+curr_min[1-n]	Current min or hysteresis value.
+		Preferably a hysteresis value, reported as a absolute
+		current, NOT a delta from the max value.
+		Fixed point XXXXX, divide by 1000 to get Amps.
+		Read/Write.
+
+curr_input[1-n]	Current input value
+		Fixed point XXXXX, divide by 1000 to get Amps.
+		Read only.
+		
+fan_min[1-3]	Fan minimum value
+		Integer value indicating RPM
+		Read/Write.
+
+fan_input[1-3]	Fan input value.
+		Integer value indicating RPM
+		Read only.
+
+fan_div[1-3]	Fan divisor.
+		Integers in powers of two (1,2,4,8,16,32,64,128).
+		Some chips only support values 1,2,4,8.
+		See doc/fan-divisors for details.
+
+in_min[0-8]	Voltage min value.
+		Fixed point value in form XXXX.  Divide by 1000 to get
+		Volts.
+		Read/Write
+		
+in_max[0-8]	Voltage max value.
+		Fixed point value in form XXXX.  Divide by 1000 to get
+		Volts.
+		Read/Write
+		
+in_input[0-8]	Voltage input value.
+		Fixed point value in form XXXX.  Divide by 1000 to get
+		Volts.
+		Read only
+		Actual voltage depends on the scaling resistors on the
+		motherboard, as recommended in the chip datasheet.
+		This varies by chip and by motherboard.
+		Because of this variation, values are generally NOT scaled
+		by the chip driver, and must be done by the application.
+		However, some drivers (notably lm87 and via686a)
+		do scale, with various degrees of success.
+		These drivers will output the actual voltage.
+		First two values are read/write and third is read only.
+		Typical usage:
+			in_*0	CPU #1 voltage (not scaled)
+			in_*1	CPU #1 voltage (not scaled)
+			in_*2	3.3V nominal (not scaled)
+			in_*3	5.0V nominal (scaled)
+			in_*4	12.0V nominal (scaled)
+			in_*5	-12.0V nominal (scaled)
+			in_*6	-5.0V nominal (scaled)
+			in_*7	varies
+			in_*8	varies
+
+pwm[1-3]	Pulse width modulation fan control.
+		Integer 0 - 255
+		Read/Write
+		255 is max or 100%.
+		Corresponds to the fans 1-3.
+
+pwm_enable[1-3] pwm enable
+		not always present even if pwm* is.
+		0 to turn off
+		1 to turn on
+		Read/Write
+
+sensor[1-3]	Sensor type selection.
+		Integers 1,2,3, or thermistor Beta value (3435)
+		Read/Write.
+
+temp_max[1-3]	Temperature max value.
+		Fixed point value in form XXXXX and should be divided by
+		1000 to get degrees Celsius.
+		Read/Write value.
+
+temp_min[1-3]	Temperature min or hysteresis value.
+		Fixed point value in form XXXXX and should be divided by
+		1000 to get degrees Celsius.  This is preferably a
+		hysteresis value, reported as a absolute temperature,
+		NOT a delta from the max value.
+		Read/Write value.
+
+temp_input[1-3] Temperature input value.
+		Read only value.
+
+		If there are multiple temperature sensors, temp_*1 is
+		generally the sensor inside the chip itself, generally
+		reported as "motherboard temperature".  temp_*2 and
+		temp_*3 are generally sensors external to the chip
+		itself, for example the thermal diode inside the CPU or
+		a thermistor nearby.
+
+vid		CPU core voltage.
+		Read only.
+		Fixed point value in form XXXX corresponding to CPU core
+		voltage as told to the sensor chip.  Divide by 1000 to
+		get Volts.  Not always correct.
+
+vrm		Voltage Regulator Module version number. 
+		Read only.
+		Two digit number (XX), first is major version, second is
+		minor version.
+		Affects the way the driver calculates the core voltage from
+		the vid pins. See doc/vid for details.