From e04654e6d9c18262f0e2818ea344a1e961bf1d73 Mon Sep 17 00:00:00 2001 From: Joel Bodenmann Date: Thu, 25 Oct 2012 01:04:36 +0200 Subject: [PATCH] version 1.3 release --- docs/codingstyle.txt | 289 ------------------------------------------ docs/configure.txt | 43 ------- docs/console.txt | 20 --- docs/contributors.txt | 27 ---- docs/files.txt | 119 ----------------- docs/readme.txt | 2 - docs/releases.txt | 31 ----- docs/usage.txt | 27 ---- readme.txt | 19 +-- 9 files changed, 1 insertion(+), 576 deletions(-) delete mode 100644 docs/codingstyle.txt delete mode 100644 docs/configure.txt delete mode 100644 docs/console.txt delete mode 100644 docs/contributors.txt delete mode 100644 docs/files.txt delete mode 100644 docs/readme.txt delete mode 100644 docs/releases.txt delete mode 100644 docs/usage.txt diff --git a/docs/codingstyle.txt b/docs/codingstyle.txt deleted file mode 100644 index ceab047c..00000000 --- a/docs/codingstyle.txt +++ /dev/null @@ -1,289 +0,0 @@ - ChibiOS/GFX coding style - -To provide an easy-to-read code, we want to have a uniform -coding style within ChibiOS/GFX. -Because I personally like the widley used linux kernel coding style, -I decided to use it for ChibiOS/GFX as well. -Therefore, the coding style documentation is a 1:1 copy from the -codingstyle.txt of the linux kernel source code. - -Please make sure you match these coding styles before you contribute -any code. If you find any existing code which dosen't match these rules, -please feel free to submit a patch. - -There are only two rules which are not similar to the following -documentation: - - - Prefered tabsize is 4, not 8 - - We don't use 80 character columns - - -Please read through the following carefully: - - - - Linux kernel coding style - -This is a short document describing the preferred coding style for the -linux kernel. Coding style is very personal, and I won't _force_ my -views on anybody, but this is what goes for anything that I have to be -able to maintain, and I'd prefer it for most other things too. Please -at least consider the points made here. - -First off, I'd suggest printing out a copy of the GNU coding standards, -and NOT read it. Burn them, it's a great symbolic gesture. - -Anyway, here goes: - - - Chapter 1: Indentation - -Tabs are 8 characters, and thus indentations are also 8 characters. -There are heretic movements that try to make indentations 4 (or even 2!) -characters deep, and that is akin to trying to define the value of PI to -be 3. - -Rationale: The whole idea behind indentation is to clearly define where -a block of control starts and ends. Especially when you've been looking -at your screen for 20 straight hours, you'll find it a lot easier to see -how the indentation works if you have large indentations. - -Now, some people will claim that having 8-character indentations makes -the code move too far to the right, and makes it hard to read on a -80-character terminal screen. The answer to that is that if you need -more than 3 levels of indentation, you're screwed anyway, and should fix -your program. - -In short, 8-char indents make things easier to read, and have the added -benefit of warning you when you're nesting your functions too deep. -Heed that warning. - - - Chapter 2: Placing Braces - -The other issue that always comes up in C styling is the placement of -braces. Unlike the indent size, there are few technical reasons to -choose one placement strategy over the other, but the preferred way, as -shown to us by the prophets Kernighan and Ritchie, is to put the opening -brace last on the line, and put the closing brace first, thusly: - - if (x is true) { - we do y - } - -However, there is one special case, namely functions: they have the -opening brace at the beginning of the next line, thus: - - int function(int x) - { - body of function - } - -Heretic people all over the world have claimed that this inconsistency -is ... well ... inconsistent, but all right-thinking people know that -(a) K&R are _right_ and (b) K&R are right. Besides, functions are -special anyway (you can't nest them in C). - -Note that the closing brace is empty on a line of its own, _except_ in -the cases where it is followed by a continuation of the same statement, -ie a "while" in a do-statement or an "else" in an if-statement, like -this: - - do { - body of do-loop - } while (condition); - -and - - if (x == y) { - .. - } else if (x > y) { - ... - } else { - .... - } - -Rationale: K&R. - -Also, note that this brace-placement also minimizes the number of empty -(or almost empty) lines, without any loss of readability. Thus, as the -supply of new-lines on your screen is not a renewable resource (think -25-line terminal screens here), you have more empty lines to put -comments on. - - - Chapter 3: Naming - -C is a Spartan language, and so should your naming be. Unlike Modula-2 -and Pascal programmers, C programmers do not use cute names like -ThisVariableIsATemporaryCounter. A C programmer would call that -variable "tmp", which is much easier to write, and not the least more -difficult to understand. - -HOWEVER, while mixed-case names are frowned upon, descriptive names for -global variables are a must. To call a global function "foo" is a -shooting offense. - -GLOBAL variables (to be used only if you _really_ need them) need to -have descriptive names, as do global functions. If you have a function -that counts the number of active users, you should call that -"count_active_users()" or similar, you should _not_ call it "cntusr()". - -Encoding the type of a function into the name (so-called Hungarian -notation) is brain damaged - the compiler knows the types anyway and can -check those, and it only confuses the programmer. No wonder MicroSoft -makes buggy programs. - -LOCAL variable names should be short, and to the point. If you have -some random integer loop counter, it should probably be called "i". -Calling it "loop_counter" is non-productive, if there is no chance of it -being mis-understood. Similarly, "tmp" can be just about any type of -variable that is used to hold a temporary value. - -If you are afraid to mix up your local variable names, you have another -problem, which is called the function-growth-hormone-imbalance syndrome. -See next chapter. - - - Chapter 4: Functions - -Functions should be short and sweet, and do just one thing. They should -fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, -as we all know), and do one thing and do that well. - -The maximum length of a function is inversely proportional to the -complexity and indentation level of that function. So, if you have a -conceptually simple function that is just one long (but simple) -case-statement, where you have to do lots of small things for a lot of -different cases, it's OK to have a longer function. - -However, if you have a complex function, and you suspect that a -less-than-gifted first-year high-school student might not even -understand what the function is all about, you should adhere to the -maximum limits all the more closely. Use helper functions with -descriptive names (you can ask the compiler to in-line them if you think -it's performance-critical, and it will probably do a better job of it -that you would have done). - -Another measure of the function is the number of local variables. They -shouldn't exceed 5-10, or you're doing something wrong. Re-think the -function, and split it into smaller pieces. A human brain can -generally easily keep track of about 7 different things, anything more -and it gets confused. You know you're brilliant, but maybe you'd like -to understand what you did 2 weeks from now. - - - Chapter 5: Commenting - -Comments are good, but there is also a danger of over-commenting. NEVER -try to explain HOW your code works in a comment: it's much better to -write the code so that the _working_ is obvious, and it's a waste of -time to explain badly written code. - -Generally, you want your comments to tell WHAT your code does, not HOW. -Also, try to avoid putting comments inside a function body: if the -function is so complex that you need to separately comment parts of it, -you should probably go back to chapter 4 for a while. You can make -small comments to note or warn about something particularly clever (or -ugly), but try to avoid excess. Instead, put the comments at the head -of the function, telling people what it does, and possibly WHY it does -it. - - - Chapter 6: You've made a mess of it - -That's OK, we all do. You've probably been told by your long-time Unix -user helper that "GNU emacs" automatically formats the C sources for -you, and you've noticed that yes, it does do that, but the defaults it -uses are less than desirable (in fact, they are worse than random -typing - a infinite number of monkeys typing into GNU emacs would never -make a good program). - -So, you can either get rid of GNU emacs, or change it to use saner -values. To do the latter, you can stick the following in your .emacs file: - -(defun linux-c-mode () - "C mode with adjusted defaults for use with the Linux kernel." - (interactive) - (c-mode) - (c-set-style "K&R") - (setq c-basic-offset 8)) - -This will define the M-x linux-c-mode command. When hacking on a -module, if you put the string -*- linux-c -*- somewhere on the first -two lines, this mode will be automatically invoked. Also, you may want -to add - -(setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode) - auto-mode-alist)) - -to your .emacs file if you want to have linux-c-mode switched on -automagically when you edit source files under /usr/src/linux. - -But even if you fail in getting emacs to do sane formatting, not -everything is lost: use "indent". - -Now, again, GNU indent has the same brain dead settings that GNU emacs -has, which is why you need to give it a few command line options. -However, that's not too bad, because even the makers of GNU indent -recognize the authority of K&R (the GNU people aren't evil, they are -just severely misguided in this matter), so you just give indent the -options "-kr -i8" (stands for "K&R, 8 character indents"). - -"indent" has a lot of options, and especially when it comes to comment -re-formatting you may want to take a look at the manual page. But -remember: "indent" is not a fix for bad programming. - - - Chapter 7: Configuration-files - -For configuration options (arch/xxx/config.in, and all the Config.in files), -somewhat different indentation is used. - -An indention level of 3 is used in the code, while the text in the config- -options should have an indention-level of 2 to indicate dependencies. The -latter only applies to bool/tristate options. For other options, just use -common sense. An example: - -if [ "$CONFIG_EXPERIMENTAL" = "y" ]; then - tristate 'Apply nitroglycerine inside the keyboard (DANGEROUS)' CONFIG_BOOM - if [ "$CONFIG_BOOM" != "n" ]; then - bool ' Output nice messages when you explode' CONFIG_CHEER - fi -fi - -Generally, CONFIG_EXPERIMENTAL should surround all options not considered -stable. All options that are known to trash data (experimental write- -support for file-systems, for instance) should be denoted (DANGEROUS), other -Experimental options should be denoted (EXPERIMENTAL). - - - Chapter 8: Data structures - -Data structures that have visibility outside the single-threaded -environment they are created and destroyed in should always have -reference counts. In the kernel, garbage collection doesn't exist (and -outside the kernel garbage collection is slow and inefficient), which -means that you absolutely _have_ to reference count all your uses. - -Reference counting means that you can avoid locking, and allows multiple -users to have access to the data structure in parallel - and not having -to worry about the structure suddenly going away from under them just -because they slept or did something else for a while. - -Note that locking is _not_ a replacement for reference counting. -Locking is used to keep data structures coherent, while reference -counting is a memory management technique. Usually both are needed, and -they are not to be confused with each other. - -Many data structures can indeed have two levels of reference counting, -when there are users of different "classes". The subclass count counts -the number of subclass users, and decrements the global count just once -when the subclass count goes to zero. - -Examples of this kind of "multi-reference-counting" can be found in -memory management ("struct mm_struct": mm_users and mm_count), and in -filesystem code ("struct super_block": s_count and s_active). - -Remember: if another thread can find your data structure, and you don't -have a reference count on it, you almost certainly have a bug. diff --git a/docs/configure.txt b/docs/configure.txt deleted file mode 100644 index 17540062..00000000 --- a/docs/configure.txt +++ /dev/null @@ -1,43 +0,0 @@ -There are serval macros available to configure the behaviour of the GFX-Library. - -HAL macros: - - #define HAL_USE_GFX // enables the GDISP sub system. This is essentially needed to use the display - #define GFX_USE_TOUCHPAD // enables the TouchPad sub system. This is essentially needed to use the touchpad - - - -GDISP macors: - - #define GDISP_USE_GPIO // GDISP is connected to the MCU using GPIO interface, involves using lld_lcdWriteGPIO() and lld_lcdReadGPIO() - #define GDISP_USE_FSMC // GDISP is connected to the MCU using FSMC interface - #define GDISP_USE_SPI // GDISP is connected to the MCU using SPI interface - - #define GDISP_SCREEN_WIDTH // defines width of panel in pixels. This is essentially needed to use the display - #define GDISP_SCREEN_HEIGHT // defines height of panel in pixels. This is essentailly needed to use the display - - #define GDISP_NEED_MULTITHREAD // GDISP will be accessed across different threads -> thread safe mode - #define GDISP_NEED_CONTROL // must be set to TRUE if controll access to the LCD controller is needed, eg for changing orientation or power mode - #define GDISP_NEED_CLIP // when clipping is needed - #define GDISP_NEED_CIRCLE // for circle drawing support (filled and frame) - #define GDISP_NEED_ELLIPSE // for ellipse drawing support (filled and frame) - #define GDISP_NEED_ARC // for arc drawing support (filled and frame) - #define GDISP_NEED_TEXT // for font rendering support - #define GDISP_NEED_PIXELREAD // to read a pixels color value back - #define GDISP_NEED_SCROLL // is scrolling is needed (pixel shift) - #define GDISP_NEED_QUERY // to make certain queries to the LCD controller - - #define GFX_USE_CONSOLE // for the console abstraction - - -TouchPad macros: - - #define TOUCHPAD_NEED_MULTITHREAD // TouchPad will be accessed across different threads -> thread safe mode - - #define TOUCHPAD_XY_INVERTED // output of tpReadX() and tpReadY() swapped - needed if touchpad writes swapped to touchpad controller - - #define TOUCHPAD_STORE_CALIBRATION // calibration values can be stored if set to true. Therefore tpCalibration() is not neccessary to call on each reset. involves using lld_tpWriteCalibration() and lld_tpReadCalibration() - - - - diff --git a/docs/console.txt b/docs/console.txt deleted file mode 100644 index 09e7ae86..00000000 --- a/docs/console.txt +++ /dev/null @@ -1,20 +0,0 @@ -The console module acts as a BaseSequentialStream at a user defined area of the LCD. - -Requirements: -The console code requires a lld that has vertical scroll implemented. -It is also necessary to enable the scroll code: - - #define GDISP_NEED_SCROLL TRUE - -Usage: - - #include "console.h" - - /* Define a console object */ - GLCDConsole CON1; - - /* initialise the console to take up the entire screen */ - lcdConsoleInit(&CON1, 0, 0, 320, 240, &fontLarger, Black, White); - - /* print something */ - chprintf((BaseSequentialStream *)&CON1, "Hello the time is %d\nGoodbye.", chTimeNow()); diff --git a/docs/contributors.txt b/docs/contributors.txt deleted file mode 100644 index e43f1be2..00000000 --- a/docs/contributors.txt +++ /dev/null @@ -1,27 +0,0 @@ -This file is a complete history of persons who contributed to the GLCD Library. - -At this point we want to thank all of these people for their work. - - -NickName RealName Contribution -======== ======== ============ - -Mobyfab Fabien Poussin SSD1963 driver, TOUCHPAD_XY_INVERTED macro - -inmarket Andrew Hannam GDISP (restructorizing the entire library) - VMT - ASYNC and MULTITHREAD implementation - -Badger Thomas Saunders console implementation - FSMC for STM32F1 and F4 - lld orientation fixed for S6F1121 and SSD1289 - -Abhishek Abhishek Kumar S6D1121 GPIO - font rendering - touchpad noise filtering & optimizations - -benwilliam - lcdDrawEllipse() - fastMath - -dxli Dongxu Li lcdDrawEllipse() filled option - diff --git a/docs/files.txt b/docs/files.txt deleted file mode 100644 index 94869efb..00000000 --- a/docs/files.txt +++ /dev/null @@ -1,119 +0,0 @@ -This is a tree of the toplevel directory of the GLCD library. -The maintainer is supposed to keep it up to date at any new release. - -. -├── demos -│   ├── console -│   │   └── main.c -│   ├── lcd -│   │   └── main.c -│   ├── notepad -│   │   └── main.c -│   ├── readme.txt -│   └── touchpad -│   └── main.c -├── docs -│   ├── codingstyle.txt -│   ├── configure.txt -│   ├── console.txt -│   ├── contributors.txt -│   ├── files.txt -│   ├── readme.txt -│   ├── releases.txt -│   └── usage.txt -├── Doxygenfile -├── drivers -│   ├── gdisp -│   │   ├── Nokia6610 -│   │   │   ├── gdisp_lld_board_example.h -│   │   │   ├── gdisp_lld_board_olimexsam7ex256.h -│   │   │   ├── gdisp_lld.c -│   │   │   ├── gdisp_lld_config.h -│   │   │   ├── gdisp_lld.mk -│   │   │   ├── GE12.h -│   │   │   ├── GE8.h -│   │   │   └── readme.txt -│   │   ├── S6D1121 -│   │   │   ├── gdisp_lld.c -│   │   │   ├── gdisp_lld_config.h -│   │   │   ├── gdisp_lld.mk -│   │   │   ├── readme.txt -│   │   │   └── s6d1121_lld.c.h -│   │   ├── SSD1289 -│   │   │   ├── gdisp_lld.c -│   │   │   ├── gdisp_lld_config.h -│   │   │   ├── gdisp_lld.mk -│   │   │   ├── readme.txt -│   │   │   └── ssd1289_lld.c.h -│   │   ├── SSD1963 -│   │   │   ├── gdisp_lld.c -│   │   │   ├── gdisp_lld_config.h -│   │   │   ├── gdisp_lld.mk -│   │   │   ├── gdisp_lld_panel.h -│   │   │   ├── readme.txt -│   │   │   └── ssd1963.h -│   │   ├── TestStub -│   │   │   ├── gdisp_lld.c -│   │   │   ├── gdisp_lld_config.h -│   │   │   ├── gdisp_lld.mk -│   │   │   └── readme.txt -│   │   └── VMT -│   │   ├── gdisp_lld.c -│   │   ├── gdisp_lld_config.h -│   │   ├── gdisp_lld_driver1.c -│   │   ├── gdisp_lld_driver2.c -│   │   ├── gdisp_lld.mk -│   │   └── readme.txt -│   └── touchpad -│   ├── ADS7843 -│   │   ├── readme.txt -│   │   ├── touchpad_lld.c -│   │   ├── touchpad_lld_config.h -│   │   └── touchpad_lld.mk -│   └── XPT2046 -│   ├── readme.txt -│   ├── touchpad_lld.c -│   ├── touchpad_lld_config.h -│   └── touchpad_lld.mk -├── gfx.mk -├── include -│   ├── console.h -│   ├── gdisp_emulation.c -│   ├── gdisp_fonts.h -│   ├── gdisp.h -│   ├── gdisp_lld.h -│   ├── gdisp_lld_msgs.h -│   ├── touchpad.h -│   └── touchpad_lld.h -├── license.txt -├── old -│   ├── graph -│   │   ├── graph.c -│   │   ├── graph.h -│   │   └── graph.mk -│   └── gui -│   ├── gui.c -│   ├── gui.h -│   └── gui.mk -├── readme.txt -├── src -│   ├── console.c -│   ├── gdisp.c -│   ├── gdisp_fonts.c -│   ├── gdisp-readme.txt -│   └── touchpad.c -├── templates -│   ├── gdispXXXXX -│   │   ├── gdisp_lld.c -│   │   ├── gdisp_lld_config.h -│   │   ├── gdisp_lld.mk -│   │   └── readme.txt -│   ├── readme.txt -│   └── touchpadXXXXX -│   ├── touchpad_lld.c -│   ├── touchpad_lld_config.h -│   └── touchpad_lld.mk -└── tools - └── readme.txt - -26 directories, 87 files diff --git a/docs/readme.txt b/docs/readme.txt deleted file mode 100644 index 3a76a92f..00000000 --- a/docs/readme.txt +++ /dev/null @@ -1,2 +0,0 @@ -This folder contains documentation about this GLCD library. - diff --git a/docs/releases.txt b/docs/releases.txt deleted file mode 100644 index 12f1eb87..00000000 --- a/docs/releases.txt +++ /dev/null @@ -1,31 +0,0 @@ -***************************************************************************** -*** Releases *** -***************************************************************************** - -current stable: 1.2 - -*** changes after 1.2 *** - - -*** changer after 1.1 *** -FIX: orientation macros changed -FIX: huge internal bugfix in orientation stuff (big thanks to Abhishek) -FEATURE: added TOUCHPAD_XY_INVERTED macro -FIX: struct cal renamed to struct cal_t -FIX: SCREEN_WIDTH and SCREEN_HEIGHT renamed to GDISP_SCREEN_WIDTH and GDISP_SCREEN_HEIGHT -FIX: struct TOUCHPAD_t renamed to struct TOUCHPADDriver_t -FIX: struct GConsole renamed to struct GConsole_t -FIX: lcdConsoleXXX() functions have been renamed to gfxConsoleXXX() -FEATURE: FSMC for SSD1289 F2/F4 - -*** changes after 1.0 *** -FIX: removed gdisp and touchpad prefix of driver directories -UPDATE: added SSD1963 driver -FIX: fixed Validation, VMT driver, console and BitBlit -FEATURE: added clipping support -FEATURE: addad gdispDrawArc() -FEATURE: added SSD1963 DMA support -FEATURE: added touchpad interface for storing calibration values (#define TOUCHPAD_STORE_CALIBRATION) -CHANGE: replaced every GDISP_XXX macro with GDISP_XXX -CHANGE: removed last digit of version number - diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 100644 index a68c618a..00000000 --- a/docs/usage.txt +++ /dev/null @@ -1,27 +0,0 @@ -To include any of these functions/drivers in your project... - - 1/ Specify the path to the GFXLIB. If none defined, default is $(CHIBIOS)/ext/lcd - - 2/ In your project Makefile (amongst similiar lines but after the hal line) add the line... - include $(GFXLIB)/gfx.mk - - 3/ Add $(GFXSRC) and $(GFXINC) to your SRCS and INCDIR of your projects Makefile - - 4/ In your project Makefile add the makefiles for any specific drivers you want e.g - include $(GFXLIB)/drivers/touchpad/XPT2046/touchpad_lld.mk - include $(GFXLIB)/drivers/gdisp/SSD1289/gdisp_lld.mk - - 5/ In your project halconf.h turn on the support you want. Please take a look to - docs/configure.txt for a list and description of all available macros. For example: - - #define GFX_USE_GDISP TRUE - #define GFX_USE_TOUCHPAD TRUE - - #define GDISP_USE_GPIO TRUE - #define GDISP_GDISP_SCREEN_WIDTH 240 - #define GDISP_GDISP_SCREEN_HEIGHT 320 - #define GDISP_NEED_CONTROL TRUE - #define TOUCHPAD_NEED_MULTITHREAD TRUE - - 6/ Do a make clean - diff --git a/readme.txt b/readme.txt index 0b67c9b0..cb534a3c 100644 --- a/readme.txt +++ b/readme.txt @@ -1,19 +1,2 @@ -## Doxygen -run doxygen in the toplevel directory to generate the doxygen documentation in html - - - -## Wiki -please read the wiki pages to this project carefully, before you ask any questions: - -http://chibios.org/dokuwiki/doku.php?id=chibios:community - - - -## Maintainer & Contributors -please read the contributors.txt file which contains a full history of each contribution - -Maintainer: - - Joel Bodenmann aka Tectu - +please visit http://chibios-gfx.com