source: arduino-1-6-7/trunk/fuentes/arduino-ide-amd64/hardware/arduino/avr/firmwares/wifishield/wifi_dnld/src/SOFTWARE_FRAMEWORK/DRIVERS/PM/power_clocks_lib.h @ 4837

Last change on this file since 4837 was 4837, checked in by daduve, 2 years ago

Adding new version

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