/* * COPYRIGHT (c) 2010-2012. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be * found in the file LICENSE in this distribution or at * http://www.rtems.com/license/LICENSE. */
RTEMS includes a mixture of code which was developed specifically for RTEMS and code from actively maintained FOSS projects. This document addresses coding style issues within the RTEMS Project code base.
Unfortunately, RTEMS has never had a formal written set of coding conventions which have been reviewed and blessed by an ISO9000 committee of non-coders. However, the style of the code in RTEMS is generally very consistent in the core areas of RTEMS. This page attempts to capture some of the generally accepted practices.
Historically, the RTEMS project has not outright rejected any submission of general utility. We have worked with the authors to ensure that the code conforms to the standards. In many cases, the source code has been merged into the source base under the good faith assumption that concerns will be addressed. Sometimes that good faith was justified and in other cases, it was not.
As an exception, code the is merged from another source such as FreeBSD or another open source project into the RTEMS source tree will NOT be reformatted!!! This is critical as it makes it difficult to merge future updates and bug fixes.
This code should remain as unmodified as possible. Any modifications made should adhere to the originating project’s style conventions. All changes should be submitted upstream.
RTEMS leverages FreeBSD for USB and TCP/IP functionality. We have to modify this code to account for RTEMS differences and implement multiple FreeBSD kernel APIs in terms of RTEMS. These will all follow the FreeBSD style.
XXX URL
Every file should include a header with the copyright notice. This is a typical example:
/* * COPYRIGHT (c) 2010-2012. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be * found in the file LICENSE in this distribution or at * http://www.rtems.com/license/LICENSE. */
Do not put unrelated functions or data in a single file. This results in object code bloat.
If adding code to cpukit be sure the filename is unique since it will be merged all code under that directory gets merged into a single library.
Use ANSI C99 not K&R
Do not use compiler extensions.
Pay attention to warnings.
Check all return statuses.
Favor C over assembly language and use inline assembly.
Further inline assembly should try to be hidden in CPU specific files that provide nice method name wrappers (e.g. sparc_get_XXX()).
Think portable — RTEMS supports a lot of target hardware.
Share code with other targets where possible.
Simple code is easier to debug and easier to read than clever code.
Favor C automatic variables over global or static variables.
Use global variables only when necessary and be conscious that RTEMS is a multitasking system. This means that you often have to ensure atomicity of operations.
Avoid declaring large buffers or structures on the stack.
Do not duplicate standard OS or C Library routines.
Avoid unnecessary dependencies. This can mean splitting your code into multiple file to limit the minimum footprint or not calling printf() on error paths.
two space indent
no tabs
no spaces at end of line
Adhere to a limit of 80 characters per line
brace style
Using astyle’s terminology, we are probably more like K&R in general but I could easily go with "one true brace style" I like single statements to be enclosed in braces.
padding around operators
padding inside parentheses
space after if, while, for
align pointer with name
UNIX CR/LF
automatic variable initialization
Is this allowable? If allowable, what are the limits?
An example code method:
bool test_method(
int arg1,
int arg2
)
{
if ( arg1 > arg 2 )
return true;
return false;
}
The above raises questions:
spaces around expression in if
braces around single line return true
Although style is important, RTEMS is a real-time operating system and, consequently, any enhancements or modifications should also have certain execution characteristics. The following is a list of guidelines which RTEMS adheres to in order to improve the performance and stability of the services it provides.
If you need to temporarily change the execution mode of a task/thread, restore it.
Favor mutual exclusion primitives over disabling preemption.
Use algorithms with the lowest order of execution. By favoring O(constant) over O(n) algorithms, RTEMS works hard to ensure deterministic execution times as much as possible.
Limit execution times in Interrupt and Timer Service Routines (TSRs). TSRs scheduled by rtems_timer_fire_XXX run in the context of the clock tick ISR while TSRs scheduled by rtems_timer_server_fire_XXX run in the context of a dedicated Timer Server task. Either way, excessive execution times could have a negative impact on the system performance.
Do not hard code limits such as maximum instances into your code.
The RTEMS Project has identified two tools with potential for aiding in style adjustments.
| Tool | Project Site |
|---|---|
astyle |
|
indent |
XXX |
This is based on a review of the manual and untested:
| indent | astyle | |
|---|---|---|
two space indent |
TBD |
TBD |
brace style |
TBD |
TBD |
padding around operators |
TBD |
--pad-oper |
padding around parentheses |
TBD |
--pad-paren-in |
space after if, while, for |
TBD |
--pad-header |
align pointer with name |
TBD |
--align-pointer=name |
UNIX CR/LF |
TBD |
--lineend=linux |
Eric Valette did some research and came up with a set of arguments for version 2.2.7 of the 'indent' program which seem to match the RTEMS style. So if you need help, try this and see how it does:
indent -br -ce -i2 -nut FILE.c
TBD: This desperately needs updating and augmenting
XXX
If you are a vim user then the following additions to your .vimrc will assist in the indentation:
:set tabstop=2 :set shiftwidth=2 :set expandtab
XXX
XXX