From 46f930bf982c901289bd95f7d98efa8793f0469b Mon Sep 17 00:00:00 2001 From: gfk Date: Tue, 1 Oct 2002 18:40:21 +0000 Subject: [PATCH] Starting the developers docs in docbook. --- docs/Makefile.am | 2 +- docs/lcdproc-dev/Makefile.am | 1 + docs/lcdproc-dev/README.docbook | 14 + docs/lcdproc-dev/add-your-driver.docbook | 171 +++++++++ docs/lcdproc-dev/bookinfo.docbook | 48 +++ docs/lcdproc-dev/introduction.docbook | 35 ++ docs/lcdproc-dev/lcdproc-dev.docbook | 20 + docs/lcdproc-dev/license.docbook | 464 +++++++++++++++++++++++ docs/lcdproc-dev/make-driver.docbook | 146 +++++++ docs/lcdproc-dev/shared-files.docbook | 263 +++++++++++++ 10 files changed, 1163 insertions(+), 1 deletion(-) create mode 100644 docs/lcdproc-dev/Makefile.am create mode 100644 docs/lcdproc-dev/README.docbook create mode 100644 docs/lcdproc-dev/add-your-driver.docbook create mode 100644 docs/lcdproc-dev/bookinfo.docbook create mode 100644 docs/lcdproc-dev/introduction.docbook create mode 100644 docs/lcdproc-dev/lcdproc-dev.docbook create mode 100644 docs/lcdproc-dev/license.docbook create mode 100644 docs/lcdproc-dev/make-driver.docbook create mode 100644 docs/lcdproc-dev/shared-files.docbook diff --git a/docs/Makefile.am b/docs/Makefile.am index 72328fd..0300001 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,3 +1,3 @@ man_MANS = lcdproc.1 LCDd.8 -SUBDIRS = lcdproc-user +SUBDIRS = lcdproc-user lcdproc-dev EXTRA_DIST = README.dg README.dg2 menustuff.txt netstuff.txt lcdproc.1 LCDd.8 diff --git a/docs/lcdproc-dev/Makefile.am b/docs/lcdproc-dev/Makefile.am new file mode 100644 index 0000000..9abdf36 --- /dev/null +++ b/docs/lcdproc-dev/Makefile.am @@ -0,0 +1 @@ +EXTRA_DIST = lcdproc-dev.docbook bookinfo.docbook introduction.docbook shared-files.docbook make-driver.docbook add-your-driver.docbook license.docbook diff --git a/docs/lcdproc-dev/README.docbook b/docs/lcdproc-dev/README.docbook new file mode 100644 index 0000000..3485a98 --- /dev/null +++ b/docs/lcdproc-dev/README.docbook @@ -0,0 +1,14 @@ +README.docbook + +You can generate the documentation of LCDproc using +the Docbook utilities. + +$ docbook2html lcdproc-user.docbook + +should generate ist as HTML. + +On my box (Mdk 8.1) I have to run + +$ docbook2html -c /etc/sgml/catalog lcdproc-user.docbook + +(-c defines the location of the SGML catalog) \ No newline at end of file diff --git a/docs/lcdproc-dev/add-your-driver.docbook b/docs/lcdproc-dev/add-your-driver.docbook new file mode 100644 index 0000000..e18ee6c --- /dev/null +++ b/docs/lcdproc-dev/add-your-driver.docbook @@ -0,0 +1,171 @@ + +Adding your driver to LCDproc + + +Introduction + + +LCDproc is meant to be modular, it is relatively easy to add new input and output drivers to LCDproc. + + + +This chapter will explain you the major steps and few gotchas of adding your own driver to LCDproc. Enjoy! + + + + + +Autoconf, automake, börk börk börk! + +How I Learned to Stop Worrying and Love the Configure Script + + +It was decided pretty early in LCDproc's life to use GNU autoconf and GNU automake. This allows LCDproc to be ported to several platforms with much less effort. It can be quite daunting to understand how autoconf & automake interact with each others and with your code, but don't be discouraged. We have taken great care in making this as simple as possible for programers to add their own driver to LCDproc. Hopefully, you'll only have to modify two files, one for autoconf and one for automake. + + + +The first thing you need to do is to find a name for your driver, it should be as descriptive as possible; most drivers are named after their respective chipset, for example hd44780, mtc_s16209x, sed1330 and stv5730, others are named after the company that makes that particular LCD display, for example CFontz and MtxOrb. Remember that these names are case sensitive. In this chapter, we'll use myDriver (which is an absolute non-descriptive name). + + + +Autoconf and its friend, acinclude.m4 + + +You need to add your driver to function LCD_DRIVERS_SELECT of file acinclude.m4. This can be done in three steps. + + + +Step 1 + +First you need to add your driver name to the list of possible choices in the help screen. + + +This: + +AC_ARG_ENABLE(drivers, + [ --enable-drivers=<list> compile driver for LCDs in <list>.] + [ drivers may be separated with commas.] + [ Possible choices are:] + [ mtxorb,cfontz,cfontz633,curses,text,lb216,] + [ hd44780,joy,irman,lirc,bayrad,glk,,mtc_s16209x] + [ stv5730,sed1330,sed1520,svga,lcdm001,t6963] + [ lcterm,icp_a106] + [ \"all\" compiles all drivers], + drivers="$enableval", + +becomes: + +AC_ARG_ENABLE(drivers, + [ --enable-drivers=<list> compile driver for LCDs in <list>.] + [ drivers may be separated with commas.] + [ Possible choices are:] + [ mtxorb,cfontz,cfontz633,curses,text,lb216,] + [ hd44780,joy,irman,lirc,bayrad,glk,,mtc_s16209x] + [ stv5730,sed1330,sed1520,svga,lcdm001,t6963] + [ lcterm,icp_a106,myDriver] + [ \"all\" compiles all drivers], + drivers="$enableval", + + + + + +Step 2 + +Second, you need to add your driver to the list of all drivers. + +This: + +if test "$drivers" = "all"; then + drivers=[mtxorb,cfontz,...biglist...,lcterm,icp_a106] +fi + +becomes: + +if test "$drivers" = "all"; then + drivers=[mtxorb,cfontz,...biglist...,lcterm,icp_a106,myDriver] +fi + + + + + +Step 3 + +Then last, you need to add your driver to be big switch-case in this function, see below. + + + myDriver) + DRIVERS="$DRIVERS myDriver${SO}" + actdrivers=["$actdrivers myDriver"] + ;; + + + +If your driver only works in some platform or requires a particular library or header, you can add your autoconf test here. You can see how other drivers do it, but if you're not sure on how to do this, just send an email to the mailing list and we'll make it for you. + + + + + + + +Automake and its friend, Makefile.am + +Allready half of the job is done! Not to bad, wasn't it? The rest should be just as easy. In this section, you'll be adding your driver to the file server/drivers/Makefile.am. As you can guess, it's the Makefile for the drivers. This can be done in three (or two) simple steps. + + +Step 1 + +First, you need to add your driver to the list of drivers in this file, this list is called EXTRA_PROGRAMS. + +This + +EXTRA_PROGRAMS = bayrad CFontz ...biglist... text wirz_sli + +becomes + +EXTRA_PROGRAMS = bayrad CFontz ...biglist... text wirz_sli myDriver + + + + + +Step 2 + +This second step is only needed if your driver needs a particular library. If it doesn't, you can skip to step 3. + +You basically need to put you driver name followed by _LDADD and egal this to the name of the library that you need. Usually, these library are substituted by a autoconf variable, if you're not comfortable with this, you send an email to the mailing list and we'll set this up for you. + +For example, we would put this for our fictional driver + +myDriver_LDADD = @SOMESTRANGELIB@ + + + + + +Step 3 + +Last but not least, you need to specify which source files should be associated with your driver. You put your driver name followed by _SOURCES and egal this to a space separated list of the source and header files. See below for an example. + + +myDriver_SOURCES = lcd.h myDriver.c myDriver.h report.h + + + + + + + +Test your setup + +You're almost done! You only need to check out if you didn't made any mistake. Just run sh autogen.sh to regenerate the configure script and Makefiles, then run ./configure --enable-driver=myDriver and type make. If your driver compiles without error, then congratulations, you've just added your driver to LCDproc! Remember to submit a patch to the mailing list so that we can add it to the standard distribution. + +If you had an error, just send us an email describing it to the mailing list and we'll try to help you. + + + + + + diff --git a/docs/lcdproc-dev/bookinfo.docbook b/docs/lcdproc-dev/bookinfo.docbook new file mode 100644 index 0000000..194b888 --- /dev/null +++ b/docs/lcdproc-dev/bookinfo.docbook @@ -0,0 +1,48 @@ + + +LCDproc Developer's Guide +The Hitchhicker's Guide to LCDproc 0.5 + + + + +Guillaume +Filion +
gfk@logidac.com
 + + + + +2002-10-01 +0.0.1 + + + +This document is a guide to LCDproc written for developers. It covers LCDproc 0.5. Users should read the user guide. + + + + +2002 +Guillaume Filion + + + + +Permission is granted to copy, distribute and/or modify this +document under the terms of the GNU Free Documentation License, Version +1.1 or any later version published by the Free Software Foundation; with +no Invariant Sections, with no Front-Cover texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled "GNU +Free Documentation License". + + + + +documentation +LCDproc +0.5 +developer guide + + + diff --git a/docs/lcdproc-dev/introduction.docbook b/docs/lcdproc-dev/introduction.docbook new file mode 100644 index 0000000..f5a1937 --- /dev/null +++ b/docs/lcdproc-dev/introduction.docbook @@ -0,0 +1,35 @@ + +Introduction + + +About this Document + + +This document is meant to be a reference for LCDproc developers. It tries to indicate you +where to find the relevant information about LCDproc's inner workings. + + + +Please note that this document is still "under construction". +If you run into any trouble feel free to write to the LCDproc mailing list. +See http://lcdproc.org/mail.php3 +for details on how to subscribe to the list. + + +Therefore you might want to have a look at http://lcdproc.sf.net/docs/, +to get the latest version of this document, unless you want to generate it yourself from the +docbook files in the CVS). + + + +This document was written for LCDproc 0.5. + + + +In several other places e-mails and other documents have been included in this +document. The authors of those are listed below every such document. + + + + + diff --git a/docs/lcdproc-dev/lcdproc-dev.docbook b/docs/lcdproc-dev/lcdproc-dev.docbook new file mode 100644 index 0000000..7671c82 --- /dev/null +++ b/docs/lcdproc-dev/lcdproc-dev.docbook @@ -0,0 +1,20 @@ + + + + + + +]> + + + +&bookinfo; + +&introduction; +&shared-files; +&make-driver; +&add-your-driver; +&license; + + diff --git a/docs/lcdproc-dev/license.docbook b/docs/lcdproc-dev/license.docbook new file mode 100644 index 0000000..ec33470 --- /dev/null +++ b/docs/lcdproc-dev/license.docbook @@ -0,0 +1,464 @@ + +GNU Free Documentation License + + + + + + +Version 1.1, March 2000 + +
+Copyright (C) 2000 Free Software Foundation, Inc. +59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +
+ + +PREAMBLE + +The purpose of this License is to make a manual, textbook, + or other written document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by + others. + +This License is a kind of "copyleft", which means that + derivative works of the document must themselves be free in the + same sense. It complements the GNU General Public License, which + is a copyleft license designed for free software. + +We have designed this License in order to use it for manuals + for free software, because free software needs free documentation: + a free program should come with manuals providing the same + freedoms that the software does. But this License is not limited + to software manuals; it can be used for any textual work, + regardless of subject matter or whether it is published as a + printed book. We recommend this License principally for works + whose purpose is instruction or reference. + + + +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work that + contains a notice placed by the copyright holder saying it can be + distributed under the terms of this License. The "Document", + below, refers to any such manual or work. Any member of the + public is a licensee, and is addressed as "you". + +A "Modified Version" of the Document means any work + containing the Document or a portion of it, either copied + verbatim, or with modifications and/or translated into another + language. + +A "Secondary Section" is a named appendix or a front-matter + section of the Document that deals exclusively with the + relationship of the publishers or authors of the Document to the + Document's overall subject (or to related matters) and contains + nothing that could fall directly within that overall subject. + (For example, if the Document is in part a textbook of + mathematics, a Secondary Section may not explain any mathematics.) + The relationship could be a matter of historical connection with + the subject or with related matters, or of legal, commercial, + philosophical, ethical or political position regarding + them. + +The "Invariant Sections" are certain Secondary Sections + whose titles are designated, as being those of Invariant Sections, + in the notice that says that the Document is released under this + License. + +The "Cover Texts" are certain short passages of text that + are listed, as Front-Cover Texts or Back-Cover Texts, in the + notice that says that the Document is released under this + License. + +A "Transparent" copy of the Document means a + machine-readable copy, represented in a format whose specification + is available to the general public, whose contents can be viewed + and edited directly and straightforwardly with generic text + editors or (for images composed of pixels) generic paint programs + or (for drawings) some widely available drawing editor, and that + is suitable for input to text formatters or for automatic + translation to a variety of formats suitable for input to text + formatters. A copy made in an otherwise Transparent file format + whose markup has been designed to thwart or discourage subsequent + modification by readers is not Transparent. A copy that is not + "Transparent" is called "Opaque". + +Examples of suitable formats for Transparent copies include + plain ASCII without markup, Texinfo input format, LaTeX input + format, SGML or XML using a publicly available DTD, and + standard-conforming simple HTML designed for human modification. + Opaque formats include PostScript, PDF, proprietary formats that + can be read and edited only by proprietary word processors, SGML + or XML for which the DTD and/or processing tools are not generally + available, and the machine-generated HTML produced by some word + processors for output purposes only. + +The "Title Page" means, for a printed book, the title page + itself, plus such following pages as are needed to hold, legibly, + the material this License requires to appear in the title page. + For works in formats which do not have any title page as such, + "Title Page" means the text near the most prominent appearance of + the work's title, preceding the beginning of the body of the + text. + + + +VERBATIM COPYING + +You may copy and distribute the Document in any medium, + either commercially or noncommercially, provided that this + License, the copyright notices, and the license notice saying this + License applies to the Document are reproduced in all copies, and + that you add no other conditions whatsoever to those of this + License. You may not use technical measures to obstruct or + control the reading or further copying of the copies you make or + distribute. However, you may accept compensation in exchange for + copies. If you distribute a large enough number of copies you + must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated + above, and you may publicly display copies. + + + +COPYING IN QUANTITY + +If you publish printed copies of the Document numbering more + than 100, and the Document's license notice requires Cover Texts, + you must enclose the copies in covers that carry, clearly and + legibly, all these Cover Texts: Front-Cover Texts on the front + cover, and Back-Cover Texts on the back cover. Both covers must + also clearly and legibly identify you as the publisher of these + copies. The front cover must present the full title with all + words of the title equally prominent and visible. You may add + other material on the covers in addition. Copying with changes + limited to the covers, as long as they preserve the title of the + Document and satisfy these conditions, can be treated as verbatim + copying in other respects. + +If the required texts for either cover are too voluminous to + fit legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + +If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a + machine-readable Transparent copy along with each Opaque copy, or + state in or with each Opaque copy a publicly-accessible + computer-network location containing a complete Transparent copy + of the Document, free of added material, which the general + network-using public has access to download anonymously at no + charge using public-standard network protocols. If you use the + latter option, you must take reasonably prudent steps, when you + begin distribution of Opaque copies in quantity, to ensure that + this Transparent copy will remain thus accessible at the stated + location until at least one year after the last time you + distribute an Opaque copy (directly or through your agents or + retailers) of that edition to the public. + +It is requested, but not required, that you contact the + authors of the Document well before redistributing any large + number of copies, to give them a chance to provide you with an + updated version of the Document. + + + +MODIFICATIONS + +You may copy and distribute a Modified Version of the + Document under the conditions of sections 2 and 3 above, provided + that you release the Modified Version under precisely this + License, with the Modified Version filling the role of the + Document, thus licensing distribution and modification of the + Modified Version to whoever possesses a copy of it. In addition, + you must do these things in the Modified Version: + + +Use in the Title Page + (and on the covers, if any) a title distinct from that of the + Document, and from those of previous versions (which should, if + there were any, be listed in the History section of the + Document). You may use the same title as a previous version if + the original publisher of that version gives permission. + + +List on the Title Page, + as authors, one or more persons or entities responsible for + authorship of the modifications in the Modified Version, + together with at least five of the principal authors of the + Document (all of its principal authors, if it has less than + five). + + +State on the Title page + the name of the publisher of the Modified Version, as the + publisher. + + +Preserve all the + copyright notices of the Document. + + +Add an appropriate + copyright notice for your modifications adjacent to the other + copyright notices. + + +Include, immediately + after the copyright notices, a license notice giving the public + permission to use the Modified Version under the terms of this + License, in the form shown in the Addendum below. + + +Preserve in that license + notice the full lists of Invariant Sections and required Cover + Texts given in the Document's license notice. + + +Include an unaltered + copy of this License. + + +Preserve the section + entitled "History", and its title, and add to it an item stating + at least the title, year, new authors, and publisher of the + Modified Version as given on the Title Page. If there is no + section entitled "History" in the Document, create one stating + the title, year, authors, and publisher of the Document as given + on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence. + + +Preserve the network + location, if any, given in the Document for public access to a + Transparent copy of the Document, and likewise the network + locations given in the Document for previous versions it was + based on. These may be placed in the "History" section. You + may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission. + + +In any section entitled + "Acknowledgements" or "Dedications", preserve the section's + title, and preserve in the section all the substance and tone of + each of the contributor acknowledgements and/or dedications + given therein. + + +Preserve all the + Invariant Sections of the Document, unaltered in their text and + in their titles. Section numbers or the equivalent are not + considered part of the section titles. + + +Delete any section + entitled "Endorsements". Such a section may not be included in + the Modified Version. + + +Do not retitle any + existing section as "Endorsements" or to conflict in title with + any Invariant Section. + + +If the Modified Version includes new front-matter sections + or appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option + designate some or all of these sections as invariant. To do this, + add their titles to the list of Invariant Sections in the Modified + Version's license notice. These titles must be distinct from any + other section titles. + +You may add a section entitled "Endorsements", provided it + contains nothing but endorsements of your Modified Version by + various parties--for example, statements of peer review or that + the text has been approved by an organization as the authoritative + definition of a standard. + +You may add a passage of up to five words as a Front-Cover + Text, and a passage of up to 25 words as a Back-Cover Text, to the + end of the list of Cover Texts in the Modified Version. Only one + passage of Front-Cover Text and one of Back-Cover Text may be + added by (or through arrangements made by) any one entity. If the + Document already includes a cover text for the same cover, + previously added by you or by arrangement made by the same entity + you are acting on behalf of, you may not add another; but you may + replace the old one, on explicit permission from the previous + publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by + this License give permission to use their names for publicity for + or to assert or imply endorsement of any Modified Version. + + + +COMBINING DOCUMENTS + +You may combine the Document with other documents released + under this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination + all of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice. + +The combined work need only contain one copy of this + License, and multiple identical Invariant Sections may be replaced + with a single copy. If there are multiple Invariant Sections with + the same name but different contents, make the title of each such + section unique by adding at the end of it, in parentheses, the + name of the original author or publisher of that section if known, + or else a unique number. Make the same adjustment to the section + titles in the list of Invariant Sections in the license notice of + the combined work. + +In the combination, you must combine any sections entitled + "History" in the various original documents, forming one section + entitled "History"; likewise combine any sections entitled + "Acknowledgements", and any sections entitled "Dedications". You + must delete all sections entitled "Endorsements." + + + +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and + other documents released under this License, and replace the + individual copies of this License in the various documents with a + single copy that is included in the collection, provided that you + follow the rules of this License for verbatim copying of each of + the documents in all other respects. + +You may extract a single document from such a collection, + and distribute it individually under this License, provided you + insert a copy of this License into the extracted document, and + follow this License in all other respects regarding verbatim + copying of that document. + + + +AGGREGATION WITH INDEPENDENT WORKS +A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of + a storage or distribution medium, does not as a whole count as a + Modified Version of the Document, provided no compilation + copyright is claimed for the compilation. Such a compilation is + called an "aggregate", and this License does not apply to the + other self-contained works thus compiled with the Document, on + account of their being thus compiled, if they are not themselves + derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to + these copies of the Document, then if the Document is less than + one quarter of the entire aggregate, the Document's Cover Texts + may be placed on covers that surround only the Document within the + aggregate. Otherwise they must appear on covers around the whole + aggregate. + + + +TRANSLATION + +Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires + special permission from their copyright holders, but you may + include translations of some or all Invariant Sections in addition + to the original versions of these Invariant Sections. You may + include a translation of this License provided that you also + include the original English version of this License. In case of + a disagreement between the translation and the original English + version of this License, the original English version will + prevail. + + + +TERMINATION +You may not copy, modify, sublicense, or distribute the + Document except as expressly provided for under this License. Any + other attempt to copy, modify, sublicense or distribute the + Document is void, and will automatically terminate your rights + under this License. However, parties who have received copies, or + rights, from you under this License will not have their licenses + terminated so long as such parties remain in full + compliance. + + + +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised + versions of the GNU Free Documentation License from time to time. + Such new versions will be similar in spirit to the present + version, but may differ in detail to address new problems or + concerns. See http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing + version number. If the Document specifies that a particular + numbered version of this License "or any later version" applies to + it, you have the option of following the terms and conditions + either of that specified version or of any later version that has + been published (not as a draft) by the Free Software Foundation. + If the Document does not specify a version number of this License, + you may choose any version ever published (not as a draft) by the + Free Software Foundation. + + + +How to use this License for your documents + +To use this License in a document you have written, include + a copy of the License in the document and put the following + copyright and license notices just after the title page: + +
+Copyright (c) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.1 + or any later version published by the Free Software Foundation; + with the Invariant Sections being LIST THEIR TITLES, with the + Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. + A copy of the license is included in the section entitled "GNU + Free Documentation License". +
+ +If you have no Invariant Sections, write "with no Invariant + Sections" instead of saying which ones are invariant. If you have + no Front-Cover Texts, write "no Front-Cover Texts" instead of + "Front-Cover Texts being LIST"; likewise for Back-Cover + Texts. + +If your document contains nontrivial examples of program + code, we recommend releasing these examples in parallel under your + choice of free software license, such as the GNU General Public + License, to permit their use in free software. + + + + + diff --git a/docs/lcdproc-dev/make-driver.docbook b/docs/lcdproc-dev/make-driver.docbook new file mode 100644 index 0000000..8805b36 --- /dev/null +++ b/docs/lcdproc-dev/make-driver.docbook @@ -0,0 +1,146 @@ + +Making a LCDproc driver + + +Introduction + + +LCDproc is meant to be modular, it is relatively easy to add new input and output drivers to LCDproc. Actually, there are a few things that you can do to make your life easier, they are listed here. + + + +This chapter will explain you the major steps and few gotchas of adding your own driver to LCDproc. Enjoy! + + + + + +Shared files specific for drivers + + +Driving an LCD display is not easy; you need to address ports, to send bytes in a certain order, to respect timing, and unfortunaly no two operating system let you do this in the same way. But don't dispair! There's hope! Someone in a galaxy far far away, has allready done the dirty job for you! This dirty job has been put in shared files. These shared files are full cross platform and are automagically configured by the configure script. You only need to include them and use their functions to benefit from them. + + + +These files are provided only for drivers, others are provided for all of LCDproc. These files are located in the shared directory, they have a 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. + + +Of course, these functions will only work if the computer where LCDproc runs 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: + + +Read a byte from port + + + + static inline int port_in + unsigned short int port + + +Returns the content of the byte. + + + +Write a char(byte) 'val' to port + + + + static inline void port_out + unsigned short int port + unsigned char val + + +Returns nothing (void). + + + +Get access to a specific port + + + + static inline int port_access + unsigned short int port + + +Returns 0 if successful, -1 if failed. + + + + +Close access to a specific port + + + + static inline int port_deny + unsigned short int port + + +Returns 0 if successful, -1 if failed. + + + + +Get access to three sequential ports + + +/* port (CONTROL), port+1 (STATUS) and port+2 (DATA) */ + + static inline int port_access_full + unsigned short int port + + +Returns 0 if successful, -1 if failed. + + + +Close access to three sequential ports + + + + static inline int port_deny_full + unsigned short int port + + +Returns 0 if successful, -1 if failed. + + + + +Example use + +#include "port.h" + +/* Get access to these 3 ports: + 0x378 (CONTROL), + 0x379 (STATUS) and + 0x37A (DATA) +*/ +if ( -1 == port_access_full(0x378) ) { + /* Access denied, do something */ +} + +/* Write a 'A' to the control port */ +ort_out(0x378, 'A'); + +/* Read from the status port */ +char status = port_in(0x379); + +/* Close the 3 ports */ +port_deny_full(0x378); + + + + + + + + + diff --git a/docs/lcdproc-dev/shared-files.docbook b/docs/lcdproc-dev/shared-files.docbook new file mode 100644 index 0000000..5c858df --- /dev/null +++ b/docs/lcdproc-dev/shared-files.docbook @@ -0,0 +1,263 @@ + +Shared files + + +Introduction + + +Here we provide functions that should be used by all parts of the program. + + + + + +report.h : Debugging and reporting + +To enable the debug() function on all of the software, just type: +./configure --enable-debug and recompile with 'make'. + +To enable the debug() function only in specific files: +1) Configure without enabling debug (that is without --enable-debug) +2) Edit the source file that you want to debug and put the following + line at the top, before the #include "report.h" line: + #define DEBUG +3) Then recompile with 'make' +This way, the global DEBUG macro is off but is locally enabled in +certains parts of the software. + +The reporting levels have the following meaning. + +Reporting Levels + +0 RPT_CRIT + +Critical conditions: the program stops right after +this. Only use this if the program is actually exited +from the current function. + + + +1 RPT_ERR + +Error conditions: serious problem, program continues. +Use this just before you return -1 from a function. + + + +2 RPT_WARNING + +Warning conditions: Something that the user should +fix, but the program can continue without a real +problem. Ex: Protocol errors from a client. + + + +3 RPT_NOTICE + +Major event in the program: (un)loading of driver, client (dis)connect. + + + +4 RPT_INFO + +Minor event in the program: the activation of a +setting, details of a loaded driver, a key +reservation, a keypress, a screen switch. + + + +5 RPT_DEBUG + +Insignificant event: What function has been called, what subpart of a +function is being executed, what was received and sent +over the socket, etc. + + + + + +Levels 4 (maybe) and 5 (certainly) should be reported using the debug +function. The code that this function generates will not be in the executable when +compiled without debugging. This way memory and CPU cycles are saved. + +report.h file defines 3 functions for debugging and reporting: + + +Sets reporting level and message destination + + + + int set_reporting + char * application_name + int new_level + int new_dest + + +Returns the content of the byte. + + + + +Report the message to the selected destination if important enough + + + + void report + const int level + const char *format + ... + + +Returns nothing (void). + +The format parameter is the same as the one used by printf. + + + + +Send debugging information if important enough + +Consider the debug function to be exactly the same as the report function. The only difference is that it is only compiled in if DEBUG is defined. + + + + + + +LL.h : Linked Lists (Doubly-Linked Lists) + + +Creating a list + +To create a list, do the following: + + +LinkedList *list; +list = LL_new(); +if(!list) handle_an_error(); + + +The list can hold any type of data. You will need to typecast your datatype to a "void *", though. So, to add something to the list, the following would be a good way to start: + + +typedef struct my_data { + char string[16]; + int number; +} my_data; + +my_data *thingie; + +for(something to something else) { + thingie = malloc(sizeof(my_data)); + LL_AddNode(list, (void *)thingie); // typecast it to a "void *" +} + + +For errors, the general convention is that "0" means success, and a negative number means failure. Check LL.c to be sure, though. + + + +Changing data + +To change the data, try this: + + +thingie = (my_data *)LL_Get(list); // typecast it back to "my_data" +thingie->number = another_number; + + +You don't need to "Put" the data back, but it doesn't hurt anything. + + +LL_Put(list, (void *)thingie); + + +However, if you want to point the node's data somewhere else, you'll need to get the current data first, keep track of it, then set the data to a new location: + + +my_data * old_thingie, new_thingie; + +old_thingie = (my_data *)LL_Get(list); +LL_Put(list, (void *)new_thingie); + +// Now, do something with old_thingie. (maybe, free it?) + + +Or, you could just delete the node entirely and then add a new one: + + +my_data * thingie; + +thingie = (my_data *)LL_DeleteNode(list); +free(thingie); + +thingie->number = 666; + +LL_InsertNode(list, (void *)thingie); + + + + +Iterations throught the list + +To iterate on each list item, try this: + + +LL_Rewind(list); +do { + my_data = (my_data *)LL_Get(list); + /* ... do something to it ... */ +} while(LL_Next(list) == 0); + + + + +Using the list as a stack or a queue + +You can also treat the list like a stack, or a queue. Just use the following functions: + + +LL_Push() // Regular stack stuff: add, remove, peek, rotate +LL_Pop() +LL_Top() +LL_Roll() + +LL_Shift() // Other end of the stack (like in perl) +LL_Unshift() +LL_Look() +LL_UnRoll() + +LL_Enqueue() // Standard queue operations +LL_Dequeue() + + +There are also other goodies, like sorting and searching. + + + +Future + +Array-like operations will come later, to allow numerical indexing: + + +LL_nGet(list, 3); +LL_nSwap(list, 6, 13); +LL_nPut(list, -4, data); // Puts item at 4th place from the end.. + + +More ideas for later: + + +LL_MoveNode(list, amount); // Slides a node to another spot in the list +-- LL_MoveNode(list, -1); // moves a node back one toward the head + + +That's about it, for now... Be sure to free the list when you're done! + +See LL.c for more detailed descriptions of these functions. + + + + + +