cpu/stm32_common: add clock config documentation

cpu/stm32_common/doc.txt

@@ -7,4 +7,39 @@
  * families supported by RIOT: @ref cpu_stm32f0, @ref cpu_stm32l0,
  * @ref cpu_stm32f1, @ref cpu_stm32f2, @ref cpu_stm32f3, @ref cpu_stm32f4,
  * @ref cpu_stm32l4, @ref cpu_stm32f7.
- */
+ *
\ No newline at end of file
+ * STM32F[2|4|7] Clock configuration
+ * =================================
+ *
+ * stm32f2, stm32f4 and stm32f7 cpus share clock configuration code and macro.
+ * It can be configured as described here.
+ *
+ * The following macro must be defined in the board's periph_conf.h:
+ *  - CLOCK_HSE: 0 if HSI must be used as PLL source, frequency in Hz otherwise,
+ *  - CLOCK_LSE: 0 if LSI must be used as low speed clock, 1 otherwise
+ * (the LSE is a 32.768kHz crytal)
+ *  - CLOCK_CORECLOCK: desired main clock frequency
+ *  - CLOCK_AHB_DIV, CLOCK_AHB: AHB prescaler in register value and AHB frequecny in Hz
+ *  - CLOCK_APB1_DIV, CLOCK_APB1: APB1 prescaler in register value and APB1 frequecny in Hz
+ *  - CLOCK_APB2_DIV, CLOCK_APB2: APB2 prescaler in register value and APB2 frequecny in Hz
+ *  - CLOCK_PLL_M, CLOCK_PLL_N, CLOCK_PLL_P, CLOCK_PLL_Q: Main PLL factors
+ *
+ * The following macro are optional and can be defined depending on board config
+ * and application needs:
+ *  - CLOCK_ENABLE_PLL_I2S: if a second PLL (PLL I2S) is available on the cpu, it
+ * can be activated with this macro, then CLOCK_PLL_I2S_M, CLOCK_PLL_I2S_N,
+ * CLOCK_PLL_I2S_P and CLOCK_PLL_I2S_Q need to be defined
+ *  - CLOCK_ENABLE_PLL_SAI: if a second PLL (PLL SAI) is available on the cpu, it
+ * can be activated with this macro, then CLOCK_PLL_SAI_M, CLOCK_PLL_SAI_N,
+ * CLOCK_PLL_SAI_P and CLOCK_PLL_SAI_Q need to be defined
+ *  - CLOCK_USE_ALT_48MHZ: if the 48MHz clock should be generated by the alternate
+ * source (PLL I2S or PLL SAI, depending on cpu)
+ *
+ * All the previous constants can be generated using the tool in
+ * `cpu/stm32_common/dist/clk_conf`.
+ *
+ * Clock outputs can also be setup with macro:
+ *  - CLOCK_MCOx_SRC, CLOCK_MCOx_PRE, with x=1,2: MCO1 and MCO2 output configuration
+ * macros. CLOCK_MCOx_SRC defines the MCOx source, as a register value (see vendor header),
+ * CLOCK_MCOx_PRE defines the MCOx prescaler, as a register value.
+ */