clean-up and document

server/drivers/hd44780-lis2.c

@@ -14,6 +14,7 @@
  *		  2001-2002, Joris Robijn <joris@robijn.net>
  *                2005, Pillon Matteo <matteo.pillon@email.it>
  *		  2005, Laurent ARNAL <laurent@clae.net>
+ *		  2007, Peter Marschall <peter@adpm.de>
  *
  * This file is released under the GNU General Public License. Refer to the
  * COPYING file distributed with this package.
@@ -46,11 +47,11 @@ void lis2_HD44780_senddata(PrivateData *p, unsigned char displayID, unsigned cha
 void lis2_HD44780_backlight(PrivateData *p, unsigned char state);
 unsigned char lis2_HD44780_scankeypad(PrivateData *p);
 
-static void SetMatrice(PrivateData *p,int fd, int matriceNum, int ligne, int point);
+static void setLIS2CustomCharRow(int fd, unsigned char custom, unsigned char row, unsigned char data);
-static void SetFan(int fd, int fan1, int fan2, int fan3, int fan4);
+static void setLIS2Fan(int fd, int fan1, int fan2, int fan3, int fan4);
-static void gotoXY(int fd, int x, int y);
+static void gotoXY(int fd, unsigned char x, unsigned char y);
 
-static void writeChar(int fd, int code);
+static void writeChar(int fd, unsigned char code);
 
 
 // initialise the driver
@@ -105,19 +106,32 @@ int hd_init_lis2(Driver *drvthis)
 }
 
 
-static void SetMatrice(PrivateData *p, int fd, int matriceNum, int ligne, int point)
+/**
+ * Set one pixel row of a custom character, valid on LIS2 devices only.
+ * \param fd      File handle to write to.
+ * \param custom  Custom character to set (from 0 to 7).
+ * \param row     Index of pixel row to set (from (0 [=top] to 7 [=bottom]).
+ * \param data    Pixel data: 5 bit coding from 0 to 31 from right to left (16/8/4/2/1).
+ */
+static void setLIS2CustomCharRow(int fd, unsigned char custom, unsigned char row, unsigned char data)
 {
-	// char from 0 to 7
+	writeChar(fd, 0);
-	// line from 0 to 7 from top to bottom
+	writeChar(fd, 171);
-	// pixel 0/1 is 5 bit coding from 0 to 31 from right to left (16/8/4/2/1)
+	writeChar(fd, custom);
-	writeChar(p->fd, 0);
+	writeChar(fd, row);
-	writeChar(p->fd, 171);
+	writeChar(fd, data);
-	writeChar(p->fd, matriceNum);
-	writeChar(fd, ligne);
-	writeChar(fd, point);
 }
 
-static void SetFan(int fd, int fan1, int fan2, int fan3, int fan4)
+
+/**
+ * ??? Set fans, valid on LIS2 devices only. ???
+ * \param fd    File handle to write to.
+ * \param fan1  Data for 1st fan.
+ * \param fan2  Data for 2nd fan.
+ * \param fan3  Data for 3rd fan.
+ * \param fan4  Data for 4th fan.
+ */
+static void setLIS2Fan(int fd, int fan1, int fan2, int fan3, int fan4)
 {
 	writeChar(fd, 0);
 	writeChar(fd, 174);
@@ -134,7 +148,13 @@ static void SetFan(int fd, int fan1, int fan2, int fan3, int fan4)
 	writeChar(fd, 0);
 }
 
-static void gotoXY(int fd, int x, int y)
+
+/** Move cursor to given character coordinates.
+ * \param fd  File handle to write to.
+ * \param x   Character column to set cursor to.
+ * \param y   Character row to set cursor to.
+ */
+static void gotoXY(int fd, unsigned char x, unsigned char y)
 {
 	writeChar(fd, 0);
 	writeChar(fd, 161 + y);
@@ -142,75 +162,86 @@ static void gotoXY(int fd, int x, int y)
 	writeChar(fd, 167);
 }
 
-static void writeChar(int fd, int code)
-{
-	char buf = code;
 
-	write(fd, &buf, 1);
+/**
+ * Write a character.
+ * \param fd  File handle to write to.
+ * \param ch  Character to write.
+ */
+static void writeChar(int fd, unsigned char code)
+{
+	write(fd, &code, 1);
 }
 
 
-static int mode = 0;
-static int charNum = 0;
-static int rowNum = 0;
-
 void lis2_HD44780_senddata(PrivateData *p, unsigned char displayID, unsigned char flags, unsigned char ch)
 {
-	if (flags == RS_DATA) {
+static int mode = 0;
+static unsigned char charNum = 0;
+static unsigned char rowNum = 0;
+
+	if (flags == RS_DATA) {	// RS_DATA: we have data
 		if (mode == SETCHAR) {
-			writeChar(p->fd, 0);
+			// define row for custom char (reset mode to normal if illegal row)
-			writeChar(p->fd, 171);
+			if (rowNum < p->cellheight)
-			writeChar(p->fd, charNum);
+				setLIS2CustomCharRow(p->fd, charNum, rowNum, ch);
-			writeChar(p->fd, rowNum);
+			else
-			writeChar(p->fd, ch);
-			rowNum++;
-			if (rowNum == p->cellheight) {
 				mode = 0;
-				rowNum = 0;
+
-			}
+			// increase row counter
+			rowNum++;
 		}
 		else {
+			// offset given char by one to avoid collisions with command prefix
+			// TODO: check if this is correct
 			if (ch < 7)
 				ch++;
+
+			// simply write character byte
 			write(p->fd, &ch, 1);
 		}
 	}
-	else {
+	else {	// RS_INSTR: we have an instruction
 		if ((ch & POSITION) != 0) {
-			int x = 0;
+			unsigned char divisor = (p->ext_mode) ? 0x20 : 0x40;
-			int y = 0;
-			int pos = 0;
 
-			pos = (ch & ~POSITION);
+			// get mangled position by stripping POSITION flag from given data
+			ch &= ~POSITION;
 
-			if (p->ext_mode) {				
+			// goto X & Y coordinates from un-mangled position
-				y = pos / 0x20;
+			gotoXY(p->fd, ch % divisor, ch / divisor);
-				x = pos % 0x20;
-			}
-			else {
-				y = pos / 0x40;
-				x = pos % 0x40;
-			}
-
-			gotoXY(p->fd, x, y);
 		}
 		else if ((ch & SETCHAR) != 0) {
 			mode = SETCHAR;
-			charNum = ((ch & ~SETCHAR)/8) + 1;
+
+			// extract character to set from given info
+			charNum = (ch & ~SETCHAR) / 8;
+			
+			// offset it by one to avoid collisions with command prefix 
+			// TODO: check if this is correct
+			charNum++;
+
+			// restrict it to range [1, 7]
+			// TODO: check if this is correct
 			if (charNum == 8)
 				charNum = 7;
+
+			// reset row number
+			rowNum = 0;
 		}
 	 	else
+			// simply write through instruction byte
 			write(p->fd, &ch, 1);
 	}
-
 }
 
+
 void lis2_HD44780_backlight(PrivateData *p, unsigned char state)
 {
 	/* No backlight control */
 }
 
+
 unsigned char lis2_HD44780_scankeypad(PrivateData *p)
 {
 	return '\0';