diff --git a/docs/lcdproc-dev/add-your-driver.docbook b/docs/lcdproc-dev/add-your-driver.docbook index da82c1b..00a8eea 100644 --- a/docs/lcdproc-dev/add-your-driver.docbook +++ b/docs/lcdproc-dev/add-your-driver.docbook @@ -19,6 +19,11 @@ Be sure to read and as well. + +As a starting point you may take a look at the debug driver. It is available +as server/drivers/debug.c. + + @@ -32,7 +37,7 @@ driver to be included in LCDproc's code some conditions have to be met: The hardware (display or enclosing product) is publicly sold - OR the schematics and firmware (if required) are publicy + OR the schematics and firmware (if required) are publicly available. Therefore I will not commit drivers for displays ripped out from an old telephone for your private hardware project and are not @@ -47,27 +52,27 @@ driver to be included in LCDproc's code some conditions have to be met: The submitter is or is acting on behalf of the original driver developer. I will not submit drivers found somewhere on the internet and - submitted without the original developer's acknowledgement. + submitted without the original developer's written acknowledgement. - The driver describtion contains a valid email address for contacting + The driver description contains a valid email address for contacting the submitter or developer. The code is commented AND includes appropriate - Doxygen comments, especially for private / non-API functions. + Doxygen comments, especially for internal / non-API functions. End user documentation (updates to man pages AND - user-guide in docbook) is available. + User's Guide in docbook format) is available. Driver options are described in the end user documentation AND LCDd.conf. - The driver adhere the style guide as described in . + The driver adheres to the style guide as described in . @@ -271,6 +276,34 @@ Please do not forget to also add the required documentation, so that your driver can be used from others as well. + +Within the source code + + +We use Doxygen to document functions and data types. The doxygen documentation +can be created anytime by changing to the docs/ directory +and running doxygen. + + +When documenting your driver's API functions you may use a short hand version +and add 'API:' to the beginning of your comment and leave out the parameter +and return value description (as we know what the API is doing). If you use +some clever algorithm inside a function please add a few words about it. + + + +Always document functions internal to the driver! We do know what the API +does (or is expected to do) but we don't know about what your driver does +internally. + + +Read on how for format comments. + + + + + + The configuration file, LCDd.conf diff --git a/docs/lcdproc-dev/make-driver.docbook b/docs/lcdproc-dev/make-driver.docbook index 0b3fca1..a81df9c 100644 --- a/docs/lcdproc-dev/make-driver.docbook +++ b/docs/lcdproc-dev/make-driver.docbook @@ -21,9 +21,9 @@ dedicated chapter in this book. port.h : Parallel port I/O -The file port.h, located in the server/drivers/ directory provide Input/Output -and port permissions for the PC compatible parallel port, also known as the -LPT port. +The file port.h, located in the server/drivers/ +directory provide Input/Output and port permissions for the PC compatible +parallel port, also known as the LPT port. @@ -32,7 +32,15 @@ has parallel port! In these situations, the configure script will see this and disable drivers that need a parallel port. -port.h file defines 6 static inline functions for port I/O: + +The functions in port.h are defined and as 'static inline'. +Therefore each driver including this header file gets its own copy of the +functions and they are inlined into the driver's code. As a result calls to +port_in() and port_out() are directly translated to inb() or outb() or +assembly code by the compiler. There is less to no overhead in using them. + + +port.h file defines 6 static inline functions for port I/O: Read a byte from port @@ -130,23 +138,24 @@ disable drivers that need a parallel port. #include "port.h" -/* Get access to these 3 ports: - 0x378 (CONTROL), - 0x379 (STATUS) and - 0x37A (DATA) -*/ -if ( -1 == port_access_multiple(0x378,3) ) { +/* + * Get access to these 3 ports: + * 0x378 (CONTROL), + * 0x379 (STATUS) and + * 0x37A (DATA) + */ +if (port_access_multiple(0x378, 3) == -1) { /* Access denied, do something */ } /* Write a 'A' to the control port */ -ort_out(0x378, 'A'); +port_out(0x378, 'A'); /* Read from the status port */ char status = port_in(0x379); /* Close the 3 ports */ -port_deny_multiple(0x378,3); +port_deny_multiple(0x378, 3); diff --git a/docs/lcdproc-dev/programming.docbook b/docs/lcdproc-dev/programming.docbook index 77dcb59..c2e8d94 100644 --- a/docs/lcdproc-dev/programming.docbook +++ b/docs/lcdproc-dev/programming.docbook @@ -114,7 +114,7 @@ should look like. - + File format and indention @@ -140,7 +140,7 @@ should look like. Indention: Tab indention shall be used (with tab width set to 8 characters). Only exception are switch labels which are - indented a half tab (4 characters). + indented a half tab (4 spaces). @@ -153,14 +153,15 @@ should look like. - + Naming conventions Function names: - Function names shall be lowercase. We do not use CamelCase. Multiple words - are separated by underscore. + Function names shall be lowercase. We do not use CamelCase (some + historical exceptions may exist). Multiple words are separated by + underscore. @@ -198,7 +199,7 @@ unsigned char HD44780_scankeypad(PrivateData *p); - + Comments @@ -248,7 +249,7 @@ unsigned char HD44780_scankeypad(PrivateData *p); - + Statement style @@ -309,7 +310,7 @@ y--; Function calls: - There shall be no space between the function call and the opening '(' of + There shall be no space between the function call and the opening brace '(' of the parameter list. Within the parameter list a space shall be after each parameter.