Issue #18: Write doxygen headers for safety memory

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

@@ -23,6 +23,10 @@
 
 #include <stdint.h>
 
+/** @addtogroup safety-memory
+ * @{
+ */
+
 /**
  * @brief Magic number to signal a valid safety memory header.
  */
@@ -81,34 +85,60 @@ struct safety_memory_boot_status {
 	uint32_t reset_from_panic;
 };
 
+/**
+ * @brief The state of the safety memory
+ *
+ * This is returned by certain functions in order to signal, if the header and CRC infos are valid.
+ */
 enum safety_memory_state {
-	SAFETY_MEMORY_INIT_FRESH = 0,
-	SAFETY_MEMORY_INIT_CORRUPTED = 1,
-	SAFETY_MEMORY_INIT_VALID_MEMORY = 2,
+	SAFETY_MEMORY_INIT_FRESH = 0,		/**< @brief Memory header not found */
+	SAFETY_MEMORY_INIT_CORRUPTED = 1,	/**< @brief Header found, but corrupt memory */
+	SAFETY_MEMORY_INIT_VALID_MEMORY = 2,	/**< @brief Valid header found and CRC check is valid */
 };
 
+/**
+ * @brief Types of error memory entries
+ */
 enum safety_memory_error_entry_type {
-	SAFETY_MEMORY_ERR_ENTRY_FLAG = 1,
-	SAFETY_MEMORY_ERR_ENTRY_NOP = 2,
+	SAFETY_MEMORY_ERR_ENTRY_FLAG = 1,	/**< @brief Flag error entry. Logs a flag */
+	SAFETY_MEMORY_ERR_ENTRY_NOP = 2,	/**< @brief NOP entry. Has no meaning, but will be treated as a valid entry */
 };
 
+/**
+ * @brief Firmware internal representation of an error memory entry.
+ */
 struct error_memory_entry {
 	enum safety_memory_error_entry_type type;
 	uint8_t flag_num;
 	uint16_t counter;
 };
 
+/**
+ * @brief Types of conig override entries
+ */
 enum config_override_entry_type {
 	SAFETY_MEMORY_CONFIG_OVERRIDE_WEIGHT = 1,
 	SAFETY_MEMORY_CONFIG_OVERRIDE_PERSISTANCE = 2,
 };
 
+/**
+ * @brief Weights of error flags.
+ */
+enum config_override_weight {
+	SAFETY_MEMORY_CONFIG_WEIGTH_NONE = 0, /**< @brief This flag has no global error consequence, but might be respected by certain software modules. */
+	SAFETY_MEMORY_CONFIG_WEIGTH_PID = 1, /**< @brief This flag will force a stop of the temperature PID controller */
+	SAFETY_MEMORY_CONFIG_WEIGTH_PANIC = 2, /**< @brief This flag will trigger the panic mode */
+};
+
+/**
+ * @brief representation of a config override memory entry
+ */
 struct config_override {
 	enum config_override_entry_type type;
 	union {
 		struct {
 			uint8_t flag;
-			uint8_t weight;
+			enum config_override_weight weight;
 		} weight_override;
 		struct {
 			uint8_t flag;
@@ -117,26 +147,104 @@ struct config_override {
 	} entry;
 };
 
+/**
+ * @brief First time init the safety memory. This requests all clocks etc.
+ *
+ * The error memory is always vlaid after this function. At least, if it returns without error.
+ * The \p found_state output tells the caller, in which state the memory was found. If it was uninitialized,
+ * or corrupted, it is completely wiped and a fresh memory structure is written.
+ *
+ * @param[out] found_state State the error memory was found in
+ * @return 0 if successful
+ * @warning Also check @ref safety_memory_reinit
+ */
 int safety_memory_init(enum safety_memory_state *found_state);
 
+/**
+ * @brief Same as @ref safety_memory_init, but without specifically requesting the clock modules.
+ *
+ * Use this, if a call to @ref safety_memory_init has already been done.
+ *
+ * @param[out] found_state State the error memory was found in
+ * @return 0 if successful
+ */
 int safety_memory_reinit(enum safety_memory_state *found_state);
 
+/**
+ * @brief Get the boot status structure from safety memory
+ * @param[out] status Status read from memory.
+ * @return 0 if successful
+ */
 int safety_memory_get_boot_status(struct safety_memory_boot_status *status);
 
+/**
+ * @brief Write the boot status structure to safety memory
+ * @param[in] status Status to write
+ * @return 0 if successful
+ */
 int safety_memory_set_boot_status(const struct safety_memory_boot_status *status);
 
+/**
+ * @brief Get the amout of error entries in the error memory. This also includes NOP entries.
+ * @param[out] count Count
+ * @return 0 if successful
+ */
 int safety_memory_get_error_entry_count(uint32_t *count);
 
+/**
+ * @brief Check the header and CRC of the safety memory.
+ * @return 0 if all checks pass
+ */
 int safety_memory_check(void);
 
+/**
+ * @brief Read an error entry from the error memory
+ * @param idx Index of the entry
+ * @param[out] entry Error entry
+ * @return 0 if successful
+ */
 int safety_memory_get_error_entry(uint32_t idx, struct error_memory_entry *entry);
 
+/**
+ * @brief Insert an error entry
+ *
+ * This function inserts an error entry on the first NOP entry found in the error memory.
+ * If an entry is found with the same flag number, its counter is incremented by the counter value of the
+ * element to insert.
+ *
+ * If there are no NOPs or fitting entries in the error memory, error memory is expanded until it hits the memory
+ * boundary.
+ *
+ * @param entry Error entry to insert
+ * @returns 0 if successful, -3 if out of memory, and other negative error codes
+ */
 int safety_memory_insert_error_entry(struct error_memory_entry *entry);
 
+/**
+ * @brief Insert a config override entry at the first free location.
+ *
+ * Free locations are entries containing 0x00000000
+ *
+ * @param config_override Config to write
+ * @return 0 if successful
+ */
 int safety_memory_insert_config_override(struct config_override *config_override);
 
+/**
+ * @brief Get count of config overrides
+ * @param[out] count Number of overrides
+ * @return 0 if successful
+ */
 int safety_memory_get_config_override_count(uint32_t *count);
 
+/**
+ * @brief Get a config ovveide entry
+ * @param idx Index of the requested entry
+ * @param[out] config_override READ override
+ * @return 0 if successful
+ */
 int safety_memory_get_config_override(uint32_t idx, struct config_override *config_override);
 
 #endif /* __SAFETY_MEMORY_H__ */
+
+/** @} */