From b869ed9c45c0220dbd091e95c79ee494beab87c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20H=C3=BCttel?= Date: Tue, 22 Sep 2020 23:45:22 +0200 Subject: [PATCH] Improve comments and doxygen headers --- .../safety/safety-controller.h | 183 ++++++++++++++++-- .../reflow-controller/safety/stack-check.h | 8 + stm-firmware/safety/fault.c | 1 - 3 files changed, 171 insertions(+), 21 deletions(-) diff --git a/stm-firmware/include/reflow-controller/safety/safety-controller.h b/stm-firmware/include/reflow-controller/safety/safety-controller.h index 65e7e96..db2b721 100644 --- a/stm-firmware/include/reflow-controller/safety/safety-controller.h +++ b/stm-firmware/include/reflow-controller/safety/safety-controller.h @@ -23,7 +23,6 @@ * @{ */ - #ifndef __SAFETY_CONTROLLER_H__ #define __SAFETY_CONTROLLER_H__ @@ -32,30 +31,39 @@ #include #include -enum analog_monitor_status {ANALOG_MONITOR_OK = 0, - ANALOG_MONITOR_ERROR, - ANALOG_MONITOR_INACTIVE, - ANALOG_MONITOR_OVER, - ANALOG_MONITOR_UNDER}; +/** + * @brief State of an analog monitor + */ +enum analog_monitor_status {ANALOG_MONITOR_OK = 0, /**< @brief Monitor set up and ok */ + ANALOG_MONITOR_ERROR, /**< @brief An internal error occured */ + ANALOG_MONITOR_INACTIVE, /**< @brief Monitor inactive. Reading is not valid */ + ANALOG_MONITOR_OVER, /**< @brief Value too high */ + ANALOG_MONITOR_UNDER}; /**< @brief Value too low */ +/** + * @brief Info structure describing an analog monitor + */ struct analog_monitor_info { - float value; - float min; - float max; - enum analog_monitor_status status; - uint64_t timestamp; -}; - -struct timing_monitor_info { - uint64_t last_run; - uint64_t min; - uint64_t max; - bool enabled; - uint64_t delta; + float value; /**< @brief Current analog value */ + float min; /**< @brief Minumum value allowed */ + float max; /**< @brief Maximum value allowed */ + enum analog_monitor_status status; /**< @brief Current monitor status */ + uint64_t timestamp; /**< @brief ms timestamp when @ref analog_monitor_info::value was taken. */ }; /** - * @brief Initialize the safety controller + * @brief Info structure describing a timing monitor + */ +struct timing_monitor_info { + uint64_t last_run; /**< @brief Timestamp, when the monitor was last triggered */ + uint64_t min; /**< @brief Minimum delay between two activations in ms */ + uint64_t max; /**< @brief Maximum delay between two activations in ms */ + bool enabled; /**< @brief Monitor enabled */ + uint64_t delta; /**< @brief Last delta between two activations */ +}; + +/** + * @brief Initialize the safety controller. * * After a call to this function the controller is iniotlaized and the watchdog is set up. * You have to call safety_controller_handle @@ -70,42 +78,177 @@ void safety_controller_init(); */ int safety_controller_handle(); +/** + * @brief Report one or multiple errors to the safety controller + * + * When passing multipe error glags, the flags have to be ORed together. + * + * @param flag Error flag to report + * @return 0 if successful. + */ int safety_controller_report_error(enum safety_flag flag); +/** + * @brief Report one or multiple error flags with a key. + * + * When setting a \p key on an error flag. The error flag can only be cleared, + * by passing the same key value to the @ref safety_controller_ack_flag_with_key function. + * + * @param flag Error flag to report + * @param key Key + * @return 0 if successful + */ int safety_controller_report_error_with_key(enum safety_flag flag, uint32_t key); +/** + * @brief Report timing to a timing monitor. + * @param monitor Monitor to report + */ void safety_controller_report_timing(enum timing_monitor monitor); +/** + * @brief Report an analog value to an analog value monitor + * @param monitor Monitor to report + * @param value Analog value + */ void safety_controller_report_analog_value(enum analog_value_monitor monitor, float value); +/** + * @brief Enable or disable a timing monitor. + * @param monitor Monitor to enable + * @param enable State to set the monitor to. + * @return 0 if successful. + */ int safety_controller_enable_timing_mon(enum timing_monitor monitor, bool enable); +/** + * @brief Get the value of an analog monitor. + * @param monitor Monitor to get value from + * @param[out] value The analog value + * @returns Status of the analog monitor. \p value only valid, if return value does not indicate an internal error, + * or an inactive monitor. + */ enum analog_monitor_status safety_controller_get_analog_mon_value(enum analog_value_monitor monitor, float *value); +/** + * @brief Get error flag state and optionally acknowledge the flag + * + * If the flag is persistent, it cannot be ack'ed. In this case this function + * does not return an error code. + * + * @param flag Error flag + * @param[out] status state of the flag. + * @param try_ack Try to ack the flag. This might fail, if the flag is persistent. + * @return 0 if successful. + */ int safety_controller_get_flag(enum safety_flag flag, bool *status, bool try_ack); +/** + * @brief Ack an error flag + * @param flag Error flag to ack + * @return 0 if successful, -2 if flag is persistent or keyed. All other values: Errors + */ int safety_controller_ack_flag(enum safety_flag flag); +/** + * @brief Acknowledge error flag with a key + * @param flag Error flag + * @param key Key + * @return 0 if successful, -2 if flag is persistent or key wrong. All other values: Errors + */ int safety_controller_ack_flag_with_key(enum safety_flag flag, uint32_t key); +/** + * @brief Get an ored status of multiple flags. + * @param mask Flags to check + * @return True if errors. False if no errors. + */ bool safety_controller_get_flags_by_mask(enum safety_flag mask); +/** + * @brief Get the count of error flags + * @return Error flag count + */ uint32_t safety_controller_get_flag_count(); +/** + * @brief Get the count of analog monitors + * @return Analog monitor count + */ uint32_t safety_controller_get_analog_monitor_count(); +/** + * @brief Get an error flag's name by its index. + * + * The name of the flag will be cropped, if the buffersize is too small. + * Paramter \p buffsize may not be zero. + * + * @param index 0 based index. + * @param[out] buffer Buffer to write the name to. + * @param buffsize Buffer size. This has to be big enough to hold the name and the \0-terminator + * @return 0 of successful + */ int safety_controller_get_flag_name_by_index(uint32_t index, char *buffer, size_t buffsize); +/** + * @brief Get the safety flag by its internal index. + * @param index 0 based index. + * @param[out] status Current flag state. May be NULL. + * @param[out] flag_enum Flag enum used in SW. May be NULL. + * @return 0 if successful; else: negative + */ int safety_controller_get_flag_by_index(uint32_t index, bool *status, enum safety_flag *flag_enum); +/** + * @brief Get an analog monitor info by the monitor's index + * @param index 0 based index + * @param[out] info Info structure. + * @return 0 if successful. + * -1001, if \p index out of range + * -1002, if \p info is NULL + */ int safety_controller_get_analog_mon_by_index(uint32_t index, struct analog_monitor_info *info); +/** + * @brief Get the name of an analog monitor by its index + * + * The buffer has to be large enough to hold the name plus a null terminator. + * If the buffer is not large enough, The name will be cropped. + * Parameter \p buffsize may not be zero. + * + * @param index 0 based index + * @param buffer Buffer to write name to + * @param buffsize Buffer size + * @return + */ int safety_controller_get_analog_mon_name_by_index(uint32_t index, char *buffer, size_t buffsize); +/** + * @brief Get timing monitor information by index + * @param index 0 based index + * @param[out] info Info + * @return 0 if successful + */ int safety_controller_get_timing_mon_by_index(uint32_t index, struct timing_monitor_info *info); +/** + * @brief Get the name of a timing monitor by its index + * + * The buffer has to be large enough to hold the name plus a null terminator. + * If the buffer is not large enough, The name will be cropped. + * Parameter \p buffsize may not be zero. + * + * @param index 0 based index + * @param buffer Buffer to write name to. + * @param buffsize Buffer size + * @return 0 if successful + */ int safety_controller_get_timing_mon_name_by_index(uint32_t index, char *buffer, size_t buffsize); +/** + * @brief Get the count of timing monitors + * @return Timing monitor count + */ uint32_t safety_controller_get_timing_monitor_count(); #endif /* __SAFETY_CONTROLLER_H__ */ diff --git a/stm-firmware/include/reflow-controller/safety/stack-check.h b/stm-firmware/include/reflow-controller/safety/stack-check.h index df88d90..24dfa61 100644 --- a/stm-firmware/include/reflow-controller/safety/stack-check.h +++ b/stm-firmware/include/reflow-controller/safety/stack-check.h @@ -37,6 +37,10 @@ int32_t stack_check_get_usage(); */ int32_t stack_check_get_free(); +/** + * @brief Check if the current free stack space is bigger than @ref STACK_CHECK_MIN_HEAP_GAP + * @return 0: enough space available, -1: stack space low + */ static inline int stack_check_collision() { int ret = 0; @@ -49,6 +53,10 @@ static inline int stack_check_collision() return ret; } +/** + * @brief Get the current stack pointer value + * @return + */ static inline uint32_t read_stack_pointer() { uint32_t stack_pointer; diff --git a/stm-firmware/safety/fault.c b/stm-firmware/safety/fault.c index d8f97a8..21a9a38 100644 --- a/stm-firmware/safety/fault.c +++ b/stm-firmware/safety/fault.c @@ -52,7 +52,6 @@ void panic_mode(void) oven_driver_set_power(0); oven_driver_apply_power_level(); - /* TODO: implement panic mode */ if (!safety_memory_get_boot_status(&boot_status)) { boot_status.reset_from_panic = 0xFFFFFFFF; (void)safety_memory_set_boot_status(&boot_status);