[#493] First draft of documentation for parsing exceptions

Author: mikir

compiler/extensions/cpp/README.md

@@ -15,3 +15,59 @@ compatibility version and fires an error when it detects any problem.
 
 > Note: Binary encoding of packed arrays has been changed in version `2.5.0` and thus versions `2.4.x` are
 binary incompatible with later versions.
+
+## Functional Safety Features
+
+### C++ runtime library
+
+The following describes features which minimize the risk of Zserio C++ runtime library malfunctioning behavior:
+
+- Supported compilers (minimum versions): gcc 5.4.0, clang 8, MinGW 5.4.0, MSVC 2017
+- Warnings are treaded as errors for all supported compilers
+- All features are properly tested by unit tests for all supported compilers (>600 tests)
+- Implemented automatic check of test coverage threshold for [clang](https://zserio.org/doc/runtime/cpp/coverage/clang/index.html) builds (>98%)
+- AddressSanitizer is run with no findings
+- UndefinedBehaviourSanitizer is run with no findings
+- C++ runtime library sources are checked by static analysis tool clang-tidy version 14 using [this configuration](https://github.com/ndsev/zserio/blob/master/compiler/extensions/cpp/runtime/ClangTidyConfig.txt) with [this report](https://zserio.org/doc/runtime/cpp/clang-tidy/clang-tidy-report.txt)
+
+### C++ Generated Code
+
+The following describes features which minimize the risk of Zserio C++ generated code malfunctioning behavior:
+
+- Supported compilers (minimum versions): gcc 5.4.0, clang 8, MinGW 5.4.0, MSVC 2017
+- Warnings are treaded as errors for all supported compilers
+- All features are properly tested by unit tests for all supported compilers (>1700 tests)
+- Generated C++ sources are checked by static analysis tool clang-tidy version 14 using [this configuration](https://github.com/ndsev/zserio/blob/master/compiler/extensions/cpp/runtime/ClangTidyConfig.txt)
+
+### Exceptions
+
+Zserio C++ runtime library together with the C++ generated code can throw a `zserio::CppRuntimeException` in
+some rare circumstances, mainly
+
+- during parsing (reading)
+- during writing
+- in reflection code
+- in type info code
+
+Because there are hundreds possibilities when exception `zserio::CppRuntimeException` can be thrown, the
+following section contains only description of exceptions during parsing.
+
+#### Exceptions During Parsing
+
+The following table describes all possibilities when C++ generated code can throw
+a `zserio::CppRuntimeException` during parsing of binary data:
+
+| Module | Method | Exception Message | Description |
+| ------ | ------ | ----------------- | ----------- |
+| `BitStreamReader.cpp` | constructor | "BitStreamReader: Buffer size exceeded limit '[MAX_BUFFER_SIZE]' bytes!" | Throws if provided buffer is bigger that 536870908 bytes (cca 511MB) on 32-bit OS or 2**64/8-4 bytes on 64-bit OS. |
+| `BitStreamReader.cpp` | constructor | "BitStreamReader: Wrong buffer bit size ('[BUFFER_SIZE]' < '[SPECIFIED_BYTE_SIZE]')!" | Throws if provided buffer is smaller than specified bit size. This could happen only in case of wrong arguments. |
+| `BitStreamReader.cpp` | `throwNumBitsIsNotValid()` | "BitStreamReader: ReadBits #[NUM_BITS] is not valid, reading from stream failed!" | Throws if `readBits()`, `readSignedBits()`, `readBits64()` or `readSignedBits64()` has been called with wrong (too big) `numBits` argument. This could happen only in case of data inconsistency, e.g. if dynamic bit field has length bigger than 32 or 64 bits respectively. |
+| `BitStreamReader.cpp` | `throwEof()` | "BitStreamReader: Reached eof(), reading from stream failed!" | Throws if end of underlying buffer has been reached (reading beyond stream). This could happen only in case of data inconsistency, e.g. if array length is defined bigger than is actually stored in the stream). |
+| `BitStreamReader.cpp` | `readVarSize()` | "BitStreamReader: Read value '[VARSIZE_VALUE]' is out of range for varsize type!" | Throws if `varsize` value stored in stream is bigger than 2147483647. This could happen only in case of data inconsistency when `varsize` value stored in the stream is wrong. |
+| `OptionalHolder.h` | `throwNonPresentException()` | "Trying to access value of non-present optional field!" | Throws if optional value is not present during access. This could happen only in case of data inconsistency when optional field is not present in the stream and there is a reference to it in some expression. |
+| Generated Sources | Object read constructor | "Read: Wrong offset for field [COMPOUND_NAME].[FIELD_NAME]: [STREAM_BYTE_POSITION] != [OFFSET_VALUE]!" | Throws in case of wrong offset. This could happen only in case of data inconsistency when offset value stored in the stream is wrong. |
+| Generated Sources | Object read constructor | "Read: Constraint violated at [COMPOUND_NAME].[FIELD_NAME]!" | Throws in case of wrong constraint. This could happen only in case of data inconsistency when some constraint is violated. |
+| Generated Sources | Object read constructor | "No match in choice [NAME]!" | Throws in case of wrong choice selector. This could happen only in case of data inconsistency when choice selector stored in the stream is wrong. |
+| Generated Sources | Object read constructor | "No match in union [NAME]!" | Throws in case of wrong union tag. This could happen only in case of data inconsistency when union tag stored in the stream is wrong. |
+| Generated Sources | Bitmask constructor | "Value for bitmask [NAME] out of bounds: [VALUE]!" | Throws if value stored in stream is bigger than bitmask upper bound. This could happen only in case of data inconsistency when bitmask value stored in the stream is wrong. |
+| Generated Sources | `valueToEnum` | "Unknown value for enumeration [NAME]: [VALUE]!" | Throws in case of unknown enumeration value. This could happen only in case of data inconsistency when enumeration value stored in the stream is wrong. |