From b6a2790a599c56cf1c2d05dc787ac89c39e75232 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mario=20H=C3=BCttel?= <mario.huettel@gmx.net>
Date: Sun, 28 Nov 2021 23:40:43 +0100
Subject: [PATCH] cleanup code and write a little documentation

---
 doc/source/firmware/index.rst       |  2 +-
 doc/source/firmware/peripherals.rst | 44 +++++++++++++++++++++++++++++
 stm-firmware/oven-driver.c          |  4 +--
 stm-firmware/safety/safety-adc.c    | 18 ++++++++++--
 4 files changed, 63 insertions(+), 5 deletions(-)
 create mode 100644 doc/source/firmware/peripherals.rst

diff --git a/doc/source/firmware/index.rst b/doc/source/firmware/index.rst
index 882ed40..d0f2a36 100644
--- a/doc/source/firmware/index.rst
+++ b/doc/source/firmware/index.rst
@@ -15,4 +15,4 @@ mechanisms and the behavior. For a detailed code documentation see the doxygen o
 	safety/index
 	code/index
 	hw-version-detect
-
+	peripherals
diff --git a/doc/source/firmware/peripherals.rst b/doc/source/firmware/peripherals.rst
new file mode 100644
index 0000000..82cecd4
--- /dev/null
+++ b/doc/source/firmware/peripherals.rst
@@ -0,0 +1,44 @@
+.. _peripherals:
+
+Used Peripheral Modules
+=======================
+
+This section lists all the used peripheral modules of the ``STM32F407VxT6``.
+
+Core Peripherals
+----------------
+
+- ``SysTick``: Generating a 100us tick for the LCD routine and 1ms base system tick.
+- ``NVIC``: Interrupt controller
+- ``FPU``: The Flaoting Point Unit is activated and used in this formware.
+
+AHB Peripherals
+---------------
+
+- ``DMA2``
+	- ``Stream0``: DMA transfer of PT1000 measurement ADC to memory
+	- ``Stream4``: DMA transfer of Safety ADC measurement values
+	- ``Stream5``: Shell UART RX
+	- ``Stream7``: Shell UART TX
+- ``RNG``: Random number generation for stack corruption / overflow checker.
+- ``CRC``: CRC verfication of various data (Safety structures, EEPROM data, Safety RAM)
+- ``Backup RAM``: Backup RAM storing errors and bootloader information beyond system resets. The memory is cleared by a power cycle!
+
+ABP1 Peripherals
+----------------
+
+- ``IWDG``: Independent Watchdog
+- ``TIM2``: PT1000 measurement ADC sample time generation timer. Genewrates the 1 KHz sample trigger to the ADC peripheral via the internal event routing system.
+- ``TIM3``: PWM timer for oven relais output.
+- ``TIM5``: Input capture for rotary encoder.
+- ``TIM7``: Timer for loudspeaker tone generation.
+ 
+
+APB2 Peripherals
+----------------
+
+- ``SPI1``: SPI for external SPI-EEPROM
+- ``SDIO``: SD card interface
+- ``USART1``: Shell UART
+- ``ADC1``: Safety ADC for monitoring voltages
+- ``ADC3``: PT1000 measurement ADC
diff --git a/stm-firmware/oven-driver.c b/stm-firmware/oven-driver.c
index 6dcb2bb..36c9bda 100644
--- a/stm-firmware/oven-driver.c
+++ b/stm-firmware/oven-driver.c
@@ -41,12 +41,12 @@ static struct pid_controller IN_SECTION(.ccm.bss) oven_pid;
 /**
  * @brief Oven PID is currently running
  */
-static bool oven_pid_running;
+static bool IN_SECTION(.ccm.bss) oven_pid_running;
 
 /**
  * @brief Oven PID has been aborted / abnormally stopped.
  */
-static bool oven_pid_aborted;
+static bool IN_SECTION(.ccm.bss) oven_pid_aborted;
 
 /**
  * @brief Power level [0..100] of the oven to be applied
diff --git a/stm-firmware/safety/safety-adc.c b/stm-firmware/safety/safety-adc.c
index be10bbb..9ade7df 100644
--- a/stm-firmware/safety/safety-adc.c
+++ b/stm-firmware/safety/safety-adc.c
@@ -31,8 +31,22 @@
 #include <reflow-controller/safety/safety-controller.h>
 
 static const uint8_t safety_adc_channels[SAFETY_ADC_NUM_OF_CHANNELS] = {SAFETY_ADC_CHANNELS};
-static volatile uint8_t safety_adc_conversion_complete;
-static volatile uint8_t safety_adc_triggered;
+
+/**
+ * @brief Safety ADC conversion complete. Set in interrupt.
+ */
+static volatile uint8_t IN_SECTION(.ccm.bss) safety_adc_conversion_complete;
+
+/**
+ * @brief Safety ADC has been started. It will perform all specified conversions and
+ * set @ref safety_adc_conversion_complete afterwards
+ */
+static volatile uint8_t IN_SECTION(.ccm.bss) safety_adc_triggered;
+
+/**
+ * @brief Safety ADC conversion storage. This is filled by DMA.
+ * @note Do not move this to CCM RAM as the DMA won't be able to access it.
+ */
 static volatile uint16_t safety_adc_conversions[SAFETY_ADC_NUM_OF_CHANNELS];
 
 void safety_adc_init(void)