diff --git a/stm-firmware/include/reflow-controller/safety/safety-memory.h b/stm-firmware/include/reflow-controller/safety/safety-memory.h index 18946ac..fe214cb 100644 --- a/stm-firmware/include/reflow-controller/safety/safety-memory.h +++ b/stm-firmware/include/reflow-controller/safety/safety-memory.h @@ -23,6 +23,10 @@ #include +/** @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__ */ + +/** @} */