git.sur5r.net Git - freertos/blob - Demo/AVR32_UC3A_GCC/Atmel_SW_Framework/DRIVERS/PM/power_clocks_lib.h

   1 /* This header file is part of the ATMEL AVR-UC3-SoftwareFramework-1.7.0 Release */\r
   2
   3 /*This file has been prepared for Doxygen automatic documentation generation.*/\r
   4 /*! \file *********************************************************************\r
   5  *\r
   6  * \brief High-level library abstracting features such as oscillators/pll/dfll\r
   7  *        configuration, clock configuration, System-sensible parameters\r
   8  *        configuration, buses clocks configuration, sleep mode, reset.\r
   9  *\r
  10  *\r
  11  * - Compiler:           IAR EWAVR32 and GNU GCC for AVR32\r
  12  * - Supported devices:  All AVR32 devices.\r
  13  * - AppNote:\r
  14  *\r
  15  * \author               Atmel Corporation: http://www.atmel.com \n\r
  16  *                       Support and FAQ: http://support.atmel.no/\r
  17  *\r
  18  *****************************************************************************/\r
  19 \r
  20 /* Copyright (c) 2009 Atmel Corporation. All rights reserved.\r
  21  *\r
  22  * Redistribution and use in source and binary forms, with or without\r
  23  * modification, are permitted provided that the following conditions are met:\r
  24  *\r
  25  * 1. Redistributions of source code must retain the above copyright notice, this\r
  26  * list of conditions and the following disclaimer.\r
  27  *\r
  28  * 2. Redistributions in binary form must reproduce the above copyright notice,\r
  29  * this list of conditions and the following disclaimer in the documentation\r
  30  * and/or other materials provided with the distribution.\r
  31  *\r
  32  * 3. The name of Atmel may not be used to endorse or promote products derived\r
  33  * from this software without specific prior written permission.\r
  34  *\r
  35  * 4. This software may only be redistributed and used in connection with an Atmel\r
  36  * AVR product.\r
  37  *\r
  38  * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED\r
  39  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF\r
  40  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE\r
  41  * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR\r
  42  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\r
  43  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;\r
  44  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND\r
  45  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\r
  46  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\r
  47  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE\r
  48  *\r
  49  */\r
  50 \r
  51 #ifndef _POWER_CLOCKS_LIB_H_\r
  52 #define _POWER_CLOCKS_LIB_H_\r
  53 \r
  54 #ifdef __cplusplus\r
  55 extern "C" {\r
  56 #endif\r
  57 \r
  58 #include <avr32/io.h>\r
  59 #include "compiler.h"\r
  60 \r
  61 #ifndef AVR32_PM_VERSION_RESETVALUE\r
  62 // Support for UC3A, UC3A3, UC3B parts.\r
  63   #include "pm.h"\r
  64 #else\r
  65 //! Device-specific data\r
  66 #if UC3L \r
  67   #include "pm_uc3l.h"\r
  68   #include "scif_uc3l.h"\r
  69   #include "flashcdw.h"\r
  70 #elif UC3C\r
  71   #include "pm_uc3c.h"\r
  72   #include "scif_uc3c.h"\r
  73   #include "flashc.h"\r
  74 #endif\r
  75 #endif\r
  76 \r
  77 /*! \name Clocks Management\r
  78  */\r
  79 //! @{\r
  80 \r
  81 //! The different oscillators\r
  82 typedef enum\r
  83 {\r
  84   PCL_OSC0  = 0,\r
  85   PCL_OSC1  = 1\r
  86 } pcl_osc_t;\r
  87 \r
  88 //! The different DFLLs\r
  89 typedef enum\r
  90 {\r
  91   PCL_DFLL0  = 0,\r
  92   PCL_DFLL1  = 1\r
  93 } pcl_dfll_t;\r
  94 \r
  95 //! Possible Main Clock Sources\r
  96 typedef enum\r
  97 {\r
  98   PCL_MC_RCSYS,      // Default main clock source, supported by all (aka Slow Clock)\r
  99   PCL_MC_OSC0,       // Supported by all\r
 100   PCL_MC_OSC1,       // Supported by UC3C only\r
 101   PCL_MC_OSC0_PLL0,  // Supported by UC3A, UC3B, UC3A3, UC3C (the main clock source is PLL0 with OSC0 as reference)\r
 102   PCL_MC_OSC1_PLL0,  // Supported by UC3A, UC3B, UC3A3, UC3C (the main clock source is PLL0 with OSC1 as reference)\r
 103   PCL_MC_OSC0_PLL1,  // Supported by UC3C  (the main clock source is PLL1 with OSC0 as reference)\r
 104   PCL_MC_OSC1_PLL1,  // Supported by UC3C  (the main clock source is PLL1 with OSC1 as reference)\r
 105   PCL_MC_DFLL0,      // Supported by UC3L\r
 106   PCL_MC_DFLL1,      // Not supported yet\r
 107   PCL_MC_RC120M,     // Supported by UC3L, UC3C\r
 108   PCL_MC_RC8M,       // Supported by UC3C\r
 109   PCL_MC_CRIPOSC     // Supported by UC3C\r
 110 } pcl_mainclk_t;\r
 111 \r
 112 //! Input and output parameters to configure clocks with pcl_configure_clocks().\r
 113 // NOTE: regarding the frequency settings, always abide by the datasheet rules and min & max supported frequencies.\r
 114 #ifndef AVR32_PM_VERSION_RESETVALUE\r
 115 // Support for UC3A, UC3A3, UC3B parts.\r
 116 #define pcl_freq_param_t  pm_freq_param_t // See pm.h\r
 117 #else\r
 118 // Support for UC3C, UC3L parts.\r
 119 typedef struct\r
 120 {\r
 121   //! Main clock source selection (input argument).\r
 122   pcl_mainclk_t main_clk_src;\r
 123 \r
 124   //! Target CPU frequency (input/output argument).\r
 125   unsigned long cpu_f;\r
 126 \r
 127   //! Target PBA frequency (input/output argument).\r
 128   unsigned long pba_f;\r
 129 \r
 130   //! Target PBB frequency (input/output argument).\r
 131   unsigned long pbb_f;\r
 132 \r
 133   //! Target PBC frequency (input/output argument).\r
 134   unsigned long pbc_f;\r
 135 \r
 136   //! Oscillator 0's external crystal(or external clock) frequency (board dependant) (input argument).\r
 137   unsigned long osc0_f;\r
 138 \r
 139   //! Oscillator 0's external crystal(or external clock) startup time: AVR32_PM_OSCCTRL0_STARTUP_x_RCOSC (input argument).\r
 140   unsigned long osc0_startup;\r
 141 \r
 142   //! DFLL target frequency (input/output argument) (NOTE: the bigger, the most stable the frequency)\r
 143   unsigned long dfll_f;\r
 144   \r
 145   //! Other parameters that might be necessary depending on the device (implementation-dependent).\r
 146   // For the UC3L DFLL setup, this parameter should be pointing to a structure of\r
 147   // type (scif_gclk_opt_t *).\r
 148   void *pextra_params;\r
 149 } pcl_freq_param_t;\r
 150 #endif\r
 151 \r
 152 //! Define "not supported" for the lib.\r
 153 #define PCL_NOT_SUPPORTED (-10000)\r
 154 \r
 155 /*! \brief Automatically configure the CPU, PBA, PBB, and HSB clocks\r
 156  *\r
 157  * This function needs some parameters stored in a pcl_freq_param_t structure:\r
 158  *  - main_clk_src is the id of the main clock source to use,\r
 159  *  - cpu_f and pba_f and pbb_f are the wanted frequencies,\r
 160  *  - osc0_f is the oscillator 0's external crystal (or external clock) on-board frequency (e.g. FOSC0),\r
 161  *  - osc0_startup is the oscillator 0's external crystal (or external clock) startup time (e.g. OSC0_STARTUP).\r
 162  *  - dfll_f is the target DFLL frequency to set-up if main_clk_src is the dfll.\r
 163  *\r
 164  * The CPU, HSB and PBA frequencies programmed after configuration are stored back into cpu_f and pba_f.\r
 165  *\r
 166  * \note: since it is dynamically computing the appropriate field values of the\r
 167  * configuration registers from the parameters structure, this function is not\r
 168  * optimal in terms of code size. For a code size optimal solution, it is better\r
 169  * to create a new function from pcl_configure_clocks() and modify it to use\r
 170  * preprocessor computation from pre-defined target frequencies.\r
 171  *\r
 172  * \param param    pointer on the configuration structure.\r
 173  *\r
 174  * \retval 0   Success.\r
 175  * \retval <0  The configuration cannot be performed.\r
 176  */\r
 177 extern long int pcl_configure_clocks(pcl_freq_param_t *param);\r
 178 \r
 179 /*! \brief Automatically configure the CPU, PBA, PBB, and HSB clocks using the RCSYS osc as main source clock.\r
 180  *\r
 181  * This function needs some parameters stored in a pcl_freq_param_t structure:\r
 182  *  - cpu_f and pba_f and pbb_f are the wanted frequencies\r
 183  *\r
 184  * Supported main clock sources: PCL_MC_RCSYS\r
 185  *\r
 186  * Supported synchronous clocks frequencies:\r
 187  * 115200Hz, 57600Hz, 28800Hz, 14400Hz, 7200Hz, 3600Hz, 1800Hz, 900Hz, 450Hz.\r
 188  *\r
 189  * \note: by default, this implementation doesn't perform thorough checks on the\r
 190  *        input parameters. To enable the checks, define AVR32SFW_INPUT_CHECK.\r
 191  *\r
 192  * \note: since it is dynamically computing the appropriate field values of the\r
 193  * configuration registers from the parameters structure, this function is not\r
 194  * optimal in terms of code size. For a code size optimal solution, it is better\r
 195  * to create a new function from pcl_configure_clocks_rcsys() and modify it to use\r
 196  * preprocessor computation from pre-defined target frequencies.\r
 197  *\r
 198  * \param param    pointer on the configuration structure.\r
 199  *\r
 200  * \retval 0   Success.\r
 201  * \retval <0  The configuration cannot be performed.\r
 202  */\r
 203 extern long int pcl_configure_clocks_rcsys(pcl_freq_param_t *param);\r
 204 \r
 205 /*! \brief Automatically configure the CPU, PBA, PBB, and HSB clocks using the RC120M osc as main source clock.\r
 206  *\r
 207  * This function needs some parameters stored in a pcl_freq_param_t structure:\r
 208  *  - cpu_f and pba_f and pbb_f are the wanted frequencies\r
 209  *\r
 210  * Supported main clock sources: PCL_MC_RC120M\r
 211  *\r
 212  * Supported synchronous clocks frequencies:\r
 213  * 30MHz, 15MHz, 7.5MHz, 3.75MHz, 1.875MHz, 937.5kHz, 468.75kHz.\r
 214  *\r
 215  * \note: by default, this implementation doesn't perform thorough checks on the\r
 216  *        input parameters. To enable the checks, define AVR32SFW_INPUT_CHECK.\r
 217  *\r
 218  * \note: since it is dynamically computing the appropriate field values of the\r
 219  * configuration registers from the parameters structure, this function is not\r
 220  * optimal in terms of code size. For a code size optimal solution, it is better\r
 221  * to create a new function from pcl_configure_clocks_rc120m() and modify it to\r
 222  * use preprocessor computation from pre-defined target frequencies.\r
 223  *\r
 224  * \param param    pointer on the configuration structure.\r
 225  *\r
 226  * \retval 0   Success.\r
 227  * \retval <0  The configuration cannot be performed.\r
 228  */\r
 229 extern long int pcl_configure_clocks_rc120m(pcl_freq_param_t *param);\r
 230 \r
 231 /*! \brief Automatically configure the CPU, PBA, PBB, and HSB clocks using the OSC0 osc as main source clock\r
 232  *\r
 233  * This function needs some parameters stored in a pcl_freq_param_t structure:\r
 234  *  - cpu_f and pba_f and pbb_f are the wanted frequencies,\r
 235  *  - osc0_f is the oscillator 0's external crystal (or external clock) on-board frequency (e.g. FOSC0),\r
 236  *  - osc0_startup is the oscillator 0's external crystal (or external clock) startup time (e.g. OSC0_STARTUP).\r
 237  *\r
 238  * Supported main clock sources: PCL_MC_OSC0\r
 239  *\r
 240  * Supported synchronous clocks frequencies:\r
 241  * (these obviously depend on the OSC0 frequency; we'll take 16MHz as an example)\r
 242  * 16MHz, 8MHz, 4MHz, 2MHz, 1MHz, 500kHz, 250kHz, 125kHz, 62.5kHz.\r
 243  *\r
 244  * \note: by default, this implementation doesn't perform thorough checks on the\r
 245  *        input parameters. To enable the checks, define AVR32SFW_INPUT_CHECK.\r
 246  *\r
 247  * \note: since it is dynamically computing the appropriate field values of the\r
 248  * configuration registers from the parameters structure, this function is not\r
 249  * optimal in terms of code size. For a code size optimal solution, it is better\r
 250  * to create a new function from pcl_configure_clocks_osc0() and modify it to use\r
 251  * preprocessor computation from pre-defined target frequencies.\r
 252  *\r
 253  * \param param    pointer on the configuration structure.\r
 254  *\r
 255  * \retval 0   Success.\r
 256  * \retval <0  The configuration cannot be performed.\r
 257  */\r
 258 extern long int pcl_configure_clocks_osc0(pcl_freq_param_t *param);\r
 259 \r
 260 /*! \brief Automatically configure the CPU, PBA, PBB, and HSB clocks using the DFLL0 as main source clock\r
 261  *\r
 262  * This function needs some parameters stored in a pcl_freq_param_t structure:\r
 263  *  - cpu_f and pba_f and pbb_f are the wanted frequencies,\r
 264  *  - dfll_f is the target DFLL frequency to set-up\r
 265  *\r
 266  * \note: when the DFLL0 is to be used as main source clock for the synchronous clocks,\r
 267  *  the target frequency of the DFLL should be chosen to be as high as possible\r
 268  *  within the specification range (for stability reasons); the target cpu and pbx\r
 269  *  frequencies will then be reached by appropriate division ratio.\r
 270  *\r
 271  * Supported main clock sources: PCL_MC_DFLL0\r
 272  *\r
 273  * Supported synchronous clocks frequencies:\r
 274  * (these obviously depend on the DFLL target frequency; we'll take 100MHz as an example)\r
 275  * 50MHz, 25MHz, 12.5MHz, 6.25MHz, 3.125MHz, 1562.5kHz, 781.25kHz, 390.625kHz.\r
 276  *\r
 277  * \note: by default, this implementation doesn't perform thorough checks on the\r
 278  *        input parameters. To enable the checks, define AVR32SFW_INPUT_CHECK.\r
 279  *\r
 280  * \note: since it is dynamically computing the appropriate field values of the\r
 281  * configuration registers from the parameters structure, this function is not\r
 282  * optimal in terms of code size. For a code size optimal solution, it is better\r
 283  * to create a new function from pcl_configure_clocks_dfll0() and modify it to\r
 284  * use preprocessor computation from pre-defined target frequencies.\r
 285  *\r
 286  * \param param    pointer on the configuration structure.\r
 287  *\r
 288  * \retval 0   Success.\r
 289  * \retval <0  The configuration cannot be performed.\r
 290  */\r
 291 extern long int pcl_configure_clocks_dfll0(pcl_freq_param_t *param);\r
 292 \r
 293 /*! \brief Switch the main clock source to Osc0 configured in crystal mode\r
 294  *\r
 295  * \param osc The oscillator to enable and switch to.\r
 296  * \param fcrystal Oscillator external crystal frequency (Hz)\r
 297  * \param startup Oscillator startup time.\r
 298  *\r
 299  * \return Status.\r
 300  *   \retval 0  Success.\r
 301  *   \retval <0 An error occured.\r
 302  */\r
 303 extern long int pcl_switch_to_osc(pcl_osc_t osc, unsigned int fcrystal, unsigned int startup);\r
 304 \r
 305 /*! \brief Enable the clock of a module.\r
 306  *\r
 307  * \param module The module to clock (use one of the defines in the part-specific\r
 308  * header file under "toolchain folder"/avr32/inc(lude)/avr32/; depending on the\r
 309  * clock domain, look for the sections "CPU clocks", "HSB clocks", "PBx clocks"\r
 310  * or look in the module section).\r
 311  *\r
 312  * \return Status.\r
 313  *   \retval 0  Success.\r
 314  *   \retval <0 An error occured.\r
 315  */\r
 316 #ifndef AVR32_PM_VERSION_RESETVALUE\r
 317 // Implementation for UC3A, UC3A3, UC3B parts.\r
 318 #define pcl_enable_module(module) pm_enable_module(&AVR32_PM, module)\r
 319 #else\r
 320 // Implementation for UC3C, UC3L parts.\r
 321 #define pcl_enable_module(module) pm_enable_module(module)\r
 322 #endif\r
 323 \r
 324 /*! \brief Disable the clock of a module.\r
 325  *\r
 326  * \param module The module to shut down (use one of the defines in the part-specific\r
 327  * header file under "toolchain folder"/avr32/inc(lude)/avr32/; depending on the\r
 328  * clock domain, look for the sections "CPU clocks", "HSB clocks", "PBx clocks"\r
 329  * or look in the module section).\r
 330  *\r
 331  * \return Status.\r
 332  *   \retval 0  Success.\r
 333  *   \retval <0 An error occured.\r
 334  */\r
 335 #ifndef AVR32_PM_VERSION_RESETVALUE\r
 336 // Implementation for UC3A, UC3A3, UC3B parts.\r
 337 #define pcl_disable_module(module)  pm_disable_module(&AVR32_PM, module)\r
 338 #else\r
 339 // Implementation for UC3C, UC3L parts.\r
 340 #define pcl_disable_module(module)  pm_disable_module(module)\r
 341 #endif\r
 342 \r
 343 /*! \brief Configure the USB Clock\r
 344  *\r
 345  *\r
 346  * \return Status.\r
 347  *   \retval 0  Success.\r
 348  *   \retval <0 An error occured.\r
 349  */\r
 350 extern long int pcl_configure_usb_clock(void);\r
 351 \r
 352 //! @}\r
 353 \r
 354 /*! \name Power Management\r
 355  */\r
 356 //! @{\r
 357 /*!\r
 358  * \brief Read the content of the GPLP registers\r
 359  * \param gplp GPLP register index (0,1,... depending on the number of GPLP registers for a given part)\r
 360  *\r
 361  * \return The content of the chosen GPLP register.\r
 362  */\r
 363 extern unsigned long pcl_read_gplp(unsigned long gplp);\r
 364 \r
 365 \r
 366 /*!\r
 367  * \brief Write into the GPLP registers\r
 368  * \param gplp GPLP register index (0,1,... depending on the number of GPLP registers for a given part)\r
 369  * \param value Value to write\r
 370  */\r
 371 extern void pcl_write_gplp(unsigned long gplp, unsigned long value);\r
 372 \r
 373 //! @}\r
 374 \r
 375 #ifdef __cplusplus\r
 376 }\r
 377 #endif\r
 378 \r
 379 #endif  // _POWER_CLOCKS_LIB_H_\r