Deprecate rcc_clk_init().

This function has been with us from the earliest days of libmaple.
It's showing its age, as the API it presents is tied to the
STM32F1. Deprecate it, and provide instructions for how to use newer,
more portable APIs. The new way is more verbose, but we can always add
a portable "just set up the PLL, dammit" convenience function later (a
nice candidate is to extract an interface from setup_clocks() in
boards.cpp).

Signed-off-by: Marti Bolivar <mbolivar@leaflabs.com>

4 files changed, 22 insertions, 8 deletions

diff --git a/libmaple/include/libmaple/rcc.h b/libmaple/include/libmaple/rcc.h
index 9042391..4693606 100644
--- a/libmaple/include/libmaple/rcc.h
+++ b/libmaple/include/libmaple/rcc.h
@@ -42,7 +42,7 @@ extern "C"{
  * might need them. */
 /**
  * @brief SYSCLK sources
- * @see rcc_clk_init()
+ * @see rcc_switch_sysclk()
  */
 typedef enum rcc_sysclk_src {
     RCC_CLKSRC_HSI = 0x0,
diff --git a/libmaple/stm32f1/include/series/rcc.h b/libmaple/stm32f1/include/series/rcc.h
index b72c5cf..1eb913a 100644
--- a/libmaple/stm32f1/include/series/rcc.h
+++ b/libmaple/stm32f1/include/series/rcc.h
@@ -448,8 +448,7 @@ typedef enum rcc_clk_id {
 } rcc_clk_id;
 
 /**
- * PLL multipliers
- * @see rcc_clk_init()
+ * @brief Deprecated PLL multipliers, for rcc_clk_init().
  */
 typedef enum rcc_pll_multiplier {
     RCC_PLLMUL_2 = (0x0 << 18),
@@ -470,8 +469,8 @@ typedef enum rcc_pll_multiplier {
 } rcc_pll_multiplier;
 
 /**
- * PLL entry clock source
- * @see rcc_clk_init()
+ * @brief PLL clock sources.
+ * @see rcc_configure_pll()
  */
 typedef enum rcc_pllsrc {
     RCC_PLLSRC_HSE = (0x1 << 16),
diff --git a/libmaple/stm32f1/rcc.c b/libmaple/stm32f1/rcc.c
index 0752b82..aeedf66 100644
--- a/libmaple/stm32f1/rcc.c
+++ b/libmaple/stm32f1/rcc.c
@@ -96,8 +96,23 @@ const struct rcc_dev_info rcc_dev_table[] = {
 };
 
 /**
- * @brief Initialize the clock control system. Initializes the system
- *        clock source to use the PLL driven by an external oscillator
+ * @brief Deprecated.
+ *
+ * Initialize the clock control system. Initializes the system
+ * clock source to use the PLL driven by an external oscillator.
+ *
+ * This function is limited and nonportable. Instead of using it,
+ * follow this (portable) procedure:
+ *
+ * 1. Switch to HSI by calling rcc_switch_sysclk(RCC_CLKSRC_HSI).
+ * 2. Turn off HSE by calling rcc_turn_off_clk(RCC_CLK_HSE).
+ * 3. Turn off the PLL by calling rcc_turn_off_clk(RCC_CLK_HSE).
+ * 4. Reconfigure the PLL using rcc_configure_pll().
+ * 5. Turn on RCC_CLK_HSE using rcc_turn_on_clk() and wait for it to
+ *    become ready by busy-waiting on rcc_is_clk_ready().
+ * 6. Turn on RCC_CLK_PLL using the same methods.
+ * 7. Switch to the PLL with rcc_switch_sysclk(RCC_CLKSRC_PLL).
+ *
  * @param sysclk_src system clock source, must be PLL
  * @param pll_src pll clock source, must be HSE
  * @param pll_mul pll multiplier
diff --git a/libmaple/stm32f2/include/series/rcc.h b/libmaple/stm32f2/include/series/rcc.h
index 019bb3e..79bdf73 100644
--- a/libmaple/stm32f2/include/series/rcc.h
+++ b/libmaple/stm32f2/include/series/rcc.h
@@ -833,7 +833,7 @@ typedef enum rcc_clk_id {
 
 /**
  * @brief PLL entry clock source
- * @see rcc_clk_init()
+ * @see rcc_configure_pll()
  */
 typedef enum rcc_pllsrc {
     RCC_PLLSRC_HSI = 0,