[lcd4linux @ 2000-03-19 08:41:28 by reinelt]

documentation available! README, README.MatrixOrbital, README.Drivers
added Skeleton.c as a starting point for new drivers

git-svn-id: https://ssl.bulix.org/svn/lcd4linux/trunk@14 3ae390bd-cb1e-0410-b409-cd5a39f66f1f

12 files changed, 344 insertions, 20 deletions

diff --git a/Makefile.am b/Makefile.am
index 38b15bf..8500ce5 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -14,6 +14,7 @@ lcd4linux_SOURCES = \
 	isdn.c isdn.h \
 	filter.c filter.h \
 	display.c display.h \
+	Skeleton.c \
 	MatrixOrbital.c
 
 
diff --git a/Makefile.in b/Makefile.in
index a500dd9..508d87f 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -68,7 +68,7 @@ CLEANFILES = *~
 AM_CFLAGS = -Wall
 
 bin_PROGRAMS = lcd4linux
-lcd4linux_SOURCES =  	lcd4linux.c 	cfg.c cfg.h 	parser.c parser.h 	system.c system.h 	isdn.c isdn.h 	filter.c filter.h 	display.c display.h 	MatrixOrbital.c
+lcd4linux_SOURCES =  	lcd4linux.c 	cfg.c cfg.h 	parser.c parser.h 	system.c system.h 	isdn.c isdn.h 	filter.c filter.h 	display.c display.h 	Skeleton.c 	MatrixOrbital.c
 
 ACLOCAL_M4 = $(top_srcdir)/aclocal.m4
 mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs
@@ -81,7 +81,7 @@ CPPFLAGS = @CPPFLAGS@
 LDFLAGS = @LDFLAGS@
 LIBS = @LIBS@
 lcd4linux_OBJECTS =  lcd4linux.o cfg.o parser.o system.o isdn.o filter.o \
-display.o MatrixOrbital.o
+display.o Skeleton.o MatrixOrbital.o
 lcd4linux_LDADD = $(LDADD)
 lcd4linux_DEPENDENCIES = 
 lcd4linux_LDFLAGS = 
@@ -89,7 +89,7 @@ CFLAGS = @CFLAGS@
 COMPILE = $(CC) $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
 CCLD = $(CC)
 LINK = $(CCLD) $(AM_CFLAGS) $(CFLAGS) $(LDFLAGS) -o $@
-DIST_COMMON =  COPYING INSTALL Makefile.am Makefile.in aclocal.m4 \
+DIST_COMMON =  README COPYING INSTALL Makefile.am Makefile.in aclocal.m4 \
 configure configure.in install-sh missing mkinstalldirs
 
 
@@ -97,9 +97,9 @@ DISTFILES = $(DIST_COMMON) $(SOURCES) $(HEADERS) $(TEXINFOS) $(EXTRA_DIST)
 
 TAR = tar
 GZIP_ENV = --best
-DEP_FILES =  .deps/MatrixOrbital.P .deps/cfg.P .deps/display.P \
-.deps/filter.P .deps/isdn.P .deps/lcd4linux.P .deps/parser.P \
-.deps/system.P
+DEP_FILES =  .deps/MatrixOrbital.P .deps/Skeleton.P .deps/cfg.P \
+.deps/display.P .deps/filter.P .deps/isdn.P .deps/lcd4linux.P \
+.deps/parser.P .deps/system.P
 SOURCES = $(lcd4linux_SOURCES)
 OBJECTS = $(lcd4linux_OBJECTS)
 
diff --git a/MatrixOrbital.c b/MatrixOrbital.c
index 0762b87..3ecefe4 100644
--- a/MatrixOrbital.c
+++ b/MatrixOrbital.c
@@ -1,6 +1,6 @@
-/* $Id: MatrixOrbital.c,v 1.7 2000/03/18 08:07:04 reinelt Exp $
+/* $Id: MatrixOrbital.c,v 1.8 2000/03/19 08:41:28 reinelt Exp $
  *
- *  driver for Matrix Orbital serial display modules
+ * driver for Matrix Orbital serial display modules
  *
  * Copyright 1999, 2000 by Michael Reinelt (reinelt@eunet.at)
  *
@@ -20,6 +20,11 @@
  *
  *
  * $Log: MatrixOrbital.c,v $
+ * Revision 1.8  2000/03/19 08:41:28  reinelt
+ *
+ * documentation available! README, README.MatrixOrbital, README.Drivers
+ * added Skeleton.c as a starting point for new drivers
+ *
  * Revision 1.7  2000/03/18 08:07:04  reinelt
  *
  * vertical bars implemented
diff --git a/README b/README
new file mode 100644
index 0000000..cde123f
--- /dev/null
+++ b/README
@@ -0,0 +1,130 @@
+#
+# $Id: README,v 1.1 2000/03/19 08:41:28 reinelt Exp $
+#
+
+This is the README file for lcd4linux
+
+
+INTRODUCTION 
+
+lcd4linux is a small program that reads various information from the kernel
+(and probably from other subsystems, especially ISDN) and displays them on a LCD.
+
+It supports displaying text values and different types of bars: Horizontal and
+vertical bars, logarithmic bars, split bars (two independent bars in one row).
+
+
+SUPPORTED DISPLAYS
+
+* Matrox Orbital <http://www.matrixorbital.com>
+	
+  "LCD0821": 2 lines by  8 characters
+  "LCD1621": 2 lines by 16 characters
+  "LCD2021": 2 lines by 20 characters
+  "LCD2041": 4 lines by 20 characters (tested)
+  "LCD4021": 2 lines by 40 characters
+
+* X11: not available now, but on top of my ToDo-List!
+
+* other displays: lcd4linux and especially the display driver code is very modular, 
+  so it should be quite easy to write a driver for any display. See README.driver
+  for details. Contributors are welcome!!!
+
+
+CONFIGURATION
+
+The configuration file (default: /etc/lcd4linux.conf) has a very simple format: 
+Every line consists of a key and a value, seperated by whitespace (blanks or tabs). 
+Values can contain whitespace, and can be enclosed in single or double quotes.
+A key must not contain whitespace. Keys are NOT case-sensitive. Order doesn't matter.
+
+The configuration file contains information for different modules of lcd4linux: 
+
+Global options:
+
+  tick: time in milliseconds between bar updates
+  tack: time in milliseconds between text updates (text can be updated less often than 
+        bars, so you get a smooth bar display and readable text)
+  tau:  time constant (in milliseconds) for damping function (not used by now)
+
+Data-specific options:
+
+  overload: load average threshold and bar scaling. The '%L' token (see below) displays 
+            a '!' instead of a blank if the current load average exceeds this value. 
+            load bars are scaled by this value (load=overload gives 100%)
+  fifo: path to fifo for communication with isdnlog (not implemented)
+  sensor1: path to the 1st temperature file (e.g. /proc/sys/dev/sensors/w83781d-isa-0290/temp1)
+           it is important that you use the isa sensors, because the i2c sensors are very slow!
+  sensor1_min: temperature where the corresponding bar starts
+  sensor1_max: temperature where bar ends
+  sensor[2..9], -_min, -_max: entries for the 2nd to 9th temperature sensor
+ 
+Driver-specific options:
+  
+  Display: the name of a display model (see "supported displays" above)
+  every driver has its own configuration options (e.g. 'Port', 'Speed', ...)
+  see README.<Drivername> for details!
+  
+Display options:
+  
+  row1: Text to display in row 1
+  row[2-max]: Text to display in other rows
+
+  The text to be displayed can contain specific directives, which will be replaced 
+  by the appropriate values, or will create bars:
+
+  '\nnn` will write the ASCII-character nnn (octal)
+  '%<token>' will be replaced by the value of <token>
+  '%%' will write a '%'
+  '%$' will write a '$'
+  '$<direction><length><token>[+<token>] will create a bar with the specified direction 
+   and length (in characters) with the value of <token>. If the driver supports dual bars,
+   you can specify the second value with '+<token>'. 
+   <direction> can be 'l' (left), 'r' (right), 'u' (up) or 'd' (down).
+   If you specify the direction in upper case, a logarithmic bar will be created.
+   note that the space occupied by a bar always grows from left to right or from top to
+   bottom, regardless of the direction!
+   
+Tokens:
+
+  'o',  operating system name ('Linux')
+  'v',  operating system release ('2.0.38')
+  'p',  processor ('i686')
+  'r',  total amount of memory installed (MB)
+  'mt', total memory from /proc/meminfo (kB)
+  'mu', used memory (kB)  
+  'mf', free memory (kB)
+  'ms', shared memory (kB)
+  'mb', buffers (kB)
+  'mc', page cache (kB)  
+  'ma', application memory (kB) = used - buffer - cache
+  'l1', load average for the past 1 minute
+  'l2', load average for the past 5 minutes
+  'l3', load average for the past 15 minutes
+  'L',  '!' if load > overload (from config)   
+  'cu', percentage of CPU in user mode
+  'cn', percentage of CPU in niced tasks
+  'cs', percentage of CPU in system mode
+  'cb', percentage of CPU busy (=100-idle)
+  'ci', percentage of CPU idle
+  'dr', disk blocks read
+  'dw', disk blocks written
+  'dt', disk blocks total (read+write)
+  'dm', disk blocks max (read, write)
+  'nr', network packets received
+  'nw', network packets transmitted
+  'nt', network packets total (receive+transmit)
+  'nm', network packets max (receive, transmit)
+  'ii', ISDN bytes received
+  'io', ISDN bytes sent
+  'it', ISDN bytes total (received+send)
+  'im', ISDN bytes max (received, send)
+  's1', T_SENSOR_1,   
+  's2', T_SENSOR_2,   
+  's3', T_SENSOR_3,   
+  's4', T_SENSOR_4,   
+  's5', T_SENSOR_5,   
+  's6', T_SENSOR_6,   
+  's7', T_SENSOR_7,   
+  's8', T_SENSOR_8,   
+  's9', T_SENSOR_9,   
diff --git a/README.Drivers b/README.Drivers
new file mode 100644
index 0000000..f5cccc5
--- /dev/null
+++ b/README.Drivers
@@ -0,0 +1,47 @@
+#
+# $Id: README.Drivers,v 1.1 2000/03/19 08:41:28 reinelt Exp $
+#
+
+How to write new display drivers for lcd4linux
+
+If you plan to write a new display driver for lcd4linux, you should follow
+this guidelines:
+
+* use Skeleton.c as a start point
+
+* create a new sourcefile <drivername>.c and add it to the bottom of Makefile.am
+
+* there's no need for a <drivername>.h
+
+* create one (or more) unique display names (your driver will be selected by
+  this name in the 'Display'-line of lcd4linux.conf).
+
+* include "display.h" in your driver, to get the DISPLAY structure and various 
+  BAR_ definitions
+
+* include "cfg.h" if you need to access settings in the config file.
+
+* create a DISPLAY table at the bottom of your driver, and fill it with the
+  appropriate values. Take care that you specify the correct bar capabilities
+  of your display or driver!
+
+* edit display.c and create a reference to your DISPLAY table:
+
+     external DISPLAY YourDriver[];
+
+* extend the FAMILY table in display.c with your driver:
+
+     FAMILY Driver[] = {
+       { "Skeleton",      Skeleton },
+       { "MatrixOrbital", MatrixOrbital },
+       { "YourFamily",    YourDriver },
+       { "" }
+     };
+
+* write the correspondig init(), clear(), put(), bar() and flush()-functions.
+  There's no need to use a framebuffer and display its contents with the flush()-
+  call (as in MatrixOrbital.c), you can directly write to the display in the put()- 
+  and bar()-functions, and use an empty flush()-function. But if you have a limited
+  number of user-defined characters, and therefore you have to do some sort of
+  'character reduction' or similar stuff, you will have to use a framebuffer and
+  the flush()-call. 
diff --git a/README.MatrixOrbital b/README.MatrixOrbital
new file mode 100644
index 0000000..1138b49
--- /dev/null
+++ b/README.MatrixOrbital
@@ -0,0 +1,40 @@
+#
+# $Id: README.MatrixOrbital,v 1.1 2000/03/19 08:41:28 reinelt Exp $
+#
+
+This is the README file for the MatrixOrbital display driver for lcd4linux
+
+This driver supports the serial interface alphanumeric display modules by
+Matrix Orbital Corporation (http://www.matrixorbital.com).
+
+I could only test it with the LCD2041 model, but I think every other (LCD) model 
+should work. These displays are supported:
+
+  LCD0821: 2 lines by  8 characters
+  LCD1621: 2 lines by 16 characters
+  LCD2021: 2 lines by 20 characters
+  LCD2041: 4 lines by 20 characters (tested)
+  LCD4021: 2 lines by 40 characters
+
+I could not test the vacuum fluorescent display models, but I think they should work, too.
+There are no entries for this models in the driver table (at the bottom of MatrixOrbital.c),
+but they could be easily added.
+
+The displays come with an RS-232 and an I2C interface. The driver supports the RS-232 interface
+only (because I have no idea how to find the I2C bus on my motherboard). 
+
+Power can be applied either via an external DC power supply, a modified floppy power connector
+(be aware that you can destroy your display if you get the pins wrong!) or via the RI (ring) 
+signal of the RS-232 port. I choosed the latter, and modified a serial card so that it supplies 
++5V from the ISA bus to this pin (again, be aware that this is dangerous if you connect any other 
+serial device to this modified port).
+
+The driver supports vertical, horizontal and split bars (two independent bars in one line),
+all bar types can be used simultanously. As the displays only have 8 user-defined characters,
+the needed characters to display all the bars must be reduced to 8. This is done by replacing
+characters with similar ones. To reduce flicker, a character which is displayed at the moment,
+will not be redefined, even if it's not used in this run. Only if the character compaction 
+fails, this characters will be redefined, too.
+
+The displays have a GPO (general purpose output), where you can connect a LED or something. 
+The driver supports controlling this GPO, but this function is unused by now.
diff --git a/Skeleton.c b/Skeleton.c
new file mode 100644
index 0000000..6522f34
--- /dev/null
+++ b/Skeleton.c
@@ -0,0 +1,78 @@
+/* $Id: Skeleton.c,v 1.1 2000/03/19 08:41:28 reinelt Exp $
+ *
+ * skeleton driver for new display modules
+ *
+ * Copyright 1999, 2000 by Michael Reinelt (reinelt@eunet.at)
+ *
+ * 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, 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.
+ *
+ *
+ * $Log: Skeleton.c,v $
+ * Revision 1.1  2000/03/19 08:41:28  reinelt
+ *
+ * documentation available! README, README.MatrixOrbital, README.Drivers
+ * added Skeleton.c as a starting point for new drivers
+ *
+ */
+
+/* 
+ *
+ * exported fuctions:
+ *
+ * struct DISPLAY Skeleton[]
+ *
+ */
+
+#include <stdlib.h>
+#include <stdio.h>
+
+#include "cfg.h"
+#include "display.h"
+
+static DISPLAY Display;
+
+int Skel_clear (void)
+{
+  return 0;
+}
+
+int Skel_init (DISPLAY *Self)
+{
+  Display=*Self;
+
+  Skel_clear();
+  return 0;
+}
+
+int Skel_put (int row, int col, char *text)
+{
+  return 0;
+}
+
+int Skel_bar (int type, int row, int col, int max, int len1, int len2)
+{
+  return 0;
+}
+
+int Skel_flush (void)
+{
+  return 0;
+}
+
+
+DISPLAY Skeleton[] = {
+  { "Skeleton", 4, 20, 5, 8, BAR_L | BAR_R, Skel_init, Skel_clear, Skel_put, Skel_bar, Skel_flush },
+  { "" }
+};
diff --git a/display.c b/display.c
index 96580c6..113babc 100644
--- a/display.c
+++ b/display.c
@@ -1,4 +1,4 @@
-/* $Id: display.c,v 1.7 2000/03/18 08:07:04 reinelt Exp $
+/* $Id: display.c,v 1.8 2000/03/19 08:41:28 reinelt Exp $
  *
  * framework for device drivers
  *
@@ -20,6 +20,11 @@
  *
  *
  * $Log: display.c,v $
+ * Revision 1.8  2000/03/19 08:41:28  reinelt
+ *
+ * documentation available! README, README.MatrixOrbital, README.Drivers
+ * added Skeleton.c as a starting point for new drivers
+ *
  * Revision 1.7  2000/03/18 08:07:04  reinelt
  *
  * vertical bars implemented
@@ -80,9 +85,11 @@
 #include "cfg.h"
 #include "display.h"
 
+extern DISPLAY Skeleton[];
 extern DISPLAY MatrixOrbital[];
 
 FAMILY Driver[] = {
+  { "Skeleton",      Skeleton },
   { "MatrixOrbital", MatrixOrbital },
   { "" }
 };
diff --git a/lcd4linux.c b/lcd4linux.c
index f006f97..f065022 100644
--- a/lcd4linux.c
+++ b/lcd4linux.c
@@ -1,4 +1,4 @@
-/* $Id: lcd4linux.c,v 1.6 2000/03/18 10:31:06 reinelt Exp $
+/* $Id: lcd4linux.c,v 1.7 2000/03/19 08:41:28 reinelt Exp $
  *
  * LCD4Linux
  *
@@ -20,6 +20,11 @@
  *
  *
  * $Log: lcd4linux.c,v $
+ * Revision 1.7  2000/03/19 08:41:28  reinelt
+ *
+ * documentation available! README, README.MatrixOrbital, README.Drivers
+ * added Skeleton.c as a starting point for new drivers
+ *
  * Revision 1.6  2000/03/18 10:31:06  reinelt
  *
  * added sensor handling (for temperature etc.)
@@ -69,7 +74,7 @@ int rows, cols, xres, yres, supported_bars;
 
 int token_usage[256]={0,};
 
-struct { int total, used, free, shared, buffer, cache, apps; } ram;
+struct { int total, used, free, shared, buffer, cache, avail; } ram;
 struct { double load1, load2, load3, overload; } load;
 struct { double user, nice, system, idle; } busy;
 struct { int read, write, total, max, peak; } disk;
@@ -90,7 +95,7 @@ static void collect_data (void)
   if (token_usage[C_MEM]) {
     Ram (&ram.total, &ram.free, &ram.shared, &ram.buffer, &ram.cache); 
     ram.used=ram.total-ram.free;
-    ram.apps=ram.used-ram.buffer-ram.cache;
+    ram.avail=ram.free+ram.buffer+ram.cache;
   }
   
   if (token_usage[C_LOAD]) {
@@ -145,8 +150,8 @@ static double query (int token)
     return ram.buffer;
   case T_MEM_CACHE:
     return ram.cache;
-  case T_MEM_APP:
-    return ram.apps;
+  case T_MEM_AVAIL:
+    return ram.avail;
 
   case T_LOAD_1:
     return load.load1;
@@ -220,7 +225,7 @@ static double query_bar (int token)
   case T_MEM_SHARED:
   case T_MEM_BUFFER:
   case T_MEM_CACHE:
-  case T_MEM_APP:
+  case T_MEM_AVAIL:
     return value/ram.total;
 
   case T_LOAD_1:
@@ -296,7 +301,7 @@ void print_token (int token, char **p)
   case T_MEM_SHARED:
   case T_MEM_BUFFER:
   case T_MEM_CACHE:
-  case T_MEM_APP:
+  case T_MEM_AVAIL:
     *p+=sprintf (*p, "%6.0f", query(token));
     break;
   case T_LOAD_1:
diff --git a/lcd4linux.conf.sample b/lcd4linux.conf.sample
index efcbe78..688cc23 100644
--- a/lcd4linux.conf.sample
+++ b/lcd4linux.conf.sample
@@ -26,6 +26,7 @@ Row4 "Net  %nm $R10nr+nw"
 Tick 100
 Tack 400
 Tau 500
+
 Overload 2.0
 
 Sensor1 /proc/sys/dev/sensors/w83781d-isa-0290/temp1
diff --git a/parser.c b/parser.c
index 2c7ac66..4d9346d 100644
--- a/parser.c
+++ b/parser.c
@@ -1,4 +1,4 @@
-/* $Id: parser.c,v 1.3 2000/03/18 10:31:06 reinelt Exp $
+/* $Id: parser.c,v 1.4 2000/03/19 08:41:28 reinelt Exp $
  *
  * row definition parser
  *
@@ -20,6 +20,11 @@
  *
  *
  * $Log: parser.c,v $
+ * Revision 1.4  2000/03/19 08:41:28  reinelt
+ *
+ * documentation available! README, README.MatrixOrbital, README.Drivers
+ * added Skeleton.c as a starting point for new drivers
+ *
  * Revision 1.3  2000/03/18 10:31:06  reinelt
  *
  * added sensor handling (for temperature etc.)
@@ -76,7 +81,7 @@ static SYMTAB Symtab[] = {{ "%",  T_PERCENT,    C_GENERIC, 0 },
 			  { "ms", T_MEM_SHARED, C_MEM,     1 },
 			  { "mb", T_MEM_BUFFER, C_MEM,     1 },
 			  { "mc", T_MEM_CACHE,  C_MEM,     1 },
-			  { "ma", T_MEM_APP,    C_MEM,     1 },
+			  { "ma", T_MEM_AVAIL,  C_MEM,     1 },
 			  { "l1", T_LOAD_1,     C_LOAD,    1 },
 			  { "l2", T_LOAD_2,     C_LOAD,    1 },
 			  { "l3", T_LOAD_3,     C_LOAD,    1 },
diff --git a/parser.h b/parser.h
index 8f42218..877f253 100644
--- a/parser.h
+++ b/parser.h
@@ -1,4 +1,4 @@
-/* $Id: parser.h,v 1.3 2000/03/18 10:31:06 reinelt Exp $
+/* $Id: parser.h,v 1.4 2000/03/19 08:41:28 reinelt Exp $
  *
  * row definition parser
  *
@@ -20,6 +20,11 @@
  *
  *
  * $Log: parser.h,v $
+ * Revision 1.4  2000/03/19 08:41:28  reinelt
+ *
+ * documentation available! README, README.MatrixOrbital, README.Drivers
+ * added Skeleton.c as a starting point for new drivers
+ *
  * Revision 1.3  2000/03/18 10:31:06  reinelt
  *
  * added sensor handling (for temperature etc.)
@@ -45,7 +50,7 @@
 typedef enum {
   T_PERCENT=128, T_DOLLAR,
   T_OS, T_RELEASE, T_CPU, T_RAM,
-  T_MEM_TOTAL, T_MEM_USED, T_MEM_FREE, T_MEM_SHARED, T_MEM_BUFFER, T_MEM_CACHE, T_MEM_APP, 
+  T_MEM_TOTAL, T_MEM_USED, T_MEM_FREE, T_MEM_SHARED, T_MEM_BUFFER, T_MEM_CACHE, T_MEM_AVAIL, 
   T_LOAD_1, T_LOAD_2, T_LOAD_3, T_OVERLOAD, 
   T_CPU_USER, T_CPU_NICE, T_CPU_SYSTEM, T_CPU_BUSY, T_CPU_IDLE,
   T_DISK_READ, T_DISK_WRITE, T_DISK_TOTAL, T_DISK_MAX,