Start documentation for safety RAM. Will be implemented afterwards

doc/source/firmware/backup-ram.rst

@@ -0,0 +1,60 @@
+.. _backup_ram:
+
+Safety Backup RAM
+=================
+
+Overview
+--------
+
+The STM controller's backup RAM is used to store different kinds of information that shall be preserved if the controller resets.
+The hardware setup is missing a separate powersupply for the controller's backup domain. Therefore, the backup RAM is cleared, when the power is cut.
+
+The backup RAM is used to store permanent error flags (See :ref:`safety_flags`). This ensures the flags stay present, even if a system reset is performed. The only way to clear them is by cutting the power.
+Because cutting the power is a way to clear the backup RAM, no separate method for clearing the error entries in the backup RAM is defined.
+
+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`_.
+
+If the Header is valid during boot (verified by plausible values and correct magic numbers), the backup RAM is CRC checked.
+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.
+
+.. 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.
+
+Partitioning and Entries
+------------------------
+
+The backup RAM consists of multiple sections. The memory section are listed below. 
+
+Header
+~~~~~~
+
+The backup memory header is located at offset address:
+
+.. doxygendefine:: SAFETY_MEMORY_HEADER_ADDRESS
+
+The header is defined by the following structure:
+
+.. doxygenstruct:: safety_memory_header
+
+The validity of the header is checked, if the magic and inverse amgic fields contain the correct values, and if the offset address pointers
+have values that are located inside the error memory and are not ``0`` or the same value.
+
+The safety memory header magic is:
+
+.. doxygendefine:: SAFETY_MEMORY_MAGIC
+
+
+Status Flag Entries
+~~~~~~~~~~~~~~~~~~~
+
+Error Memory
+~~~~~~~~~~~~
+
+
+CRC Checksum
+~~~~~~~~~~~~

doc/source/firmware/error-handling.rst

@@ -6,4 +6,15 @@ Error Handling
 .. _safety_panic:
 
 Panic Mode
-----------
+----------
+
+
+.. _safety_error_mem:
+
+Error memory
+------------
+
+Permanent errors are stored in the backup RAM of the STM. This ensures, that errors can be read even after a full system reset has occured.
+
+.. seealso:: :ref:`backup_ram`
+

doc/source/firmware/flags.rst

@@ -72,4 +72,22 @@ ERR_FLAG_MEAS_ADC_UNSTABLE
 persistent self-clearing Stops PID     Panic Mode
 ========== ============= ============= ===========
 no         yes           no            no
+========== ============= ============= ===========
+
+
+.. _safety_flags_safety_mem_corrupt:
+
+ERR_FLAG_SAFETY_MEM_CORRUPT
+---------------------------
+
+``ERR_FLAG_SAFETY_MEM_CORRUPT`` is set during the initialization of the controller, in case a corrupted safety memory is encountered.
+In this case the error memory is reinitialized and the flag is set in the error memory. Afer a reboot it will stay asserted until the 
+safety backup memory is cleared
+
+.. seealso:: :ref:`backup_ram`
+
+========== ============= ============= ===========
+persistent self-clearing Stops PID     Panic Mode
+========== ============= ============= ===========
+yes        no            yes           no
 ========== ============= ============= ===========

doc/source/firmware/safety.rst

@@ -16,4 +16,5 @@ which forces the output zero, but does not allow any more interaction.
 	:maxdepth: 2
 	
 	flags
+	backup-ram
 	error-handling