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