Improve documentation of Stack Checking

doc/source/firmware/index.rst

@@ -11,6 +11,6 @@ mechanisms and the behavior. For a detailed code documentation see the doxygen o
 	:maxdepth: 2
 	
 	pt1000-processing
-	safety
+	safety/index
 	code/index
 

doc/source/firmware/safety/flags.rst

@@ -8,6 +8,10 @@ The safety flags are represented in software by the following enums
 .. doxygenenum:: safety_flag
 
 The safety flags can be temporarily or permanent. Some temporary flags are reset automatically, once the error condition disappears. Others have to be explicitly cleared. 
+The safety weights (if a flag stops the PID controller, or triggers the panic mode) are configured by default as described below. However, it will be possible to override these weights by
+setting config entries in the safety memory.
+
+.. todo:: Change docu of config entires in memory
 
 ----------------------------------------------------------------------------------------------------------------------------------
 
@@ -90,4 +94,21 @@ safety backup memory is cleared
 persistent self-clearing Stops PID     Panic Mode
 ========== ============= ============= ===========
 yes        no            yes           no
-========== ============= ============= ===========
+========== ============= ============= ===========
+
+
+.. _safety_flags_stack:
+
+ERR_FLAG_STACK
+---------------------------
+
+``ERR_FLAG_STACK`` ialization of the controller, in case a corrupted safety memory is encountered.
+This error is not recoverable and will trigger the panic mode.
+
+.. seealso:: :ref:`safety_stack_checking`
+
+========== ============= ============= ===========
+persistent self-clearing Stops PID     Panic Mode
+========== ============= ============= ===========
+yes        no            yes           yes
+========== ============= ============= ===========

doc/source/firmware/safety/index.rst

@@ -21,3 +21,4 @@ which are used to retain boot information across resets, for example to communic
 	flags
 	backup-ram
 	error-handling
+	stack-checking

doc/source/firmware/safety/stack-checking.rst

@@ -0,0 +1,39 @@
+.. _safety_stack_checking:
+
+Safety Stack Checking
+=====================
+
+To ensure correct operation of the controller, the stack is continuously monitored. For this, the :ref:`firmware_safety` checks the stack in each run.
+These checks include:
+
+1. Checking of used stack space and limit to end of stack
+2. Checking a protection area between heap and stack for memory corruption
+
+Any detected error will set the :ref:`safety_flags_stack` error flag.
+
+Stack Pointer Checking
+----------------------
+
+The stack pointer is checked using :c:func:`stack_check_get_free`. The returned value for the remaining stack space is checked against
+
+.. doxygendefine:: SAFETY_MIN_STACK_FREE
+
+.. doxygenfunction:: stack_check_get_free 
+
+
+Stack and Heap Corruption Checking
+----------------------------------
+
+A section of memory is located between the stack and the heap. It is defined inside the linker script. It's size is configured by the linker script parameter ``__stack_corruption_area_size``, which is set to ``128`` by default.
+This section is filled at the initializazion of the safety controller by a call to
+
+.. doxygenfunction:: stack_check_init_corruption_detect_area
+
+On each run of the safety controller's handling function (:c:func:`safety_controller_handle`) the following function is called:
+
+.. doxygenfunction:: stack_check_corruption_detect_area
+
+
+This function constantly checks the memory area for write modifications, and therefore detects, if the stack or heap have grown outside their boundaries.
+
+