In addition to the naming and positioning of headers and source files (see directory structure), Tollos headers and code follow the conventions listed below.

Header files

Header files are not considered documentation, although they do often have useful constants. These constants should be documented in the C source file to which they apply.

Each Tollos header file typically includes two sets of function signatures:

1. those which form the application interface and which are implemented in the .c file of the same name as the .h header file
2. those which are deemed I/O functions – these are ‘glue’ functions called by Tollos code to provide the interface between the generic Tollos code and some peripheral or microcontroller hardware. The names of these functions always end in ‘IO’, and the symbol TOLLOS_IO must be defined before the header file is included in order to use them.

I/O functions are implemented in a different library associated with a device or microcontroller; that library is selected at link time so that application code can be used with multiple hardware options.

In general, I/O functions are considered a private internal Tollos interface and are subject to change, whereas the intent is to keep application interface functions stable.

Widely-used Tollos types include

• byte – an unsigned byte, not usually treated as a number
• flag – a byte which must be either 0 or 1
• int – asserted to be 32 bits
• uint – an unsigned 32 bits.

See tollos.h for more types and other details.

C source files

C source files (‘modules’) comprise functions and documentation, following the rules listed below. The Tollos module documentation is generated automatically from the block comments, via a MemoWiki.

• Block comments (/*...*/ starting in column 1) are considered ‘contractual’ – they define the behaviour of the module and its functions and form its documentation. All other comments (indented block comments or // line comments) are informational.

• The module starts with a block comment, divided into three sections (by lines containing hyphens):
  1. the name of the module (file) and a one-line description
  2. the licence which applies to the module
  3. an overview of the module, which may contain general rules applying to some or all of the functions below.

• Functions are in alphabetical order.

• All functions are preceded by a block comment that includes:
  1. the function name and one-line description
  2. (indented) the parameters (if any) and a brief description of each
  3. (indented) the possible return values (unless the return type is void)
  4. any additional information needed to complete the description of the function and its semantics.

• Functions that are neither static nor utility functions (in tollosUtil) are considered part of a Tollos application or I/O interface and their names start with a (lowercase) prefix associated with the module; the remainder of the name is ‘camel case’, starting with a capital (with the exception of string formatting functions such as drawf).

• Function return types are always either void or int (this allows them to be used automatically in a scripting or shell environment).

• Functions always end with a right brace on a line by itself, followed by a line comment with the name of the function.

• The indention style is such that each use of braces is indented two spaces, with the first brace usually moved to the end of the line above to reduce vertical white space. Braces at the end of loops or large segments of code generally are commented to indicate the start of the loop or segment.

• Only top-controlled loops (for and occasionally while) are used. break and continue are used where useful to reduce nesting, as may be early return statements. The goto statement is not used.

• All variables (except function parameters and constants) are local; static variables outside of functions must be declared as static (that is, they are not accessible or alterable by other modules except through a formal function interface) or const (read-only). Each module is responsible for protecting against race conditions on access to its static data (for example, if there is an interrupt handler in the module which could be invoked while another function in the module is changing or reading static data).

• Variable names are lower case, except that shared static variables are highlighted by the use of a common prefix and camel case.

• Declarations are always at the start of compound statements (i.e., they always follow a left brace).

• Tollos modules are compiled with heavy checking; in particular the following GCC flags are used:
   -Wall
   -std=c99
   -pedantic
   -Wextra
   -Wstrict-prototypes
   -Wnested-externs
   -Wmissing-prototypes
   -Wcast-qual
   -fstrict-aliasing
   -Wstrict-aliasing
  

This page was last updated on 2020-02-07 by mfc.