From cb3b42aece6cf679237934df0bb9c56ee8f8379a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20H=C3=BCttel?= Date: Fri, 4 Sep 2020 22:55:34 +0200 Subject: [PATCH] Start documentation for safety RAM. Will be implemented afterwards --- doc/source/firmware/backup-ram.rst | 60 +++++++++++++++++++ doc/source/firmware/error-handling.rst | 13 +++- doc/source/firmware/flags.rst | 18 ++++++ doc/source/firmware/safety.rst | 1 + .../reflow-controller/safety/backup-memory.h | 52 ++++++++++++++++ .../reflow-controller/safety/safety-memory.h | 50 ++++++++++++++++ stm-firmware/safety/safety-memory.c | 22 +++++++ 7 files changed, 215 insertions(+), 1 deletion(-) create mode 100644 doc/source/firmware/backup-ram.rst create mode 100644 stm-firmware/include/reflow-controller/safety/backup-memory.h create mode 100644 stm-firmware/include/reflow-controller/safety/safety-memory.h create mode 100644 stm-firmware/safety/safety-memory.c diff --git a/doc/source/firmware/backup-ram.rst b/doc/source/firmware/backup-ram.rst new file mode 100644 index 0000000..fc4e5d3 --- /dev/null +++ b/doc/source/firmware/backup-ram.rst @@ -0,0 +1,60 @@ +.. _backup_ram: + +Safety Backup RAM +================= + +Overview +-------- + +The STM controller's backup RAM is used to store different kinds of information that shall be preserved if the controller resets. +The hardware setup is missing a separate powersupply for the controller's backup domain. Therefore, the backup RAM is cleared, when the power is cut. + +The backup RAM is used to store permanent error flags (See :ref:`safety_flags`). This ensures the flags stay present, even if a system reset is performed. The only way to clear them is by cutting the power. +Because cutting the power is a way to clear the backup RAM, no separate method for clearing the error entries in the backup RAM is defined. + +The backup RAM contents are protected by a `CRC Checksum`_. + +The backup RAM is initialized and checked after boot. If the controller starts from a powered down state, +the backup RAM is empty. This is detected by an invalid `Header`_ at the beginning of the backup RAM. If this is the case, the safety ocntoller +will create a valid backup RAM image with a `Header`_, empty `Status Flag Entries`_, an empty `Error Memory`_, and a valid `CRC Checksum`_. + +If the Header is valid during boot (verified by plausible values and correct magic numbers), the backup RAM is CRC checked. +In case of a CRC error, the Backup RAM is wiped and reinitialized. On top of that, the error flag :ref:`safety_flags_safety_mem_corrupt` is set. + +.. note:: It may be possible that future versions of the hardware include a backup RAM battery / Goldcap. In this case, a way to clear the error memory will be implemented, + because it will no longer be possible to clear the error memory by cutting the power. + On top of that, the backup memory will also contain the calibration data. + +Partitioning and Entries +------------------------ + +The backup RAM consists of multiple sections. The memory section are listed below. + +Header +~~~~~~ + +The backup memory header is located at offset address: + +.. doxygendefine:: SAFETY_MEMORY_HEADER_ADDRESS + +The header is defined by the following structure: + +.. doxygenstruct:: safety_memory_header + +The validity of the header is checked, if the magic and inverse amgic fields contain the correct values, and if the offset address pointers +have values that are located inside the error memory and are not ``0`` or the same value. + +The safety memory header magic is: + +.. doxygendefine:: SAFETY_MEMORY_MAGIC + + +Status Flag Entries +~~~~~~~~~~~~~~~~~~~ + +Error Memory +~~~~~~~~~~~~ + + +CRC Checksum +~~~~~~~~~~~~ \ No newline at end of file diff --git a/doc/source/firmware/error-handling.rst b/doc/source/firmware/error-handling.rst index 16871ae..97f5ad9 100644 --- a/doc/source/firmware/error-handling.rst +++ b/doc/source/firmware/error-handling.rst @@ -6,4 +6,15 @@ Error Handling .. _safety_panic: Panic Mode ----------- \ No newline at end of file +---------- + + +.. _safety_error_mem: + +Error memory +------------ + +Permanent errors are stored in the backup RAM of the STM. This ensures, that errors can be read even after a full system reset has occured. + +.. seealso:: :ref:`backup_ram` + diff --git a/doc/source/firmware/flags.rst b/doc/source/firmware/flags.rst index aec37d1..7012abc 100644 --- a/doc/source/firmware/flags.rst +++ b/doc/source/firmware/flags.rst @@ -72,4 +72,22 @@ ERR_FLAG_MEAS_ADC_UNSTABLE persistent self-clearing Stops PID Panic Mode ========== ============= ============= =========== no yes no no +========== ============= ============= =========== + + +.. _safety_flags_safety_mem_corrupt: + +ERR_FLAG_SAFETY_MEM_CORRUPT +--------------------------- + +``ERR_FLAG_SAFETY_MEM_CORRUPT`` is set during the initialization of the controller, in case a corrupted safety memory is encountered. +In this case the error memory is reinitialized and the flag is set in the error memory. Afer a reboot it will stay asserted until the +safety backup memory is cleared + +.. seealso:: :ref:`backup_ram` + +========== ============= ============= =========== +persistent self-clearing Stops PID Panic Mode +========== ============= ============= =========== +yes no yes no ========== ============= ============= =========== \ No newline at end of file diff --git a/doc/source/firmware/safety.rst b/doc/source/firmware/safety.rst index 2c8aac9..e741b89 100644 --- a/doc/source/firmware/safety.rst +++ b/doc/source/firmware/safety.rst @@ -16,4 +16,5 @@ which forces the output zero, but does not allow any more interaction. :maxdepth: 2 flags + backup-ram error-handling diff --git a/stm-firmware/include/reflow-controller/safety/backup-memory.h b/stm-firmware/include/reflow-controller/safety/backup-memory.h new file mode 100644 index 0000000..737c890 --- /dev/null +++ b/stm-firmware/include/reflow-controller/safety/backup-memory.h @@ -0,0 +1,52 @@ +/* Reflow Oven Controller +* +* Copyright (C) 2020 Mario Hüttel +* +* This file is part of the Reflow Oven Controller Project. +* +* The reflow oven controller is free software: you can redistribute it and/or modify +* it under the terms of the GNU General Public License version 2 as +* published by the Free Software Foundation. +* +* The Reflow Oven Control Firmware is distributed in the hope that it will be useful, +* but WITHOUT ANY WARRANTY; without even the implied warranty of +* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +* GNU General Public License for more details. +* +* You should have received a copy of the GNU General Public License +* along with the reflow oven controller project. +* If not, see . +*/ + +#ifndef __SAFETY_MEMORY_H__ +#define __SAFETY_MEMORY_H__ + +/** + * @brief Magic number to signal a valid safety memory header. + */ +#define SAFETY_MEMORY_MAGIC 0x12AA5CB7 + +/** + * @brief Offset address for the safety_memory_header. + * @note Any other value than 0UL doesn't really make sense. Therfore, this should not be changed. + */ +#define SAFETY_MEMORY_HEADER_ADDRESS 0UL + +/** + * @brief Safety memory header + */ +struct safety_memory_header { + uint32_t magic; /**< @brief Magic. Set to SAFETY_MEMORY_MAGIC */ + uint32_t boot_status_offset; /**< Offset of the safety_memory_boot_status struct (in 32 bit words)*/ + uint32_t err_memory_offset; /**< Offset of the error memory */ + uint32_t err_memory_end; /**< End of the error memory. This points to the word after the error memory, containing the CRC of the whole backup RAM. */ + uint32_t magic_i; /**< @brief Invers Magic. Set to ~SAFETY_MEMORY_MAGIC */ +}; + +struct safety_memory_boot_status { + uint32_t reboot_to_bootloader; + uint32_t code_updated; +} + + +#endif /* __SAFETY_MEMORY_H__ */ diff --git a/stm-firmware/include/reflow-controller/safety/safety-memory.h b/stm-firmware/include/reflow-controller/safety/safety-memory.h new file mode 100644 index 0000000..f248547 --- /dev/null +++ b/stm-firmware/include/reflow-controller/safety/safety-memory.h @@ -0,0 +1,50 @@ +/* Reflow Oven Controller +* +* Copyright (C) 2020 Mario Hüttel +* +* This file is part of the Reflow Oven Controller Project. +* +* The reflow oven controller is free software: you can redistribute it and/or modify +* it under the terms of the GNU General Public License version 2 as +* published by the Free Software Foundation. +* +* The Reflow Oven Control Firmware is distributed in the hope that it will be useful, +* but WITHOUT ANY WARRANTY; without even the implied warranty of +* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +* GNU General Public License for more details. +* +* You should have received a copy of the GNU General Public License +* along with the reflow oven controller project. +* If not, see . +*/ + +#ifndef __WATCHDOG_H__ +#define __WATCHDOG_H__ + +#include +#include +#include + +/** + * @brief Setup the watchdog for the safety controller + * @param Prescaler to use for the 32 KHz LSI clock + * @return 0 if successful + * @note Once the watchdog is enabled, it cannot be turned off! + */ +int watchdog_setup(uint8_t prescaler); + +/** + * @brief Reset watchdog counter + * @param magic Magic value to prevent this fuinction from being called randomly + * @return 0 if successful + */ +int watchdog_ack(uint32_t magic); + +/** + * @brief Check if reset was generated by the watchdog. + * @note This also clears the relevant flag, so the function will reutrn false when called a second time + * @return + */ +bool watchdog_check_reset_source(void); + +#endif /* __WATCHDOG_H__ */ diff --git a/stm-firmware/safety/safety-memory.c b/stm-firmware/safety/safety-memory.c new file mode 100644 index 0000000..2ec93a5 --- /dev/null +++ b/stm-firmware/safety/safety-memory.c @@ -0,0 +1,22 @@ +/* Reflow Oven Controller +* +* Copyright (C) 2020 Mario Hüttel +* +* This file is part of the Reflow Oven Controller Project. +* +* The reflow oven controller is free software: you can redistribute it and/or modify +* it under the terms of the GNU General Public License version 2 as +* published by the Free Software Foundation. +* +* The Reflow Oven Control Firmware is distributed in the hope that it will be useful, +* but WITHOUT ANY WARRANTY; without even the implied warranty of +* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +* GNU General Public License for more details. +* +* You should have received a copy of the GNU General Public License +* along with the reflow oven controller project. +* If not, see . +*/ + +#include +