1# MISRA Compliance 2 3The FreeRTOS-Plus-TCP library files conform to the [MISRA C:2012](https://www.misra.org.uk/MISRAHome/MISRAC2012/tabid/196/Default.aspx) 4guidelines, with the deviations listed below. Compliance is checked with Coverity static analysis. 5Since the FreeRTOS-Plus-TCP library is designed for small-embedded devices, it needs to have a very small memory footprint and has to 6be efficient. To achieve that and to increase the performace of the IP-stack, it deviates from some MISRA rules. 7The specific deviations, suppressed inline, are listed below. 8 9Additionally, [MISRA configuration file](https://github.com/FreeRTOS/FreeRTOS-Plus-TCP/blob/main/test/Coverity/coverity_misra.config) contains the project wide deviations. 10 11### Suppressed with Coverity Comments 12To find the violation references in the source files run grep on the source code 13with ( Assuming rule 11.4 violation; with justification in point 2 ): 14``` 15grep 'MISRA Ref 11.4.2' . -rI 16``` 17#### Directive 4.12 18 19_Ref 4.12.1_ 20 21- MISRA C:2012 Directive 4.12: Dynamic memory allocation shall not be used. 22 MISRA warns against the use of dynamic memory allocation as it might 23 lead to undefined behavior if not used properly. However, the 24 FreeRTOS-Plus-TCP library only uses the memory allocation primitives 25 defined by the FreeRTOS-Kernel, which are deterministic. Additionally, 26 proper care is taken in the code to not use free'd pointers and to check 27 the validity of malloc'd memory before it is dereferenced or used. 28 29#### Rule 2.2 30 31_Ref 2.2.1_ 32 33- MISRA C-2012 Rule 2.2 Unions are used for checksum computation to speed up the 34 process by utilizing the full length of registers (32-bits). After this, 35 the 16-bit union members are used to then compute the final checksum. 36 Doing this is considered as 'overwriting the variable' by Coverity. 37 Thus, it marks some statements as dead code. This is a false positive. 38 39#### Rule 8.9 40_Ref 8.9.1_ 41 42- MISRA C-2012 Rule 8.9 For unit-tests to be repeatable and independent of the 43 order of execution, some variables have file scope definitions rather 44 than function scope. 45 46#### Rule 8.13 47_Ref 8.13.1_ 48 49- MISRA C-2012 Rule 8.13 Parameter passed is never used, should be declared as 50 const. The argument passed to the `prvIPTask` function is left unused which is 51 considered as the variable not being used and thus warranting the use of `const`. 52 However, the FreeRTOS-kernel function `xTaskCreate` expects a function signature 53 of type `void vSomeFunction( void * pvArgs )`. To satisfy that requirement, the 54 function signature of `prvIPTask` does not have a `const` qualifier in the 55 parameter signature. 56 57#### Rule 10.5 58_Ref 10.5.1_ 59 60- MISRA C-2012 Rule 10.5 Converting from an unsigned to an enum type. The 61 operation is safe to perform in that case, as we are using a generic API 62 to send and receive data, in that case the exact data sent it is received 63 64#### Rule 11.1 65_Ref 11.1.1_ 66 67- MISRA C-2012 Rule 11.1 Converting from a void pointer to a function pointer. 68 The `FreeRTOS_setsockopt` API allows users to configure sockets by setting 69 various options. In order to do so, the function must accept one parameter 70 which, based on the option value, can be casted to the corresponding socket 71 field. To that end, that parameter is of `void *` type to accommodate all values. 72 The caller of the API is responsible for providing correct function pointer to the 73 API. Thus, this violation can be safely suppressed. 74 75#### Rule 11.3 76_Ref 11.3.1_ 77 78- MISRA C-2012 Rule 11.3 The data received/sent by the IP stack is represent as a 79 byte stream. This byte stream needs to be casted to various data 80 structures to access certain fields of the packet. However, when casting 81 a byte stream to a structure, MISRA warns us that it can lead to 82 unaligned access. But, in case of FreeRTOS+TCP, the buffer in which the 83 packets are stored are always aligned to a 4 byte word boundary with an 84 offset of 2 bytes. The reason for this 2 byte offset is that the 85 ethernet header is of 14 (12 + 2) bytes. Thus, everything except the 86 ethernet header is properly aligned. There is one alignment exception, 87 which is the sender protocol address in the ARP Header. To combat that, 88 the sender protocol address field is declared as an array of 4 bytes 89 instead of a `uint32_t`. 90 More details can be found [here](https://github.com/FreeRTOS/FreeRTOS-Plus-TCP/pull/512#pullrequestreview-1035211706). 91 92#### Rule 11.4 93_Ref 11.4.1_ 94 95- MISRA c-2012 Rule 11.4 Warns about conversion between a pointer and an integer. 96 Whenever a socket is created using the `FreeRTOS_Socket` API, either a 97 valid socket (a valid non-NULL pointer) is returned; or 98 `FREERTOS_INVALID_SOCKET` is returned (which is essentially ~0U) to 99 depict an error in the socket creation process. This conversion from ~0U 100 to a pointer is used to convey the error to various functions. If the 101 pointer is equal to `FREERTOS_INVALID_SOCKET`, then it is not 102 dereferenced. Thus, this violation can be safely suppressed. 103 104_Ref 11.4.2_ 105 106- MISRA Rule 11.4 The following statement may trigger a: 107 warning: cast increases required alignment of target type [-Wcast-align]. 108 It has been programatically checked that the pointer is well aligned 109 before this point. 110 111_Ref 11.4.3_ 112 113- MISRA Rule 11.4 warns about casting pointer to an integer and vice versa. 114 Here, the poiner to the starting byte of the packet is cast to an 115 integer which is then used to see whether the pointer is well 116 aligned or not. It is not used to access any pointer values. Thus, this 117 violation can be safely suppressed. 118 119#### Rule 11.6 120_Ref 11.6.1_ 121 122- When sending and receiving a DHCP event to the IP-stack, the events are 123 converted to a void pointer and sent to the IP-task. The function used 124 to send the events handles various events for the IP-task and thus only 125 accepts void pointers. The IP-task converts the void pointer back to 126 the original event. Thus, this rule can be safely suppressed. 127 128_Ref 11.6.2_ 129 130- MISRA Rule 11.6 `uintptr_t` is guaranteed by the implementation to fit a 131 pointer size of the platform. The pointer has to be moved backward by a 132 constant offset to get to a 'hidden' pointer which is not available for 133 the user to use. This conversion is done to achieve that while avoiding 134 pointer arithmetic. 135 136#### Rule 11.8 137_Ref 11.8.1_ 138 139- MISRA c-2012 Rule 11.8 warns about removing the `const` qualifier when 140 assigning one value to another. In this case however, a function 141 pointer is being copied. It doesn't make sense in case of function 142 pointers for the pointee to be const or mutable. Thus, this rule is 143 safe to suppress. 1441 145#### Rule 14.3 146_Ref 14.3.1_ 147 148- MISRA C-2012 Rule 14.3 False positive as the value might be changed 149 depending on the conditionally compiled code 150 151#### Rule 17.2 152_Ref 17.2.1_ 153 154- MISRA C-2012 Rule 17.2 warns about using recursion in software as that can have 155 severe implications on the stack usage and can lead to a serious issue. 156 In this case however, the number of recursions are limited by design. 157 Any socket spawned (child) by a socket in listening state (parent) 158 cannot be in listening state. Thus it is not possible for the child to 159 have a secondary child socket thereby limiting the number of recursive 160 calls to one. 161 162#### Rule 20.5 163_Ref 20.5.1_ 164 165- MISRA C-2012 Rule 20.5 warns against the use of #undef. 166 FreeRTOS-Plus-TCP allows its users to set some configuration macros 167 to modify the behavior/performance of the library according to their 168 needs. However, the macros values must be within certain bounds. 169 To achieve that, if the macro values lie outside of the bounds, they 170 are undefined using `#undef` before being redefined to a proper 171 value. 172 173#### Rule 20.10 174_Ref 20.10.1_ 175 176- MISRA C-2012 Rule 20.10 warns against the use of ## concatination operator. 177 However, in this case, it must be used to support compile time 178 assertions in case the preprocessor does not suppport sizeof. This 179 operation (assert) has no runtime execution. 180 181#### Rule 21.6 182_Ref 21.6.1_ 183 184- MISRA C-2012 Rule 21.6 warns about the use of standard library input/output 185 functions as they might have implementation defined or undefined 186 behaviour. The function `snprintf` is used to insert information in a 187 logging string. This is only used in a utility function which aids in 188 debugging and is not part of the 'core' code governing the 189 functionality of the TCP/IP stack. 190 191
