git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_ATSAM3S-EK2_Atmel_Studio/src/asf/common/services/clock/pll.h

   1 /**\r
   2  * \file\r
   3  *\r
   4  * \brief PLL management\r
   5  *\r
   6  * Copyright (c) 2010-2011 Atmel Corporation. All rights reserved.\r
   7  *\r
   8  * \asf_license_start\r
   9  *\r
  10  * \page License\r
  11  *\r
  12  * Redistribution and use in source and binary forms, with or without\r
  13  * modification, are permitted provided that the following conditions are met:\r
  14  *\r
  15  * 1. Redistributions of source code must retain the above copyright notice,\r
  16  *    this list of conditions and the following disclaimer.\r
  17  *\r
  18  * 2. Redistributions in binary form must reproduce the above copyright notice,\r
  19  *    this list of conditions and the following disclaimer in the documentation\r
  20  *    and/or other materials provided with the distribution.\r
  21  *\r
  22  * 3. The name of Atmel may not be used to endorse or promote products derived\r
  23  *    from this software without specific prior written permission.\r
  24  *\r
  25  * 4. This software may only be redistributed and used in connection with an\r
  26  *    Atmel microcontroller product.\r
  27  *\r
  28  * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED\r
  29  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF\r
  30  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE\r
  31  * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR\r
  32  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\r
  33  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS\r
  34  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\r
  35  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,\r
  36  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN\r
  37  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE\r
  38  * POSSIBILITY OF SUCH DAMAGE.\r
  39  *\r
  40  * \asf_license_stop\r
  41  *\r
  42  */\r
  43 #ifndef CLK_PLL_H_INCLUDED\r
  44 #define CLK_PLL_H_INCLUDED\r
  45 \r
  46 #include "parts.h"\r
  47 #include "conf_clock.h"\r
  48 \r
  49 #if SAM3S\r
  50 # include "sam3s/pll.h"\r
  51 #elif SAM3XA\r
  52 # include "sam3x/pll.h"\r
  53 #elif SAM3U\r
  54 # include "sam3u/pll.h"\r
  55 #elif SAM3N\r
  56 # include "sam3n/pll.h"\r
  57 #elif SAM4S\r
  58 # include "sam4s/pll.h"\r
  59 #elif (UC3A0 || UC3A1)\r
  60 # include "uc3a0_a1/pll.h"\r
  61 #elif UC3A3\r
  62 # include "uc3a3_a4/pll.h"\r
  63 #elif UC3B\r
  64 # include "uc3b0_b1/pll.h"\r
  65 #elif UC3C\r
  66 # include "uc3c/pll.h"\r
  67 #elif UC3D\r
  68 # include "uc3d/pll.h"\r
  69 #elif (UC3L0128 || UC3L0256 || UC3L3_L4)\r
  70 # include "uc3l/pll.h"\r
  71 #elif XMEGA\r
  72 # include "xmega/pll.h"\r
  73 #else\r
  74 # error Unsupported chip type\r
  75 #endif\r
  76 \r
  77 /**\r
  78  * \ingroup clk_group\r
  79  * \defgroup pll_group PLL Management\r
  80  *\r
  81  * This group contains functions and definitions related to configuring\r
  82  * and enabling/disabling on-chip PLLs. A PLL will take an input signal\r
  83  * (the \em source), optionally divide the frequency by a configurable\r
  84  * \em divider, and then multiply the frequency by a configurable \em\r
  85  * multiplier.\r
  86  *\r
  87  * Some devices don't support input dividers; specifying any other\r
  88  * divisor than 1 on these devices will result in an assertion failure.\r
  89  * Other devices may have various restrictions to the frequency range of\r
  90  * the input and output signals.\r
  91  *\r
  92  * \par Example: Setting up PLL0 with default parameters\r
  93  *\r
  94  * The following example shows how to configure and enable PLL0 using\r
  95  * the default parameters specified using the configuration symbols\r
  96  * listed above.\r
  97  * \code\r
  98         pll_enable_config_defaults(0); \endcode\r
  99  *\r
 100  * To configure, enable PLL0 using the default parameters and to disable\r
 101  * a specific feature like Wide Bandwidth Mode (a UC3A3-specific\r
 102  * PLL option.), you can use this initialization process.\r
 103  * \code\r
 104         struct pll_config pllcfg;\r
 105         if (pll_is_locked(pll_id)) {\r
 106                 return; // Pll already running\r
 107         }\r
 108         pll_enable_source(CONFIG_PLL0_SOURCE);\r
 109         pll_config_defaults(&pllcfg, 0);\r
 110         pll_config_set_option(&pllcfg, PLL_OPT_WBM_DISABLE);\r
 111         pll_enable(&pllcfg, 0);\r
 112         pll_wait_for_lock(0); \endcode\r
 113  *\r
 114  * When the last function call returns, PLL0 is ready to be used as the\r
 115  * main system clock source.\r
 116  *\r
 117  * \section pll_group_config Configuration Symbols\r
 118  *\r
 119  * Each PLL has a set of default parameters determined by the following\r
 120  * configuration symbols in the application's configuration file:\r
 121  *   - \b CONFIG_PLLn_SOURCE: The default clock source connected to the\r
 122  *     input of PLL \a n. Must be one of the values defined by the\r
 123  *     #pll_source enum.\r
 124  *   - \b CONFIG_PLLn_MUL: The default multiplier (loop divider) of PLL\r
 125  *     \a n.\r
 126  *   - \b CONFIG_PLLn_DIV: The default input divider of PLL \a n.\r
 127  *\r
 128  * These configuration symbols determine the result of calling\r
 129  * pll_config_defaults() and pll_get_default_rate().\r
 130  *\r
 131  * @{\r
 132  */\r
 133 \r
 134 //! \name Chip-specific PLL characteristics\r
 135 //@{\r
 136 /**\r
 137  * \def PLL_MAX_STARTUP_CYCLES\r
 138  * \brief Maximum PLL startup time in number of slow clock cycles\r
 139  */\r
 140 /**\r
 141  * \def NR_PLLS\r
 142  * \brief Number of on-chip PLLs\r
 143  */\r
 144 \r
 145 /**\r
 146  * \def PLL_MIN_HZ\r
 147  * \brief Minimum frequency that the PLL can generate\r
 148  */\r
 149 /**\r
 150  * \def PLL_MAX_HZ\r
 151  * \brief Maximum frequency that the PLL can generate\r
 152  */\r
 153 /**\r
 154  * \def PLL_NR_OPTIONS\r
 155  * \brief Number of PLL option bits\r
 156  */\r
 157 //@}\r
 158 \r
 159 /**\r
 160  * \enum pll_source\r
 161  * \brief PLL clock source\r
 162  */\r
 163 \r
 164 //! \name PLL configuration\r
 165 //@{\r
 166 \r
 167 /**\r
 168  * \struct pll_config\r
 169  * \brief Hardware-specific representation of PLL configuration.\r
 170  *\r
 171  * This structure contains one or more device-specific values\r
 172  * representing the current PLL configuration. The contents of this\r
 173  * structure is typically different from platform to platform, and the\r
 174  * user should not access any fields except through the PLL\r
 175  * configuration API.\r
 176  */\r
 177 \r
 178 /**\r
 179  * \fn void pll_config_init(struct pll_config *cfg,\r
 180  *              enum pll_source src, unsigned int div, unsigned int mul)\r
 181  * \brief Initialize PLL configuration from standard parameters.\r
 182  *\r
 183  * \note This function may be defined inline because it is assumed to be\r
 184  * called very few times, and usually with constant parameters. Inlining\r
 185  * it will in such cases reduce the code size significantly.\r
 186  *\r
 187  * \param cfg The PLL configuration to be initialized.\r
 188  * \param src The oscillator to be used as input to the PLL.\r
 189  * \param div PLL input divider.\r
 190  * \param mul PLL loop divider (i.e. multiplier).\r
 191  *\r
 192  * \return A configuration which will make the PLL run at\r
 193  * (\a mul / \a div) times the frequency of \a src\r
 194  */\r
 195 /**\r
 196  * \def pll_config_defaults(cfg, pll_id)\r
 197  * \brief Initialize PLL configuration using default parameters.\r
 198  *\r
 199  * After this function returns, \a cfg will contain a configuration\r
 200  * which will make the PLL run at (CONFIG_PLLx_MUL / CONFIG_PLLx_DIV)\r
 201  * times the frequency of CONFIG_PLLx_SOURCE.\r
 202  *\r
 203  * \param cfg The PLL configuration to be initialized.\r
 204  * \param pll_id Use defaults for this PLL.\r
 205  */\r
 206 /**\r
 207  * \def pll_get_default_rate(pll_id)\r
 208  * \brief Get the default rate in Hz of \a pll_id\r
 209  */\r
 210 /**\r
 211  * \fn void pll_config_set_option(struct pll_config *cfg,\r
 212  *              unsigned int option)\r
 213  * \brief Set the PLL option bit \a option in the configuration \a cfg.\r
 214  *\r
 215  * \param cfg The PLL configuration to be changed.\r
 216  * \param option The PLL option bit to be set.\r
 217  */\r
 218 /**\r
 219  * \fn void pll_config_clear_option(struct pll_config *cfg,\r
 220  *              unsigned int option)\r
 221  * \brief Clear the PLL option bit \a option in the configuration \a cfg.\r
 222  *\r
 223  * \param cfg The PLL configuration to be changed.\r
 224  * \param option The PLL option bit to be cleared.\r
 225  */\r
 226 /**\r
 227  * \fn void pll_config_read(struct pll_config *cfg, unsigned int pll_id)\r
 228  * \brief Read the currently active configuration of \a pll_id.\r
 229  *\r
 230  * \param cfg The configuration object into which to store the currently\r
 231  * active configuration.\r
 232  * \param pll_id The ID of the PLL to be accessed.\r
 233  */\r
 234 /**\r
 235  * \fn void pll_config_write(const struct pll_config *cfg,\r
 236  *              unsigned int pll_id)\r
 237  * \brief Activate the configuration \a cfg on \a pll_id\r
 238  *\r
 239  * \param cfg The configuration object representing the PLL\r
 240  * configuration to be activated.\r
 241  * \param pll_id The ID of the PLL to be updated.\r
 242  */\r
 243 \r
 244 //@}\r
 245 \r
 246 //! \name Interaction with the PLL hardware\r
 247 //@{\r
 248 /**\r
 249  * \fn void pll_enable(const struct pll_config *cfg,\r
 250  *              unsigned int pll_id)\r
 251  * \brief Activate the configuration \a cfg and enable PLL \a pll_id.\r
 252  *\r
 253  * \param cfg The PLL configuration to be activated.\r
 254  * \param pll_id The ID of the PLL to be enabled.\r
 255  */\r
 256 /**\r
 257  * \fn void pll_disable(unsigned int pll_id)\r
 258  * \brief Disable the PLL identified by \a pll_id.\r
 259  *\r
 260  * After this function is called, the PLL identified by \a pll_id will\r
 261  * be disabled. The PLL configuration stored in hardware may be affected\r
 262  * by this, so if the caller needs to restore the same configuration\r
 263  * later, it should either do a pll_config_read() before disabling the\r
 264  * PLL, or remember the last configuration written to the PLL.\r
 265  *\r
 266  * \param pll_id The ID of the PLL to be disabled.\r
 267  */\r
 268 /**\r
 269  * \fn bool pll_is_locked(unsigned int pll_id)\r
 270  * \brief Determine whether the PLL is locked or not.\r
 271  *\r
 272  * \param pll_id The ID of the PLL to check.\r
 273  *\r
 274  * \retval true The PLL is locked and ready to use as a clock source\r
 275  * \retval false The PLL is not yet locked, or has not been enabled.\r
 276  */\r
 277 /**\r
 278  * \fn void pll_enable_source(enum pll_source src)\r
 279  * \brief Enable the source of the pll.\r
 280  * The source is enabled, if the source is not already running.\r
 281  *\r
 282  * \param src The ID of the PLL source to enable.\r
 283  */\r
 284 /**\r
 285  * \fn void pll_enable_config_defaults(unsigned int pll_id)\r
 286  * \brief Enable the pll with the default configuration.\r
 287  * PLL is enabled, if the PLL is not already locked.\r
 288  *\r
 289  * \param pll_id The ID of the PLL to enable.\r
 290  */\r
 291 \r
 292 /**\r
 293  * \brief Wait for PLL \a pll_id to become locked\r
 294  *\r
 295  * \todo Use a timeout to avoid waiting forever and hanging the system\r
 296  *\r
 297  * \param pll_id The ID of the PLL to wait for.\r
 298  *\r
 299  * \retval STATUS_OK The PLL is now locked.\r
 300  * \retval ERR_TIMEOUT Timed out waiting for PLL to become locked.\r
 301  */\r
 302 static inline int pll_wait_for_lock(unsigned int pll_id)\r
 303 {\r
 304         Assert(pll_id < NR_PLLS);\r
 305 \r
 306         while (!pll_is_locked(pll_id)) {\r
 307                 /* Do nothing */\r
 308         }\r
 309 \r
 310         return 0;\r
 311 }\r
 312 \r
 313 //@}\r
 314 //! @}\r
 315 \r
 316 #endif /* CLK_PLL_H_INCLUDED */\r