MISRA C rules for Xen

Note

IMPORTANT All MISRA C rules, text, and examples are copyrighted by the MISRA Consortium Limited and used with permission.

Please refer to https://www.misra.org.uk/ to obtain a copy of MISRA C, or for licensing options for other use of the rules.

The following is the list of MISRA C rules that apply to the Xen hypervisor.

It is possible that in specific circumstances it is best not to follow a rule because it is not possible or because the alternative leads to better code quality. Those cases are called “deviations”. They are permissible as long as they are documented. For details, please refer to docs/misra/documenting-violations.rst and docs/misra/deviations.rst

Other documentation mechanisms are work-in-progress.

The existing codebase is not 100% compliant with the rules. Some of the violations are meant to be documented as deviations, while some others should be fixed. Both compliance and documenting deviations on the existing codebase are work-in-progress.

The list below might need to be updated over time. Reach out to THE REST maintainers if you want to suggest a change.

Dir number

Severity

Summary

Notes

Dir 1.1

Required

Any implementation-defined behaviour on which the output of the program depends shall be documented and understood

Dir 2.1

Required

All source files shall compile without any compilation errors

Dir 4.7

Required

If a function returns error information then that error information shall be tested

Dir 4.10

Required

Precautions shall be taken in order to prevent the contents of a header file being included more than once

Files that are intended to be included more than once do not need to conform to the directive

Dir 4.11

Required

The validity of values passed to library functions shall be checked

We do not have libraries in Xen (libfdt and others are not considered libraries from MISRA C point of view as they are imported in source form)

Dir 4.14

Required

The validity of values received from external sources shall be checked

Rule number

Severity

Summary

Notes

Rule 1.1

Required

The program shall contain no violations of the standard C syntax and constraints, and shall not exceed the implementation’s translation limits

We make use of several compiler extensions as documented by C-language-toolchain.rst

Rule 1.3

Required

There shall be no occurrence of undefined or critical unspecified behaviour

Rule 1.4

Required

Emergent language features shall not be used

Emergent language features, such as C11 features, should not be confused with similar compiler extensions, which we use. When the time comes to adopt C11, this rule will be revisited.

Rule 2.1

Required

A project shall not contain unreachable code
The following are allowed:

  • Invariantly constant conditions, e.g. if(IS_ENABLED(CONFIG_HVM)) { S; }

  • Switch with a controlling value statically determined not to match one or more case statements

  • Functions that are intended to be referenced only from assembly code (e.g. ‘do_trap_fiq’)

  • asm-offsets.c, as they are not linked deliberately, because they are used to generate definitions for asm modules

  • Declarations without initializer are safe, as they are not executed

Rule 2.6

Advisory

A function should not contain unused label declarations

Rule 3.1

Required

The character sequences /* and // shall not be used within a comment

Comments containing hyperlinks inside C-style block comments are safe

Rule 3.2

Required

Line-splicing shall not be used in // comments

Rule 4.1

Required

Octal and hexadecimal escape sequences shall be terminated

Rule 4.2

Advisory

Trigraphs should not be used

Rule 5.1

Required

External identifiers shall be distinct

The Xen characters limit for identifiers is 40. Public headers (xen/include/public/) are allowed to retain longer identifiers for backward compatibility.

Rule 5.2

Required

Identifiers declared in the same scope and name space shall be distinct

The Xen characters limit for identifiers is 40. Public headers (xen/include/public/) are allowed to retain longer identifiers for backward compatibility.

Rule 5.3

Required

An identifier declared in an inner scope shall not hide an identifier declared in an outer scope

Using macros as macro parameters at invocation time is allowed even if both macros use identically named local variables, e.g. max(var0, min(var1, var2))

Rule 5.4

Required

Macro identifiers shall be distinct

The Xen characters limit for macro identifiers is 40. Public headers (xen/include/public/) are allowed to retain longer identifiers for backward compatibility.

Rule 5.6

Required

A typedef name shall be a unique identifier

Rule 6.1

Required

Bit-fields shall only be declared with an appropriate type

In addition to the C99 types, we also consider appropriate types enum and all explicitly signed / unsigned integer types.

Rule 6.2

Required

Single-bit named bit fields shall not be of a signed type

Rule 7.1

Required

Octal constants shall not be used

Rule 7.2

Required

A “u” or “U” suffix shall be applied to all integer constants that are represented in an unsigned type

The rule asks that any integer literal that is implicitly unsigned is made explicitly unsigned by using one of the indicated suffixes. As an example, on a machine where the int type is 32-bit wide, 0x77777777 is signed whereas 0x80000000 is (implicitly) unsigned. In order to comply with the rule, the latter should be rewritten as either 0x80000000u or 0x80000000U. Consistency considerations may suggest using the same suffix even when not required by the rule. For instance, if one has:

Original: f(0x77777777); f(0x80000000);

one should do

Solution 1: f(0x77777777U); f(0x80000000U);

over

Solution 2: f(0x77777777); f(0x80000000U);

after having ascertained that “Solution 1” is compatible with the intended semantics.

Rule 7.3

Required

The lowercase character l shall not be used in a literal suffix

Rule 7.4

Required

A string literal shall not be assigned to an object unless the object type is pointer to const-qualified char

All “character types” are permitted, as long as the string element type and the character type match. (There should be no casts.) Assigning a string literal to any object with type “pointer to const-qualified void” is allowed.

Rule 8.1

Required

Types shall be explicitly specified

Rule 8.2

Required

Function types shall be in prototype form with named parameters

Clarification: both function and function pointers types shall have named parameters.

Rule 8.3

Required

All declarations of an object or function shall use the same names and type qualifiers

The type ret_t maybe be deliberately used and defined as int or long depending on the type of guest to service

Rule 8.4

Required

A compatible declaration shall be visible when an object or function with external linkage is defined

Allowed exceptions: asm-offsets.c, definitions for asm modules not called from C code, gcov_base.c

Rule 8.5

Required

An external object or function shall be declared once in one and only one file

Rule 8.6

Required

An identifier with external linkage shall have exactly one external definition

Declarations without definitions are allowed (specifically when the definition is compiled-out or optimized-out by the compiler)

Rule 8.8

Required

The static storage class specifier shall be used in all declarations of objects and functions that have internal linkage

Rule 8.10

Required

An inline function shall be declared with the static storage class

gnu_inline (without static) is allowed.

Rule 8.12

Required

Within an enumerator list the value of an implicitly-specified enumeration constant shall be unique

Rule 8.14

Required

The restrict type qualifier shall not be used

Rule 9.1

Mandatory

The value of an object with automatic storage duration shall not be read before it has been set

Rule clarification: do not use variables before they are initialized. An explicit initializer is not necessarily required. Try reducing the scope of the variable. If an explicit initializer is added, consider initializing the variable to a poison value.

Rule 9.2

Required

The initializer for an aggregate or union shall be enclosed in braces

Rule 9.3

Required

Arrays shall not be partially initialized

{} is also allowed to specify explicit zero-initialization

Rule 9.4

Required

An element of an object shall not be initialized more than once

Rule 10.1

Required

Operands shall not be of an inappropriate essential type
The following are allowed:

  • Value-preserving conversions of integer constants

  • Bitwise and, or, xor, one’s complement, bitwise and assignment, bitwise or assignment, bitwise xor assignment (bitwise and, or, xor are safe on non-negative integers; also Xen assumes two’s complement representation)

  • Left shift, right shift, left shift assignment, right shift assignment (see C-language-toolchain.rst for uses of compilers’ extensions)

  • Implicit conversions to boolean for conditionals (?: if while for) and logical operators (! || &&)

Rule 10.2

Required

Expressions of essentially character type shall not be used inappropriately in addition and subtraction operations

Rule 10.3

Required

The value of an expression shall not be assigned to an object with a narrower essential type or of a different essential type category

Please beware that this rule has many violations in the Xen codebase today, and its adoption is aspirational. However, when submitting new patches please try to decrease the number of violations when possible.

gcc has a helpful warning that can help you spot and remove violations of this kind: conversion. For instance, you can use it as follows:

CFLAGS=”-Wconversion -Wno-error=sign-conversion -Wno-error=conversion” make -C xen

Rule 10.4

Required

Both operands of an operator in which the usual arithmetic conversions are performed shall have the same essential type category

Please beware that this rule has many violations in the Xen codebase today, and its adoption is aspirational. However, when submitting new patches please try to decrease the number of violations when possible.

gcc has a helpful warning that can help you spot and remove violations of this kind: arith-conversion. For instance, you can use it as follows:

CFLAGS=”-Warith-conversion -Wno-error=arith-conversion” make -C xen

Rule 11.7

Required

A cast shall not be performed between pointer to object and a noninteger arithmetic type

Rule 11.8

Required

A cast shall not remove any const or volatile qualification from the type pointed to by a pointer

Rule 11.9

Required

The macro NULL shall be the only permitted form of null pointer constant

Rule 12.5

Mandatory

The sizeof operator shall not have an operand which is a function parameter declared as “array of type”

Rule 13.6

Mandatory

The operand of the sizeof operator shall not contain any expression which has potential side effects

Rule 13.1

Required

Initializer lists shall not contain persistent side effects

Rule 14.1

Required

A loop counter shall not have essentially floating type

Rule 14.3

Required

Controlling expressions shall not be invariant

Due to the extensive usage of IS_ENABLED, sizeof compile-time checks, and other constructs that are detected as errors by MISRA C scanners, managing the configuration of a MISRA C scanner for this rule would be unmanageable. Thus, this rule is adopted with a project-wide deviation on if, ?:, switch(sizeof(…)), and switch(offsetof(…)) statements.

while(0) and while(1) and alike are allowed.

Rule 16.7

Required

A switch-expression shall not have essentially Boolean type

Rule 17.3

Mandatory

A function shall not be declared implicitly

Rule 17.4

Mandatory

All exit paths from a function with non-void return type shall have an explicit return statement with an expression

Rule 17.6

Mandatory

The declaration of an array parameter shall not contain the static keyword between the [ ]

Rule 18.3

Required

The relational operators > >= < and <= shall not be applied to objects of pointer type except where they point into the same object

Rule 19.1

Mandatory

An object shall not be assigned or copied to an overlapping object

Be aware that the static analysis tool Eclair might report several findings for Rule 19.1 of type “caution”. These are instances where Eclair is unable to verify that the code is valid in regard to Rule 19.1. Caution reports are not violations.

Rule 20.7

Required

Expressions resulting from the expansion of macro parameters shall be enclosed in parentheses

Extra parentheses are not required when macro parameters are used as function arguments, as macro arguments, array indices, lhs in assignments

Rule 20.13

Required

A line whose first token is # shall be a valid preprocessing directive

Rule 20.14

Required

All #else #elif and #endif preprocessor directives shall reside in the same file as the #if #ifdef or #ifndef directive to which they are related

Rule 21.13

Mandatory

Any value passed to a function in <ctype.h> shall be representable as an unsigned char or be the value EOF

Rule 21.17

Mandatory

Use of the string handling functions from <string.h> shall not result in accesses beyond the bounds of the objects referenced by their pointer parameters

Rule 21.18

Mandatory

The size_t argument passed to any function in <string.h> shall have an appropriate value

Rule 21.19

Mandatory

The pointers returned by the Standard Library functions localeconv, getenv, setlocale or, strerror shall only be used as if they have pointer to const-qualified type

Rule 21.20

Mandatory

The pointer returned by the Standard Library functions asctime ctime gmtime localtime localeconv getenv setlocale or strerror shall not be used following a subsequent call to the same function

Rule 21.21

Required

The Standard Library function system of <stdlib.h> shall not be used

Rule 22.2

Mandatory

A block of memory shall only be freed if it was allocated by means of a Standard Library function

Rule 22.4

Mandatory

There shall be no attempt to write to a stream which has been opened as read-only

Rule 22.5

Mandatory

A pointer to a FILE object shall not be dereferenced

Rule 22.6

Mandatory

The value of a pointer to a FILE shall not be used after the associated stream has been closed