This page contains guidelines for writing new C source code for the OpenOCD project.
Formatting Guide
- remove any trailing white space at the end of lines.
- use TAB characters for indentation; do NOT use spaces.
- displayed TAB width is 4 characters.
- use Unix line endings ('\n'); do NOT use DOS endings ('\r\n')
- limit adjacent empty lines to at most two (2).
- remove any trailing empty lines at the end of source files
- do not "comment out" code from the tree nor put it within a block otherwise it would never be checked at compile time and when new patches get merged it could be not compilable anymore. Code that is not fully working nor ready for submission should instead be removed entirely (git can retrieve the old version). For exceptional cases that require keeping some unused code, let the compiler check it by putting it in a block
- in a
switch
statement align the switch
with the case
label switch (dev_id) {
case 0x0123:
break;
case 0x0412:
break;
default:
break;
}
size_t size
Size of the control block search area.
- in an
if / then / else
statement, if only one of the conditions require curly brackets due to multi-statement block, put the curly brackets also to the other condition if (x > 0)
a = 12 + x;
else
a = 24;
if (x > 0) {
a = 12 + x;
} else {
a = 24;
x = 0;
}
Finally, try to avoid lines of code that are longer than 72-80 columns:
- long lines frequently indicate other style problems:
- insufficient use of static functions, macros, or temporary variables
- poor flow-control structure; "inverted" logical tests
- a few lines may be wider than this limit (typically format strings), but:
- all C compilers will concatenate series of string constants.
- all long string constants should be split across multiple lines.
- do never exceed 120 columns.
Naming Rules
- most identifiers must use lower-case letters (and digits) only.
- macros must use upper-case letters (and digits) only.
- OpenOCD identifiers should NEVER use
MixedCaps
.
typedef
names must end with the '_t' suffix.
- This should be reserved for types that should be passed by value.
- Do not mix the typedef keyword with
struct
.
- use underline characters between consecutive words in identifiers (e.g.
more_than_one_word
).
Include Guards
Every header file should have a unique include guard to prevent multiple inclusion. To guarantee uniqueness, an include guard should be based on the filename and the full path in the project source tree.
For the header file src/helper/jim-nvp.h, the include guard would look like this:
#ifndef OPENOCD_HELPER_JIM_NVP_H
#define OPENOCD_HELPER_JIM_NVP_H
#endif
C99 Rules
- inline functions
//
comments – in new code, prefer these for single-line comments
- trailing comma allowed in enum declarations
- designated initializers ( .field = value )
- variables declarations should occur at the point of first use
- new block scopes for selection and iteration statements
- use malloc() to create dynamic arrays. Do not use
alloca
or variable length arrays on the stack. non-MMU hosts(uClinux) and pthreads require modest and predictable stack usage.
Type Guidelines
- use native types (
int
or unsigned int
) if the type is not important
- if size matters, use the types from <stdint.h> or <inttypes.h>:
int8_t
, int16_t
, int32_t
, or int64_t:
signed types of specified size
uint8_t
, uint16_t
, uint32_t
, or uint64_t:
unsigned types of specified size
- use the associated
printf
and scanf
formatting strings for these types (e.g. PRId8
, PRIx16, SCNu8, ...)
- do NOT redefine
uN
types from "types.h"
- use type
target_addr_t
for target's address values
- prefer type
unsigned int
to type unsigned
Functions
- static inline functions should be preferred over macros:
#define CUBE(x) ((x) * (x) * (x))
static inline int cube(int x) { return x * x * x; }
- Functions should be declared static unless required by other modules
- define static functions before first usage to avoid forward declarations.
- Functions should have no space between its name and its parameter list:
int f(int x1, int x2)
{
...
int y = f(x1, x2 - x1);
...
}
- Separate assignment and logical test statements. In other words, you should write statements like the following: More directly, do not combine these kinds of statements:
- Do not compare
bool
values with true
or false
but use the value directly
- Avoid comparing pointers with
NULL
buf = malloc(buf_size);
if (!buf) {
}
#define LOG_ERROR(expr ...)