C Programming Language Coding Guidelines¶

Preprocessor
Compilation Units
Declarations and Initialization
Functions
Statements
Expressions
Types
Identifiers
Coding Style
Naming Convention
Implementation-Specific Behaviors
Language Extensions

Preprocessor ¶

C-PP-01: ## or # operators shall be used with restrictions ¶

## or # operators shall only be used alone. The following cases shall not be allowed:

The result from the ## or # operation shall not be used as the operands of another ## or # operation.
Mixed use of ## or # operators shall not be allowed.

Compliant example:

#define CONCAT(x, y) x ## y

uint32_t ab = 32U;
printf("%d \n", CONCAT(a, b));

Non-compliant example:

#define CONCAT(x, y, z) x ## y ## z

uint32_t abc = 32U;
printf("%d \n", CONCAT(a, b, c));

C-PP-02: Function-like MACRO shall be used with restrictions ¶

Function-like MACRO shall be replaced with inline function if it is possible.

Compliant example:

static inline uint32_t func_showcase(uint32_t a, uint32_t b)
{
        return a + b;
}

Non-compliant example:

#define SHOWCASE(a, b) ((a) + (b))

C-PP-03: Header file shall not be included multiple times ¶

The content inside shall be protected with #ifndef, #if !defined, or #ifdef.

Compliant example:

/* In `showcase.h`: */
#ifndef SHOWCASE_H
#define SHOWCASE_H

/* header contents */
uint32_t func_showcase(uint32_t param);

#endif /* SHOWCASE_H */

Non-compliant example:

/* In `showcase.h`: */

/* header contents without any protection */
uint32_t func_showcase(uint32_t param);

C-PP-04: Parentheses shall be used when referencing a MACRO parameter ¶

Compliant example:

#define NEGATING(x) -(x)

Non-compliant example:

#define NEGATING(x) -x

Compilation Units ¶

C-CU-01: Only one assignment shall be on a single line ¶

Multiple assignments on a single line are not allowed.

Compliant example:

a = d;
b = d;
c = d;

Non-compliant example:

int a = b = c = d;

C-CU-02: Only one return statement shall be in a function ¶

Multiple return statements in a function are not allowed.

Compliant example:

int32_t foo(char *ptr)
{
        int32_t ret;

        if (ptr == NULL) {
                ret = -1;
        } else {
                ...
                ret = 0;
        }

        return ret;
}

Non-compliant example:

int32_t foo(char *ptr) {
        if (ptr == NULL) {
                return -1;
        }
        ...
        return 0;
}

C-CU-03: All code shall be reachable ¶

Compliant example:

uint32_t func_showcase(void)
{
        uint32_t showcase = 32U;

        printf("showcase: %d \n", showcase);
        return showcase;
}

Non-compliant example:

uint32_t func_showcase(void)
{
        uint32_t showcase = 32U;

        return showcase;
        printf("showcase: %d \n", showcase);
}

C-CU-04: Cyclomatic complexity shall be less than 20 ¶

A function with cyclomatic complexity greater than 20 shall be split into multiple sub-functions to simplify the function logic.

Compliant example:

bool is_even_number(uint32_t param)
{
        bool even = false;

        if ((param & 0x1U) == 0U) {
                even = true;
        }

        return even;
}

uint32_t func_showcase(uint32_t param)
{
        uint32_t ret;

        if (param >= 20U) {
                ret = 20U;
        } else if (is_even_number(param)) {
                ret = 10U;
        } else {
                ret = 0U;
        }

        return ret;
}

Non-compliant example:

uint32_t func_showcase(uint32_t param)
{
        uint32_t ret;

        if (param >= 20U) {
                ret = 20U;
        }

        if ((param == 0U) || (param == 2U) || (param == 4U) || (param == 6U) ||
                (param == 8U) || (param == 10U) || (param == 12U) || (param == 14U) ||
                (param == 16U) || (param == 18U)) {
                ret = 10U;
        }

        if ((param == 1U) || (param == 3U) || (param == 5U) || (param == 7U) ||
                (param == 9U) || (param == 11U) || (param == 13U) || (param == 15U) ||
                (param == 17U) || (param == 19U)) {
                ret = 0U;
        }

        return ret;
}

Declarations and Initialization ¶

C-DI-01: Variable shall be used after its initialization ¶

Compliant example:

uint32_t a, b;

a = 0U;
b = a;

Non-compliant example:

uint32_t a, b;

b = a;

C-DI-02: Function shall be called after its declaration ¶

Compliant example:

static void showcase_2(void)
{
        /* main body */
}

static void showcase_1(void)
{
        showcase_2(void);
}

Non-compliant example:

static void showcase_1(void)
{
        showcase_2(void);
}

static void showcase_2(void)
{
        /* main body */
}

C-DI-03: The initialization statement shall not be skipped ¶

Compliant example:

        uint32_t showcase;

        showcase = 0U;
        goto increment_ten;
        showcase += 20U;

increment_ten:
        showcase += 10U;

Non-compliant example:

        uint32_t showcase;

        goto increment_ten;
        showcase = 0U;
        showcase += 20U;

increment_ten:
        showcase += 10U;

C-DI-04: The initialization of a struct shall be enclosed with brackets ¶

Compliant example:

struct struct_showcase_sub
{
        uint32_t temp_1;
        uint32_t temp_2;
};

struct struct_showcase
{
        uint32_t temp_3;
        struct struct_showcase_sub temp_struct;
};

struct struct_showcase showcase = {32U, {32U, 32U}};

Non-compliant example:

struct struct_showcase_sub
{
        uint32_t temp_1;
        uint32_t temp_2;
};

struct struct_showcase
{
        uint32_t temp_3;
        struct struct_showcase_sub temp_struct;
};

struct struct_showcase showcase = {32U, 32U, 32U};

C-DI-05: The array size shall be specified explicitly ¶

Compliant example:

uint32_t showcase[2] = {0U, 1U};

Non-compliant example:

uint32_t showcase[] = {0U, 1U};

C-DI-06: Global variables shall be declared only once ¶

Global variables shall be declared only once with the following exception: A global variable may be declared twice if one declaration is in a header file with the extern specifier and the other one is in a source file without the extern specifier.

Compliant example:

/* In `showcase.h` */
extern uint32_t showcase;

/* In `showcase.c`: */
/* global variable */
uint32_t showcase = 32U;

void func_showcase(void)
{
        showcase++;
}

Non-compliant example:

/* In `showcase.c`: */
/* global variable */
uint32_t showcase;
uint32_t showcase = 32U;

void func_showcase(void)
{
        showcase++;
}

C-DI-07: An array shall be fully initialized ¶

Compliant example:

uint32_t showcase_array[5] = {0, 1, 2, 3, 4};

Non-compliant example:

uint32_t showcase_array[5] = {0, 1};

C-DI-08: An array declaration shall use a constant for the size ¶

Compliant example:

uint32_t array_showcase[10];

Non-compliant example:

uint32_t array_size = 10U;
uint32_t array_showcase[array_size];

Functions ¶

C-FN-01: A non-void function shall have a return statement ¶

Compliant example:

uint32_t showcase(uint32_t param)
{
        printf("param: %d\n", param);
        return param;
}

Non-compliant example:

uint32_t showcase(uint32_t param)
{
        printf("param: %d\n", param);
}

C-FN-02: A non-void function shall have a return value rather than empty return ¶

Compliant example:

uint32_t showcase(uint32_t param)
{
        printf("param: %d\n", param);
        return param;
}

Non-compliant example:

uint32_t showcase(uint32_t param)
{
        printf("param: %d\n", param);
        return;
}

C-FN-03: A non-void function shall return a value on all paths ¶

Compliant example:

uint32_t showcase(uint32_t param)
{
        if (param < 10U) {
                return 10U;
        } else {
                return param;
        }
}

Non-compliant example:

uint32_t showcase(uint32_t param)
{
        if (param < 10U) {
                return 10U;
        } else {
                return;
        }
}

C-FN-04: The return value of a void-returning function shall not be used ¶

Compliant example:

void showcase_1(uint32_t param)
{
        printf("param: %d\n", param);
}

void showcase_2(void)
{
        uint32_t a;

        showcase_1(0U);
        a = 0U;
}

Non-compliant example:

void showcase_1(uint32_t param)
{
        printf("param: %d\n", param);
}

void showcase_2(void)
{
        uint32_t a;

        a = showcase_1(0U);
}

C-FN-05: A parameter passed by pointer to a function shall not be reassigned ¶

Compliant example:

void func_showcase(uint32_t *param_ptr)
{
        uint32_t *local_ptr = param_ptr;

        local_ptr++;
        printf("%d \n", *local_ptr);
}

Non-compliant example:

void func_showcase(uint32_t *param_ptr)
{
        param_ptr++;
        printf("%d \n", *param_ptr);
}

C-FN-06: A parameter passed by value to a function shall not be modified directly ¶

Compliant example:

void func_showcase(uint32_t param)
{
        uint32_t local = param;

        local++;
        printf("%d \n", local);
}

Non-compliant example:

void func_showcase(uint32_t param)
{
        param++;
        printf("%d \n", param);
}

C-FN-07: A non-static function shall be declared in a header file ¶

Compliant example:

/* In `showcase.h`: */
uint32_t func_showcase(uint32_t param);

/* In `showcase.c`: */
#include "showcase.h"

uint32_t func_showcase(uint32_t param)
{
        return param;
}

Non-compliant example:

/* There is no `showcase.h`. */

/* In `showcase.c`: */
uint32_t func_showcase(uint32_t param)
{
        return param;
}

C-FN-08: All static functions shall be used within the file in which they are declared ¶

Unlike global functions in C, access to a static function is restricted to the file where it is declared. Therefore, a static function shall be used in the file where it is declared, either called explicitly or indirectly via its address. Otherwise, the static function shall be removed.

Compliant example:

static void func_showcase(uint32_t param)
{
        printf("param %d \n", param);
}

void main(void)
{
        func_showcase(10U);
}

Non-compliant example:

/* func_showcase is not called explicitly or accessed via the address */
static void func_showcase(uint32_t param)
{
        printf("param %d \n", param);
}

C-FN-09: The formal parameter name of a function shall be consistent ¶

The formal parameter name of a function shall be the same between its declaration and its definition.

Compliant example:

/* In `showcase.h`: */
uint32_t func_showcase(uint32_t param);

/* In `showcase.c`: */
#include "showcase.h"

uint32_t func_showcase(uint32_t param)
{
        return param;
}

Non-compliant example:

/* In `showcase.h`: */
uint32_t func_showcase(uint32_t param);

/* In `showcase.c`: */
#include "showcase.h"

uint32_t func_showcase(uint32_t param_1)
{
        return param_1;
}

C-FN-10: The formal parameter type of a function shall be consistent ¶

The formal parameter type of a function shall be the same between its declaration and its definition.

Compliant example:

/* In `showcase.h`: */
uint32_t func_showcase(uint32_t param);

/* In `showcase.c`: */
#include "showcase.h"

uint32_t func_showcase(uint32_t param)
{
        return param;
}

Non-compliant example:

/* In `showcase.h`: */
uint32_t func_showcase(uint64_t param);

/* In `showcase.c`: */
#include "showcase.h"

uint32_t func_showcase(uint32_t param)
{
        return param;
}

C-FN-11: The return type of a function shall be consistent ¶

The return type of a function shall be the same between its declaration and its definition.

Compliant example:

/* In `showcase.h`: */
uint32_t func_showcase(uint32_t param);

/* In `showcase.c`: */
#include "showcase.h"

uint32_t func_showcase(uint32_t param)
{
        return param;
}

Non-compliant example:

/* In `showcase.h`: */
uint64_t func_showcase(uint64_t param);

/* In `showcase.c`: */
#include "showcase.h"

uint32_t func_showcase(uint32_t param)
{
        return param;
}

C-FN-12: Banned functions shall not be used ¶

The following cases shall be covered:

These dynamic memory allocation functions shall not be used: calloc, malloc, realloc, and free. Dynamic memory allocation shall be replaced with static memory allocation.
The functions va_arg, va_start, and va_end shall be used only within variadic functions (functions taking a variable number of parameters) such as printf.

Compliant example:

uint32_t showcase_array[32];

Non-compliant example:

uint32_t *showcase_ptr = (uint32_t *)malloc(32U * sizeof(uint32_t));

C-FN-13: All declared functions shall have a corresponding definition ¶

Compliant example:

/* In `showcase.h`: */
/* declaration */
uint32_t func_showcase(uint32_t param);

/* In `showcase.c`: */
#include "showcase.h"

/* definition */
uint32_t func_showcase(uint32_t param)
{
        return param;
}

Non-compliant example:

/* In `showcase.h`: */
/* declaration */
uint32_t func_showcase(uint32_t param);

/* There is no definition of `func_showcase` anywhere in the source files */

C-FN-14: All defined functions shall be used ¶

All defined functions shall be used, either called explicitly or indirectly via the address. Otherwise, the function shall be removed. The following case is an exception: Some extra functions may be kept in order to provide a more complete library of APIs. These functions may be implemented but not used currently. These functions will come in handy in the future. In this case, these functions may remain.

Compliant example:

/* In `showcase.h`: */
uint32_t func_showcase(uint32_t param);

/* In `showcase.c`: */
#include "showcase.h"

uint32_t func_showcase(uint32_t param)
{
        return param;
}

/* In `main.c`: */
#include "showcase.h"

void main(void)
{
        uint32_t showcase;

        showcase = func_showcase(32U);
}

Non-compliant example:

/* In `showcase.h`: */
uint32_t func_showcase(uint32_t param);

/* In `showcase.c`: */
#include "showcase.h"

/* There is no usage of `func_showcase` anywhere in all source files */
uint32_t func_showcase(uint32_t param)
{
        return param;
}

C-FN-15: A function shall not return a pointer to a local object ¶

A function shall not return a pointer to a local object, either directly or within a returned structure or array.

Compliant example:

struct struct_showcase
{
        uint32_t temp_32;
        uint64_t temp_64;
};

struct struct_showcase func_showcase(void)
{
        struct struct_showcase showcase;
        uint32_t showcase_u32 = 32U;
        uint64_t showcase_u64 = 64UL;

        showcase.temp_32 = showcase_u32;
        showcase.temp_64 = showcase_u64;

        return showcase;
}

Non-compliant example:

struct struct_showcase
{
        uint32_t *temp_32;
        uint64_t *temp_64;
};

struct struct_showcase func_showcase(void)
{
        struct struct_showcase showcase;
        uint32_t showcase_u32 = 32U;
        uint64_t showcase_u64 = 64UL;

        showcase.temp_32 = &showcase_u32;
        showcase.temp_64 = &showcase_u64;

        return showcase;
}

C-FN-16: Mixed-use of C code and assembly code in a single function shall not be allowed ¶

A function with mixed-use of C code and assembly code shall be split into multiple sub-functions to separate the usage of C code and assembly code.

Compliant example:

void asm_hlt(void)
{
        asm volatile ("hlt");
}

void func_showcase(void)
{
        bool showcase_flag = true;

        if (showcase_flag) {
                asm_hlt();
        }
}

Non-compliant example:

void func_showcase(void)
{
        bool showcase_flag = true;

        if (showcase_flag) {
                asm volatile ("hlt");
        }
}

C-FN-17: The return value of a non-void function shall be either used or discarded ¶

The return value of a non-void function shall be either used or discarded explicitly via (void). If the return value contains the error code, this return value shall be checked in all possible paths.

Compliant example:

/** Indicates that argument is not valid. */
#define EINVAL                22

int32_t func_showcase(uint32_t param)
{
        int32_t error;

        if (param < 32U) {
                error = 0;
        } else {
                error = -EINVAL;
        }

        return error;
}

void main(uint32_t index)
{
        int32_t error;
        uint32_t test;
        uint32_t array_showcase[32];

        error = func_showcase(index);

        if (error == 0) {
                test = array_showcase[index];
        }
}

Non-compliant example:

/** Indicates that argument is not valid. */
#define EINVAL                22

int32_t func_showcase(uint32_t param)
{
        int32_t error;

        if (param < 32U) {
                error = 0;
        } else {
                error = -EINVAL;
        }

        return error;
}

void main(uint32_t index)
{
        int32_t error;
        uint32_t test;
        uint32_t array_showcase[32];

        error = func_showcase(index);

        test = array_showcase[index];
}

C-FN-18: The array size shall be valid if the array is a function input parameter ¶

This is to guarantee that the destination array has sufficient space for the operation, such as copy, move, compare, and concatenate.

Compliant example:

void showcase(uint32_t array_source[16])
{
        uint32_t array_destination[16];

        (void)memcpy(array_destination, array_source, 16U);
}

Non-compliant example:

void showcase(uint32_t array_source[32])
{
        uint32_t array_destination[16];

        (void)memcpy(array_destination, array_source, 32U);
}

C-FN-19: Recursion shall not be used in function calls ¶

Compliant example:

uint32_t func_showcase(uint32_t param) {
        uint32_t mult = 1;
        uint32_t i;

        for (i = param; i > 0U; i--) {
                mult = mult * i;
        }

        return mult;
}

Non-compliant example:

uint32_t func_showcase(uint32_t param) {
        uint32_t mult = 1;

        if (param > 0U) {
                mult = param * func_showcase(param - 1);
        }

        return mult;
}

C-FN-20: Each function shall have at most 6 parameters ¶

Compliant example:

void func_showcase(uint32_t param_1, uint32_t param_2, uint32_t param_3,
        uint32_t param_4, uint32_t param_5, uint32_t param_6) {
        ...
}

Non-compliant example:

void func_showcase(uint32_t param_1, uint32_t param_2, uint32_t param_3,
        uint32_t param_4, uint32_t param_5, uint32_t param_6,
        uint32_t param_7) {
        ...
}

Statements ¶

C-ST-01: The condition of a selection or iteration statement shall not be constant ¶

The condition of a selection or iteration statement shall not be constant with the following exception: do { ... } while (0) shall be allowed if it is used in a MACRO.

Compliant example:

void func_showcase(uint32_t param)
{
        if (param != 0U) {
                printf("param %d \n", param);
        }
}

Non-compliant example:

void func_showcase(uint32_t param)
{
        if (false) {
                printf("param %d \n", param);
        }
}

C-ST-02: The loop body shall be enclosed with brackets ¶

Compliant example:

uint32_t i;

for (i = 0U; i < 5U; i++) {
        printf("count: %d \n", i);
}

Non-compliant example:

uint32_t i;

for (i = 0U; i < 5U; i++)
        printf("count: %d \n", i);

C-ST-03: Infinite loop shall not exist ¶

Every path in the iteration loop shall have the chance to exit.

Compliant example:

uint32_t count = 10U;
bool showcase_flag = false;

while (count > 5U)
{
        if (showcase_flag) {
                count--;
        } else {
                count = count - 2U;
        }
}

Non-compliant example:

uint32_t count = 10U;
bool showcase_flag = false;

while (count > 5U)
{
        if (showcase_flag) {
                count--;
        }
}

C-ST-04: The else statement shall not be empty if it is following an else if ¶

Either a non-null statement or a comment shall be included in the else statement. This is to guarantee that the developers have considered all of the possible cases.

Compliant example:

uint32_t param, showcase;

if (param < 10U) {
        showcase = 10U;
} else if (param < 20U) {
        showcase = 20U;
} else {
        showcase = 30U;
}

Non-compliant example:

uint32_t param, showcase;

if (param < 10U) {
        showcase = 10U;
} else if (param < 20U) {
        showcase = 20U;
} else {
}

C-ST-05: A switch statement shall have the default statement ¶

This is to guarantee that the developers have considered all of the possible cases.

Compliant example:

char showcase;

switch (showcase) {
case 'a':
        /* do something */
        break;
case 'A':
        /* do something */
        break;
default:
        /* do something */
        break;
}

Non-compliant example:

char showcase;

switch (showcase) {
case 'a':
        /* do something */
        break;
case 'A':
        /* do something */
        break;
}

C-ST-06: Every switch clause shall be terminated with a break statement ¶

Falling through a case shall not be allowed.

Compliant example:

char showcase;

switch (showcase) {
case 'a':
        /* do something */
        break;
case 'A':
        /* do something */
        break;
default:
        /* do something */
        break;
}

Non-compliant example:

char showcase;

switch (showcase) {
case 'a':
        /* do something */
case 'A':
        /* do something */
default:
        /* do something */
        break;
}

C-ST-07: The for loop counter shall not be changed inside the loop body ¶

Compliant example:

uint32_t i;

for (i = 0U; i < 5U; i++) {
        printf("count: %d \n", i);
}

Non-compliant example:

uint32_t i;

for (i = 0U; i < 5U; i++) {
        printf("count: %d \n", i);
        i++;
}

C-ST-08: `goto` statement shall not be used ¶

Compliant example:

uint32_t showcase(uint32_t param)
{
        uint32_t ret;

        if (param < 10U) {
                ret = 10U;
        } else {
                ret = param;
                /* do something */
        }

        return ret;
}

Non-compliant example:

uint32_t showcase(uint32_t param)
{
        uint32_t ret;

        if (param < 10U) {
                ret = 10U;
                goto done;
        } else {
                ret = param;
        }

        /* do something */

done:
        return ret;
}

Expressions ¶

C-EP-01: The initialization expression of a for loop shall be simple ¶

The initialization expression of a for loop shall be used only to initialize the loop counter. All other operations shall not be allowed.

Compliant example:

uint32_t i;

for (i = 0U; i < 5U; i++) {
        printf("count: %d \n", i);
}

Non-compliant example:

uint32_t i;
uint32_t showcase = 0U;

for (i = 0U, showcase = 10U; i < 5U; i++) {
        printf("count: %d \n", i);
}

C-EP-02: The controlling expression of a for loop shall not be empty ¶

Compliant example:

uint32_t i;

for (i = 0U; i < 5U; i++) {
        printf("count: %d \n", i);
}

Non-compliant example:

uint32_t i;

for (i = 0U; ; i++) {
        printf("count: %d \n", i);
        if (i > 4U) {
                break;
        }
}

C-EP-03: The third expression of a for loop shall be simple ¶

The third expression of a for loop shall be used only to increase or decrease the loop counter with the following operators: ++, –, +=, or -=. All other operations shall not be allowed.

Compliant example:

uint32_t i;

for (i = 0U; i < 5U; i++) {
        printf("count: %d \n", i);
}

Non-compliant example:

uint32_t i;
uint32_t showcase = 0U;

for (i = 0U; i < 5U; i++, showcase++) {
        printf("count: %d \n", i);
}

C-EP-04: The evaluation order of an expression shall not influence the result ¶

Compliant example:

uint32_t showcase = 0U;
uint32_t showcase_test = 10U;

showcase++;
showcase_test = showcase_test + showcase;

Non-compliant example:

uint32_t showcase = 0U;
uint32_t showcase_test = 10U;

showcase_test = showcase_test + ++showcase;

C-EP-05: Parentheses shall be used to set the operator precedence explicitly ¶

Compliant example:

uint32_t showcase_u32_1 = 0U;
uint32_t showcase_u32_2 = 0xFFU;
uint32_t showcase_u32_3;

showcase_u32_3 = showcase_u32_1 * (showcase_u32_2 >> 4U);

Non-compliant example:

uint32_t showcase_u32_1 = 0U;
uint32_t showcase_u32_2 = 0xFU;
uint32_t showcase_u32_3;

showcase_u32_3 = showcase_u32_1 * showcase_u32_2 >> 4U;

C-EP-06: Overflow shall not be allowed ¶

Compliant example:

uint8_t showcase = 255U;

Non-compliant example:

uint8_t showcase = 255U + 1U;

C-EP-07: Negation shall not be performed on an unsigned expression ¶

Compliant example:

int32_t showcase = -10;

Non-compliant example:

int32_t showcase = -10U;

C-EP-08: The address of an object shall not be assigned to a different object with a longer lifetime ¶

Compliant example:

void func_showcase(void)
{
        uint32_t showcase_local = 32U;
        uint32_t *showcase_ptr_local;

        showcase_ptr_local = &showcase_local;
        printf("*showcase_ptr_local %d \n", *showcase_ptr_local);
}

Non-compliant example:

uint32_t *showcase_ptr_global;

void func_showcase(void)
{
        uint32_t showcase_local = 32U;
        uint32_t *showcase_ptr_local;

        showcase_ptr_local = &showcase_local;
        showcase_ptr_global = showcase_ptr_local;
}

void main(void)
{
        func_showcase();
        printf("*showcase_ptr_global %d \n", *showcase_ptr_global);
}

C-EP-09: The sizeof operator shall not be used on an array function parameter ¶

When an array is used as a function parameter, the array address is passed. Thus, the return value of the sizeof operation is the pointer size rather than the array size.

Compliant example:

#define SHOWCASE_SIZE 32U

void showcase(uint32_t array_source[SHOWCASE_SIZE])
{
        uint32_t num_bytes = SHOWCASE_SIZE * sizeof(uint32_t);

        printf("num_bytes %d \n", num_bytes);
}

Non-compliant example:

#define SHOWCASE_SIZE 32U

void showcase(uint32_t array_source[SHOWCASE_SIZE])
{
        uint32_t num_bytes = sizeof(array_source);

        printf("num_bytes %d \n", num_bytes);
}

C-EP-10: Argument of strlen shall end with a null character ¶

Compliant example:

uint32_t size;
char showcase[3] = {'0', '1', '\0'};

size = strlen(showcase);

Non-compliant example:

uint32_t size;
char showcase[2] = {'0', '1'};

size = strlen(showcase);

C-EP-11: Two strings shall not be copied to each other if they have memory overlap ¶

Compliant example:

char *str_source = "showcase";
char str_destination[32];

(void)strncpy(str_destination, str_source, 8U);

Non-compliant example:

char *str_source = "showcase";
char *str_destination = &str_source[1];

(void)strncpy(str_destination, str_source, 8U);

C-EP-12: memcpy shall not be performed on objects with overlapping memory ¶

Compliant example:

char *str_source = "showcase";
char str_destination[32];

(void)memcpy(str_destination, str_source, 8U);

Non-compliant example:

char str_source[32];
char *str_destination = &str_source[1];

(void)memcpy(str_destination, str_source, 8U);

C-EP-13: Assignment shall not be performed between variables with overlapping storage ¶

Compliant example:

union union_showcase
{
        uint8_t data_8[4];
        uint16_t data_16[2];
};

union union_showcase showcase;

showcase.data_16[0] = 0U;
showcase.data_8[3] = (uint8_t)showcase.data_16[0];

Non-compliant example:

union union_showcase
{
        uint8_t data_8[4];
        uint16_t data_16[2];
};

union union_showcase showcase;

showcase.data_16[0] = 0U;
showcase.data_8[0] = (uint8_t)showcase.data_16[0];

C-EP-14: The destination object shall have sufficient space for operation ¶

The destination object shall have sufficient space for operation, such as copy, move, compare, and concatenate. Otherwise, data corruption may occur.

Compliant example:

uint32_t array_source[32];
uint32_t array_destination[32];

(void)memcpy(array_destination, array_source, 32U);

Non-compliant example:

uint32_t array_source[32];
uint32_t array_destination[16];

(void)memcpy(array_destination, array_source, 32U);

C-EP-15: The size param to memcpy/memset shall be valid ¶

The size param shall not be larger than either the source size or destination size. Otherwise, data corruption may occur.

Compliant example:

#define SHOWCASE_BYTES (32U * sizeof(uint32_t))

uint32_t array_source[32];

(void)memset(array_source, 0U, SHOWCASE_BYTES);

Non-compliant example:

#define SHOWCASE_BYTES (32U * sizeof(uint32_t))

uint32_t array_source[32];

(void)memset(array_source, 0U, 2U * SHOWCASE_BYTES);

C-EP-16: The denominator of a divide shall not be zero ¶

The denominator of a divide shall be checked before use.

Compliant example:

uint32_t numerator = 32U;
uint32_t denominator = 0U;

if (denominator != 0U) {
        uint32_t quotient = numerator / denominator;
}

Non-compliant example:

uint32_t numerator = 32U;
uint32_t denominator = 0U;

uint32_t quotient = numerator / denominator;

C-EP-17: A NULL pointer shall not be dereferenced ¶

A pointer shall be checked before use.

Compliant example:

uint32_t *showcase_ptr = NULL;

if (showcase_ptr != NULL) {
        uint32_t showcase = *showcase_ptr;
}

Non-compliant example:

uint32_t *showcase_ptr = NULL;

uint32_t showcase = *showcase_ptr;

C-EP-18: A string literal shall not be modified ¶

Compliant example:

const char *showcase = "showcase";

printf("%s \n", showcase);

Non-compliant example:

char *showcase = "showcase";

showcase[0] = 'S';
printf("%s \n", showcase);

C-EP-19: ++ or – operation shall be used with restrictions ¶

Only the following cases shall be allowed:

++ or – operation shall be allowed if it is used alone in the expression.
++ or – operation shall be allowed if it is used as the third expression of a for loop.

Compliant example:

uint32_t showcase = 0U;

showcase++;

Non-compliant example:

uint32_t showcase = 0U;
uint32_t showcase_test;

showcase_test = showcase++;

C-EP-20: Array indexing shall be in-bounds ¶

An array index value shall be between zero (for the first element) and the array size minus one (for the last element). Out-of-bounds array references are an undefined behavior and shall be avoided.

Compliant example:

char showcase_array[4] = {'s', 'h', 'o', 'w'};

char showcase = showcase_array[0];

Non-compliant example:

char showcase_array[4] = {'s', 'h', 'o', 'w'};

char showcase = showcase_array[10];

C-EP-21: The comma operator shall not be used ¶

Compliant example:

uint32_t showcase_a = 10U;
uint32_t showcase_b = 20U;

showcase_a++;
showcase_b++;

Non-compliant example:

uint32_t showcase_a = 10U;
uint32_t showcase_b = 20U;

showcase_a++, showcase_b++;

C-EP-22: Magic numbers shall be used with restrictions ¶

Only the following cases shall be allowed:

The magic number is defined as a MACRO with a name clearly indicating its meaning.
The meaning of the magic number is clearly documented in the comments before its usage.
The meaning of the magic number is straightforward in the specific context.

Compliant example:

#define APIC_ID_MASK 0xff000000U

uint32_t showcase = APIC_ID_MASK;

Non-compliant example:

uint32_t showcase = 0xff000000U;

C-EP-23: Pointer arithmetic shall be used with restrictions ¶

Pointer arithmetic shall be performed on an array if it is possible. If not, the data type and the value range of this pointer shall be checked before access to ensure that the pointer reference is within the correct address space.

Compliant example:

#define SHOWCASE_SIZE 32U

uint32_t showcase_arr[SHOWCASE_SIZE];
uint32_t i;

for (i = 0U; i < SHOWCASE_SIZE; i++) {
        showcase_arr[i] = i;
}

Non-compliant example:

#define SHOWCASE_SIZE 32U

uint32_t *showcase_ptr;
uint32_t i;

for (i = 0U; i < SHOWCASE_SIZE; i++) {
        *showcase_ptr = i;
        showcase_ptr = showcase_ptr + 1U;
}

Types ¶

C-TY-01: The function return value shall be consistent with the declared return type ¶

Compliant example:

uint32_t func_showcase(uint32_t param)
{
        if (param < 10U) {
                return 10U;
        } else {
                return 20U;
        }
}

Non-compliant example:

uint32_t func_showcase(uint32_t param)
{
        if (param < 10U) {
                return 10U;
        } else {
                return -1;
        }
}

C-TY-02: The operands of bit operations shall be unsigned ¶

Compliant example:

uint32_t showcase = 32U;
uint32_t mask = 0xFU;

showcase = showcase & mask;

Non-compliant example:

uint32_t showcase = 32U;
int32_t mask = -1;

showcase = showcase & mask;

C-TY-03: Mixed-use of Boolean values and integers shall not be allowed ¶

Some detailed rules are listed below:

The operands of the arithmetic operation shall be integers.
The operands of the logical operation shall be Boolean values.
The controlling expression of a selection or iteration statement shall be Boolean.
A Boolean type expression shall be used where Boolean is expected.

Compliant example:

bool showcase_flag = true;
uint32_t exp = 32U;
uint32_t cond_exp = 64U;

uint32_t showcase = showcase_flag ? exp : cond_exp;

Non-compliant example:

uint32_t showcase_flag = 1U;
uint32_t exp = 32U;
uint32_t cond_exp = 64U;

uint32_t showcase = showcase_flag ? exp : cond_exp;

C-TY-04: The enum shall not be used for arithmetic operations ¶

Only the following operations on enum shall be allowed:

enum assignment shall be allowed if the operands of = operation have the same enum type.
enum comparison shall be allowed, including the operators ==, !=, >, <, >=, and <=.

Compliant example:

enum enum_showcase {
        ENUM_SHOWCASE_0,
        ENUM_SHOWCASE_1
};

enum enum_showcase showcase_0 = ENUM_SHOWCASE_0;
enum enum_showcase showcase_1 = showcase_0;

Non-compliant example:

enum enum_showcase {
        ENUM_SHOWCASE_0,
        ENUM_SHOWCASE_1
};

enum enum_showcase showcase_0 = ENUM_SHOWCASE_0;
enum enum_showcase showcase_1 = showcase_0 + 1U;

C-TY-05: static keyword shall not be used in an array index declaration ¶

Compliant example:

char showcase[2] = {'0', '1'};
char chr;

chr = showcase[1];

Non-compliant example:

char showcase[2] = {'0', '1'};
char chr;

chr = showcase[static 1];

C-TY-06: A pointer shall point to a const object if the object is not modified ¶

Compliant example:

void func_showcase(const uint32_t *ptr)
{
        printf("value: %d \n", *ptr);
}

Non-compliant example:

void func_showcase(uint32_t *ptr)
{
        printf("value: %d \n", *ptr);
}

C-TY-07: The expressions type in a ternary operation shall be consistent ¶

Compliant example:

bool showcase_flag = true;
uint32_t exp = 32U;
uint32_t cond_exp = 64U;

uint32_t showcase = showcase_flag ? exp : cond_exp;

Non-compliant example:

bool showcase_flag = true;
int32_t exp = -1;
uint32_t cond_exp = 64U;

uint32_t showcase = showcase_flag ? exp : cond_exp;

C-TY-08: The struct field type shall be consistent ¶

The struct field type shall be consistent between its definition and initialization.

Compliant example:

struct struct_showcase
{
        uint32_t temp_32;
        uint64_t temp_64;
};

struct struct_showcase showcase = {32U, 64UL};

Non-compliant example:

struct struct_showcase
{
        uint32_t temp_32;
        uint64_t temp_64;
};

struct struct_showcase showcase = {32U, -1};

C-TY-09: The type used in a switch statement shall be consistent ¶

The type shall be consistent between the case expression and the controlling expression of switch statement.

Compliant example:

enum enum_showcase {
        ENUM_SHOWCASE_0,
        ENUM_SHOWCASE_1,
        ENUM_SHOWCASE_2
};

enum enum_showcase showcase;

switch (showcase) {
case ENUM_SHOWCASE_0:
        /* showcase */
        break;
case ENUM_SHOWCASE_1:
        /* showcase */
        break;
default:
        /* showcase */
        break;
}

Non-compliant example:

enum enum_showcase {
        ENUM_SHOWCASE_0,
        ENUM_SHOWCASE_1,
        ENUM_SHOWCASE_2
};

enum enum_showcase showcase;

switch (showcase) {
case ENUM_SHOWCASE_0:
        /* showcase */
        break;
case 1U:
        /* showcase */
        break;
default:
        /* showcase */
        break;
}

C-TY-10: const qualifier shall not be discarded in a cast operation ¶

Compliant example:

const uint32_t *showcase_const;
const uint32_t *showcase = showcase_const;

Non-compliant example:

const uint32_t *showcase_const;
uint32_t *showcase = (uint32_t *)showcase_const;

C-TY-11: A variable shall be declared as static if it is used only in the file where it is declared ¶

Compliant example:

/* In `showcase.c`: */
/* `showcase` is only in `showcase.c` */
static uint32_t showcase;

Non-compliant example:

/* In `showcase.c`: */
/* `showcase` is only in `showcase.c` */
uint32_t showcase;

C-TY-12: All type conversions shall be explicit ¶

Implicit type conversions shall not be allowed.

Compliant example:

uint32_t showcase_u32;
uint64_t showcase_u64 = 64UL;

showcase_u32 = (uint32_t)showcase_u64;

Non-compliant example:

uint32_t showcase_u32;
uint64_t showcase_u64 = 64UL;

showcase_u32 = showcase_u64;

C-TY-13: Cast shall be performed on operands rather than arithmetic expressions ¶

Compliant example:

uint32_t showcase_u32_1 = 10U;
uint32_t showcase_u32_2 = 10U;
uint64_t showcase_u64;

showcase_u64 = (uint64_t)showcase_u32_1 + (uint64_t)showcase_u32_2;

Non-compliant example:

uint32_t showcase_u32_1 = 10U;
uint32_t showcase_u32_2 = 10U;
uint64_t showcase_u64;

showcase_u64 = (uint64_t)(showcase_u32_1 + showcase_u32_2);

C-TY-14: A complex integer expression shall not be cast to types other than integer ¶

Compliant example:

/* 0x61 is 'a' in ASCII Table */
uint32_t showcase_u32;
char showcase_char;

showcase_u32 = 0x61U + 1U;
showcase_char = (char)showcase_u32;

Non-compliant example:

/* 0x61 is 'a' in ASCII Table */
uint32_t showcase_u32;
char showcase_char;

showcase_u32 = 0x61U;
showcase_char = (char)(showcase_u32 + 1U);

C-TY-15: Integer shall not be used when a character is expected ¶

Compliant example:

char showcase;

switch (showcase) {
case 'a':
        /* do something */
        break;
case 'A':
        /* do something */
        break;
default:
        break;
}

Non-compliant example:

char showcase;

switch (showcase) {
/* 0x61 is 'a' in ASCII Table */
case 0x61:
        /* do something */
        break;
case 'A':
        /* do something */
        break;
default:
        break;
}

C-TY-16: A pointer shall not be cast to any other types ¶

Compliant example:

uint64_t *showcase_ptr;

uint64_t showcase = *showcase_ptr;

Non-compliant example:

uint64_t *showcase_ptr;

uint64_t showcase = (uint64_t)showcase_ptr;

C-TY-17: A pointer shall not be cast from any other types ¶

Only the following pointer assignment shall be allowed:

Assignment shall be allowed via the address operator &.
Assignment shall be allowed if the objects pointed to by the two pointers are of the same type.

Compliant example:

uint64_t showcase = 10UL;

uint64_t *showcase_ptr = &showcase;

Non-compliant example:

uint64_t showcase = 10UL;

uint64_t *showcase_ptr = (uint64_t *)showcase;

C-TY-18: All types declared by typedef shall be used ¶

Typedefs that are not used shall be deleted.

Compliant example:

typedef unsigned int uint32_t;

uint32_t showcase;

Non-compliant example:

typedef unsigned int uint32_t;
/* uint32_t_backup is not being used anywhere */
typedef unsigned int uint32_t_backup;

uint32_t showcase;

C-TY-19: Array indexing shall be performed only on array type ¶

Compliant example:

char showcase[4] = {'s', 'h', 'o', 'w'};

char chr = showcase[1];

Non-compliant example:

char *showcase = "show";

char chr = showcase[1];

C-TY-20: The actual parameter type shall be the same as the formal parameter type ¶

Compliant example:

void func_showcase(uint32_t formal_param)
{
        printf("formal_param: %d \n", formal_param);
}

void main(void)
{
        uint32_t actual_param = 32U;

        func_showcase(actual_param);
}

Non-compliant example:

void func_showcase(uint32_t formal_param)
{
        printf("formal_param: %d \n", formal_param);
}

void main(void)
{
        uint64_t actual_param = 32UL;

        func_showcase(actual_param);
}

C-TY-21: A bit-field shall be a signed integer, unsigned integer, or bool ¶

All the other types shall not be allowed.

Compliant example:

struct struct_showcase
{
        uint8_t function : 3;
        uint8_t device : 5;
        uint8_t bus;
};

Non-compliant example:

struct struct_showcase
{
        int function : 3;
        int device : 5;
        int bus;
};

C-TY-22: Cast shall not be performed on pointers with different object types ¶

Compliant example:

struct struct_showcase
{
        uint32_t *temp_32;
        uint64_t *temp_64;
};

uint32_t *showcase_ptr_u32;
struct struct_showcase *showcase_ptr_struct;

showcase_ptr_u32 = showcase_ptr_struct->temp_32;

Non-compliant example:

struct struct_showcase
{
        uint32_t *temp_32;
        uint64_t *temp_64;
};

uint32_t *showcase_ptr_u32;
struct struct_showcase *showcase_ptr_struct;

showcase_ptr_u32 = (uint32_t *)showcase_ptr_struct;

C-TY-23: Assignment on function pointers shall be performed with the same type ¶

Compliant example:

typedef void (*func_ptr_t)(void);

func_ptr_t func_ptr_a;
func_ptr_t func_ptr_b;

func_ptr_a = func_ptr_b;

Non-compliant example:

typedef void (*func_ptr_a_t)(void);
typedef uint32_t (*func_ptr_b_t)(uint32_t param);

func_ptr_a_t func_ptr_a;
func_ptr_b_t func_ptr_b;

func_ptr_a = func_ptr_b;

C-TY-24: Cast shall not be performed on a function pointer ¶

Compliant example:

typedef uint32_t (*func_ptr_t)(uint32_t param);

uint32_t func_showcase(uint32_t param)
{
        return param;
}

func_ptr_t func_ptr_showcase;
func_ptr_showcase = func_showcase;

Non-compliant example:

typedef uint32_t (*func_ptr_t)(uint32_t param);

void func_showcase(uint32_t param)
{
        printf("param: %d \n", param);
}

func_ptr_t func_ptr_showcase;
func_ptr_showcase = (func_ptr_t)func_showcase;

C-TY-25: A string literal shall be used only as a const object ¶

The following operations shall be covered:

If a string literal is assigned to a variable, this variable shall be declared with const qualifier.
If a string literal is passed as a function parameter, this function parameter shall be declared with the const qualifier.
If a string literal is used as the return value of a function, this function return type shall be declared with the const qualifier.

Compliant example:

const char *showcase = "showcase";

Non-compliant example:

char *showcase = "showcase";

C-TY-26: The basic numerical types shall not be used other than in typedefs ¶

The typedef name shall be used to replace the usage of basic numerical types. This is to guarantee the code portability between different compilers and platforms.

Compliant example:

typedef unsigned int uint32_t;

uint32_t showcase = 32U;

Non-compliant example:

unsigned int showcase = 32U;

C-TY-27: The operands of an assignment operator shall be the same type ¶

Compliant example:

uint32_t showcase = 32U;

Non-compliant example:

uint32_t showcase = 32UL;

C-TY-28: The operands of arithmetic operations shall be the same type ¶

Compliant example:

uint16_t showcase_u16 = 16U;
uint32_t showcase_u32 = 32U;
uint64_t showcase_u64 = 64UL;

uint32_t test = (uint32_t)showcase_u16 + showcase_u32 + (uint32_t)showcase_u64;

Non-compliant example:

uint16_t showcase_u16 = 16U;
uint32_t showcase_u32 = 32U;
uint64_t showcase_u64 = 64UL;

uint32_t test = showcase_u16 + showcase_u32 + showcase_u64;

C-TY-29: The “U” suffix shall be used for unsigned integer constants ¶

For 8-bit, 16-bit, and 32-bit unsigned integer constants, the “U” suffix shall be used. For 64-bit unsigned integer constants, the “UL” suffix shall be used.

Compliant example:

uint8_t showcase_u8 = 8U;
uint16_t showcase_u16 = 16U;
uint32_t showcase_u32 = 32U;

uint64_t showcase_u64 = 64UL;

Non-compliant example:

uint8_t showcase_u8 = 8;
uint16_t showcase_u16 = 16;
uint32_t showcase_u32 = 32;

uint64_t showcase_u64 = 64;

Identifiers ¶

C-ID-01: A parameter name shall not be the same as the name of struct, union, enum, variable, or function ¶

Compliant example:

struct struct_showcase
{
        char *str_source;
        char *str_destination;
};

void func_showcase(uint32_t showcase)
{
        /* main body */
}

Non-compliant example:

struct showcase
{
        char *str_source;
        char *str_destination;
};

void func_showcase(uint32_t showcase)
{
        /* main body */
}

C-ID-02: A member name shall not be the same as the name of struct, union, or enum ¶

Compliant example:

struct struct_showcase_1
{
        char *str_source;
        char *str_destination;
};

struct struct_showcase_2
{
        uint32_t showcase_1;
        uint32_t showcase_2;
};

Non-compliant example:

struct showcase_1
{
        char *str_source;
        char *str_destination;
};

struct showcase_2
{
        uint32_t showcase_1;
        uint32_t showcase_2;
};

C-ID-03: A global variable name shall be unique ¶

A global variable name shall not be the same as the name of struct, union, enum, typedef, function, function parameter, macro, member, enum constant, local variable, or other global variables.

Compliant example:

struct struct_showcase
{
        char *str_source;
        char *str_destination;
};

/* global variable */
uint32_t showcase;

void func_showcase(void)
{
        showcase++;
}

Non-compliant example:

struct showcase
{
        char *str_source;
        char *str_destination;
};

/* global variable */
uint32_t showcase;

void func_showcase(void)
{
        showcase++;
}

C-ID-04: A local variable name shall not be the same as a global variable name ¶

Compliant example:

/* global variable */
uint32_t showcase;

void func_showcase(void)
{
        uint32_t showcase_local;

        showcase_local = 32U;
}

Non-compliant example:

/* global variable */
uint32_t showcase;

void func_showcase(void)
{
        uint32_t showcase;

        showcase = 32U;
}

C-ID-05: The function name shall be unique ¶

The function name shall not be the same as the name of struct, union, enum, typedef, macro, member, enum constant, variable, function parameter, or other functions.

Compliant example:

/* global variable */
uint32_t showcase;

void func_showcase(void)
{
        /* main body */
}

Non-compliant example:

/* global variable */
uint32_t showcase;

void showcase(void)
{
        /* main body */
}

C-ID-06: The typedef name shall be unique ¶

The typedef name shall be unique and not be used for any other purpose.

Compliant example:

typedef unsigned int uint32_t;

uint32_t showcase;

Non-compliant example:

typedef unsigned int uint32_t;

uint32_t uint32_t;

C-ID-07: Names defined by developers shall not start with underscore ¶

All names starting with one or two underscores are reserved for use by the compiler and standard libraries to eliminate potential conflicts with user-defined names.

Compliant example:

uint32_t showcase;

Non-compliant example:

uint32_t __showcase;

C-ID-08: A variable name shall not be the same as a struct, union, or enum ¶

Compliant example:

struct struct_showcase
{
        char *str_source;
        char *str_destination;
};

uint32_t showcase;

Non-compliant example:

struct showcase
{
        char *str_source;
        char *str_destination;
};

uint32_t showcase;

C-ID-09: The typedef name of a numerical type shall indicate the number of bits ¶

Compliant example:

typedef unsigned short uint16_t;

Non-compliant example:

typedef unsigned short ushort_t;

C-ID-10: A C keyword shall not be re-defined by a MACRO ¶

Compliant example:

typedef _Bool bool;

Non-compliant example:

#define _Bool bool

Coding Style ¶

C-CS-01: Each line shall contain at most 120 characters ¶

No more than 120 characters shall be on a line, with tab stops every 8 characters. Statements longer than this limit shall be broken into multiple lines with proper alignment.

Compliant example:

cpuid(CPUID_EXTEND_FEATURE, &unused,
        &boot_cpu_data.cpuid_leaves[FEAT_7_0_EBX],
        &boot_cpu_data.cpuid_leaves[FEAT_7_0_ECX],
        &boot_cpu_data.cpuid_leaves[FEAT_7_0_EDX]);

Non-compliant example:

cpuid(CPUID_EXTEND_FEATURE, &unused, &boot_cpu_data.cpuid_leaves[FEAT_7_0_EBX], &boot_cpu_data.cpuid_leaves[FEAT_7_0_ECX], &boot_cpu_data.cpuid_leaves[FEAT_7_0_EDX]);

C-CS-02: Each line shall contain only one statement ¶

Compliant example:

if (condition) {
        do_a();
} else {
        do_b();
}

Non-compliant example:

if (condition) { do_a();} else {do_b();}

C-CS-03: Tabs shall be used for code indentation ¶

Spaces are allowed only for indenting comments or aligning statements that span multiple lines.

Compliant example:

if (condition) {
        do_a();
} else {
        do_b();
}

Non-compliant example:

if (condition) {
  do_a();
} else {
  do_b();
}

C-CS-04: Tabs shall be 8 characters wide ¶

A tab character shall be considered 8-character wide when limiting the line width.

C-CS-05: Trailing whitespace shall not be allowed at the end of lines ¶

This rule applies to both spaces and tabs at the end of a line.

Compliant example:

uint32_t a;
uint32_t b;
uint32_t c;

Non-compliant example:

/*
 * The example here uses the char ~ to stand for the space at the end of the line
 * in order to highlight the non-compliant part.
 */
uint32_t a;~~~~
uint32_t b;~~~~
uint32_t c;~~~~

C-CS-06: A single space shall exist between non-function-like keywords and opening brackets ¶

A single space shall exist between a non-function-like keyword and the opening bracket (either a brace or a parenthesis) that follows. This rule applies to the keywords if, else, for, do, while, switch, and return.

Compliant example:

uint32_t showcase;

if (showcase == 0U) {
        showcase = 32U;
}

Non-compliant example:

uint32_t showcase;

if(showcase == 0U){
        showcase = 32U;
}

C-CS-07: A space shall not exist between the function identifier and the following open-parenthesis ¶

Compliant example:

size_t entry_size = sizeof(struct vcpuid_entry);

Non-compliant example:

size_t entry_size = sizeof (struct vcpuid_entry);

C-CS-08: A space shall not exist right after opening brackets and right before closing ones ¶

Brackets in this rule refer to parenthesis, braces, and square brackets.

Compliant example:

size_t entry_size = sizeof(struct vcpuid_entry);

Non-compliant example:

size_t entry_size = sizeof( struct vcpuid_entry );

C-CS-09: The `*` characters used for pointers shall be right before the function or variable identifiers ¶

The following cases shall be covered:

For declaration of variables of a pointer type, the * character shall be right before the variable identifier with no space in between.
For functions whose return value is of a pointer type, the * character shall be right before the function identifier with no spaces in between in the function prototype.

Compliant example:

uint32_t *showcase_ptr;
uint32_t *showcase_func(void);

Non-compliant example:

uint32_t* showcase_ptr;
uint32_t* showcase_func(void);

C-CS-10: A single space shall exist around binary and ternary operators ¶

This rule applies to all binary arithmetic, bit-wise, logical, relational, equality, and assignment operators, as well as the ternary conditional operator.

Compliant example:

uint32_t showcase = 32U;

showcase = showcase * 2U;

Non-compliant example:

uint32_t showcase=32U;

showcase=showcase*2U;

C-CS-11: Space shall not exist after unary operator ¶

There shall be no space between a unary operator and its operand. This rule applies to member accesses, prefix or postfix increments and decrements, address and indirection operators.

Compliant example:

int *x;
int y = y + *x;
int a = b->member;

Non-compliant example:

int * x;
int y = y + * x;
int a = b ->member;

C-CS-12: A single space shall exist right after semicolons in for-loop headers ¶

A single space shall exist right after semicolons that separate the different expressions in for-loop headers.

Compliant example:

uint32_t i;

for (i = 0U; i < 5U; i++) {
        printf("count: %d \n", i);
}

Non-compliant example:

uint32_t i;

for (i = 0U;i < 5U;i++) {
        printf("count: %d \n", i);
}

C-CS-13: Braces after if/switch/for/do/while shall be on the same line ¶

The statement after if/switch/for/do/while shall always be a compound statement with its opening brace on the same line as the keyword.

Compliant example:

uint32_t numerator = 32U;
uint32_t denominator = 0U;
uint32_t quotient;

if (denominator != 0U) {
        quotient = numerator / denominator;
}

Non-compliant example:

uint32_t numerator = 32U;
uint32_t denominator = 0U;
uint32_t quotient;

if (denominator != 0U)
{
        quotient = numerator / denominator;
}

C-CS-14: A function body shall start with a line containing a single opening brace ¶

Compliant example:

uint32_t func_showcase(uint32_t param)
{
        return param;
}

Non-compliant example:

uint32_t func_showcase(uint32_t param) {
        return param;
}

C-CS-15: A `switch` statement and its subordinate `case` shall be aligned ¶

Compliant example:

switch(suffix) {
case 'u':
        do_something();
        break;
default:
        do_something_else();
        break;
}

Non-compliant example:

switch(suffix) {
        case 'u':
                do_something();
                break;
        default:
                do_something_else();
                break;
}

C-CS-16: Function parameters shall be aligned ¶

When function call parameters are not in single line, the parameters shall be aligned only with tabs. Mixed-use of spaces and tabs shall not be allowed. The number of tabs could be decided by the developers based on each case and it shall be the same for one case.

Compliant example:

uint32_t showcase;

showcase = func(param_1,
                param_2,
                param_3);

Non-compliant example:

uint32_t showcase;

showcase = func(param_1,
           param_2,
              param_3);

C-CS-17: `//` shall not be used for single-line comments ¶

/* */ shall be used to replace // for single-line comments.

Compliant example:

/* This is a comment */

Non-compliant example:

// This is a comment

C-CS-18: Function information shall be documented with doxygen-style comments ¶

Some detailed rules are listed below to illustrate the comments format for each function:

The comments block shall start with /** (slash-asterisk-asterisk) in a single line.
The comments block shall end with */ (space-asterisk-slash) in a single line.
Other than the first line and the last line, every line inside the comments block shall start with * (space-asterisk). It also applies to the line which is used to separate different paragraphs. We’ll call it a blank line for simplicity.
For each function, following information shall be documented: brief description, detailed description, parameters description, pre-conditions, post-conditions, return value description, and comments explaining the actual return values. We’ll call each block of information a paragraph for simplicity. A paragraph may be removed from the list if it is not applicable for that function.
Each line shall only contain the description for one parameter, or one pre-condition, or one post-condition, or one actual return value. We’ll call each of these an element for simplicity.
A blank line shall separate different paragraphs. Inside each paragraph, a blank line is not required to separate each element.
The brief description of the function shall be documented with the format @brief <brief description>.
No specific format is required for the detailed description of the function.
The description of the function parameter shall be documented with the format @param <parameter name> <parameter description>.
The pre-condition of the function shall be documented with the format @pre <pre-condition description>.
The post-condition of the function shall be documented with the format @post <post-condition description>.
The brief description of the function return value shall be documented with the format @return <brief description of return value>.
A void-returning function shall be documented with the format @return None.
The comments explaining the actual return values shall be documented with the format @retval <return value> <return value explanation>.
If the description of one element needs to span multiple lines, each line shall be aligned to the start of the description in the first line for that element.
The comments block shall appear immediately before the function definition/declaration in the C source file or header file.

Compliant example:

/**
 * @brief Brief description of the function.
 *
 * Detailed description of the function. Detailed description of the function. Detailed description of the
 * function. Detailed description of the function.
 * Application Constraints: Detailed description of application constraint.
 *
 * @param param_1 Parameter description for param_1.
 * @param param_2 Parameter description for param_2.
 * @param param_3 Parameter description for param_3. Parameter description for param_3. Parameter description
 *                for param_3. Parameter description for param_3. Parameter description for param_3. Parameter
 *                description for param_3.
 *
 * @pre param_1 != NULL
 * @pre param_2 <= 255U
 *
 * @post retval <= 0
 *
 * @return Brief description of the return value.
 *
 * @retval 0 Success to handle specific case.
 * @retval -EINVAL Fail to handle specific case because the argument is invalid.
 * @retval -EBUSY Fail to handle specific case because the target is busy.
 *
 */
int32_t func_showcase(uint32_t *param_1, uint32_t param_2, uint32_t param_3);

Non-compliant example:

/* Brief description of the function.
Detailed description of the function. Detailed description of the function. Detailed description of the
function. Detailed description of the function.

@param param_1 Parameter description for param_1. @param param_2 Parameter description for param_2.
@param param_3 Parameter description for param_3. Parameter description for param_3. Parameter description
for param_3. Parameter description for param_3. Parameter description for param_3. Parameter
description for param_3.

pre-conditions: param_1 != NULL, param_2 <= 255U
post-conditions: retval <= 0

Brief description of the return value. */
int32_t func_showcase(uint32_t *param_1, uint32_t param_2, uint32_t param_3);

C-CS-19: Legal entity shall be documented in every file ¶

Legal entity shall be documented in a separate comments block at the start of every file. The following information shall be included:

Copyright
License (using an SPDX-License-Identifier)

Compliant example:

/* Legal entity shall be placed at the start of the file. */
-------------File Contents Start After This Line------------

/*
 * Copyright (C) 2019 Intel Corporation.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

/* Coding or implementation related comments start after the legal entity. */
#include <types.h>

Non-compliant example:

/* Neither copyright nor license information is included in the file. */
-------------------File Contents Start After This Line------------------

/* Coding or implementation related comments start directly. */
#include <types.h>

Naming Convention ¶

C-NC-01: Object-like MACRO shall be named with full upper case ¶

Compliant example:

#define MAX_CONFIG_NAME_SIZE        32U

Non-compliant example:

#define max_config_name_size        32U

C-NC-02: Mixed-use of lower case and upper case in function-like MACRO shall not be allowed ¶

Function-like MACRO shall be named with either full lower case or full upper case. Mixed-use of lower case and upper case shall not be allowed.

Compliant example:

#define max(x, y)        ((x) < (y)) ? (y) : (x)

Non-compliant example:

#define Max(x, y)        ((x) < (y)) ? (y) : (x)

C-NC-03: Data structures exposed to external components shall be named with prefix `acrn_`¶

The data structure types include struct, union, and enum. This rule applies to the data structure with all the following properties:

The data structure is used by multiple modules.
The corresponding resource is exposed to external components, such as the Service VM or a User VM.
The name meaning is simplistic or common, such as vcpu or vm.

Compliant example:

struct acrn_vcpu {
        ...
};

Non-compliant example:

struct vcpu {
        ...
};

C-NC-04: Data structures only used by hypervisor shall be named with prefix `hv_`¶

The data structure types include struct, union, and enum. This rule applies to the data structure with all the following properties:

The data structure is used by multiple modules.
The corresponding resource is only used by hypervisor.
The name meaning is simplistic or common, such as timer.

Compliant example:

struct hv_timer {
        ...
};

Non-compliant example:

struct timer {
        ...
};

C-NC-05: Data structures only used by one module shall be named with the module name as prefix ¶

The data structure types include struct, union, and enum. This rule applies to the data structure with all the following properties:

The data structure is only used by one module.
The name meaning is simplistic or common, such as context.

Compliant example:

struct instr_emul_ctxt {
        ...
};

Non-compliant example:

struct ctxt {
        ...
};

C-NC-07: Function pointer shall be named with suffix `fn`¶

Compliant example:

struct firmware_operations {
        void (*init_fn)(void);
        void *(*get_rsdp_fn)(void);
};

Non-compliant example:

struct firmware_operations {
        void (*init)(void);
        void *(*get_rsdp)(void);
};

C-NC-08: Function name shall be descriptive ¶

Function name shall be descriptive and clearly indicate the purpose of the function. Some detailed rules are listed below:

If the function is performing actions, it shall be named with one of the following formats:
1. <verb>_<nouns>, such as init_vmcs.
2. <verb>_<adjective>_<nouns>, such as init_primary_pcpu.
If the function is doing checks, it shall be named with one of the following formats:
1. is_<nouns>, such as is_space.
2. is_<nouns>_<adjective>, such as is_pcpu_active.
If the function is doing conversions, it shall be named with one of the following formats:
1. <nouns>_to_<nouns>, such as irq_to_vector.
2. <nouns>2<nouns>, such as gva2gpa.
If the function is specific for one module and the name is not descriptive enough with prior rules, it shall be named with the module name as prefix, such as vie_read_mmio.
If the function is a wrapper of inline Assembly codes, it shall be named with one of the following formats:
1. asm_<Assembly instruction mnemonic>, such as asm_pause.
2. If the Assembly instruction mnemonic does not clearly indicate the purpose of the function or the function includes multiple Assembly instruction statements, the function shall be named with asm_ as prefix and apply the other non-assembly function naming rules.
<nouns> mentioned in prior rules may either be one noun or multiple nouns, as long as it could clearly illustrate the object.

Compliant example:

uint32_t init_vmcs(uint32_t param);

uint32_t init_primary_pcpu(uint32_t param);

bool is_space(uint32_t param);

bool is_pcpu_active(uint32_t param);

uint32_t vie_read_mmio(uint32_t param);

uint32_t irq_to_vector(uint32_t param);

uint32_t gva2gpa(uint32_t param);

uint32_t asm_pause(uint32_t param);

Non-compliant example:

uint32_t vmcs_init(uint32_t param);

uint32_t primary_pcpu_init(uint32_t param);

bool space(uint32_t param);

bool pcpu_active(uint32_t param);

uint32_t vie_mmio_read(uint32_t param);

uint32_t from_irq_to_vector(uint32_t param);

uint32_t get_gpa_based_on_gva(uint32_t param);

uint32_t pause(uint32_t param);

Implementation-Specific Behaviors ¶

C-IB-01: All characters in an identifier are significant initial characters ¶

The number of significant initial characters in an identifier is implementation-defined, according to J.3.3 item 2 in C99. For ACRN hypervisor, all characters in an identifier are significant initial characters.

C-IB-02: The number of bits in a byte is 8 ¶

The number of bits in a byte is implementation-defined, according to J.3.4 item 1 in C99. For ACRN hypervisor, the number of bits in a byte is 8.

C-IB-03: The values of the members of the execution character set depends on ASCII Table ¶

The values of the members of the execution character set is implementation-defined, according to J.3.4 item 2 in C99. For ACRN hypervisor, characters are encoded in ASCII. This rule applies to the source code that is being compiled. Non-ASCII characters are allowed in comments, such as the author name.

aligned, refers to section 6.33.1 in GCC 8.3 Manual.
packed, refers to section 6.33.1 in GCC 8.3 Manual.
unused, refers to section 6.33.1 in GCC 8.3 Manual.
section, refers to section 6.32.1 in GCC 8.3 Manual.

C-LE-04: Use of extended builtin-function is allowed ¶

This rule applies to the following builtin-functions:

__builtin_va_arg, refers to section 6.20 in GCC 8.3 Manual.
__builtin_va_start, refers to section 6.20 in GCC 8.3 Manual.
__builtin_va_end, refers to section 6.20 in GCC 8.3 Manual.
__builtin_offsetof, refers to section 6.51 in GCC 8.3 Manual.

C-LE-05: Use of extended designated initializers is allowed ¶

This rule applies to the following designated initializer: writing [first ... last] = value to initialize a range of elements to the same value, refers to section 6.27 in GCC 8.3 Manual.