ChibiOS Code Style Guide

ChibiOS/RT code follows well define style conventions that must be followed in order to have code accepted in the distribution.

Why so much focus on Style

Simply because we believe that a good product must be consistent, it is not acceptable to have different modules following different styles.

C dialect

Only C89 constructs can be used, things like // or inline are C99 and must be avoided. Non standard constructs like anonymous structures or unions must be avoided in the portable code but can be used in the compiler-specific code, for example in the ports code.

The only exception is “static inline”, which is acceptable in RT but not in HAL nor NIL.

C Code style conventions

ChibiOS follows the K&R style indentation style with few modifications:

  • Only two spaces are used for indentation.
  • TAB characters are forbidden.
  • Non UTF-8 characters are forbidden.
  • EOL must be CRLF (windows convention).
  • The else statement goes to the line after the closing }.
  • Column 80 must not be exceeded unless there is some technical reason because the line cannot be split.
  • A single space must follow the statements: if, while, do and switch before the expression opening (.
  • The expression following a return statement must not be surrounded by ( and ).
  • #ifdef and ifndef are not recommended, use #if defined() and #if !defined() instead.
  • The case statement are indented to the same level of the switch statement.
  • Pointer variable names are usually suffixed by a “p”, there is no other concession to types into names.
  • Automatic variables are recommended to be all lower case.
  • Very important types are allowed to be use camel case. Less important types must be all lower case and suffixed by a “_t”.
  • Multiple statement on a single line are discouraged.

An Eclipse style file is available in order to quickly reformat code.

FilenameFilesizeLast modified
chibios.xml16.0 KiB2015/07/21 10:06

Empty Lines

The use of empty lines varies:

  • More than one consecutive empty lines are forbidden everywhere.
  • An empty line between functions is mandatory.
  • Empty lines between logical blocks of code is mandatory following this template:
  /* Comment about the block1.*/
  Block1 statements...
 
  /* Comment about the block2.*/
  Block2 statements...
 
  /* Comment about the block3.*/
  Block3 statements...

Comments

Of course there are rules about comments.

Global objects
  • Comments must be written using Doxygen tags using the /** prefix, the /*! prefix is forbidden.
  • Comments of private or static objects should be done using Doxygen but it is not mandatory.
Doxygen usage

Please use the following general Doxygen template:

/**
 * @brief   A brief description, one sentence, one line.
 * @details A detailed description of the functionality, it can span over
 *          multiple lines, can be omitted.
 * @pre     Prerequisites about the use of the functionality, there can be
 *          more than one "pre" tags, can be omitted.
 * @post    Postrequisites about the use of the functionality, there can be
 *          more than one "post" tags, can be omitted.
 * @note    There can be one or more notes, can be omitted.
 *
 * @param[in] p1        description of parameter one
 * @param[out] p2       description of parameter two
 * @param[in,out] p3    description of parameter three
 * @return              Description of the returned value, must be omitted if
 *                      a function returns void.
 * @retval VALUE1       description of the special returned value one, can be
 *                      omitted.
 * @retval VALUE2       description of the special returned value two, can be
 *                      omitted.
 *
 * @api|@notapi|@special|@init|@sclass|@iclass|@xclass|@isr
 */

Notes:

  • Brief description and documentation of all parameters and return are mandatory.
  • The shown indenting columns are mandatory.
  • The text sections always begin with an upper case with the exception of text following @param and @retval.
  • The last tag is ChibiOS-defined and has the following meaning:
    • @api, a normal API usable from thread context.
    • @notapi, not an API, internal use only.
    • @special, an API with special usage protocol, see notes.
    • @init, an API that initializes an object, can be invoked even before the system is started.
    • @sclass, an S-Class API.
    • @xclass, an X-class API.
    • @iclass, an I-Class API.
    • @isr, an IRQ handler.
  • Text sections are always terminated with a dot except the text following @param and unless the text following @param is composed of multiple sentences.
  • The tag @p is mandatory before words representing code objects, for example: @p NULL, @p foo(), @p i2cp param.
Comments inside functions

The preferred style of comment are the following, note:

  • There must be one space after the /*.
  • Comments always start with an upper case.
  • Comments are always terminated with a dot.
  • There is no space between the final dot and the closing */.
  • Multiple line comments do not have a * as line start.
  /* This is a single line comment.*/
 
  /* This is a very long comment that necessarily has to span over
     multiple lines.*/
  • Comments on the right of a line of code are not recommended unless can all be aligned elegantly to the same column. Alignment must be followed for both the /* and the */.

More articles and guides are available on the technical wiki.

learn more

Need Tutorials?

Try the video tutorials and guides on Play Embedded.

learn more

Need Support?

The forums is the best place, registration required.

learn more