1 /* This header file is part of the ATMEL AVR-UC3-SoftwareFramework-1.7.0 Release */
\r
3 /*This file has been prepared for Doxygen automatic documentation generation.*/
\r
4 /*! \file *********************************************************************
\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
11 * - Compiler: IAR EWAVR32 and GNU GCC for AVR32
\r
12 * - Supported devices: All AVR32 devices.
\r
15 * \author Atmel Corporation: http://www.atmel.com \n
\r
16 * Support and FAQ: http://support.atmel.no/
\r
18 *****************************************************************************/
\r
20 /* Copyright (c) 2009 Atmel Corporation. All rights reserved.
\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
25 * 1. Redistributions of source code must retain the above copyright notice, this
\r
26 * list of conditions and the following disclaimer.
\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
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
35 * 4. This software may only be redistributed and used in connection with an Atmel
\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
51 #ifndef _POWER_CLOCKS_LIB_H_
\r
52 #define _POWER_CLOCKS_LIB_H_
\r
58 #include <avr32/io.h>
\r
59 #include "compiler.h"
\r
61 #ifndef AVR32_PM_VERSION_RESETVALUE
\r
62 // Support for UC3A, UC3A3, UC3B parts.
\r
65 //! Device-specific data
\r
67 #include "pm_uc3l.h"
\r
68 #include "scif_uc3l.h"
\r
69 #include "flashcdw.h"
\r
71 #include "pm_uc3c.h"
\r
72 #include "scif_uc3c.h"
\r
77 /*! \name Clocks Management
\r
81 //! The different oscillators
\r
88 //! The different DFLLs
\r
95 //! Possible Main Clock Sources
\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
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
118 // Support for UC3C, UC3L parts.
\r
121 //! Main clock source selection (input argument).
\r
122 pcl_mainclk_t main_clk_src;
\r
124 //! Target CPU frequency (input/output argument).
\r
125 unsigned long cpu_f;
\r
127 //! Target PBA frequency (input/output argument).
\r
128 unsigned long pba_f;
\r
130 //! Target PBB frequency (input/output argument).
\r
131 unsigned long pbb_f;
\r
133 //! Target PBC frequency (input/output argument).
\r
134 unsigned long pbc_f;
\r
136 //! Oscillator 0's external crystal(or external clock) frequency (board dependant) (input argument).
\r
137 unsigned long osc0_f;
\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
142 //! DFLL target frequency (input/output argument) (NOTE: the bigger, the most stable the frequency)
\r
143 unsigned long dfll_f;
\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
152 //! Define "not supported" for the lib.
\r
153 #define PCL_NOT_SUPPORTED (-10000)
\r
155 /*! \brief Automatically configure the CPU, PBA, PBB, and HSB clocks
\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
164 * The CPU, HSB and PBA frequencies programmed after configuration are stored back into cpu_f and pba_f.
\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
172 * \param param pointer on the configuration structure.
\r
174 * \retval 0 Success.
\r
175 * \retval <0 The configuration cannot be performed.
\r
177 extern long int pcl_configure_clocks(pcl_freq_param_t *param);
\r
179 /*! \brief Automatically configure the CPU, PBA, PBB, and HSB clocks using the RCSYS osc as main source clock.
\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
184 * Supported main clock sources: PCL_MC_RCSYS
\r
186 * Supported synchronous clocks frequencies:
\r
187 * 115200Hz, 57600Hz, 28800Hz, 14400Hz, 7200Hz, 3600Hz, 1800Hz, 900Hz, 450Hz.
\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
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
198 * \param param pointer on the configuration structure.
\r
200 * \retval 0 Success.
\r
201 * \retval <0 The configuration cannot be performed.
\r
203 extern long int pcl_configure_clocks_rcsys(pcl_freq_param_t *param);
\r
205 /*! \brief Automatically configure the CPU, PBA, PBB, and HSB clocks using the RC120M osc as main source clock.
\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
210 * Supported main clock sources: PCL_MC_RC120M
\r
212 * Supported synchronous clocks frequencies:
\r
213 * 30MHz, 15MHz, 7.5MHz, 3.75MHz, 1.875MHz, 937.5kHz, 468.75kHz.
\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
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
224 * \param param pointer on the configuration structure.
\r
226 * \retval 0 Success.
\r
227 * \retval <0 The configuration cannot be performed.
\r
229 extern long int pcl_configure_clocks_rc120m(pcl_freq_param_t *param);
\r
231 /*! \brief Automatically configure the CPU, PBA, PBB, and HSB clocks using the OSC0 osc as main source clock
\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
238 * Supported main clock sources: PCL_MC_OSC0
\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
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
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
253 * \param param pointer on the configuration structure.
\r
255 * \retval 0 Success.
\r
256 * \retval <0 The configuration cannot be performed.
\r
258 extern long int pcl_configure_clocks_osc0(pcl_freq_param_t *param);
\r
260 /*! \brief Automatically configure the CPU, PBA, PBB, and HSB clocks using the DFLL0 as main source clock
\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
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
271 * Supported main clock sources: PCL_MC_DFLL0
\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
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
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
286 * \param param pointer on the configuration structure.
\r
288 * \retval 0 Success.
\r
289 * \retval <0 The configuration cannot be performed.
\r
291 extern long int pcl_configure_clocks_dfll0(pcl_freq_param_t *param);
\r
293 /*! \brief Switch the main clock source to Osc0 configured in crystal mode
\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
300 * \retval 0 Success.
\r
301 * \retval <0 An error occured.
\r
303 extern long int pcl_switch_to_osc(pcl_osc_t osc, unsigned int fcrystal, unsigned int startup);
\r
305 /*! \brief Enable the clock of a module.
\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
313 * \retval 0 Success.
\r
314 * \retval <0 An error occured.
\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
320 // Implementation for UC3C, UC3L parts.
\r
321 #define pcl_enable_module(module) pm_enable_module(module)
\r
324 /*! \brief Disable the clock of a module.
\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
332 * \retval 0 Success.
\r
333 * \retval <0 An error occured.
\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
339 // Implementation for UC3C, UC3L parts.
\r
340 #define pcl_disable_module(module) pm_disable_module(module)
\r
343 /*! \brief Configure the USB Clock
\r
347 * \retval 0 Success.
\r
348 * \retval <0 An error occured.
\r
350 extern long int pcl_configure_usb_clock(void);
\r
354 /*! \name Power Management
\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
361 * \return The content of the chosen GPLP register.
\r
363 extern unsigned long pcl_read_gplp(unsigned long gplp);
\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
371 extern void pcl_write_gplp(unsigned long gplp, unsigned long value);
\r
379 #endif // _POWER_CLOCKS_LIB_H_
\r