New program doc-insmod.pl to automatically document the insmod

parameters of a module.


git-svn-id: http://lm-sensors.org/svn/lm-sensors/trunk@389 7894878c-1315-0410-8ee3-d5d059ff63e0

doc/chips/lm75

@@ -1,9 +1,17 @@
 Kernel driver `lm75.o'
+=====================
 
-Prefixes: lm75 (LM75, I2C)
+Status: Complete and well-tested
 
-This driver implements support for the National Semiconductor LM75, a
-`Digital Temperature Sensor and Thermal Watchdog with Two-Wire Interface'.
+Supported chips: 
+  * National Semiconductors LM75
+    Prefix: `lm75'
+    Addresses scanned: I2C 0x48 - 0x4f (inclusive)
+    Datasheet: Publicly available at the National Semiconductors website
+
+
+Description
+-----------
 
 The LM75 implements one temperature sensor. Limits can be set through the
 Overtemperature Shutdown register and Hysteris register. Each value can be 
@@ -11,19 +19,27 @@ set and read to half-degree accuracy.
 An alarm is issued (usually to a connected LM78) when the temperature
 gets higher then the Overtemperature Shutdown value; it stays on until
 the temperature falls below the Hysteris value.
-All temperatures are in degrees Celcius.
+All temperatures are in degrees Celcius, and are guaranteed within a 
+range of -55 to +125 degrees.
 
 The LM75 only updates its values each 1.5 seconds; reading it more often
 will do no harm, but will return 'old' values.
 
+The LM75 is usually used in combination with LM78-like chips, to measure
+the temperature of the processor(s).
 
-/proc and sysctl interface files:
-  * temp (LM75_SYSCTL_TEMP)
-    Overtemperature Shutdown Value (RW,1), Hysteris Value (RW,1) and Current 
-    Temperature (R,1).
 
-configuration file features:
-               NAME        LABEL CLASS     COMPUTE CLASS   RW
-               temp:                                       R 
-          temp_hyst:              temp              temp   RW
-          temp_over:              temp              temp   RW
+Configuration file features
+---------------------------
+
+          LABEL     LABEL CLASS   COMPUTE CLASS ACCESS MAGNITUDE
+           temp            NONE            NONE      R     1
+      temp_hyst            temp            temp      RW    1
+      temp_over            temp            temp      RW    1
+
+
+          LABEL                           FEATURE SYMBOL     SYSCTL FILE:OFFSET
+           temp                        SENSORS_LM75_TEMP            temp:3
+      temp_hyst                   SENSORS_LM75_TEMP_HYST            temp:2
+      temp_over                   SENSORS_LM75_TEMP_OVER            temp:1
+

prog/detect/sensors-detect

@@ -1,7 +1,7 @@
 #!/usr/bin/perl
 
 #
-#    detect.pl - Detect PCI bus and chips
+#    sensors-detect - Detect PCI bus and chips
 #    Copyright (c) 1998, 1999  Frodo Looijaard <frodol@dds.nl>
 #
 #    This program is free software; you can redistribute it and/or modify

prog/doc/doc-features.pl

@@ -1,5 +1,24 @@
 #!/usr/bin/perl
 
+#
+#    doc-features.pl - Generate module/library documentation
+#    Copyright (c) 1999  Frodo Looijaard <frodol@dds.nl>
+#
+#    This program is free software; you can redistribute it and/or modify
+#    it under the terms of the GNU General Public License as published by
+#    the Free Software Foundation; either version 2 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program; if not, write to the Free Software
+#    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+#
+
 use strict;
 
 # Features is a hash of references (indexed by SENSORS_*_PREFIX names) to 
@@ -196,13 +215,13 @@ sub scan_kernel_module
 # $_[0]: Base directory
 sub scan_all
 {
-  my ($prefix) = @_;
+  my ($prefix,@modules) = @_;
   my ($filename);
   scan_chips_h $prefix . "/lib/chips.h";
   scan_chips_c_1 $prefix . "/lib/chips.c";
   scan_chips_c_2 $prefix . "/lib/chips.c";
-  foreach $filename (glob ($prefix ."/kernel/chips/*.c")) { 
-    scan_kernel_module $filename 
+  foreach $filename (@modules) { 
+    scan_kernel_module "$prefix/kernel/chips/$filename"
   }
 }
 
@@ -244,11 +263,42 @@ sub initialize
   $feature_name{SENSORS_NO_MAPPING} = "NONE";
 }
 
+sub help_message
+{
+  print STDERR "Syntax: doc-features PATH MODULES...\n";
+  print STDERR "PATH is the path to the base of the lm_sensors tree.\n";
+  print STDERR "MODULES are the modules that need to be examined. If none ".
+               "are specified,\n".
+               "all modules are examined. Modules are looked for in ".
+               "PATH/kernel/chips\n.";
+}
+
+# @_: @ARGV
+# Returns ($base_dir,@modules)
+sub scan_arguments 
+{
+  my ($base_dir,@modules);
+  if (@_ < 1 or @_[0] =~ /^-/) {
+    help_message;
+    exit 0;
+  }
+  $base_dir = @_[0];
+  if (@_ == 1) {
+    @modules = map { substr $_, length "$base_dir/kernel/chips/" }
+                   glob "$base_dir/kernel/chips/*.c";
+  } else {
+    splice(@_,0,1);
+    @modules = map { $_ !~ /\./ ? $_.".c" : $_ } @_; 
+  }
+  return ($base_dir,@modules)
+}
 
 initialize;
-scan_all "../..";
+scan_all scan_arguments @ARGV;
 my $el;
 foreach $el (keys %features) {
-  output_data $el;
-  print "\n\n";
+  if (exists $sysctls{$features{$el}->{features}->[0]->{sysctl}}) {
+    output_data $el;
+    print "\n\n";
+  }
 }

prog/doc/doc-insmod.pl

@@ -0,0 +1,77 @@
+#!/usr/bin/perl
+
+#
+#    doc-insmod.pl - Generate documentation about insmod parameters.
+#    Copyright (c) 1998, 1999  Frodo Looijaard <frodol@dds.nl>
+#
+#    This program is free software; you can redistribute it and/or modify
+#    it under the terms of the GNU General Public License as published by
+#    the Free Software Foundation; either version 2 of the License, or
+#    (at your option) any later version.
+#
+#    This program is distributed in the hope that it will be useful,
+#    but WITHOUT ANY WARRANTY; without even the implied warranty of
+#    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#    GNU General Public License for more details.
+#
+#    You should have received a copy of the GNU General Public License
+#    along with this program; if not, write to the Free Software
+#    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+#
+
+# Use the following patch (apply by hand) if modinfo does not seem to terminate:
+#
+# *** /tmp/modutils-2.1.121/insmod/modinfo.c      Mon Sep 14 20:55:28 1998
+# --- modutils-2.1.121/insmod/modinfo.c   Wed Apr 14 20:54:38 1999
+# ***************
+# *** 457,462 ****
+#    error_file = "modinfo";
+#  
+#!   while (optind < argc)
+#      show_module_info(argv[optind], fmtstr, do_parameters);
+#  
+#    return 0;
+#--- 457,464 ----
+#    error_file = "modinfo";
+#  
+#!   while (optind < argc) {
+#      show_module_info(argv[optind], fmtstr, do_parameters);
+#+     optind ++;
+#+   }
+#  
+#    return 0;
+
+
+use strict;
+
+use Text::Wrap;
+
+# @_[0]: name and path of the kernel module
+sub print_info
+{
+  my ($modname) = @_;
+  my (@lines,$line,$option,$type,$desc);
+  print "Author: ", `modinfo -a $modname`, "\n";
+  print "Insmod Parameters\n";
+  print "-----------------\n";
+  print "\n";
+  open OPTIONS,"modinfo -p $modname|";
+  @lines = <OPTIONS>;
+  close OPTIONS;
+  foreach $line ( sort { $a cmp $b } @lines ) {
+    ($option,$type,$desc) = $line =~ /^(\S+) (.+), description "(.*)"$/;
+    print "* $option: $type\n";
+    print wrap("  ","  ",$desc),"\n";
+  }
+}
+
+if (@ARGV != 1 or @ARGV[0] =~ /^-/) {
+  print STDERR "Syntax: doc-insmod.pl MODULE\n";
+  print STDERR "MODULE should be the full path to a module name.\n";
+  print STDERR "This program is only tested with modutils-2,1.121.\n";
+  print STDERR "If it does not seem to terminate, you need to patch modinfo. ".
+               "Examine the source\n".
+               "code of doc-modules.pl to find the patch.\n";
+  exit 0;
+}
+print_info @ARGV