diff options
Diffstat (limited to 'source/libmaple/api/rcc.rst')
| -rw-r--r-- | source/libmaple/api/rcc.rst | 677 |
1 files changed, 330 insertions, 347 deletions
diff --git a/source/libmaple/api/rcc.rst b/source/libmaple/api/rcc.rst index 4b96c00..ce58ec8 100644 --- a/source/libmaple/api/rcc.rst +++ b/source/libmaple/api/rcc.rst @@ -1,377 +1,360 @@ .. highlight:: c .. _libmaple-rcc: -``rcc.h`` -========= +``<libmaple/rcc.h>`` +==================== Reset and Clock Control (RCC) support. +The RCC is responsible for managing the MCU's various clocks. This +includes the core clock SYSCLK, which determines the CPU clock +frequency, as well as the clock lines that drive peripherals. + +Because of this, the available RCC functionality varies by target. +There are a :ref:`variety of abstractions <libmaple-rcc-core-types>` +in place to make managing this more convenient. + .. contents:: Contents :local: + :depth: 2 + +.. _libmaple-rcc-core-types: + +Core Types +---------- + +The core abstractions in place are +:ref:`rcc_clk_id <libmaple-rcc-rcc_clk_id>`, +:ref:`rcc_clk <libmaple-rcc-rcc_clk>`, +:ref:`rcc_sysclk_src <libmaple-rcc-rcc_sysclk_src>`, +:ref:`rcc_clk_domain <libmaple-rcc-rcc_clk_domain>`, and +:ref:`rcc_prescaler <libmaple-rcc-rcc_prescaler>`. + +.. _libmaple-rcc-rcc_clk_id: + +Peripheral Identifiers: ``rcc_clk_id`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``rcc_clk_id`` is an enum used to identify peripherals. The RCC +back-ends use them to look up a peripheral's bus and clock line, but +they are also generally useful as unique identifiers for each +peripheral. You can manage peripherals using their ``rcc_clk_id``\ s +with :ref:`these functions <libmaple-rcc-clk-id-funcs>`. + +Peripherals which are common across targets have the same token +(though not necessarily the same value) for their ``rcc_clk_id`` +across different targets. For example, the ``rcc_clk_id`` for the ADC1 +peripheral is always ``RCC_ADC1`` regardless of the target. +Additionally, as explained in :ref:`libmaple-overview-devices`, each +peripheral device type struct contains the ``rcc_clk_id`` for that +peripheral in a ``clk_id`` field. + +The available ``rcc_clk_id``\ s on each supported target series are as +follows. + +STM32F1 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f1::rcc_clk_id -Types ------ +STM32F2 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f2::rcc_clk_id + +.. _libmaple-rcc-rcc_sysclk_src: + +System Clock (SYSCLK) Sources: ``rcc_sysclk_src`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +SYSCLK is the core system clock. It determines the CPU clock rate, and +it's the base clock which is used to drive (most of) the peripherals +on the STM32. ``rcc_sysclk_src`` is an enum for the possible SYSCLK +sources. Switch the SYSCLK source with :ref:`rcc_switch_sysclk() +<libmaple-rcc-rcc_switch_sysclk>`. -.. doxygenstruct:: rcc_reg_map .. doxygenenum:: rcc_sysclk_src -.. doxygenenum:: rcc_pllsrc -.. doxygenenum:: rcc_pll_multiplier -.. doxygenenum:: rcc_clk_id -.. doxygenenum:: rcc_clk_domain -.. doxygenenum:: rcc_prescaler -.. doxygenenum:: rcc_adc_divider -.. doxygenenum:: rcc_apb1_divider -.. doxygenenum:: rcc_apb2_divider -.. doxygenenum:: rcc_ahb_divider -Devices -------- +As a special case, you can configure the PLL with a call to +:ref:`rcc_configure_pll() <libmaple-rcc-rcc_configure_pll>`. + +.. _libmaple-rcc-rcc_clk: + +System and Secondary Clock Sources: ``rcc_clk`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``rcc_clk`` type gives available system and secondary clock +sources (e.g. HSI, HSE, LSE). As with :ref:`rcc_clk_id +<libmaple-rcc-rcc_clk_id>`, clock sources which are common across +targets have the same token, but not necessarily the same value, for +their ``rcc_clk`` on each target. A variety of :ref:`clock management +functions <libmaple-rcc-clk-funcs>` are available. + +Note that the inclusion of secondary clock sources, like LSI and LSE, +makes ``rcc_clk`` different from the SYSCLK sources, which are managed +using :ref:`rcc_sysclk_src <libmaple-rcc-rcc_sysclk_src>`. + +The available ``rcc_clk``\ s for each supported target series are as +follows. + +STM32F1 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f1::rcc_clk -None. +STM32F2 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f2::rcc_clk + +.. _libmaple-rcc-rcc_clk_domain: + +Clock Domains: ``rcc_clk_domain`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These specify the available clock domains. For example, each AHB and +APB is a clock domain. + +This type mostly exists to enable asking devices what bus they're on, +which, given knowledge of your system's clock configuration, can be +useful when making decisions about prescalers, etc. + +Given an :ref:`rcc_clk_id <libmaple-rcc-rcc_clk_id>`, you can get the +peripheral's clock domain with :ref:`rcc_dev_clk() +<libmaple-rcc-rcc_dev_clk>`. Clock domains that are common across +series have the same token (but not necessarily the same value) for +their corresponding ``rcc_clk_domain``. + +The available ``rcc_clk_domain``\ s for each supported target series +are as follows. + +STM32F1 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f1::rcc_clk_domain + +STM32F2 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f2::rcc_clk_domain + +.. _libmaple-rcc-rcc_prescaler: + +Prescalers: ``rcc_prescaler`` and Friends +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Available prescalers are managed via the ``rcc_prescaler`` type, the +``rcc_set_prescaler()`` function, and a variety of related prescaler +divider types. See :ref:`libmaple-rcc-prescalers` for more +information and usage notes. Functions --------- -.. doxygenfunction:: rcc_clk_init +.. _libmaple-rcc-sysclk-funcs: +.. _libmaple-rcc-rcc_switch_sysclk: + +SYSCLK Management +~~~~~~~~~~~~~~~~~ + +Change the SYSCLK source with ``rcc_switch_sysclk()``. + +.. doxygenfunction:: rcc_switch_sysclk + +.. _libmaple-rcc-rcc_configure_pll: + +PLL Configuration +~~~~~~~~~~~~~~~~~ + +You can configure the PLL with ``rcc_configure_pll()``. This takes an +``rcc_pll_cfg`` struct as its argument. Though the definition of +``rcc_pll_cfg`` is common across series, its contents are entirely +target-dependent. + +.. doxygenstruct:: rcc_pll_cfg +.. _rcc-rcc_configure_pll: +.. doxygenfunction:: rcc_configure_pll + +The fields in an ``rcc_pll_cfg`` on each target are as follows. + +rcc_pll_cfg on STM32F1 Targets +++++++++++++++++++++++++++++++ + +The ``pllsrc`` field is chosen from the following. + +.. doxygenenum:: stm32f1::rcc_pllsrc + +.. FIXME [0.0.13] We've got plans to redo this; make sure you watch +.. libmaple for changes here. + +The ``data`` field must point to a ``struct stm32f1_rcc_pll_data``. +This just contains an ``rcc_pll_multiplier``. + +.. doxygenenum:: stm32f1::rcc_pll_multiplier + +.. doxygenstruct:: stm32f1::stm32f1_rcc_pll_data + +rcc_pll_cfg on STM32F2 Targets +++++++++++++++++++++++++++++++ + +The ``pllsrc`` field is chosen from the following. + +.. doxygenenum:: stm32f2::rcc_pllsrc + +The ``data`` field must point to a ``struct stm32f2_rcc_pll_data``. + +.. doxygenstruct:: stm32f2::stm32f2_rcc_pll_data + +.. _libmaple-rcc-clk-funcs: + +System and Secondary Clock Management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These functions are useful for managing clocks via their :ref:`rcc_clk +<libmaple-rcc-rcc_clk>`. + +.. doxygenfunction:: rcc_turn_on_clk +.. doxygenfunction:: rcc_turn_off_clk +.. doxygenfunction:: rcc_is_clk_on +.. doxygenfunction:: rcc_is_clk_ready + +.. _libmaple-rcc-clk-id-funcs: + +Peripheral Management +~~~~~~~~~~~~~~~~~~~~~ + +These functions are useful for managing peripherals via their +:ref:`rcc_clk_id <libmaple-rcc-rcc_clk_id>`. + +.. _libmaple-rcc-rcc_clk_enable: .. doxygenfunction:: rcc_clk_enable .. doxygenfunction:: rcc_reset_dev +.. _libmaple-rcc-rcc_dev_clk: .. doxygenfunction:: rcc_dev_clk + +.. _libmaple-rcc-prescalers: + +Prescaler Management +~~~~~~~~~~~~~~~~~~~~ + +All clock prescalers managed by RCC can be controlled with a single +function, ``rcc_set_prescaler()``. + .. doxygenfunction:: rcc_set_prescaler -Register Map Base Pointers --------------------------- +The arguments to ``rcc_set_prescaler()`` are target-dependent, but +follow a common pattern: + +- The first argument is the prescaler to set, so there's one for each + peripheral clock domain, etc. These have names like + ``RCC_PRESCALER_FOO``, e.g. ``RCC_PRESCALER_APB1``. Choose the + prescaler from the ``rcc_prescaler``\ s on your target (see below). + +- The second argument is the actual clock divider to use; it's chosen + based on the first argument. The dividers for ``RCC_PRESCALER_FOO`` + are given by the type ``rcc_foo_divider``, and have values like + ``RCC_FOO_xxx_DIV_y``. This means that the foo clock will be the + ``xxx`` clock divided by ``y``. + +For example, calling ``rcc_set_prescaler(RCC_PRESCALER_APB1, +RCC_APB1_HCLK_DIV_1)`` would set the APB1 clock to HCLK divided by 1. + +Prescalers which are common across targets have the same token, though +not necessarily the same value, for their ``rcc_prescaler`` (for +example, ``RCC_PRESCALER_APB1`` is available on both STM32F1 and +STM32F2 targets). The available prescalers and dividers on each +supported target series are as follows. + +STM32F1 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f1::rcc_prescaler +.. doxygenenum:: stm32f1::rcc_adc_divider +.. doxygenenum:: stm32f1::rcc_apb1_divider +.. doxygenenum:: stm32f1::rcc_apb2_divider +.. doxygenenum:: stm32f1::rcc_ahb_divider + +STM32F2 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f2::rcc_prescaler +.. doxygenenum:: stm32f2::rcc_mco2_divider +.. doxygenenum:: stm32f2::rcc_mco1_divider +.. doxygenenum:: stm32f2::rcc_rtc_divider +.. doxygenenum:: stm32f2::rcc_apb2_divider +.. doxygenenum:: stm32f2::rcc_apb1_divider +.. doxygenenum:: stm32f2::rcc_ahb_divider + +Register Maps +------------- + +These vary by target. The base pointer is always ``RCC_BASE``. .. doxygendefine:: RCC_BASE +STM32F1 Targets +~~~~~~~~~~~~~~~ + +.. doxygenstruct:: stm32f1::rcc_reg_map + +STM32F2 Targets +~~~~~~~~~~~~~~~ + +.. doxygenstruct:: stm32f2::rcc_reg_map + Register Bit Definitions ------------------------ -Clock control register -~~~~~~~~~~~~~~~~~~~~~~ - -.. doxygendefine:: RCC_CR_PLLRDY_BIT -.. doxygendefine:: RCC_CR_PLLON_BIT -.. doxygendefine:: RCC_CR_CSSON_BIT -.. doxygendefine:: RCC_CR_HSEBYP_BIT -.. doxygendefine:: RCC_CR_HSERDY_BIT -.. doxygendefine:: RCC_CR_HSEON_BIT -.. doxygendefine:: RCC_CR_HSIRDY_BIT -.. doxygendefine:: RCC_CR_HSION_BIT - -.. doxygendefine:: RCC_CR_PLLRDY -.. doxygendefine:: RCC_CR_PLLON -.. doxygendefine:: RCC_CR_CSSON -.. doxygendefine:: RCC_CR_HSEBYP -.. doxygendefine:: RCC_CR_HSERDY -.. doxygendefine:: RCC_CR_HSEON -.. doxygendefine:: RCC_CR_HSICAL -.. doxygendefine:: RCC_CR_HSITRIM -.. doxygendefine:: RCC_CR_HSIRDY -.. doxygendefine:: RCC_CR_HSION - -Clock configuration register -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. doxygendefine:: RCC_CFGR_USBPRE_BIT -.. doxygendefine:: RCC_CFGR_PLLXTPRE_BIT -.. doxygendefine:: RCC_CFGR_PLLSRC_BIT - -.. doxygendefine:: RCC_CFGR_MCO -.. doxygendefine:: RCC_CFGR_USBPRE -.. doxygendefine:: RCC_CFGR_PLLMUL -.. doxygendefine:: RCC_CFGR_PLLXTPRE -.. doxygendefine:: RCC_CFGR_PLLSRC -.. doxygendefine:: RCC_CFGR_ADCPRE -.. doxygendefine:: RCC_CFGR_PPRE2 -.. doxygendefine:: RCC_CFGR_PPRE1 -.. doxygendefine:: RCC_CFGR_HPRE -.. doxygendefine:: RCC_CFGR_SWS -.. doxygendefine:: RCC_CFGR_SWS_PLL -.. doxygendefine:: RCC_CFGR_SWS_HSE -.. doxygendefine:: RCC_CFGR_SW -.. doxygendefine:: RCC_CFGR_SW_PLL -.. doxygendefine:: RCC_CFGR_SW_HSE - -Clock interrupt register -~~~~~~~~~~~~~~~~~~~~~~~~ - -.. doxygendefine:: RCC_CIR_CSSC_BIT -.. doxygendefine:: RCC_CIR_PLLRDYC_BIT -.. doxygendefine:: RCC_CIR_HSERDYC_BIT -.. doxygendefine:: RCC_CIR_HSIRDYC_BIT -.. doxygendefine:: RCC_CIR_LSERDYC_BIT -.. doxygendefine:: RCC_CIR_LSIRDYC_BIT -.. doxygendefine:: RCC_CIR_PLLRDYIE_BIT -.. doxygendefine:: RCC_CIR_HSERDYIE_BIT -.. doxygendefine:: RCC_CIR_HSIRDYIE_BIT -.. doxygendefine:: RCC_CIR_LSERDYIE_BIT -.. doxygendefine:: RCC_CIR_LSIRDYIE_BIT -.. doxygendefine:: RCC_CIR_CSSF_BIT -.. doxygendefine:: RCC_CIR_PLLRDYF_BIT -.. doxygendefine:: RCC_CIR_HSERDYF_BIT -.. doxygendefine:: RCC_CIR_HSIRDYF_BIT -.. doxygendefine:: RCC_CIR_LSERDYF_BIT -.. doxygendefine:: RCC_CIR_LSIRDYF_BIT - -.. doxygendefine:: RCC_CIR_CSSC -.. doxygendefine:: RCC_CIR_PLLRDYC -.. doxygendefine:: RCC_CIR_HSERDYC -.. doxygendefine:: RCC_CIR_HSIRDYC -.. doxygendefine:: RCC_CIR_LSERDYC -.. doxygendefine:: RCC_CIR_LSIRDYC -.. doxygendefine:: RCC_CIR_PLLRDYIE -.. doxygendefine:: RCC_CIR_HSERDYIE -.. doxygendefine:: RCC_CIR_HSIRDYIE -.. doxygendefine:: RCC_CIR_LSERDYIE -.. doxygendefine:: RCC_CIR_LSIRDYIE -.. doxygendefine:: RCC_CIR_CSSF -.. doxygendefine:: RCC_CIR_PLLRDYF -.. doxygendefine:: RCC_CIR_HSERDYF -.. doxygendefine:: RCC_CIR_HSIRDYF -.. doxygendefine:: RCC_CIR_LSERDYF -.. doxygendefine:: RCC_CIR_LSIRDYF - -APB2 peripheral reset register -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. doxygendefine:: RCC_APB2RSTR_TIM11RST_BIT -.. doxygendefine:: RCC_APB2RSTR_TIM10RST_BIT -.. doxygendefine:: RCC_APB2RSTR_TIM9RST_BIT -.. doxygendefine:: RCC_APB2RSTR_ADC3RST_BIT -.. doxygendefine:: RCC_APB2RSTR_USART1RST_BIT -.. doxygendefine:: RCC_APB2RSTR_TIM8RST_BIT -.. doxygendefine:: RCC_APB2RSTR_SPI1RST_BIT -.. doxygendefine:: RCC_APB2RSTR_TIM1RST_BIT -.. doxygendefine:: RCC_APB2RSTR_ADC2RST_BIT -.. doxygendefine:: RCC_APB2RSTR_ADC1RST_BIT -.. doxygendefine:: RCC_APB2RSTR_IOPGRST_BIT -.. doxygendefine:: RCC_APB2RSTR_IOPFRST_BIT -.. doxygendefine:: RCC_APB2RSTR_IOPERST_BIT -.. doxygendefine:: RCC_APB2RSTR_IOPDRST_BIT -.. doxygendefine:: RCC_APB2RSTR_IOPCRST_BIT -.. doxygendefine:: RCC_APB2RSTR_IOPBRST_BIT -.. doxygendefine:: RCC_APB2RSTR_IOPARST_BIT -.. doxygendefine:: RCC_APB2RSTR_AFIORST_BIT - -.. doxygendefine:: RCC_APB2RSTR_TIM11RST -.. doxygendefine:: RCC_APB2RSTR_TIM10RST -.. doxygendefine:: RCC_APB2RSTR_TIM9RST -.. doxygendefine:: RCC_APB2RSTR_ADC3RST -.. doxygendefine:: RCC_APB2RSTR_USART1RST -.. doxygendefine:: RCC_APB2RSTR_TIM8RST -.. doxygendefine:: RCC_APB2RSTR_SPI1RST -.. doxygendefine:: RCC_APB2RSTR_TIM1RST -.. doxygendefine:: RCC_APB2RSTR_ADC2RST -.. doxygendefine:: RCC_APB2RSTR_ADC1RST -.. doxygendefine:: RCC_APB2RSTR_IOPGRST -.. doxygendefine:: RCC_APB2RSTR_IOPFRST -.. doxygendefine:: RCC_APB2RSTR_IOPERST -.. doxygendefine:: RCC_APB2RSTR_IOPDRST -.. doxygendefine:: RCC_APB2RSTR_IOPCRST -.. doxygendefine:: RCC_APB2RSTR_IOPBRST -.. doxygendefine:: RCC_APB2RSTR_IOPARST -.. doxygendefine:: RCC_APB2RSTR_AFIORST - -APB1 peripheral reset register -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. doxygendefine:: RCC_APB1RSTR_DACRST_BIT -.. doxygendefine:: RCC_APB1RSTR_PWRRST_BIT -.. doxygendefine:: RCC_APB1RSTR_BKPRST_BIT -.. doxygendefine:: RCC_APB1RSTR_CANRST_BIT -.. doxygendefine:: RCC_APB1RSTR_USBRST_BIT -.. doxygendefine:: RCC_APB1RSTR_I2C2RST_BIT -.. doxygendefine:: RCC_APB1RSTR_I2C1RST_BIT -.. doxygendefine:: RCC_APB1RSTR_UART5RST_BIT -.. doxygendefine:: RCC_APB1RSTR_UART4RST_BIT -.. doxygendefine:: RCC_APB1RSTR_USART3RST_BIT -.. doxygendefine:: RCC_APB1RSTR_USART2RST_BIT -.. doxygendefine:: RCC_APB1RSTR_SPI3RST_BIT -.. doxygendefine:: RCC_APB1RSTR_SPI2RST_BIT -.. doxygendefine:: RCC_APB1RSTR_WWDRST_BIT -.. doxygendefine:: RCC_APB1RSTR_TIM14RST_BIT -.. doxygendefine:: RCC_APB1RSTR_TIM13RST_BIT -.. doxygendefine:: RCC_APB1RSTR_TIM12RST_BIT -.. doxygendefine:: RCC_APB1RSTR_TIM7RST_BIT -.. doxygendefine:: RCC_APB1RSTR_TIM6RST_BIT -.. doxygendefine:: RCC_APB1RSTR_TIM5RST_BIT -.. doxygendefine:: RCC_APB1RSTR_TIM4RST_BIT -.. doxygendefine:: RCC_APB1RSTR_TIM3RST_BIT -.. doxygendefine:: RCC_APB1RSTR_TIM2RST_BIT - -.. doxygendefine:: RCC_APB1RSTR_DACRST -.. doxygendefine:: RCC_APB1RSTR_PWRRST -.. doxygendefine:: RCC_APB1RSTR_BKPRST -.. doxygendefine:: RCC_APB1RSTR_CANRST -.. doxygendefine:: RCC_APB1RSTR_USBRST -.. doxygendefine:: RCC_APB1RSTR_I2C2RST -.. doxygendefine:: RCC_APB1RSTR_I2C1RST -.. doxygendefine:: RCC_APB1RSTR_UART5RST -.. doxygendefine:: RCC_APB1RSTR_UART4RST -.. doxygendefine:: RCC_APB1RSTR_USART3RST -.. doxygendefine:: RCC_APB1RSTR_USART2RST -.. doxygendefine:: RCC_APB1RSTR_SPI3RST -.. doxygendefine:: RCC_APB1RSTR_SPI2RST -.. doxygendefine:: RCC_APB1RSTR_WWDRST -.. doxygendefine:: RCC_APB1RSTR_TIM14RST -.. doxygendefine:: RCC_APB1RSTR_TIM13RST -.. doxygendefine:: RCC_APB1RSTR_TIM12RST -.. doxygendefine:: RCC_APB1RSTR_TIM7RST -.. doxygendefine:: RCC_APB1RSTR_TIM6RST -.. doxygendefine:: RCC_APB1RSTR_TIM5RST -.. doxygendefine:: RCC_APB1RSTR_TIM4RST -.. doxygendefine:: RCC_APB1RSTR_TIM3RST -.. doxygendefine:: RCC_APB1RSTR_TIM2RST - -AHB peripheral clock enable register -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. doxygendefine:: RCC_AHBENR_SDIOEN_BIT -.. doxygendefine:: RCC_AHBENR_FSMCEN_BIT -.. doxygendefine:: RCC_AHBENR_CRCEN_BIT -.. doxygendefine:: RCC_AHBENR_FLITFEN_BIT -.. doxygendefine:: RCC_AHBENR_SRAMEN_BIT -.. doxygendefine:: RCC_AHBENR_DMA2EN_BIT -.. doxygendefine:: RCC_AHBENR_DMA1EN_BIT - -.. doxygendefine:: RCC_AHBENR_SDIOEN -.. doxygendefine:: RCC_AHBENR_FSMCEN -.. doxygendefine:: RCC_AHBENR_CRCEN -.. doxygendefine:: RCC_AHBENR_FLITFEN -.. doxygendefine:: RCC_AHBENR_SRAMEN -.. doxygendefine:: RCC_AHBENR_DMA2EN -.. doxygendefine:: RCC_AHBENR_DMA1EN - -APB2 peripheral clock enable register -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +These are given as source code. Available register bit definitions +vary by target. -.. doxygendefine:: RCC_APB2ENR_TIM11EN_BIT -.. doxygendefine:: RCC_APB2ENR_TIM10EN_BIT -.. doxygendefine:: RCC_APB2ENR_TIM9EN_BIT -.. doxygendefine:: RCC_APB2ENR_ADC3EN_BIT -.. doxygendefine:: RCC_APB2ENR_USART1EN_BIT -.. doxygendefine:: RCC_APB2ENR_TIM8EN_BIT -.. doxygendefine:: RCC_APB2ENR_SPI1EN_BIT -.. doxygendefine:: RCC_APB2ENR_TIM1EN_BIT -.. doxygendefine:: RCC_APB2ENR_ADC2EN_BIT -.. doxygendefine:: RCC_APB2ENR_ADC1EN_BIT -.. doxygendefine:: RCC_APB2ENR_IOPGEN_BIT -.. doxygendefine:: RCC_APB2ENR_IOPFEN_BIT -.. doxygendefine:: RCC_APB2ENR_IOPEEN_BIT -.. doxygendefine:: RCC_APB2ENR_IOPDEN_BIT -.. doxygendefine:: RCC_APB2ENR_IOPCEN_BIT -.. doxygendefine:: RCC_APB2ENR_IOPBEN_BIT -.. doxygendefine:: RCC_APB2ENR_IOPAEN_BIT -.. doxygendefine:: RCC_APB2ENR_AFIOEN_BIT - -.. doxygendefine:: RCC_APB2ENR_TIM11EN -.. doxygendefine:: RCC_APB2ENR_TIM10EN -.. doxygendefine:: RCC_APB2ENR_TIM9EN -.. doxygendefine:: RCC_APB2ENR_ADC3EN -.. doxygendefine:: RCC_APB2ENR_USART1EN -.. doxygendefine:: RCC_APB2ENR_TIM8EN -.. doxygendefine:: RCC_APB2ENR_SPI1EN -.. doxygendefine:: RCC_APB2ENR_TIM1EN -.. doxygendefine:: RCC_APB2ENR_ADC2EN -.. doxygendefine:: RCC_APB2ENR_ADC1EN -.. doxygendefine:: RCC_APB2ENR_IOPGEN -.. doxygendefine:: RCC_APB2ENR_IOPFEN -.. doxygendefine:: RCC_APB2ENR_IOPEEN -.. doxygendefine:: RCC_APB2ENR_IOPDEN -.. doxygendefine:: RCC_APB2ENR_IOPCEN -.. doxygendefine:: RCC_APB2ENR_IOPBEN -.. doxygendefine:: RCC_APB2ENR_IOPAEN -.. doxygendefine:: RCC_APB2ENR_AFIOEN - -APB1 peripheral clock enable register -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. We need this include to avoid crashing Emacs's ReST parser. Yuck. + +.. include:: rcc-reg-bits.txt + +Deprecated Functionality +------------------------ -.. doxygendefine:: RCC_APB1ENR_DACEN_BIT -.. doxygendefine:: RCC_APB1ENR_PWREN_BIT -.. doxygendefine:: RCC_APB1ENR_BKPEN_BIT -.. doxygendefine:: RCC_APB1ENR_CANEN_BIT -.. doxygendefine:: RCC_APB1ENR_USBEN_BIT -.. doxygendefine:: RCC_APB1ENR_I2C2EN_BIT -.. doxygendefine:: RCC_APB1ENR_I2C1EN_BIT -.. doxygendefine:: RCC_APB1ENR_UART5EN_BIT -.. doxygendefine:: RCC_APB1ENR_UART4EN_BIT -.. doxygendefine:: RCC_APB1ENR_USART3EN_BIT -.. doxygendefine:: RCC_APB1ENR_USART2EN_BIT -.. doxygendefine:: RCC_APB1ENR_SPI3EN_BIT -.. doxygendefine:: RCC_APB1ENR_SPI2EN_BIT -.. doxygendefine:: RCC_APB1ENR_WWDEN_BIT -.. doxygendefine:: RCC_APB1ENR_TIM14EN_BIT -.. doxygendefine:: RCC_APB1ENR_TIM13EN_BIT -.. doxygendefine:: RCC_APB1ENR_TIM12EN_BIT -.. doxygendefine:: RCC_APB1ENR_TIM7EN_BIT -.. doxygendefine:: RCC_APB1ENR_TIM6EN_BIT -.. doxygendefine:: RCC_APB1ENR_TIM5EN_BIT -.. doxygendefine:: RCC_APB1ENR_TIM4EN_BIT -.. doxygendefine:: RCC_APB1ENR_TIM3EN_BIT -.. doxygendefine:: RCC_APB1ENR_TIM2EN_BIT - -.. doxygendefine:: RCC_APB1ENR_DACEN -.. doxygendefine:: RCC_APB1ENR_PWREN -.. doxygendefine:: RCC_APB1ENR_BKPEN -.. doxygendefine:: RCC_APB1ENR_CANEN -.. doxygendefine:: RCC_APB1ENR_USBEN -.. doxygendefine:: RCC_APB1ENR_I2C2EN -.. doxygendefine:: RCC_APB1ENR_I2C1EN -.. doxygendefine:: RCC_APB1ENR_UART5EN -.. doxygendefine:: RCC_APB1ENR_UART4EN -.. doxygendefine:: RCC_APB1ENR_USART3EN -.. doxygendefine:: RCC_APB1ENR_USART2EN -.. doxygendefine:: RCC_APB1ENR_SPI3EN -.. doxygendefine:: RCC_APB1ENR_SPI2EN -.. doxygendefine:: RCC_APB1ENR_WWDEN -.. doxygendefine:: RCC_APB1ENR_TIM14EN -.. doxygendefine:: RCC_APB1ENR_TIM13EN -.. doxygendefine:: RCC_APB1ENR_TIM12EN -.. doxygendefine:: RCC_APB1ENR_TIM7EN -.. doxygendefine:: RCC_APB1ENR_TIM6EN -.. doxygendefine:: RCC_APB1ENR_TIM5EN -.. doxygendefine:: RCC_APB1ENR_TIM4EN -.. doxygendefine:: RCC_APB1ENR_TIM3EN -.. doxygendefine:: RCC_APB1ENR_TIM2EN - -Backup domain control register -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. doxygendefine:: RCC_BDCR_BDRST_BIT -.. doxygendefine:: RCC_BDCR_RTCEN_BIT -.. doxygendefine:: RCC_BDCR_LSEBYP_BIT -.. doxygendefine:: RCC_BDCR_LSERDY_BIT -.. doxygendefine:: RCC_BDCR_LSEON_BIT - -.. doxygendefine:: RCC_BDCR_BDRST -.. doxygendefine:: RCC_BDCR_RTCEN -.. doxygendefine:: RCC_BDCR_RTCSEL -.. doxygendefine:: RCC_BDCR_RTCSEL_NONE -.. doxygendefine:: RCC_BDCR_RTCSEL_LSE -.. doxygendefine:: RCC_BDCR_RTCSEL_HSE -.. doxygendefine:: RCC_BDCR_LSEBYP -.. doxygendefine:: RCC_BDCR_LSERDY -.. doxygendefine:: RCC_BDCR_LSEON - -Control/status register -~~~~~~~~~~~~~~~~~~~~~~~ - -.. doxygendefine:: RCC_CSR_LPWRRSTF_BIT -.. doxygendefine:: RCC_CSR_WWDGRSTF_BIT -.. doxygendefine:: RCC_CSR_IWDGRSTF_BIT -.. doxygendefine:: RCC_CSR_SFTRSTF_BIT -.. doxygendefine:: RCC_CSR_PORRSTF_BIT -.. doxygendefine:: RCC_CSR_PINRSTF_BIT -.. doxygendefine:: RCC_CSR_RMVF_BIT -.. doxygendefine:: RCC_CSR_LSIRDY_BIT -.. doxygendefine:: RCC_CSR_LSION_BIT - -.. doxygendefine:: RCC_CSR_LPWRRSTF -.. doxygendefine:: RCC_CSR_WWDGRSTF -.. doxygendefine:: RCC_CSR_IWDGRSTF -.. doxygendefine:: RCC_CSR_SFTRSTF -.. doxygendefine:: RCC_CSR_PORRSTF -.. doxygendefine:: RCC_CSR_PINRSTF -.. doxygendefine:: RCC_CSR_RMVF -.. doxygendefine:: RCC_CSR_LSIRDY -.. doxygendefine:: RCC_CSR_LSION +.. _rcc-rcc_clk_init: +.. doxygenfunction:: stm32f1::rcc_clk_init + +To replace a call to ``rcc_clk_init()`` in order to set SYSCLK to PLL +driven by an external oscillator, you can use something like this, +which is portable except for the initialization of ``your_pll_cfg``:: + + /* You need to make this point to something valid for your target; see + * the documentation for rcc_configure_pll() for more details. */ + extern rcc_pll_cfg *your_pll_cfg; + + void pll_reconfigure() { + /* Turn on HSI using rcc_turn_on_clk() and wait for it to + * become ready by busy-waiting on rcc_is_clk_ready(). + * + * Switch to HSI to ensure we're not using the PLL while we + * reconfigure it. */ + rcc_turn_on_clk(RCC_CLK_HSI); + while (!rcc_is_clk_ready(RCC_CLK_HSI)) + ; + rcc_switch_sysclk(RCC_CLKSRC_HSI); + + /* Turn off HSE and the PLL, or we can't reconfigure it. */ + rcc_turn_off_clk(RCC_CLK_PLL); + rcc_turn_off_clk(RCC_CLK_HSE); + + /* Reconfigure the PLL. You can also perform any other + * prescaler management here. */ + rcc_configure_pll(your_pll_cfg); + + /* Turn on RCC_CLK_HSE. */ + rcc_turn_on_clk(RCC_CLK_HSE); + while (!rcc_is_clk_ready(RCC_CLK_HSE)) + ; + + /* Turn on RCC_CLK_PLL. */ + rcc_turn_on_clk(RCC_CLK_PLL); + while (!rcc_is_clk_ready(RCC_CLK_PLL)) + ; + + /* Finally, switch to the PLL. */ + rcc_switch_sysclk(RCC_CLKSRC_PLL); + } |