Re: [PATCH] More i2c driver changes for 2.5.66

Greg KH
2003-04-03T00:09:59Z

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.