# MISRA Compliance

The coreMQTT library files conform to the [MISRA C:2012](https://www.misra.org.uk/misra-c)
guidelines, with the deviations listed below. Compliance is checked with Coverity static analysis.
Since the coreMQTT library is designed for small-embedded devices, it needs to have a very small memory footprint and has to
be efficient. To achieve that and to increase the performace of the library, it deviates from some MISRA rules.
The specific deviations, suppressed inline, are listed below.

Additionally, [MISRA configuration file](https://github.com/FreeRTOS/FreeRTOS-Plus-TCP/blob/main/test/Coverity/coverity_misra.config) contains the project wide deviations.

### Suppressed with Coverity Comments
To find the deviation references in the source files run grep on the source code
with ( Assuming rule 18.2 violation; with justification in point 1 ):
```
grep 'MISRA Ref 18.2.1' . -rI
```

#### Rule 2.2

_Ref 2.2.1_

- MISRA C-2012 Rule 2.2 states that there shall be no dead code. In
  `core_mqtt_serializer.h`, the `MQTT_PACKET_TYPE_*_VAL` static const variables
  back the `MQTT_PROP_VALIDATE_*` convenience macros. Each translation unit
  that includes the header gets its own copy of these variables, and a TU that
  does not use a particular `MQTT_PROP_VALIDATE_*` macro will leave the
  corresponding variable unreferenced — Coverity flags this as dead code.
  This is expected: the variables exist so that the address-of operator in the
  macros yields a valid `const uint8_t *`, and the alternative (compound
  literals) is not portable to C90. The cost is at most one byte of read-only
  data per unused variable per TU, which is negligible.

#### Rule 2.8

_Ref 2.8.1_

- MISRA C-2012 Rule 2.8 (Advisory) states that a project should not contain
  unused object definitions. The `MQTT_PACKET_TYPE_*_VAL` static const
  variables in `core_mqtt_serializer.h` are object definitions that may be
  unused in any given translation unit that does not reference the
  corresponding `MQTT_PROP_VALIDATE_*` macro. The deviation has the same
  rationale as Rule 2.2 above: the variables must exist at file scope so the
  macros can take their address, and the alternative is not portable to C90.

#### Rule 10.5

_Ref 10.5.1_

- MISRA C-2012 Rule 10.5 states that unsigned values should not be cast to enums. In
  this case we are casting the uint8_t to MQTTSuccessFailReasonCode_t with a switch
  case which protects against all uncovered enum cases.

#### Rule 10.8

_Ref 10.8.1_

- MISRA C-2012 Rule 10.8 states that value of composite expressions should not be cast
  to variables of different signedness. In this library, array of bytes are used to
  process data. Functions which fill the arrays with data update an index to an
  offset. To know the amount of data added to the array, the beginning address of the
  array has to be subtracted from the index. When the two pointers are subracted, it
  results in a signed value. It is verified however that the value will always be positive.
  And thus, can be casted and added to a size_t variable (which is unsigned).

#### Rule 18.2

_Ref 18.2.1_

- MISRA C-2012 Rule 18.2 states that two pointers may only be subtracted if they point
  to elements of the same array. In this library, array of bytes are used to process
  data. Functions which fill the arrays with data update an index to an offset.
  To know the amount of data added to the array, the beginning address of the array has
  to be subtracted from the index. It is manually verified that the index will always be
  within bounds of the array. However, Coverity is flagging this as a deviation. Thus, we
  are suppressing it.

#### Rule 14.3

_Ref 14.3.1_

- MISRA C-2012 Rule 14.3 prohibits use of invariants in conditional statements. Since
  coreMQTT is designed to be compiled and executed on different machines with different
  architectures, it is designed to protect against overflows when converting different
  types to one another. In doing so, we have macros which check for such conditions on
  different platforms. A side effect of this is that on some systems, those macros always
  evaluate to false - that is intentional.
