wiki:Developer/Coding/Conventions

Version 11 (modified by Gedare, on Feb 12, 2013 at 7:43:35 PM) (diff)

/* Source Code Style */

Coding Conventions

Unfortunately, RTEMS does not have 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.

As an exception, code that 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.

Source Documentation

RTEMS uses Doxygen to generate documentation from source code. See Doxygen Recommendations for how to use Doxygen with RTEMS sources.

File Issues

  • Every file should include two comment header blocks, one for the Doxygen output and a copyright notice. This is a typical example:
    /**
     * @file
     *
     * @ingroup TheGroupForThisFile
     *
     * @brief Short "Table of Contents" Description of File Contents
     *
     * A short description of the purpose of this file.
     */
    
    /*
     *  COPYRIGHT (c) 1989-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.
     */
    
  • Use exactly one blank line between the Doxygen header and copyright notice. Leave the first line of the copyright notice blank.
  • Separate the Doxygen header and copyright notice so the copyright notice is not included in the Doxygen output.
  • The copyright owner and specific license terms may vary.
    • The above is typical and the preferred license.
    • 2- and 3-clause BSD, MIT, "use as is", and other OSI approved licenses that permit linking with code of different licenses are acceptable.
    • Pure GPL licensed code is NOT acceptable.
    • Advertising obligations are NOT acceptable, but restrictions are permissible.

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 it will be merged all code under that directory gets merged into a single library.

Source Code Style

  • Use ANSI C not K&R.
  • Do not use compiler extensions.
  • Use spaces instead of tabs.
  • Use two spaces for indentation, four spaces for hanging indentation.
  • Adhere to a limit of 80 characters per line.
  • Pay attention to warnings.
  • Check all return statuses.
  • Favor C over assembly language and use inline assembly.
  • Share code with other targets where possible.
  • Think portable -- RTEMS supports a lot of target hardware.
  • Simple code is easier to debug and easier to read than clever code.

When in doubt, use the source code in cpukit/rtems as a style reference.

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

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

But remember, it is better to write code in the accepted style than to use a program to get it there.

RTEMS Coding Style

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

Naming

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;

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