diff options
| -rw-r--r-- | codingstyle.txt | 289 | ||||
| -rw-r--r-- | releases.txt | 39 |
2 files changed, 328 insertions, 0 deletions
diff --git a/codingstyle.txt b/codingstyle.txt new file mode 100644 index 00000000..ceab047c --- /dev/null +++ b/codingstyle.txt @@ -0,0 +1,289 @@ + 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/releases.txt b/releases.txt new file mode 100644 index 00000000..c4107866 --- /dev/null +++ b/releases.txt @@ -0,0 +1,39 @@ +*****************************************************************************
+*** Releases ***
+*****************************************************************************
+
+current stable: 1.3
+
+
+*** changes after 1.3 ***
+
+
+*** changes after 1.2 ***
+FEATURE: added FSMC for SSD1289 / F4
+FEATURE: added calibration storage interface
+FIX: bugfix in filling functions for SSD1289
+FEATURE: added point_t struct in gdisp.h
+FEATURE: added graph module
+
+*** 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
+
|