Issue #18: Firther improve documentation

doc/source/firmware/backup-ram.rst

@@ -16,15 +16,18 @@ The backup RAM contents are protected by a `CRC Checksum`_.
 
 The backup RAM is initialized and checked after boot. If the controller starts from a powered down state,
 the backup RAM is empty. This is detected by an invalid `Header`_ at the beginning of the backup RAM. If this is the case, the safety ocntoller
-will create a valid backup RAM image with a `Header`_, empty `Status Flag Entries`_, an empty `Error Memory`_, and a valid `CRC Checksum`_.
+will create a valid backup RAM image with a `Header`_, empty `Status Flag Entries`_, empty `Config Overrides`_, an empty `Error Memory`_, and a valid `CRC Checksum`_.
 
-If the Header is valid during boot (verified by plausible values and correct magic numbers), the backup RAM is CRC checked.
+If the Header is valid during boot (verified by plausible values and correct magic numbers), the backup RAM is CRC checked and the error memory is
-In case of a CRC error, the Backup RAM is wiped and reinitialized. On top of that, the error flag :ref:`safety_flags_safety_mem_corrupt` is set.
+checked for valid entries.
+In case of a CRC error or invalid entries in the error memory, the Backup RAM is wiped and reinitialized. On top of that, the error flag :ref:`safety_flags_safety_mem_corrupt` is set.
 
 .. note:: It may be possible that future versions of the hardware include a backup RAM battery / Goldcap. In this case, a way to clear the error memory will be implemented,
     because it will no longer be possible to clear the error memory by cutting the power.
     On top of that, the backup memory will also contain the calibration data.
 
+..note:: The firmware will not use the ``NOP`` entries of the error memory by default, but they will be respected by the validity checker.
+
 Partitioning and Entries
 ------------------------
 
@@ -52,9 +55,46 @@ The safety memory header magic is:
 Status Flag Entries
 ~~~~~~~~~~~~~~~~~~~
 
+Config Overrides
+~~~~~~~~~~~~~~~~
+
+Config overrides are used to override persistance and flag weights dynamically. The safety controlelr will parse the entries on 
+startup.
+
+======================= ============ ================= ===================== =====================================
+Entry                   Byte 1 (LSB) Byte 2            Byte 3                Byte 4 (MSB)
+======================= ============ ================= ===================== =====================================
+Weight override         ``0xA2``      ``Weight``       ``Flag Number`` (LSB) ``Flag number`` (MSB) (always ``0``)
+Persistance override    ``0x8E``      ``Persistance``  ``Flag Number`` (LSB) ``Flag number`` (MSB) (always ``0``) 
+======================= ============ ================= ===================== =====================================
+
+
 Error Memory
 ~~~~~~~~~~~~
 
+The error memory contains error entries in form of 32 bit words. The entries are coded as stated below.
+
+``Error Flag`` entries are used to restore error flags after boot. In theory, all flags can be set using this entry type,
+however, only persistent flags are stored in the error memory by the firmware.
+
+``NOP`` entries have no meaning. They are used as a filler. When adding a new error memory entry, the error memory is scanned until the first ``NOP`` entry is found.
+It is replaced with a valid entry. If the error memory contains a word, that is not defined below, it is considered invalid and will trigger the RAM checker on boot.
+``NOP`` entries can be used to preallocate the error memory in advance.
+
+
+======================= ============ ================= ===================== =====================================
+Entry                   Byte 1 (LSB) Byte 2            Byte 3                Byte 4 (MSB)
+======================= ============ ================= ===================== =====================================
+Error Flag              ``0x51``     ``0x00``          ``Flag Number`` (LSB) ``Flag number`` (MSB) (always ``0``)
+NOP Entry               ``0x22``     ``0x12``          ``0xAA``              ``0xC1``
+======================= ============ ================= ===================== =====================================
 
 CRC Checksum
-~~~~~~~~~~~~
+~~~~~~~~~~~~
+
+The CRC checksum is located after the error memory. The checksum is calculated by the internal peripheral module of the STM32F4 controller.
+Therefore, the CRC calculation is fixed.
+
+The polynomial is ``0x4C11DB7`` (Ethernet CRC32):
+
+.. math:: P_{CRC}(x) = x^{32}+x^{26}+x^{23}+x^{22}+x^{16}+x^{12}+x^{11}+x^{10}+x^{8}+x^{7}+x^{5}+x^{4}+x^{2}+x+1

stm-firmware/include/reflow-controller/safety/safety-memory.h

@@ -40,6 +40,8 @@
 struct safety_memory_header {
 	uint32_t magic;			/**< @brief Magic. Set to @ref SAFETY_MEMORY_MAGIC */
 	uint32_t boot_status_offset;	/**< @brief Offset of the safety_memory_boot_status struct (in 32 bit words)*/
+	uint32_t config_overrides_offset; /**< @brief Offset address of override entries */
+	uint32_t config_overrides_len;	/**< @brief Length of override entries in words */
 	uint32_t err_memory_offset;	/**< @brief Offset of the error memory */
 	uint32_t err_memory_end;	/**< @brief End of the error memory. This points to the word after the error memory, containing the CRC of the whole backup RAM. */
 	uint32_t magic_i;		/**< @brief Invers Magic. Set to the bitwise inverse of @ref SAFETY_MEMORY_MAGIC */