begriffs open source - freertos/blob - MISRA.md

   1 # MISRA Compliance
   2
   3 FreeRTOS-Kernel conforms to [MISRA C:2012](https://www.misra.org.uk/misra-c)
   4 guidelines, with the deviations listed below. Compliance is checked with
   5 Coverity static analysis. Since the FreeRTOS kernel is designed for
   6 small-embedded devices, it needs to have a very small memory footprint and
   7 has to be efficient. To achieve that and to increase the performance, it
   8 deviates from some MISRA rules. The specific deviations, suppressed inline,
   9 are listed below.
  10
  11 Additionally, [MISRA configuration](#misra-configuration) contains project
  12 wide deviations.
  13
  14 ### Suppressed with Coverity Comments
  15 To find the violation references in the source files run grep on the source code
  16 with ( Assuming rule 8.4 violation; with justification in point 1 ):
  17 ```
  18 grep 'MISRA Ref 8.4.1' . -rI
  19 ```
  20
  21 #### Rule 8.4
  22
  23 MISRA C:2012 Rule 8.4: A compatible declaration shall be visible when an
  24         object or function with external linkage is defined.
  25
  26 _Ref 8.4.1_
  27  - pxCurrentTCB(s) is defined with external linkage but it is only referenced
  28    from the assembly code in the port files. Therefore, adding a declaration in
  29    header file is not useful as the assembly code will still need to declare it
  30    separately.
  31
  32 _Ref 8.4.2_
  33  - xQueueRegistry is defined with external linkage because it is accessed by the
  34    kernel unit tests. It is not meant to be directly accessed by the application
  35    and therefore, not declared in a header file.
  36
  37 #### Rule 11.3
  38
  39 MISRA C:2012 Rule 11.3: A cast shall not be performed between a pointer to
  40 object type and a pointer to a different object type.
  41
  42 _Ref 11.3.1_
  43  - This rule prohibits casting a pointer to object into a pointer to a
  44    different object because it may result in an incorrectly aligned pointer,
  45    leading to undefined behavior. Even if the casting produces a correctly
  46    aligned pointer, the behavior may be still undefined if the pointer is
  47    used to access an object. FreeRTOS deliberately creates external aliases
  48    for all the kernel object types (StaticEventGroup_t, StaticQueue_t,
  49    StaticStreamBuffer_t, StaticTimer_t and StaticTask_t) for data hiding
  50    purposes. The internal object types and the corresponding external
  51    aliases are guaranteed to have the same size and alignment which is
  52    checked using configASSERT.
  53
  54
  55 #### Rule 11.5
  56
  57 MISRA C:2012 Rule 11.5: A conversion should not be performed from pointer to
  58 void into pointer to object.
  59 This rule prohibits conversion of a pointer to void into a pointer to
  60 object because it may result in an incorrectly aligned pointer leading
  61 to undefined behavior.
  62
  63 _Ref 11.5.1_
  64  - The memory blocks returned by pvPortMalloc() are guaranteed to meet the
  65    architecture alignment requirements specified by portBYTE_ALIGNMENT.
  66    The casting of the pointer to void returned by pvPortMalloc() is,
  67    therefore, safe because it is guaranteed to be aligned.
  68
  69 _Ref 11.5.2_
  70  - The conversion from a pointer to void into a pointer to EventGroup_t is
  71    safe because it is a pointer to EventGroup_t, which is returned to the
  72    application at the time of event group creation for data hiding
  73    purposes.
  74
  75 _Ref 11.5.3_
  76  - The conversion from a pointer to void in list macros for list item owner
  77    is safe because the type of the pointer stored and retrieved is the
  78    same.
  79
  80 _Ref 11.5.4_
  81  - The conversion from a pointer to void into a pointer to EventGroup_t is
  82    safe because it is a pointer to EventGroup_t, which is passed as a
  83    parameter to the xTimerPendFunctionCallFromISR API when the callback is
  84    pended.
  85
  86 _Ref 11.5.5_
  87  - The conversion from a pointer to void into a pointer to uint8_t is safe
  88    because data storage buffers are implemented as uint8_t arrays for the
  89    ease of sizing, alignment and access.
  90
  91
  92 ### MISRA configuration
  93
  94 Copy below content to `misra.conf` to run Coverity on FreeRTOS-Kernel.
  95
  96 ```
  97 // MISRA C-2012 Rules
  98 {
  99     version : "2.0",
 100     standard : "c2012",
 101     title: "Coverity MISRA Configuration",
 102     deviations : [
 103         // Disable the following rules.
 104         {
 105             deviation: "Directive 4.8",
 106             reason: "HeapRegion_t and HeapStats_t are used only in heap files but declared in portable.h which is included in multiple source files. As a result, these definitions appear in multiple source files where they are not used."
 107         },
 108         {
 109             deviation: "Directive 4.9",
 110             reason: "FreeRTOS-Kernel is optimised to work on small micro-controllers. To achieve that, function-like macros are used."
 111         },
 112         {
 113             deviation: "Rule 1.2",
 114             reason: "The __attribute__ tags are used via macros which are defined in port files."
 115         },
 116         {
 117             deviation: "Rule 3.1",
 118             reason: "We post HTTP links in code comments which contain // inside comments blocks."
 119         },
 120         {
 121             deviation: "Rule 8.7",
 122             reason: "API functions are not used by the library outside of the files they are defined; however, they must be externally visible in order to be used by an application."
 123         }
 124     ]
 125 }
 126 ```