Expand documentation

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

@@ -67,7 +67,7 @@ int safety_adc_poll_result(void);
  * After that, it is safe to use the output values until a new conversion is triggered using #safety_adc_trigger_meas
  *
  * @warning This function return a constant buffer, that is directly written on by the DMA! Check #safety_adc_poll_result to prevent race conditions.
- * @return Array of raw ADC readings with lenght of #SAFETY_ADC_NUM_OF_CHANNELS
+ * @return Array of raw ADC readings with length of #SAFETY_ADC_NUM_OF_CHANNELS
  */
 const uint16_t *safety_adc_get_values(void);
 

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

@@ -144,6 +144,9 @@ enum analog_value_monitor {
  */
 #define SAFETY_CONTROLLER_ADC_DELAY_MS 250
 
+/**
+ * @brief Default persistence of safety flags. These values are loaded into the safety tables on startup
+ */
 #define SAFETY_CONFIG_DEFAULT_PERSIST	ERR_FLAG_PERSIST_ENTRY(ERR_FLAG_MEAS_ADC_OFF, false), \
 					ERR_FLAG_PERSIST_ENTRY(ERR_FLAG_MEAS_ADC_WATCHDOG, false), \
 					ERR_FLAG_PERSIST_ENTRY(ERR_FLAG_MEAS_ADC_UNSTABLE, false), \
@@ -163,7 +166,9 @@ enum analog_value_monitor {
 					ERR_FLAG_PERSIST_ENTRY(ERR_FLAG_SAFETY_TAB_CORRUPT, true), \
 					ERR_FLAG_PERSIST_ENTRY(ERR_FLAG_AMON_SUPPLY_VOLT, false), \
 					ERR_FLAG_PERSIST_ENTRY(ERR_FLAG_OVERTEMP, false), \
-
+/**
+ * @brief Default config weights of safety flags. These values are loaded into the safety tables on startup
+ */
 #define SAFETY_CONFIG_DEFAULT_WEIGHTS 	ERR_FLAG_WEIGHT_ENTRY(ERR_FLAG_MEAS_ADC_OFF, SAFETY_FLAG_CONFIG_WEIGHT_PID), \
 			ERR_FLAG_WEIGHT_ENTRY(ERR_FLAG_MEAS_ADC_WATCHDOG, SAFETY_FLAG_CONFIG_WEIGHT_PID), \
 			ERR_FLAG_WEIGHT_ENTRY(ERR_FLAG_MEAS_ADC_UNSTABLE, SAFETY_FLAG_CONFIG_WEIGHT_NONE), \
@@ -175,8 +180,6 @@ enum analog_value_monitor {
 			ERR_FLAG_WEIGHT_ENTRY(ERR_FLAG_STACK, SAFETY_FLAG_CONFIG_WEIGHT_PANIC), \
 			ERR_FLAG_WEIGHT_ENTRY(ERR_FLAG_SAFETY_ADC, SAFETY_FLAG_CONFIG_WEIGHT_PANIC), \
 			ERR_FLAG_WEIGHT_ENTRY(ERR_FLAG_SYSTICK, SAFETY_FLAG_CONFIG_WEIGHT_PANIC), \
-			/* Watchdog timeout is not handled periodically, but only on startup.
-			 * Therefore, it is not listed here */\
 			ERR_FLAG_WEIGHT_ENTRY(ERR_FLAG_WTCHDG_FIRED, SAFETY_FLAG_CONFIG_WEIGHT_PID), \
 			ERR_FLAG_WEIGHT_ENTRY(ERR_FLAG_UNCAL, SAFETY_FLAG_CONFIG_WEIGHT_NONE), \
 			ERR_FLAG_WEIGHT_ENTRY(ERR_FLAG_DEBUG, SAFETY_FLAG_CONFIG_WEIGHT_NONE), \

stm-firmware/include/reflow-controller/systick.h

@@ -69,10 +69,28 @@ void systick_setup(void);
  */
 void systick_wait_ms(uint32_t ms);
 
+/**
+ * @brief Get the gloabl millisecond tick. This can be used to implement all sorts of time based procedures / waits.
+ * @warning Use this with care in interrupts. It may lead to race conditions. It is generally safe for use in standard program flow though.
+ * @return  Global millisecond tick.
+ */
 uint64_t systick_get_global_tick();
 
+/**
+ * @brief Calculate the uptime from the current millisecond tick.
+ * @param[out] days Days. May be NULL.
+ * @param[out] hours Hours. May be NULL.
+ * @param[out] minutes Minutes. May be NULL.
+ * @param[out] seconds Seconds. May be NULL.
+ */
 void systick_get_uptime_from_tick(uint32_t *days, uint32_t *hours, uint32_t *minutes, uint32_t *seconds);
 
+/**
+ * @brief Check if \p ticks (milliseconds) have passed since \p start_timestamp
+ * @param start_timestamp Start timestamp
+ * @param ticks tick count
+ * @return true: Time has passed
+ */
 bool systick_ticks_have_passed(uint64_t start_timestamp, uint64_t ticks);
 
 #endif /* __SYSTICK_H__ */

stm-firmware/systick.c

@@ -106,7 +106,8 @@ bool __attribute__((optimize("O3"))) systick_ticks_have_passed(uint64_t start_ti
 /**
  * @brief Interrupt Handler for SysTick
  *
- * This handler is called every millisecond
+ * This handler is called every 100 us.
+ * It is important to keep this function simple as it is called that often and may prevent program flow.
  *
  * @warning For calling cyclic functions use separate timers/flags and don't spoil this function
  */