update documentation to reality (as far as I know it ;-)

docs/API-v0.5.txt

@@ -23,18 +23,27 @@ I will walk through the driver struct here.
 
 typedef struct lcd_logical_driver {
 
-	//////// Variables in the driver module
+	//////// Variables to be provided by the driver module
 	// The driver loader will look for symbols with these names !
-	char *api_version;
-	int *stay_in_foreground;	// Does this driver require to be in foreground ?
-	int *does_input;	// Does this driver do output ?
-	int *does_output;	// Does this driver do output ?
 
+	// pointer to a string describing the API version
+	char *api_version;
+
+	// Does this driver require to be in foreground ?
+	int *stay_in_foreground;// Does this driver require to be in foreground ?
+
+	/ Does this driver support multiple instances ?
+	int *supports_multiple;
+
+	// What should alternatively be prepended to the function names ?
+	char **symbol_prefix;
+
+/*
 The programmer should define the following symbols:
 char * api_version = API_VERSION;  // <-- this symbol is defined by make
 int stay_in_foreground = 0;	// This driver does not need to be in foreground
-int does_input = 0;	    // This driver does not do input
+int supports_multiple = 0;	// This driver does not c$support multiple instances
-int does_output = 1;	    // But only output
+char *symbol_prefix = "MyDriver_";	// Driver functions start with MyDriver_
 And fill these values with the correct values. Upon loading the driver module,
 the server will locate these symbols and store pointers to them in the
 driver struct.
@@ -45,103 +54,120 @@ the api_version symbol (a string). For the v0.5 version this should be "0.5".
 If the version is incompatible, the driver will not be loaded. The current
 API version can always be determined by inserting the compiler define
 API_VERSION in the code.
+*/
+
+	//////// Functions to be provided by the driver module
+
+	//// Mandatory functions (necessary for all drivers)
+	
+	// initialize driver: return >= 0 on success
+	int (*init)		(Driver *drvthis);
+	
+	// close driver
+	void (*close)		(Driver *drvthis);
+
+
+	//// Essential output functions (necessary for output drivers)
+	
+	// get display width & height (in characters)
+	int (*width)		(Driver *drvthis);
+	int (*height)		(Driver *drvthis);
+
+	// clear screen
+	void (*clear)		(Driver *drvthis);
+
+	// flush screen contents to LCD
+	void (*flush)		(Driver *drvthis);
+
+	// write string s at position (x,y)
+	void (*string)		(Driver *drvthis, int x, int y, char *str);
+
+	// write char c at position (x,y)
+	void (*chr)		(Driver *drvthis, int x, int y, char c);
+
+
+	//// essential input functions (necessary for input drivers)
+
+	// get key from driver: returns a string denoting the key pressed
+	const char *(*get_key)	(Driver *drvthis);
+
+	
+	//// Extended output functions (optional; core provides alternatives)
+
+	// draw a bar from pos (x,y) upward / to the right filling promille of len chars
+	void (*vbar)		(Driver *drvthis, int x, int y, int len, int promille, int options);
+	void (*hbar)		(Driver *drvthis, int x, int y, int len, int promille, int options);
+
+	// display (big) number num at horizontal position x
+	void (*num)		(Driver *drvthis, int x, int num);
+
+	// set heartbeat state; animalte heartbeat
+	void (*heartbeat)	(Driver *drvthis, int state);
+
+	// draw named icon at position (x,y)
+	void (*icon)		(Driver *drvthis, int x, int y, int icon);
+
+
+	//// User-defined character functions
+
+	// set special character / get free characters
+	// - It is currently unclear how this system should work exactly
+	// - The set_char function expects a simple block of data with 1 byte for each pixel-line.
+	//   (So that is 8 bytes for a 5x8 char)
+	void (*set_char)	(Driver *drvthis, char ch, char *dat);
+	int (*get_free_chars)	(Driver *drvthis);
+
+	// get width & height of a character cell (in pixels)
+	// - necessary to provide info about cell size to clients
+	// - if not defined, the core will provide alternatives returning default values
+	int (*cellwidth)	(Driver *drvthis);
+	int (*cellheight)	(Driver *drvthis);
+
+
+	//// Hardware functions
+
+	// get & set ithe display's contrast
+	int (*get_contrast)	(Driver *drvthis);
+	int (*set_contrast)	(Driver *drvthis, int promille);
+
+	// get & set brightness for given backlight state
+	int (*get_brightness)	(Driver *drvthis, int state);
+	int (*set_brightness)	(Driver *drvthis, int state, int promille);
+
+	// set backlight state
+	void (*backlight)	(Driver *drvthis, int state);
+
+	// set output
+	void (*output)		(Driver *drvthis, int state);
+
+
+	//// Informational functions
+	// get a string describing the driver and it's features
+	char * (*get_info) (Driver *drvthis);
 
 
 
-	//////// Functions in the driver module
+	//////// Variables in server core, available for drivers
-	// Basic functions
 
-All these Basic functions should be implemented !
+	// name of the driver instance (name of the config file section)
+	// - do not change from the driver; consider it read-only
+	// - to be used to access the driver's own section in the config file
+	char * name;	
 
-	int (*init)		(drvthis);
+	// pointer to the driver instance's private data
-	void (*close)		(drvthis);
+	// - filled by the server by calling store_private_ptr()
-	int (*width)		(drvthis);
+	// - the driver should cast this to it's own private structure pointer
-	int (*height)		(drvthis);
-	void (*clear)		(drvthis);
-	void (*flush)		(drvthis);
-	void (*string)		(drvthis, int x, int y, char *str);
-	void (*chr)		(drvthis, int x, int y, char c);
-
-
-	// Extended functions
-	void (*vbar)		(drvthis, int x, int y, int len, int promille, int options);
-	void (*hbar)		(drvthis, int x, int y, int len, int promille, int options);
-
-These functions have been extended since v0.4. They now now expext complete
-coordinates, a length (in chars, not pixels!) a promillage (0 to 1000) and an
-option.
-
-	void (*num)		(drvthis, int x, int num);
-
-Draw big numbers on your display. Only 6 positions exist, 1 to 6.
-David GLAUDE:
-"
-I don't think this is valid... There are as many position as wanted.
-A BigNum could be at any column from 1 to end of the LCD.
-It could also be at -1 and -2 (where only the end is visible).
-Optionaly it could be on a specific raw from -3 to end of the LCD.
-This permit scrolling of BIGNUM or in the futur BIGFONT.
-"
-
-	void (*heartbeat)	(drvthis, int state);
-
-Should be called to animate the heartbeat. The driver should thererfor
-probably call the icon function below.
-
-	void (*icon)		(drvthis, int x, int y, int icon);
-
-Tells to place a certain icon at a position.
-
-
-	// Userdef characters
-	void (*set_char)	(drvthis, char ch, char *dat);
-	int (*get_free_chars)	(drvthis);
-	int (*cellwidth)	(drvthis);
-	int (*cellheight)	(drvthis);
-
-Functions to define a character. It is currently unclear how this system
-should exactly work. The set_char function expects a simple block of data
-with 1 byte for each pixel-line. So that is 8 bytes for a 5x8 char.
-
-
-	// Hardware functions
-	int (*contrast)		(drvthis, int contrast);
-	void (*backlight)	(drvthis, int brightness);
-	void (*output)		(drvthis, int state);
-
-
-	// Key functions
-	const char *(*get_key)	(drvthis);
-
-Returns a string. This string is withing driver's memory space and the server
-should therefor never try to modify this string.
-
-	char * (*get_info) ();
-
-Returns a string describing the driver and it's features.
-
-
-
-	//////// Variables in server core available for drivers
-
-	char * name;		// Name of this driver.
 	void * private_data;
 
-These variables should be taken read-only for the drivers. The name variable
-should be used to access the driver's own section in the config file.
-The private_data pointer is the pointer to the driver's own data block. This
-pointer should be stored using the store_private_ptr function below. The
-driver should cast this to it's own private structure pointer.
 
+	//////// Functions in server core, available for drivers
 
-	//////// Functions in server core available for drivers
+	// store a pointer to the driver instance's private data
-
 	int (*store_private_ptr) (struct lcd_logical_driver * driver, void * private_data);
 
-Store the driver's private data:
+	// Config file functions, cwprovided by the server
-
+	// - see configfile.h on how to use these functions
-
+	// - as sectionname, always use the driver name: drvthis->name
-	// Config file functions, filled by server
 	char (*config_get_bool)	(char * sectionname, char * keyname,
 				int skip, char default_value);
 	int (*config_get_int)	(char * sectionname, char * keyname,
@@ -155,33 +181,17 @@ Store the driver's private data:
 	int config_has_section	(char *sectionname);
 	int config_has_key	(char *sectionname, char *keyname);
 
-See configfile.h on how to use these functions. As sectionname, always use the
+	// error reporting function
-driver name: drvthis->name
+	// - see drivers/report.h for details
-
-
-	// Reporting function
 	void (*report)			( const int level, const char *format, .../*args*/ );
 
-Easily usable report functions by including drivers/report.h. See that file
-for details.
-
-
 	// Display properties functions (for drivers that adapt to other loaded drivers)
+	// - the return the size of another already loaded driver
+	// - if no driver is loaded yet, the return values will be 0
 	int (*get_display_width) ();
 	int (*get_display_height) ();
-
-If you have a driver that can adapt its size to the size of an other driver,
-it should read these values. If there is no other driver loaded yet, the
-returned values will be 0.
-
-
-	// Driver private data
-	void * private_data;	// Filled by server by calling store_private_ptr()
-
 } Driver;
 
-The flush_box and draw_frame functions have been removed for v0.5.
-
 
 
 PRIVATE DATA
@@ -195,35 +205,38 @@ daemons on one machine. They will then use the same variables !
 In the driver's private structure will probably at least be something like:
 
 typedef struct my_driver_private {
-
+	int fd;				// file descriptor for the LCD device
-        // Size in cells of the LCD
+	int width, height;		// dimension of the LCD (in characters, 1-based
-        int width, height;
+	int cellwidth, cellheight;	// Size of each LCD cell, in pixels
-        // Size of each LCD cell, in pixels
+	unsigned char *framebuf;	// Frame buffer...
-        int cellwidth, cellheight;
-        // Frame buffer...
-        char *framebuf;
 } PrivateData;
 
 You allocate and store this structure like this:
 
-	PrivateData * p;
+	PrivateData *p;
 
 	// Alocate and store private data
-	p = (PrivateData *) malloc( sizeof(PrivateData) );
+	p = (PrivateData *) malloc(sizeof(PrivateData));
-	if( p == NULL )
+	if (p == NULL)
 		return -1;
-	if( drvthis->store_private_ptr( drvthis, p ) < 0 )
+	if (drvthis->store_private_ptr(drvthis, p) < 0)
 		return -1;
 
+	// initialize private data
+	p->fd = -1;
+	p->cellheight = 8;
+	p->cellwidth = 6;
+
 	(... continue with the rest of your init routine)
 
 
 You retrieve this private data pointer by adding the following code to the
 beginning of your functions:
 
-  PrivateData * p = (PrivateData*) drvthis->private_data;
+	PrivateData *p = (PrivateData *) drvthis->private_data;
 
 Then you can access your data like:
+
 	p->framebuf
 
 
@@ -231,76 +244,87 @@ Then you can access your data like:
 
 FUNCTIONS IN DETAIL
 
-int (*init)		(drvthis, char *args);
+int (*init)		(Driver *drvthis, char *args);
 // The init function
 // Starts up the LCD, initializes all vars. Allocates private data space
 // and stores the pointer by calling store_private_ptr();
 
-void (*close)		(drvthis);
+void (*close)		(Driver *drvthis);
 // Shuts down the connection with the LCD.
 // Called just before unloading the driver.
 
-int (*width)		(drvthis);
+int (*width)		(Driver *drvthis);
 // Get the screen width.
 
-int (*height)		(drvthis);
+int (*height)		(Driver *drvthis);
 // Get the screen height.
 
-void (*clear)		(drvthis);
+void (*clear)		(Driver *drvthis);
 // Clears the framebuffer
 
-void (*flush)		(drvthis);
+void (*flush)		(Driver *drvthis);
 // Flushes the framebuffer to the LCD.
 
-void (*string)		(drvthis, int x, int y, char *str);
+void (*string)		(Driver *drvthis, int x, int y, char *str);
 // Places a string in the framebuffer
 // All coordinates are 1-based, (1,1) is top left.
 // Driver should check for overflows
 
-void (*chr)		(drvthis, int x, int y, char c);
+void (*chr)		(Driver *drvthis, int x, int y, char c);
 // Places a char in the framebuffer
 // Driver should check for overflows
 
-void (*vbar)		(drvthis, int x, int len);
+void (*vbar)		(Driver *drvthis, int x, int len);
 // Draws a vertical bar at horizontal position x and with length len.
 // init_vbar will be called once before this functions.
 
-void (*hbar)		(drvthis, int x, int y, int len);
+void (*hbar)		(Driver *drvthis, int x, int y, int len);
 // Draws a horizontal bar at position x,y and with length len.
 // init_hbar will be called once before this functions.
 
-void (*num)		(drvthis, int x, int num);
+void (*num)		(Driver *drvthis, int x, int num);
-// Displays a big number at position x.
+// Displays a big number at horizontal position x.
 
-void (*heartbeat)	(drvthis, int state);
+void (*heartbeat)	(Driver *drvthis, int type);
-// Sets the heartbeat to the indicated state.
+// Sets the heartbeat to the indicated type: 0=off 1=graph1 2=graph2
-// 0=off 1=graph1 2=graph2
+//HEARTBEAT_ON to say that we want to display/refresh the heartbeat.
-David GLAUDE:
+//The driver choose how to do it. See MtxOrb.c"
-"state is apparently type and it could have the value
-HEARTBEAT_ON to say that we want to display/refresh the heartbeat.
-The driver choose how to do it. See MtxOrb.c"
 
-int (*contrast)		(drvthis, int contrast);
+int (*get_contrast)		(Driver *drvthis);
+// Gets the contrast from the driver.
+// the value returned is in the ramnge 0 - 1000
+// Many displays do not support software setting of contrast.
+
+void (*set_contrast)		(Driver *drvthis, int contrast);
+// Sets the contrast to the given value. Values should be 0 to 1000.
+// Many displays do not support software setting of contrast.
+
+int (*get_brightness)		(Driver *drvthis, int state);
+// Get the brightness for the given backlight state.
+// Returned values are in the range from 0 - 1000.
+// Many displays do not support software setting of contrast.
+
+void (*set_brightness)		(Driver *drvthis, int state, int int brightness);
 // Sets the contrast to the given value. Values should be 0 to 255.
 // Many displays do not support software setting of contrast.
 // Use -1 to get the current value returned.
 
-void (*backlight)	(drvthis, int on);
+void (*backlight)	(Driver *drvthis, int state);
 // Sets the backlight to brightness 'on'.
 // Often hardware can only support on and off, in that case any value
 // of on>0 will switch the backlight on.
 
-void (*output)		(drvthis, int on);
+void (*output)		(Driver *drvthis, int state);
 // Sets the output value. Some displays/wirings have a general purpose
 // output, which can be controlled by calling this function. See the
 // 'output' command in the 'widget language'.
 
-char *(*getkey) ();
+char *(*get_key) (Driver *drvthis);
 // Checks if a key has been pressed on the device.
 // Returns NULL for "no key pressed", or a string describing the pressd key.
 // These characters should match the keypad-layout.
 
-char *(*getinfo) ();
+char *(*get_info) (Driver *drvthis);
 // Returns a string describing the driver and its features.
 
 
@@ -340,4 +364,5 @@ int config_has_key	(char *sectionname, char *keyname);
 
 
 First version, Joris Robijn, 20011016
+Corrected and expanded, Peter Marschall 20060411
 

docs/lcdproc-dev/driver-api.docbook

@@ -35,119 +35,154 @@
 </para>
 
 <screen>
+
 typedef struct lcd_logical_driver {
 
-	//////// Variables in the driver module
+	//////// Variables to be provided by the driver module
 	// The driver loader will look for symbols with these names !
+
+	// pointer to a string describing the API version
 	char *api_version;
-	int *stay_in_foreground;	// Does this driver require to be in foreground ?
-	int *does_input;	// Does this driver do output ?
-	int *does_output;	// Does this driver do output ?
 
-  The programmer should define the following symbols:
+	// Does this driver require to be in foreground ?
+	int *stay_in_foreground;// Does this driver require to be in foreground ?
 
+	/ Does this driver support multiple instances ?
+	int *supports_multiple;
+
+	// What should alternatively be prepended to the function names ?
+	char **symbol_prefix;
+
+/*
+The programmer should define the following symbols:
 char * api_version = API_VERSION;	// &lt;-- this symbol is defined by make
 int stay_in_foreground = 0;		// This driver does not need to be in foreground
-int does_input = 0;	    // This driver does not do input
+int supports_multiple = 0;		// This driver does not c$support multiple instances
-int does_output = 1;	    // But only output
+char *symbol_prefix = "MyDriver_";	// Driver functions start with MyDriver_
+And fill these values with the correct values. Upon loading the driver module,
+the server will locate these symbols and store pointers to them in the
+driver struct.
 
-  And fill these values with the correct values. Upon loading the driver module,
+Because the drivers are loadable, some kind of version checking should be
-  the server will locate these symbols and store pointers to them in the
+done. Therefor the server expects the correct version number to be found in
-  driver struct.
+the api_version symbol (a string). For the v0.5 version this should be "0.5".
+If the version is incompatible, the driver will not be loaded. The current
+API version can always be determined by inserting the compiler define
+API_VERSION in the code.
+*/
 
-  Because the drivers are loadable, some kind of version checking should be
+	//////// Functions to be provided by the driver module
-  done. Therefor the server expects the correct version number to be found in
-  the api_version symbol (a string). For the v0.5 version this should be "0.5".
-  If the version is incompatible, the driver will not be loaded. The current
-  API version can always be determined by inserting the compiler define
-  API_VERSION in the code.
 
-	///// Functions in the driver module
+	//// Mandatory functions (necessary for all drivers)
-	// Basic functions
- 	// All these Basic functions should be implemented !
-	int (*init)		(drvthis);
-	void (*close)		(drvthis);
-	int (*width)		(drvthis);
-	int (*height)		(drvthis);
-	void (*clear)		(drvthis);
-	void (*flush)		(drvthis);
-	void (*string)		(drvthis, int x, int y, char *str);
-	void (*chr)		(drvthis, int x, int y, char c);
 	
-	// Extended functions
+	// initialize driver: returns &gt;= 0 on success
-	void (*vbar)		(drvthis, int x, int y, int len, int promille, int options);
+	int (*init)		(Driver *drvthis);
-	void (*hbar)		(drvthis, int x, int y, int len, int promille, int options);
 	
-  These functions have been extended since v0.4. They now now expext complete
+	// close driver
-  coordinates, a length (in chars, not pixels!) a promillage (0 to 1000) and an
+	void (*close)		(Driver *drvthis);
-  option.
-
-	void (*num)		(drvthis, int x, int num);
-
-  Draw big numbers on your display. Only 6 positions exist, 1 to 6.
-  David GLAUDE:
-    "I don't think this is valid... There are as many position as wanted.
-    A BigNum could be at any column from 1 to end of the LCD.
-    It could also be at -1 and -2 (where only the end is visible).
-    Optionaly it could be on a specific raw from -3 to end of the LCD.
-    This permit scrolling of BIGNUM or in the futur BIGFONT."
-
-	void (*heartbeat)	(drvthis, int state);
-
-  Should be called to animate the heartbeat. The driver should therefore
-  probably call the icon function below.
-
-	void (*icon)		(drvthis, int x, int y, int icon);
-
-  Tells to place a certain icon at a position.
 
 
-	// Userdef character functions
+	//// Essential output functions (necessary for output drivers)
 	
-	void (*set_char)	(drvthis, char ch, char *dat)
+	// get display width / height (in characters; 1-based)
-	int (*get_free_chars)	(drvthis)
+	int (*width)		(Driver *drvthis);
-	int (*cellwidth)	(drvthis)
+	int (*height)		(Driver *drvthis);
-	int (*cellheight)	(drvthis)
 
-  Functions to define a character. It is currently unclear how this system
+	// clear screen
-  should exactly work. The set_char function expects a simple block of data
+	void (*clear)		(Driver *drvthis);
-  with 1 byte for each pixel-line. So that is 8 bytes for a 5x8 char.
 
-	// Hardware functions
+	// flush screen contents to LCD
-	int (*contrast)		(drvthis, int contrast);
+	void (*flush)		(Driver *drvthis);
-	void (*backlight)	(drvthis, int on);
-	void (*output)		(drvthis, int on);
 
-	// Key functions
+	// write string s at position (x,y)
-	const char *(*get_key)	(drvthis);
+	void (*string)		(Driver *drvthis, int x, int y, char *str);
 
-  Returns a string. This string is withing driver's memory space and the server
+	// write char c at position (x,y)
-  should therefor never try to modify this string.
+	void (*chr)		(Driver *drvthis, int x, int y, char c);
 
-	char *(*get_info)	(drvthis);
 
-  Returns a string describing the driver and it's features.
+	//// essential input functions (necessary for input drivers)
 
-	//////// Variables in server core available for drivers
+	// get key from driver: returns a string denoting the key pressed
+	const char *(*get_key)	(Driver *drvthis);
 
-	char * name;		// Name of this driver.
+	
+	//// Extended output functions (optional; core provides alternatives)
+
+	// draw a bar from pos (x,y) upward / to the right filling promille of len chars
+	void (*vbar)		(Driver *drvthis, int x, int y, int len, int promille, int options);
+	void (*hbar)		(Driver *drvthis, int x, int y, int len, int promille, int options);
+
+	// display (big) number num at horizontal position x
+	void (*num)		(Driver *drvthis, int x, int num);
+
+	// set heartbeat state; animalte heartbeat
+	void (*heartbeat)	(Driver *drvthis, int state);
+
+	// draw named icon at position (x,y)
+	void (*icon)		(Driver *drvthis, int x, int y, int icon);
+
+
+	//// User-defined character functions
+
+	// set special character / get free characters
+	// - It is currently unclear how this system should work exactly
+	// - The set_char function expects a simple block of data with 1 byte for each pixel-line.
+	//   (So that is 8 bytes for a 5x8 char)
+	void (*set_char)	(Driver *drvthis, char ch, char *dat);
+	int (*get_free_chars)	(Driver *drvthis);
+
+	// get width / height of a character cell (in pixels)
+	// - necessary to provide info about cell size to clients
+	// - if not defined, the core will provide alternatives returning default values
+	int (*cellwidth)	(Driver *drvthis);
+	int (*cellheight)	(Driver *drvthis);
+
+
+	//// Hardware functions
+
+	// get / set the display's contrast
+	int (*get_contrast)	(Driver *drvthis);
+	int (*set_contrast)	(Driver *drvthis, int promille);
+
+	// get / set brightness for given backlight state
+	int (*get_brightness)	(Driver *drvthis, int state);
+	int (*set_brightness)	(Driver *drvthis, int state, int promille);
+
+	// set backlight state
+	void (*backlight)	(Driver *drvthis, int state);
+
+	// set output
+	void (*output)		(Driver *drvthis, int state);
+
+
+	//// Informational functions
+	// get a string describing the driver and it's features
+	char * (*get_info) (Driver *drvthis);
+
+
+
+	//////// Variables in server core, available for drivers
+
+	// name of the driver instance (name of the config file section)
+	// - do not change from the driver; consider it read-only
+	// - to be used to access the driver's own section in the config file
+	char * name;	
+
+	// pointer to the driver instance's private data
+	// - filled by the server by calling store_private_ptr()
+	// - the driver should cast this to it's own private structure pointer
 	void * private_data;
 
-These variables should be taken read-only for the drivers. The name variable
-should be used to access the driver's own section in the config file.
-The private_data pointer is the pointer to the driver's own data block. This
-pointer should be stored using the store_private_ptr function below. The
-driver should cast this to it's own private structure pointer.
 
+	//////// Functions in server core, available for drivers
 
-	//////// Functions in server core available for drivers
+	// store a pointer to the driver instance's private data
-
 	int (*store_private_ptr) (struct lcd_logical_driver * driver, void * private_data);
 
-Store the driver's private data:
+	// Config file functions, cwprovided by the server
-
+	// - see configfile.h on how to use these functions
-
+	// - as sectionname, always use the driver name: drvthis->name
-	// Config file functions, filled by server
 	char (*config_get_bool)	(char * sectionname, char * keyname,
 				int skip, char default_value);
 	int (*config_get_int)	(char * sectionname, char * keyname,
@@ -161,32 +196,17 @@ Store the driver's private data:
 	int config_has_section	(char *sectionname);
 	int config_has_key	(char *sectionname, char *keyname);
 
-See configfile.h on how to use these functions. As sectionname, always use the
+	// error reporting function
-driver name: drvthis->name
+	// - see drivers/report.h for details
-
-
-	// Reporting function
 	void (*report)			( const int level, const char *format, .../*args*/ );
 
-Easily usable report functions by including drivers/report.h. See that file
-for details.
-
-
 	// Display properties functions (for drivers that adapt to other loaded drivers)
+	// - the return the size of another already loaded driver
+	// - if no driver is loaded yet, the return values will be 0
 	int (*get_display_width) ();
 	int (*get_display_height) ();
-
-If you have a driver that can adapt its size to the size of an other driver,
-it should read these values. If there is no other driver loaded yet, the
-returned values will be 0.
-
-
-	// Driver private data
-	void * private_data;	// Filled by server by calling store_private_ptr()
-
 } Driver;
 
-The flush_box and draw_frame functions have been removed for v0.5.
 </screen>
 
 </sect1>
@@ -208,13 +228,10 @@ The flush_box and draw_frame functions have been removed for v0.5.
 
 <screen>
 typedef struct my_driver_private {
-
+	int fd;				// file descriptor for the LCD device
-        // Size in cells of the LCD
+        int width, height;		// dimension of the LCD (in characters, 1-based
-        int width, height;
+        int cellwidth, cellheight;	// Size of each LCD cell, in pixels
-        // Size of each LCD cell, in pixels
+        unsigned char *framebuf;	// Frame buffer...
-        int cellwidth, cellheight;
-        // Frame buffer...
-        char *framebuf;
 } PrivateData;
 </screen>
 
@@ -223,15 +240,20 @@ typedef struct my_driver_private {
 </para>
 
 <screen>
-	PrivateData * p;
+	PrivateData *p;
 
 	// Allocate and store private data
-	p = (PrivateData *) malloc( sizeof(PrivateData) );
+	p = (PrivateData *) malloc(sizeof(PrivateData));
-	if( p == NULL )
+	if (p == NULL)
 		return -1;
-	if( drvthis->store_private_ptr( drvthis, p ) &lt; 0 )
+	if (drvthis->store_private_ptr( drvthis, p ) &lt; 0)
 		return -1;
 
+	// initialize private data
+	p->fd = -1;
+	p->cellheight = 8;
+	p->cellwidth = 6;
+	
 	(... continue with the rest of your init routine)
 </screen>
 
@@ -241,7 +263,7 @@ typedef struct my_driver_private {
 </para>
 
 <screen>
-	PrivateData * p = (PrivateData*) drvthis->private_data;
+	PrivateData *p = (PrivateData *) drvthis->private_data;
 </screen>
 
 <para>
@@ -470,28 +492,75 @@ typedef struct my_driver_private {
 
 <funcsynopsis>
   <funcprototype>
-	<funcdef>int <function>(*contrast)</function></funcdef>
+	<funcdef>int <function>(*get_contrast)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
-	<paramdef>int <parameter>contrast</parameter></paramdef>
   </funcprototype>
 </funcsynopsis>
 <para>
-  Sets the contrast to the given value. Values should be 0 to 255.
+  Get the contrast value from the driver.
+  The return value is an integer in the range from 0 to 1000.
+  Many displays do not support getting or setting contrast
+  using software.
+</para>
+
+<funcsynopsis>
+  <funcprototype>
+	<funcdef>int <function>(*set_contrast)</function></funcdef>
+	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
+	<paramdef>int <parameter>promille</parameter></paramdef>
+  </funcprototype>
+</funcsynopsis>
+<para>
+  Sets the contrast to the given value, which is an integer in the range from 0 to 1000.
+  It is up to the driver to map the logical interval [0, 1000] into the
+  interval that the hardware supports.
   Many displays do not support software setting of contrast.
-  Use -1 to get the current value returned.
+</para>
+
+<funcsynopsis>
+  <funcprototype>
+	<funcdef>int <function>(*get_brightness)</function></funcdef>
+	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
+	<paramdef>int <parameter>state</parameter></paramdef>
+  </funcprototype>
+</funcsynopsis>
+<para>
+  Get the brightness value from the driver for the given backlight state.
+  The parameter <parameter>state</parameter> determnies which one
+  is returned.
+  The return value is an integer in the range from 0 to 1000.
+  Many displays do not support getting or setting brightness
+  using software.
+</para>
+
+<funcsynopsis>
+  <funcprototype>
+	<funcdef>int <function>(*set_brightness)</function></funcdef>
+	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
+	<paramdef>int <parameter>state</parameter></paramdef>
+	<paramdef>int <parameter>promille</parameter></paramdef>
+  </funcprototype>
+</funcsynopsis>
+<para>
+  Set the brightness for the given backlight state to the value given.
+  Value must be an integer in the range from 0 to 1000.
+  It is up to the driver to map the logical interval [0, 1000] into the
+  interval that the hardware supports.
+  Many displays do not support software setting of brightness.
 </para>
 
 <funcsynopsis>
   <funcprototype>
 	<funcdef>void <function>(*backlight)</function></funcdef>
 	<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
-	<paramdef>int <parameter>brightness</parameter></paramdef>
+	<paramdef>int <parameter>state</parameter></paramdef>
   </funcprototype>
 </funcsynopsis>
 <para>
-  Sets the backlight to brightness 'on'.
+  Sets the backlight to the given brightness state.
-  Often hardware can only support on and off, in that case any value
+  Often hardware can only support two values for the backlight:
-  of on>0 will switch the backlight on.
+  on and off.
+  In that case any value of state &gt; 0 will switch the backlight on.
 </para>
 
 <funcsynopsis>

server/drivers/README

@@ -1,62 +1,18 @@
 UNDERSTANDING LCDPROC DRIVERS
 
-All of the drivers may be activated and compiled in; which is
+LCDproc drivers are compiled as modules that will be loaded by the 
-activated and used depends on what parameters are given at the command
+LCDd daemon's core on request.
-line.
 
-One can better understand how drivers work by reading the comments
+To understand how to write a driver see docs/API-0.5.txt and the
-and documentation in drv_base.h.
+section about the driver API in the Admin Guide.
 
-There is a structure which is used to define all of the command functions
-available from each driver.  This command structure is lcd_logical_driver.
-The main use of this structure is for the lcd structure, which contains
-all of the current drivers functions.
 
------------------------------- lcd_logical_driver ------------------------------
+-------- 8< snip >8 ------------------
-typedef struct lcd_logical_driver {
+The remainder of this file may be horribly outdated.
-	int wid, hgt;			// size of the LCD in characters
+Treat the information contained herein with caution.
-	int cellwid, cellhgt;		// size of each LCD char cell in pixels
+You have been warned.
-	char *framebuf;			// storage space for display
 
-	// Functions which might be the same for all drivers...
 
-	void (*clear) ();		// clear screen;
-	void (*string)			// string at (x,y)
-		(int x, int y, char lcd[]);
-
-	void (*chr)			// character at (x,y)
-		(int x, int y, char c);
-	void (*vbar)			// vertical bar at (x,y)
-		(int x, int y, int len);
-	void (*hbar)			// horizontal bar at (x,y)
-		(int x, int y, int len);
-	void (*init_num) ();		//
-	void (*num) (int x, int num);	// display number
-
-	// Functions which should probably be implemented in each driver...
-
-	int (*init)			// initialize driver
-		(struct lcd_logical_driver * driver);
-	void (*close) ();		// close
-	void (*flush) ();		// flush
-	void (*flush_box)		// flush box
-		(int lft, int top, int rgt, int bot);
-	int (*contrast) (int contrast);	// set contrast
-	void (*backlight) (int on);	// set backlight
-	void (*output) (int on);	// set outputs
-	void (*set_char)		// set special characters
-		(int n, char *dat);
-	void (*icon)			// set up special icon
-		(int which, char dest);
-	void (*init_vbar) ();		// initialize vertical bar
-	void (*init_hbar) ();		// initialize horizontal bar
-	void (*draw_frame) ();		// draw frame
-
-	char (*getkey) ();		// get a key (or 0)
-
-	char * (*getinfo) ();		// get a string of info
-
-} Driver;
 ------------------------------ lcd_logical_driver ------------------------------
 
 The first thing that is done is that lcd_init (lcd.c) is called.  This function