From 777c830ac0c110af088157ebe70b571b9ed10d88 Mon Sep 17 00:00:00 2001 From: "D.R.racer" Date: Wed, 21 Jul 2021 08:43:38 +0200 Subject: [PATCH] Add error handling and reporting documentation and fix links from the main.dox page --- src/hal/adc.h | 4 +- src/hal/cpu.h | 4 +- src/hal/eeprom.h | 3 +- src/hal/gpio.h | 2 + src/hal/shr16.h | 3 +- src/hal/spi.h | 5 ++- src/hal/timers.h | 5 +-- src/hal/usart.h | 4 +- src/hal/watchdog.h | 4 +- src/main.dox | 93 ++++++++++++++++++++++++++++++++++------------ 10 files changed, 89 insertions(+), 38 deletions(-) diff --git a/src/hal/adc.h b/src/hal/adc.h index 26029d3..bacbbfa 100644 --- a/src/hal/adc.h +++ b/src/hal/adc.h @@ -1,9 +1,9 @@ #pragma once #include -/// Hardware Abstraction Layer for the ADC's - namespace hal { + +/// Hardware Abstraction Layer for the ADC's namespace adc { /// ADC access routines diff --git a/src/hal/cpu.h b/src/hal/cpu.h index ff73d0b..604c7b9 100644 --- a/src/hal/cpu.h +++ b/src/hal/cpu.h @@ -1,8 +1,8 @@ #pragma once -/// Hardware Abstraction Layer for the CPU - namespace hal { + +/// Hardware Abstraction Layer for the CPU namespace cpu { #ifndef F_CPU diff --git a/src/hal/eeprom.h b/src/hal/eeprom.h index 39e2b90..40163c4 100644 --- a/src/hal/eeprom.h +++ b/src/hal/eeprom.h @@ -2,9 +2,10 @@ #include namespace hal { -namespace eeprom { /// EEPROM interface +namespace eeprom { + class EEPROM { public: using addr_t = uint16_t; diff --git a/src/hal/gpio.h b/src/hal/gpio.h index df8da66..b7bc385 100644 --- a/src/hal/gpio.h +++ b/src/hal/gpio.h @@ -6,6 +6,8 @@ #endif namespace hal { + +/// GPIO interface namespace gpio { struct GPIO_TypeDef { diff --git a/src/hal/shr16.h b/src/hal/shr16.h index 3c81b17..f68af24 100644 --- a/src/hal/shr16.h +++ b/src/hal/shr16.h @@ -3,7 +3,6 @@ #include namespace hal { -namespace shr16 { /// 16bit shift register (2x74595) interface /// @@ -36,6 +35,8 @@ namespace shr16 { /// /// SHR16_DIR_MSK = (SHR16_DIR_0 + SHR16_DIR_1 + SHR16_DIR_2) /// SHR16_ENA_MSK = (SHR16_ENA_0 + SHR16_ENA_1 + SHR16_ENA_2) +namespace shr16 { + class SHR16 { public: diff --git a/src/hal/spi.h b/src/hal/spi.h index 8b9546e..254ccd8 100644 --- a/src/hal/spi.h +++ b/src/hal/spi.h @@ -2,10 +2,11 @@ #include #include "gpio.h" -/// SPI interface - namespace hal { + +/// SPI interface namespace spi { + struct SPI_TypeDef { volatile uint8_t SPCRx; volatile uint8_t SPSRx; diff --git a/src/hal/timers.h b/src/hal/timers.h index 8eba17b..6a39a55 100644 --- a/src/hal/timers.h +++ b/src/hal/timers.h @@ -1,11 +1,10 @@ #pragma once -/// Hardware Abstraction Layer for the CPU's features and peripherals - namespace hal { + +/// Hardware Abstraction Layer for the CPU's internal timers namespace timers { -/// timers void ConfigureTimer(uint8_t timer /* some config struct */); void StartTimer(uint8_t timer); void StopTimer(uint8_t timer); diff --git a/src/hal/usart.h b/src/hal/usart.h index d7c2771..344796b 100644 --- a/src/hal/usart.h +++ b/src/hal/usart.h @@ -4,11 +4,11 @@ #include "gpio.h" #include "circular_buffer.h" +namespace hal { + /// USART interface /// @@TODO decide, if this class will behave like a singleton, or there will be multiple classes /// for >1 USART interfaces - -namespace hal { namespace usart { constexpr uint16_t UART_BAUD_SELECT(uint32_t baudRate, uint32_t xtalCpu) { diff --git a/src/hal/watchdog.h b/src/hal/watchdog.h index 850589d..c57d373 100644 --- a/src/hal/watchdog.h +++ b/src/hal/watchdog.h @@ -1,8 +1,8 @@ #pragma once -/// Hardware Abstraction Layer for the CPU's features and peripherals - namespace hal { + +/// Hardware Abstraction Layer for the CPU's internal watchdog namespace watchdog { /// watchdog interface diff --git a/src/main.dox b/src/main.dox index e9fe5b3..983db99 100644 --- a/src/main.dox +++ b/src/main.dox @@ -39,37 +39,37 @@ ///digraph architecture { /// node [shape=record, fontname=Helvetica, fontsize=10]; /// subgraph cluster_main { label="main" -/// main [ URL="\ref main"]; +/// main [ URL="main.cpp"]; /// } /// subgraph cluster_logic { label="logic" /// logic [ URL="\ref logic"]; /// } /// /// subgraph cluster_modules { label="modules" -/// buttons [ URL="\ref buttons"]; -/// debouncer [ URL="\ref debouncer"]; -/// finda [ URL="\ref finda"]; -/// fsensor [ URL="\ref fsensor"]; -/// globals [ URL="\ref globals"]; -/// idler [ URL="\ref idler"]; -/// leds [ URL="\ref leds"]; -/// selector [ URL="\ref selector"]; -/// motion [ URL="\ref motion"]; -/// permanent_storage [ URL="\ref permanent_storage"]; -/// protocol [ URL="\ref protocol"]; -/// timebase [ URL="\ref timebase"]; +/// buttons [ URL="\ref modules::buttons"]; +/// debouncer [ URL="\ref modules::debounce"]; +/// finda [ URL="\ref modules::finda"]; +/// fsensor [ URL="\ref modules::fsensor"]; +/// globals [ URL="\ref modules::globals"]; +/// idler [ URL="\ref modules::idler"]; +/// leds [ URL="\ref modules::leds"]; +/// selector [ URL="\ref modules::selector"]; +/// motion [ URL="\ref modules::motion"]; +/// permanent_storage [ URL="\ref modules::permanent_storage"]; +/// protocol [ URL="\ref modules::protocol"]; +/// timebase [ URL="\ref modules::time"]; /// } /// subgraph cluster_hal { label="hal" -/// adc [ URL="\ref adc"]; -/// cpu [ URL="\ref cpu"]; -/// eeprom [ URL="\ref eeprom"]; -/// gpio [ URL="\ref gpio"]; -/// shr16 [ URL="\ref shr16"]; -/// spi [ URL="\ref spi"]; -/// timers [ URL="\ref timers"]; -/// tmc2130 [ URL="\ref tmc2130"]; -/// usart [ URL="\ref usart"]; -/// watchdog [ URL="\ref watchdog"]; +/// adc [ URL="\ref hal::adc"]; +/// cpu [ URL="\ref hal::cpu"]; +/// eeprom [ URL="\ref hal::eeprom"]; +/// gpio [ URL="\ref hal::gpio"]; +/// shr16 [ URL="\ref hal::shr16"]; +/// spi [ URL="\ref hal::spi"]; +/// timers [ URL="\ref hal::timers"]; +/// tmc2130 [ URL="\ref hal::tmc2130"]; +/// usart [ URL="\ref hal::usart"]; +/// watchdog [ URL="\ref hal::watchdog"]; /// } /// main -> logic [ arrowhead="open" ]; /// @@ -112,6 +112,53 @@ /// The good news is that the Slicer's MMU code is fully backwards compatible. /// /// +///@section errors_sec Error sources and handling +/// +/// There are several different types/sources of errors in the MMU: +/// - runtime sensors +/// - algorithmic errors +/// - hardware component failures +/// +/// For a list of currently supported error states please see error_codes.h . +/// +///@subsection runtime_ssec Runtime sensors +/// +/// Errors like this are abnormal operational states resulting from the fact, that some of the sensors didn't report an expected state. +/// E.g. FINDA didn't trigger or the printer didn't send a trigger command from its filament sensor. +/// These failures cannot be predicted and can be only resolved partially by the MMU. +/// +/// The logic layer state machines check for these failures and act upon: +/// - Cut filament: detects FINDA_DIDNT_SWITCH_OFF, FINDA_DIDNT_SWITCH_ON +/// - Eject filament: detects FINDA_DIDNT_SWITCH_OFF, FINDA_DIDNT_SWITCH_ON +/// - Load filament: detects FINDA_DIDNT_SWITCH_ON, FSENSOR_DIDNT_SWITCH_ON +/// - Tool change: detects FINDA_DIDNT_SWITCH_OFF/FINDA_DIDNT_SWITCH_ON, FSENSOR_DIDNT_SWITCH_OFF/FSENSOR_DIDNT_SWITCH_ON +/// - Load filament: detects FINDA_DIDNT_SWITCH_OFF, FSENSOR_DIDNT_SWITCH_OFF +/// +///@subsection algorithmic_ssec Algorithmic errors +/// +/// This kind of errors represents unhandled states of state machines - which should not happen ;) +/// or at least the ocurrance can be mitigated by careful testing of the firmware code base. +/// Logic layer state machines check their internal state and if they by chance get into an unhandled state, +/// they switch into an error state INTERNAL. +/// +///@subsection hardware_ssec Hardware failures +/// +/// This kind of errors is extremely hard to tackle in full scale. +/// Basically any HW component can fail (including the HW chips on the mainboard) and we only have limited knowledge about such situations. +/// So under hardware failures we consider only stuff which can be detected by any means +/// - mostly CPU peripherals, especially the TMC2130 drivers, which are capable of some degree of error reporting. +/// +///@subsection errorrep_ssec Error reporting +/// +/// There are basically 2 ways of reporting an error to the user +/// - via USART communication with the printer - implies the communication works - the preferred way +/// - LEDs blinking - implies the shift registers work and the LEDs work as well - backup way +/// +/// The USART communication can report errors of the currently running command (see response to Q0). +/// +/// LEDs' blinking is to be defined yet, the previous firmware used elaborate blinking schemes to report all kinds of errors which most users were unable to decipher/act upon. +/// +/// ///@section tests_sec Tests and quality assurance /// ///@subsection unit_sec Unit tests