wiki:Developer/Coding/Conventions

Version 32 (modified by Gedare, on May 30, 2014 at 12:21:07 AM) (diff)

/* Formatting */ new section to consolidate some rules.

Coding Conventions

The style of RTEMS is generally consistent in the core areas. This page attempts to capture generally accepted practices. When in doubt, consult the code around you or look in cpukit/rtems.

Source Documentation

  • Doxygen: See Doxygen Recommendations for how to use Doxygen with RTEMS sources, including examples that illustrate style rules.
  • Use /* */ comments.
  • Start each file with a brief description followed by a license. See Boilerplate File Header.
  • Use comments wisely within function bodies, to explain or draw attention without being verbose.
  • Use English and strive for good grammar, spelling, and punctuation.
  • Use TODO: with a comment to indicate code that needs improvement. Make it clear what there is to do.
  • Use XXX or FIXME to indicate an error/bug/broken code.

Licenses

  • The RTEMS License is the typical and preferred license.
    • 2- and 3-clause BSD, MIT, and other OSI-approved non-copyleft licenses that permit statically linking with code of different licenses are acceptable.
    • GPL licensed code is NOT acceptable, neither is LGPL. See this blog post explanation for more information.
    • Advertising obligations are NOT acceptable, but restrictions are permissible.

Language and Compiler

  • Use C99.
  • Favor C, but when assembly language is required use inline assembly if possible.
  • Do not use compiler extensions.
  • Pay attention to warnings. Strive to eliminate them.

Formatting

  • Use spaces instead of tabs.
  • Use two spaces for indentation, four spaces for hanging indentation.
  • Adhere to a limit of 80 characters per line.
  • Check all return statuses.
  • Do not mix variable declarations and code.
  • Avoid deep nesting by using early returns
    • Parameter checking should be done first with early error returns.
    • Avoid allocation and critical sections until error checking is done.
    • For error checks that require locking, do the checks early after acquiring locks.
    • Use of 'goto' requires good reason and justification.
  • Test and action should stay close together.
  • Avoid complex logical expressions in ifs, fors, and whiles
  • Avoid inlining methods with complicated logic and decision points
  • Use debug assertions.

Miscellaneous

  • 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 all files under that directory get merged into a single library.
  • Think portable! RTEMS supports a lot of target hardware.
  • Minimize modifications to third party code.
  • Keep it simple! Simple code is easier to debug and easier to read than clever code.
  • Share code with other targets where possible.

RTEMS Coding Style

This section applies primarily to code residing under cpukit, especially cpukit/score.

Naming

SuperCore?

SuperCore? is organized in an Object-Oriented fashion. Each score Manager is a Package, or Module, and each Module contains type definitions, functions, etc. The following summarizes our conventions for using names within SuperCore? Modules.

  • Use "Module_name_Particular_type_name" for type names.
  • Use "_Module_name_Particular_function_name" for functions names.
  • Use "_Module_name_Global_or_file_scope_variable_name" for global or file scope variable names.

Within a structure,

  • Use "Name" for struct aggregate members.
  • Use "name" for reference members.
  • Use "name" for primitive type members.

Example

typedef struct {
  Other_module_Struct_type    Aggregate_member_name;
  Other_module_Struct_type   *reference_member_name;
  Other_module_Primitive_type primitive_member_name;
} The_module_Type_name;

Other

  • TODO

Inline Functions

Declare and define inline functions in one place. This makes code review easier.

Compile-Time Features

Some RTEMS features are compile-time dependent and normally can be enabled/disabled via RTEMS build configuration options, for example --enable-smp, --enable-networking, --enable-profilig, etc. There usually exists a C pre-processor symbol which is defined in case the feature is enabled, e.g. RTEMS_SMP, RTEMS_NETWORKING, RTEMS_PROFILING, etc. To limit the scope scattered with conditional compilation based on these feature defines the following rules should be followed:

  • Use inline functions which evaluate to empty bodies whenever possible.
  • Use "(void) arg;" to silence unused parameter warnings.

This provides type checks for the function calls even in case the feature is disabled. The compiler can easily optimize empty inline functions away. Example:

static inline feature_x_func(int a, double b, void *c) { #ifdef FEATURE_X

/* Do something */

#else

(void) a; (void) b; (void) c;

#endif }

Performance Issues

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.

  • 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.
  • If you need to temporarily change the execution mode of a task/thread, restore it.
  • Favor mutual exclusion primitives over disabling preemption.
  • 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.
  • 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.

Makefile.am Issues

TBD

=configure.ac Issues=

TBD

Attachments (1)

Download all attachments as: .zip