Renamed clock-enable manager to rcc manager and improve some header files with doxygen comments

stm-firmware/include/reflow-controller/periph-config/oven-driver-hwcfg.h

@@ -18,16 +18,44 @@
 * If not, see <http://www.gnu.org/licenses/>.
 */
 
+/**
+ * @file oven-driver-hwcfg.h
+ * @brief hardware configuration for oven PWM driver
+ */
+
 #ifndef __OVEN_DRIVER_HWCFG_H__
 #define __OVEN_DRIVER_HWCFG_H__
 
 #include <stm32/stm32f4xx.h>
 
+/**
+ * @brief Timer to use to generate PWM for oven
+ */
 #define OVEN_CONTROLLER_PWM_TIMER TIM3
+
+/**
+ * @brief Port the oven control output is connected to
+ */
 #define OVEN_CONTROLLER_PORT GPIOB
+
+/**
+ * @brief The Pin number the oven control output is located at
+ */
 #define OVEN_CONTROLLER_PIN (0)
+
+/**
+ * @brief The AHB1ENR Bitmask to enable the clock to the output port #OVEN_CONTROLLER_PORT
+ */
 #define OVEN_CONTROLLER_PORT_RCC_MASK RCC_AHB1ENR_GPIOBEN
+
+/**
+ * @brief The APB1ENR bitmask to enable the #OVEN_CONTROLLER_PWM_TIMER
+ */
 #define OVEN_CONTROLLER_TIM_RCC_MASK RCC_APB1ENR_TIM3EN
+
+/**
+ * @brief The alternate function #OVEN_CONTROLLER_PWM_TIMER's pwm output is located on #OVEN_CONTROLLER_PORT
+ */
 #define OVEN_CONTROLLER_PIN_ALTFUNC (2)
 
 #endif /* __OVEN_DRIVER_HWCFG_H__ */

stm-firmware/include/reflow-controller/periph-config/safety-adc-hwcfg.h

@@ -21,22 +21,82 @@
 #ifndef __SAFETY_ADC_HWCFG_H__
 #define __SAFETY_ADC_HWCFG_H__
 
+/**
+ * @file safety-adc-hwcfg.h
+ * @brief Safety ADC configuration settings
+ */
+
 #include <stm32/stm32f4xx.h>
 
+/**
+ * @brief Peripheral to use as safety ADC.
+ * @note This must be ADC1, because it is the only ADC with access to the internal temperature sensor
+ */
 #define SAFETY_ADC_ADC_PERIPHERAL ADC1
+
+/**
+ * @brief Clock enable mask in RCC->APB2ENR to enable the #SAFETY_ADC_ADC_PERIPHERAL
+ */
 #define SAFETY_ADC_ADC_RCC_MASK RCC_APB2ENR_ADC1EN
+
+/**
+ * @brief ADC channel number of the internal temperature sensor
+ */
 #define TEMP_CHANNEL_NUM (16)
+
+/**
+ * @brief ADC channel number of the internal reference voltage
+ */
 #define INT_REF_CHANNEL_NUM (17)
 
+/**
+ * @brief Nominal value of the internal reference voltage.
+ *
+ * This is used to compare to the external reference voltage.
+ */
 #define SAFETY_ADC_INT_REF_MV 1210.0f
 
+/**
+ * @brief Nominal temperature in degrees celsius of the internal temperature sensor at which it reads
+ * #SAFETY_ADC_TEMP_NOM_MV millivolts.
+ *
+ */
 #define SAFETY_ADC_TEMP_NOM 25.0f
+
+/**
+ * @brief Nominal internal temperature sensor voltage at temperature #SAFETY_ADC_TEMP_NOM
+ */
 #define SAFETY_ADC_TEMP_NOM_MV 760.0f
+
+/**
+ * @brief Sensitivity of the internal temperature sensor in millivolts per Kelvin
+ */
 #define SAFETY_ADC_TEMP_MV_SLOPE 2.5f
 
+/**
+ * @brief Number of channels to handle for the SAFETY ADC.
+ * @note The maximum amount of channels is limited to 16
+ */
 #define SAFETY_ADC_NUM_OF_CHANNELS 8
+
+/**
+ * @brief Channel numbers to sample with the SAFETY ADC
+ *
+ * - The first 4 values are the internal temperature sensor
+ * - The next 4 values are the internal reference voltage
+ *
+ * The values are samples 4 times each to allow averaging them to get
+ * more precise readings. Check the maximum value of #SAFETY_ADC_NUM_OF_CHANNELS
+ * when adding more channels.
+ * @warning Safety controller expects the current measurment list. If you change it, check @ref safety_controller_handle_safety_adc
+ */
 #define SAFETY_ADC_CHANNELS TEMP_CHANNEL_NUM, TEMP_CHANNEL_NUM, TEMP_CHANNEL_NUM, TEMP_CHANNEL_NUM, \
 				INT_REF_CHANNEL_NUM, INT_REF_CHANNEL_NUM, INT_REF_CHANNEL_NUM, INT_REF_CHANNEL_NUM
 
 
+/* Check the channel count of the safety ADC */
+#if SAFETY_ADC_NUM_OF_CHANNELS > 16 || SAFETY_ADC_NUM_OF_CHANNELS < 0
+#error "Invlaid count of channels for safety ADC"
+#endif
+
 #endif /* __SAFETY_ADC_HWCFG_H__ */

stm-firmware/include/reflow-controller/safety/safety-adc.h

@@ -29,23 +29,54 @@
 #include <stdint.h>
 #include <stdbool.h>
 
-enum safety_adc_meas_channel {SAFETY_ADC_MEAS_VREF, SAFETY_ADC_MEAS_TEMP};
+/**
+ * @brief The safety ADC's measure channel
+ */
+enum safety_adc_meas_channel {
+	SAFETY_ADC_MEAS_VREF, /**< @brief Internal reference voltage @note This will not output the internal reference voltage but the recalculated external voltage! */
+	SAFETY_ADC_MEAS_TEMP, /**< @brief Internal temperature sensor */
+};
 
+/**
+ * @brief Initialize safety ADC. Only call this function once!
+ */
 void safety_adc_init(void);
 
+/**
+ * @brief safety_adc_deinit Deactivate safety ADC
+ * @warning For completeness. Do not call! the safety ADC is a vital component. It's malfunction will trigger a critical safety flag.
+ */
 void safety_adc_deinit(void);
 
+/**
+ * @brief safety_adc_trigger_meas
+ */
 void safety_adc_trigger_meas(void);
 
 /**
  * @brief Poll ADC result.
- * @param results adc results
  * @return 1 if measurement successful, 0 if not ready, -1 if ADC aborted or not started
  */
 int safety_adc_poll_result(void);
 
+/**
+ * @brief Get the sampled signal values of the safety ADC.
+ *
+ * Use #safety_adc_poll_result to poll for a finished conversion of the safety ADC.
+ * After that, it is safe to use the output values until a new conversion is triggered using #safety_adc_trigger_meas
+ *
+ * @warning This function return a constant buffer, that is directly written on by the DMA! Check #safety_adc_poll_result to prevent race conditions.
+ * @return Array of raw ADC readings with lenght of #SAFETY_ADC_NUM_OF_CHANNELS
+ */
 const uint16_t *safety_adc_get_values(void);
 
+/**
+ * @brief Convert a safety ADC raw value to an actual signal value
+ * @param channel Measurment channel to convert voltage for
+ * @param analog_value Raw value of the ADC to convert
+ * @warning Double check @ref safety_adc_meas_channel to make sure you understand the output of this function correctly.
+ * @return
+ */
 float safety_adc_convert_channel(enum safety_adc_meas_channel channel, uint16_t analog_value);
 
 #endif /* __SAFETY_ADC_H__ */

stm-firmware/include/reflow-controller/safety/safety-config.h

@@ -18,10 +18,21 @@
 * If not, see <http://www.gnu.org/licenses/>.
 */
 
+/**
+ * @file safety-config.h
+ * @brief Safety Controller Configuration.
+ * @warning MAKE SURE XOU UNDERSTAND WHAT YOU ARE DOING IN HERE
+ */
+
 #ifndef __SAFETY_CONFIG_H__
 #define __SAFETY_CONFIG_H__
 
-
+/**
+ * @brief Enum type representing safety flags.
+ *
+ * The enum type is binary or'able to allow combining
+ * multiple safety flags.
+ */
 enum safety_flag {
 	ERR_FLAG_NO_FLAG = 0,
 	ERR_FLAG_MEAS_ADC_OFF = (1<<0),
@@ -43,6 +54,12 @@ enum safety_flag {
 	ERR_FLAG_SAFETY_TAB_CORRUPT = (1<<16),
 };
 
+/**
+ * @brief Enum Type representing timing monitors.
+ *
+ * The enum type is binary or'able to allow combining
+ * multiple safety flags.
+ */
 enum timing_monitor {
 	ERR_TIMING_PID = (1<<0),
 	ERR_TIMING_MEAS_ADC = (1<<1),
@@ -50,6 +67,12 @@ enum timing_monitor {
 	ERR_TIMING_MAIN_LOOP = (1<<3),
 };
 
+/**
+ * @brief Enum Type representing analog value monitors.
+ *
+ * The enum type is binary or'able to allow combining
+ * multiple safety flags.
+ */
 enum analog_value_monitor {
 	ERR_AMON_VREF = (1<<0),
 	ERR_AMON_UC_TEMP = (1<<1),
@@ -97,10 +120,13 @@ enum analog_value_monitor {
 
 
 /**
- * @brief Key used to lock the safety flags from external ack'ing
+ * @brief Key used to lock the safety flags coming from the measurment ADC from external ack'ing
  */
 #define MEAS_ADC_SAFETY_FLAG_KEY 0xe554dac3UL
 
+/**
+ * @brief Safety ADC trigger interval
+ */
 #define SAFETY_CONTROLLER_ADC_DELAY_MS 250
 
 #define SAFETY_CONFIG_DEFAULT_PERSIST	ERR_FLAG_PERSIST_ENTRY(ERR_FLAG_MEAS_ADC_OFF, false), \