From 06620040aacdc0e88ee2fcc3cfa379ceea2032a9 Mon Sep 17 00:00:00 2001 From: Ken Sarkies Date: Mon, 28 May 2012 21:38:55 +0930 Subject: [PATCH] Header files for Doxygen group structure, layout changes to headings, example markup in stm32f1/ rcc --- Doxyfile | 8 +- DoxygenLayout.xml | 185 ++++++++++++++++++++++ include/libopencm3/cm3/common.h | 16 -- include/libopencm3/cm3/docmain.h | 64 ++++++++ include/libopencm3/stm32/f1/doc-stm32f1.h | 13 ++ include/libopencm3/stm32/f1/rcc.h | 39 +++++ lib/stm32/f1/rcc.c | 56 ++++++- 7 files changed, 358 insertions(+), 23 deletions(-) create mode 100644 DoxygenLayout.xml create mode 100644 include/libopencm3/cm3/docmain.h create mode 100644 include/libopencm3/stm32/f1/doc-stm32f1.h diff --git a/Doxyfile b/Doxyfile index e5b6a387..a6f6985e 100644 --- a/Doxyfile +++ b/Doxyfile @@ -640,7 +640,7 @@ RECURSIVE = YES # excluded from the INPUT source files. This way you can easily exclude a # subdirectory from a directory tree whose root is specified with the INPUT tag. -EXCLUDE = +EXCLUDE = # The EXCLUDE_SYMLINKS tag can be used select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded @@ -654,7 +654,7 @@ EXCLUDE_SYMLINKS = NO # against the file with absolute path, so to exclude all test directories # for example use the pattern */test/* -EXCLUDE_PATTERNS = +EXCLUDE_PATTERNS = */*.d # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the @@ -1079,12 +1079,12 @@ ENUM_VALUES_PER_LINE = 4 # JavaScript, DHTML, CSS and frames is required (i.e. any modern browser). # Windows users are probably better off using the HTML help feature. -GENERATE_TREEVIEW = NO +GENERATE_TREEVIEW = YES # By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories, # and Class Hierarchy pages using a tree view instead of an ordered list. -USE_INLINE_TREES = NO +USE_INLINE_TREES = YES # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be # used to set the initial width (in pixels) of the frame in which the tree diff --git a/DoxygenLayout.xml b/DoxygenLayout.xml new file mode 100644 index 00000000..1a3be6ff --- /dev/null +++ b/DoxygenLayout.xml @@ -0,0 +1,185 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/include/libopencm3/cm3/common.h b/include/libopencm3/cm3/common.h index dc3e433b..06102580 100644 --- a/include/libopencm3/cm3/common.h +++ b/include/libopencm3/cm3/common.h @@ -38,20 +38,4 @@ typedef uint64_t u64; #define MMIO32(addr) (*(volatile u32 *)(addr)) #define MMIO64(addr) (*(volatile u64 *)(addr)) -/* Main page for the doxygen-generated documentation: */ - -/** - * @mainpage libopencm3 Developer Documentation - * - * The libopencm3 project (previously known as libopenstm32) aims to create - * a free/libre/open-source (GPL v3, or later) firmware library for various - * ARM Cortex-M3 microcontrollers, including ST STM32, Toshiba TX03, - * Atmel SAM3U, NXP LPC1000 and others. - * - * @par "" - * - * See the libopencm3 wiki for - * more information. - */ - #endif diff --git a/include/libopencm3/cm3/docmain.h b/include/libopencm3/cm3/docmain.h new file mode 100644 index 00000000..865b6ea1 --- /dev/null +++ b/include/libopencm3/cm3/docmain.h @@ -0,0 +1,64 @@ +/** + * @mainpage libopencm3 Developer Documentation + * + * The libopencm3 project (previously known as libopenstm32) aims to create + * a free/libre/open-source (GPL v3, or later) firmware library for various + * ARM Cortex-M3 microcontrollers, including ST STM32, Toshiba TX03, + * Atmel SAM3U, NXP LPC1000 and others. + * + * @par "" + * + * See the libopencm3 wiki for + * more information. + +LGPL License Terms @ref lgpl_license + +*/ + +/** @page lgpl_license libopencm3 License + +libopencm3 is free software: you can redistribute it and/or modify +it under the terms of the GNU Lesser General Public License as published by the Free +Software Foundation, either version 3 of the License, or (at your option) any +later version. + +libopencm3 is distributed in the hope that it will be useful, but WITHOUT ANY +WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A +PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public License along with this +program. If not, see . + +*/ + +/** @defgroup LM3S +Libraries for Texas instruments LM3S series. +*/ + +/** @defgroup LPC13xx +Libraries for NXP Semiconductor LPC13xx series. +*/ + +/** @defgroup LPC17xx +Libraries for NXP Semiconductor LPC17xx series. +*/ + +/** @defgroup STM32F +Libraries for ST Microelectronics STM32F series. +*/ + +/** @defgroup STM32F1xx +@ingroup STM32F +Libraries for ST Microelectronics STM32F1xx series. +*/ + +/** @defgroup STM32F2xx +@ingroup STM32F +Libraries for ST Microelectronics STM32F2xx series. +*/ + +/** @defgroup STM32F4xx +@ingroup STM32F +Libraries for ST Microelectronics STM32F4xx series. +*/ + diff --git a/include/libopencm3/stm32/f1/doc-stm32f1.h b/include/libopencm3/stm32/f1/doc-stm32f1.h new file mode 100644 index 00000000..33bae3a6 --- /dev/null +++ b/include/libopencm3/stm32/f1/doc-stm32f1.h @@ -0,0 +1,13 @@ +/** @defgroup STM32F1xx_defines + +@brief Defined Constants and Types for the STM32F1xx series + +@ingroup STM32F1xx + +@version 1.0.0 + +@date 24 May 2012 + +LGPL License Terms @ref lgpl_license + */ + diff --git a/include/libopencm3/stm32/f1/rcc.h b/include/libopencm3/stm32/f1/rcc.h index 9cbe1e76..3d199a3a 100644 --- a/include/libopencm3/stm32/f1/rcc.h +++ b/include/libopencm3/stm32/f1/rcc.h @@ -1,3 +1,27 @@ +/** @file + +@ingroup STM32F1xx + +@brief libopencm3 STM32F1xx Reset and Clock Control + +@version 1.0.0 + +@author @htmlonly © @endhtmlonly 2009 Federico Ruiz-Ugalde \ +@author @htmlonly © @endhtmlonly 2009 Uwe Hermann + +@date 18 May 2012 + +LGPL License Terms @ref lgpl_license + */ +/** @defgroup STM32F1xx_rcc_defines + +@brief Defined Constants and Types for the STM32F1xx Reset and Clock Control + +@ingroup STM32F1xx_defines + +LGPL License Terms @ref lgpl_license + + */ /* * This file is part of the libopencm3 project. * @@ -230,6 +254,10 @@ /* --- RCC_AHBENR values --------------------------------------------------- */ +/** @defgroup rcc_ahbenr_en RCC_AHBENR enable values +@ingroup STM32F1xx_rcc_defines + +@{*/ #define RCC_AHBENR_ETHMACENRX (1 << 16) #define RCC_AHBENR_ETHMACENTX (1 << 15) #define RCC_AHBENR_ETHMACEN (1 << 14) @@ -241,9 +269,14 @@ #define RCC_AHBENR_SRAMEN (1 << 2) #define RCC_AHBENR_DMA2EN (1 << 1) #define RCC_AHBENR_DMA1EN (1 << 0) +/*@}*/ /* --- RCC_APB2ENR values -------------------------------------------------- */ +/** @defgroup rcc_apb2enr_en RCC_APB2ENR enable values +@ingroup STM32F1xx_rcc_defines + +@{*/ #define RCC_APB2ENR_ADC3EN (1 << 15) /* (XX) */ #define RCC_APB2ENR_USART1EN (1 << 14) #define RCC_APB2ENR_TIM8EN (1 << 13) /* (XX) */ @@ -259,9 +292,14 @@ #define RCC_APB2ENR_IOPBEN (1 << 3) #define RCC_APB2ENR_IOPAEN (1 << 2) #define RCC_APB2ENR_AFIOEN (1 << 0) +/*@}*/ /* --- RCC_APB1ENR values -------------------------------------------------- */ +/** @defgroup rcc_apb1enr_en RCC_APB1ENR enable values +@ingroup STM32F1xx_rcc_defines + +@{*/ #define RCC_APB1ENR_DACEN (1 << 29) #define RCC_APB1ENR_PWREN (1 << 28) #define RCC_APB1ENR_BKPEN (1 << 27) @@ -284,6 +322,7 @@ #define RCC_APB1ENR_TIM4EN (1 << 2) #define RCC_APB1ENR_TIM3EN (1 << 1) #define RCC_APB1ENR_TIM2EN (1 << 0) +/*@}*/ /* --- RCC_BDCR values ----------------------------------------------------- */ diff --git a/lib/stm32/f1/rcc.c b/lib/stm32/f1/rcc.c index 8945e80a..e7000746 100644 --- a/lib/stm32/f1/rcc.c +++ b/lib/stm32/f1/rcc.c @@ -1,8 +1,34 @@ +/** @file + +@ingroup STM32F1xx + +@brief libopencm3 STM32F1xx Reset and Clock Control + +@version 1.0.0 + +@author @htmlonly © @endhtmlonly 2009 Federico Ruiz-Ugalde \ +@author @htmlonly © @endhtmlonly 2009 Uwe Hermann +@author @htmlonly © @endhtmlonly 2010 Thomas Otto + +@date 18 May 2012 + +This library supports the Reset and Clock +Control System in the STM32F1xx series of ARM Cortex Microcontrollers +by ST Microelectronics. + +Clock settings and resets for many peripherals are given here rather than in the +peripheral library. + +The library also provides a number of common configurations for the processor +system clock. Not all possible configurations are given here. + +@bugs None known + +LGPL License Terms @ref lgpl_license + */ /* * This file is part of the libopencm3 project. * - * Copyright (C) 2009 Federico Ruiz-Ugalde - * Copyright (C) 2009 Uwe Hermann * Copyright (C) 2010 Thomas Otto * * This library is free software: you can redistribute it and/or modify @@ -19,13 +45,23 @@ * along with this library. If not, see . */ + #include #include -/* Set the default ppre1 and ppre2 peripheral clock frequencies after reset. */ +/** Default ppre1 peripheral clock frequency after reset. */ u32 rcc_ppre1_frequency = 8000000; +/** Default ppre2 peripheral clock frequency after reset. */ u32 rcc_ppre2_frequency = 8000000; +//----------------------------------------------------------------------------- +/** @brief RCC Clear the Oscillator Ready Interrupt + +Clear the interrupt flag that was set when a clock oscillator became ready to use. + +@param[in] enum ::osc_t. Oscillator ID +*/ + void rcc_osc_ready_int_clear(osc_t osc) { switch (osc) { @@ -230,6 +266,20 @@ void rcc_osc_bypass_disable(osc_t osc) } } +//----------------------------------------------------------------------------- +/** @brief RCC Enable a peripheral clock. + +Enable the clock on a particular peripheral. Several peripherals could be +enabled simultaneously if they are controlled by the same register. + +@param[in] Unsigned int32 *reg. Pointer to a Clock Enable Register + (either RCC_AHBENR, RCC_APB1RENR or RCC_APB2RENR) +@param[in] Unsigned int32 en. OR of all enables to be set +@li If register is RCC_AHBER, from @ref rcc_ahbenr_en +@li If register is RCC_APB1RENR, from @ref rcc_apb1enr_en +@li If register is RCC_APB2RENR, from @ref rcc_apb2enr_en +*/ + void rcc_peripheral_enable_clock(volatile u32 *reg, u32 en) { *reg |= en;