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 */
pll_wait_for_lock(unsigned int pll_id)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