From f8df8dcf5c3ea3b4242000a263c5f984d4517d8d Mon Sep 17 00:00:00 2001 From: mmdolze Date: Sat, 15 Jan 2011 19:36:16 +0000 Subject: [PATCH] Convert some comments. Add more doxygen to hd44780-serial. Don't use a typedef if not really necessary. --- server/drivers/hd44780-drivers.h | 10 ++--- server/drivers/hd44780-low.h | 2 +- server/drivers/hd44780-serial.c | 73 +++++++++++++++++++------------- server/drivers/hd44780-serial.h | 58 ++++++++++++++----------- 4 files changed, 84 insertions(+), 59 deletions(-) diff --git a/server/drivers/hd44780-drivers.h b/server/drivers/hd44780-drivers.h index 995be02..53ff3ef 100644 --- a/server/drivers/hd44780-drivers.h +++ b/server/drivers/hd44780-drivers.h @@ -10,7 +10,7 @@ #ifndef HD44780_DRIVERS_H #define HD44780_DRIVERS_H -// hd44780 specific header files +/* hd44780 specific header files */ #ifdef HAVE_PCSTYLE_LPT_CONTROL # include "hd44780-4bit.h" # include "hd44780-ext8bit.h" @@ -35,7 +35,7 @@ # include "hd44780-ethlcd.h" #endif # include "hd44780-usblcd.h" -// add new connection type header files here +/* add new connection type header files to the correct section above or here */ /** connectionType mapping table: @@ -80,9 +80,9 @@ static const ConnectionMapping connectionMapping[] = { #ifdef WITH_ETHLCD { "ethlcd", HD44780_CT_ETHLCD, IF_TYPE_TCP, hd_init_ethlcd }, #endif - // add new connection types here - // .... - // default, end of structure element (do not delete) + /* add new connection types in the correct section above or here */ + + /* default, end of structure element (do not delete) */ { NULL, HD44780_CT_UNKNOWN, IF_TYPE_UNKNOWN, NULL } }; diff --git a/server/drivers/hd44780-low.h b/server/drivers/hd44780-low.h index cd0e80b..10edcd4 100644 --- a/server/drivers/hd44780-low.h +++ b/server/drivers/hd44780-low.h @@ -109,7 +109,7 @@ typedef struct hd44780_private_data { // serial connection types int fd; /* file handle to serial device */ - int serial_type; + int serial_type; /* type of device for hd44780-serial */ #if defined(HAVE_LIBUSB) // USB connection types diff --git a/server/drivers/hd44780-serial.c b/server/drivers/hd44780-serial.c index ab78e66..115187e 100644 --- a/server/drivers/hd44780-serial.c +++ b/server/drivers/hd44780-serial.c @@ -1,9 +1,17 @@ /** \file server/drivers/hd44780-serial.c - * Connection types \c picanlcd, \c lcdserializer, \c los-panel, \c vdr-lcd, - * \c vdr-wakeup, \c pertelian, ... of \c hd44780 driver for Hitachi HD44780 based LCD displays. + * Connection type of \c hd44780 driver for Hitachi HD44780 based LCD displays + * connected to a serial port. + * + * This driver supports text displays that understand the HD44780 command set + * and are connected to a serial port using some microcontroller. It supports + * protocols using escape sequences to trigger commands, backlight or keys. + * + * Currently supported are: \c picanlcd, \c lcdserializer, \c los-panel, + * \c vdr-lcd, \c vdr-wakeup, and \c pertelian. */ -/* Copyright (C) 2006-2007 Matteo Pillon +/*- + * Copyright (C) 2006-2007 Matteo Pillon * * Some parts are based on the original pic-an-lcd driver code * Copyright (C) 1997, Matthias Prinke @@ -29,29 +37,26 @@ * */ -#include "hd44780-serial.h" -#include "hd44780-low.h" - -#include "report.h" - -#include -#include -#include - -#include -#include -#include -#include - -#include - #ifdef HAVE_CONFIG_H # include "config.h" #endif +#include +#include +#include +#include +#include +#include +#include +#include + +#include "hd44780-serial.h" +#include "report.h" + +/** Shortcut to select an entry from serial_interfaces table */ #define SERIAL_IF serial_interfaces[p->serial_type] -/* bitrate conversion */ +/** bitrate conversion table */ unsigned int bitrate_conversion[][2] = { { 50, B50 }, { 75, B75 }, @@ -115,6 +120,16 @@ unsigned int bitrate_conversion[][2] = { #endif }; + +/** + * Look up a given bitrate in the bitrate_conversion table and fill bitrate + * from the correct speed_t macro. + * \param conf_bitrate Bitrate (int) as read from config. + * \param bitrate Pointer to bitrate (speed_t) in which the speed is + * stored (if found in the conversion table). + * \return 0 if the bitrate was found in the conversion table; 1 to indicate + * the configured bitrate is not in the table and therefore invalid. + */ int convert_bitrate(unsigned int conf_bitrate, size_t *bitrate) { int counter; for (counter = 0; counter < sizeof(bitrate_conversion)/(2*sizeof(unsigned int)); counter++) @@ -125,8 +140,6 @@ int convert_bitrate(unsigned int conf_bitrate, size_t *bitrate) { return 1; } -static int lastdisplayID; - void serial_HD44780_senddata(PrivateData *p, unsigned char displayID, unsigned char flags, unsigned char ch); void serial_HD44780_backlight(PrivateData *p, unsigned char state); unsigned char serial_HD44780_scankeypad(PrivateData *p); @@ -142,18 +155,17 @@ void serial_HD44780_close(PrivateData *p); int hd_init_serial(Driver *drvthis) { - PrivateData *p = (PrivateData*) drvthis->private_data; - struct termios portset; char device[256] = DEFAULT_DEVICE; unsigned int conf_bitrate; size_t bitrate; + int i; + + PrivateData *p = (PrivateData*) drvthis->private_data; /* READ CONFIG FILE */ /* Get interface type */ - int i; - p->serial_type = 0; for (i = 0; serial_interfaces[i].connectiontype != HD44780_CT_UNKNOWN; i++) { if (p->connectiontype == serial_interfaces[i].connectiontype) { @@ -224,8 +236,6 @@ hd_init_serial(Driver *drvthis) /* Set TCSANOW mode of serial device */ tcsetattr(p->fd, TCSANOW, &portset); - lastdisplayID = -1; - /* Assign functions */ p->hd44780_functions->senddata = serial_HD44780_senddata; p->hd44780_functions->backlight = serial_HD44780_backlight; @@ -246,7 +256,10 @@ hd_init_serial(Driver *drvthis) /** - * Send data or commands to the display. + * Send data or commands to the display. Commands are prefixed with the + * instruction escape character. If a data byte is within a configured range + * it is prefixed with a data escape character if one is configured. + * * \param p Pointer to driver's private data structure. * \param displayID ID of the display (or 0 for all) to send data to. * \param flags Defines whether to end a command or data. @@ -255,6 +268,8 @@ hd_init_serial(Driver *drvthis) void serial_HD44780_senddata(PrivateData *p, unsigned char displayID, unsigned char flags, unsigned char ch) { + static int lastdisplayID = -1; /* save displayID across calls */ + /* Filter illegally sent escape characters (for interfaces without data escape) */ if (flags == RS_DATA && SERIAL_IF.data_escape == 0 && ch == SERIAL_IF.instruction_escape) ch='?'; diff --git a/server/drivers/hd44780-serial.h b/server/drivers/hd44780-serial.h index afd641f..0364ecd 100644 --- a/server/drivers/hd44780-serial.h +++ b/server/drivers/hd44780-serial.h @@ -1,40 +1,50 @@ +/** \file server/drivers/hd44780-serial.h + * Contains configuration data for serial attached HD44780 displays supported + * by the \c hd44780 driver. + */ + #ifndef HD44780_SERIAL_H #define HD44780_SERIAL_H -#include "lcd.h" /* for Driver */ +#include "lcd.h" #include "hd44780-low.h" #define SERIALIF_NAME_LENGTH 20 - #define DEFAULT_DEVICE "/dev/lcd" -typedef struct SerialInterface { - int connectiontype; +/** Declares one configuration enty in the serial_interfaces table */ +struct hd44780_SerialInterface { + int connectiontype; /**< Connection type from hd44780 config */ + /** Command escape character. This is always sent, even if 0x00 */ char instruction_escape; + /** Data escape character. Only sent if not NUL data is within range + * configure by data_escape_min and data_escape_max. */ char data_escape; - char data_escape_min; /* escaped data lower limit */ - char data_escape_max; /* escaped data upper limit */ - unsigned int default_bitrate; - char if_bits; - char keypad; - char keypad_escape; - char backlight; - /* - if both escape and on/off codes are set means that display - can't set brightness, but can only switch light on or off and - needs both escape and on/off bytes (see pertelian) - */ - char backlight_escape; /* leave to 0 is the interface uses on/off codes */ + char data_escape_min; /**< Escaped data lower limit (inclusive) */ + char data_escape_max; /**< Escaped data upper limit (exclusive) */ + unsigned int default_bitrate; /**< Bitrate device is set to by default */ + char if_bits; /**< Initialize to 8 or 4 bit interface */ + char keypad; /**< Flag: keypad available */ + char keypad_escape; /**< Keys must escaped with this character */ + char backlight; /**< Flag: backlight available */ + /** Escape character to send to indicate a backlight state change */ + char backlight_escape; + /** Character to send to set display off. If not configured 0xFF is sent */ char backlight_off; - char backlight_on; /* leave these two to 0 is backlight_escape is set */ + /** Character to send to set display on. If not configured 0x00 is sent */ + char backlight_on; + /** Flag: Device has multiple controllers. If enabled, the displayID + * is added to data escape */ char multiple_displays; - char end_code; /* code to send on shutdown */ -} SerialInterface; + char end_code; /**< Code to send on shutdown */ +}; -/* List of connectiontypes managed by this driver, if you change - something here, remember also to change hd44780-drivers.h */ -static const SerialInterface serial_interfaces[] = { - /* type instr data v ^ bitrate bits K esc B Besc Boff Bon Multi End */ +/** + * List of connectiontypes managed by this driver. If you change something + * here, remember also to change hd44780-drivers.h as well. + */ +static const struct hd44780_SerialInterface serial_interfaces[] = { + /* type instr data v ^ bitrate bits K esc B Besc Boff Bon Multi End */ { HD44780_CT_PICANLCD, 0x11, 0x12, 0x00, 0x20, 9600, 8, 0, 0x00, 0, 0, 0, 0, 0, 0 }, { HD44780_CT_LCDSERIALIZER, 0xFE, 0, 0x00, 0x00, 9600, 8, 0, 0x00, 0, 0, 0, 0, 0, 0 }, { HD44780_CT_LOS_PANEL, 0xFE, 0, 0x00, 0x00, 9600, 4, 1, 0xFE, 1, 0xFF, 0, 0, 0, 0 },