How to write new display drivers

Writing a new driver for lcd4linux is quite easy, if you follow these steps:

• Get the SVN (Subversion) version: This is very important, because it makes it much easier for us to commit your changes into the official code. If you need help with SVN, look at the SVN section at the Download page.
• There's no need to keep two seperate directories (one with the original, one with your modifications): SVN does this job for you.
• Always do a svn up before editing, to ensure you're working on current code.
• use drv_Sample.c as a template but do not simply copy it, but let subversion do the job:

 svn cp drv_Sample.c drv_<yourname>.c
 

• edit drv_<yourname>.c
  • add a short description what this driver is for
  • add your copyright notice (important: your name and email)
  • Please do not modify the GPL part! (Yes, you have to put your code under GPL, otherwise I'll refuse your patch)
  • do some documentation (I know that real programmers write programs, not documentation, but…)
  • change the line static char Name[] = “Sample”; to your driver's name
  • the next steps depend on wheter your display uses text or graphic mode:
  • text mode:
    • remove #include “drv_generic_graphic.h”
    • remove the whole drv_Sample_blit function
    • remove the drv_Sample_start2, drv_Sample_init2 and drv_Sample_quit2 functions
    • remove the DRIVER drv_Sample2 declaration at the very bottom
  • graphic mode:
    • remove #include “drv_generic_text.h”
    • remove the drv_Sample_clear, drv_Sample_write and drv_Sample_defchar functions
    • remove the drv_Sample_start, drv_Sample_init and drv_Sample_quit functions
    • rename the drv_Sample_start2, drv_Sample_init2 and drv_Sample_quit2 functions and remove the 2
    • remove the DRIVER drv_Sample2 declaration at the very bottom
  • if your drisplay doesn't have any GPO's, remove all gpo and gpio stuff
  • quit editing at this point and continue with next step
• edit drv.c, add declarations and definitions for your driver (just search for Sample, copy&paste the corresponding areas, but try to keep them in alphabetical order):

extern DRIVER drv_Sample;

#ifdef WITH_SAMPLE
    &drv_Sample,
#endif

• edit Makefile.am and add your drv_*.c to EXTRA_lcd4linux_SOURCES (again, copy&paste the drv_Sample areas, take care for alphabetical order)
• edit drivers.m4 and copy&paste all Sample and SAMPLE areas (alphabetical order, please). Here you have to decide which generic drivers your display wants to use:

if test "$SAMPLE" = "yes"; then
   # select either text or graphics mode
   TEXT="yes"
   GRAPHIC="yes"
   # support for GPIO's
   GPIO="yes"
   # select bus: serial (including USB), parallel or i2c
   SERIAL="yes"
   PARPORT="yes"
   #I2C="yes"
   DRIVERS="$DRIVERS drv_Sample.o"
   AC_DEFINE(WITH_SAMPLE,1,[[:Sample|driver]])
fi

If your display uses text mode only, remove the GRAPHIC=“yes” line. If it's a graphic one, remove TEXT=“yes”. If you don't have GPO's, remove the GPO=“yes”. Same goes for serial or parallel port. Do not use I2C unless you've been talking to us and you know what you're doing. If your display uses USB, it's either a serial one (using /dev/usb/tts/0 or /dev/tts/USB0 or something), so use the serial subsystem. If it's a real USB display, you want to use libusb, which makes things a bit more complex. Please drop us an email in this case…

• run ./bootstrap, ./configure and make
• test if everything compiles and links fine. Now you should have set up the framework for your new display driver!
• edit drv_YourName.c again and fill it with life:
  • text mode:
    • drv_Sample_clear: send a command to the display which clears it
    • drv_Sample_write: do cursor positioning and send a string to the display (don't mind about double buffering, the generic text subsystem will take care of)
    • drv_Sample_defchar: define the bitmap of a user-defined char (used for bars & icons)
  • graphic mode:
    • drv_Sample_blit: transfer the framebuffer managed by the generic graphic subsystem to the display. That's all what's up to you!
    • drv_Sample_GPO: set GPO's
    • drv_Sample_start: maybe read some things from the config file, and initialize display
    • drv_Sample_init: read things from config (e.g. display size), set some necessary global variables, and initialize the driver
    • if your display supports some special features (like contrast, backlight, brightness, …) implement it as plugins. See plugin_contrast for an example.
    • if there are none, remove all the contrast stuff
    • As your display is either serial or parallel one, you have to adopt these parts, too. Serial (and USB) displays are very easy to handle (there is a drv_generic_serial_send() function which does all the low-level communication). Parallel port displays are a bit tricky, because you have to do all the bit-banging by hand. I tried to provide some very basic functionality in the sample driver (which will surely not work on any display!), and I hope you get the idea…
• test it with your display
• run ./indent.sh to apply coding style (this does source code formatting)
• send us a patch:
  • run svn diff >your_patch.diff and send us the file
  • run svn commit -m “<your log message>” if you have SVN developer access and 'you know what you're doing'
• Please add documentation to the wiki!!!

It's easy, believe me!