1 /***************************************************************************** 2 * 3 * \file 4 * 5 * \brief High-level library abstracting features such as oscillators/pll/dfll 6 * configuration, clock configuration, System-sensible parameters 7 * configuration, buses clocks configuration, sleep mode, reset. 8 * 9 * Copyright (c) 2014-2018 Microchip Technology Inc. and its subsidiaries. 10 * 11 * \asf_license_start 12 * 13 * \page License 14 * 15 * Subject to your compliance with these terms, you may use Microchip 16 * software and any derivatives exclusively with Microchip products. 17 * It is your responsibility to comply with third party license terms applicable 18 * to your use of third party software (including open source software) that 19 * may accompany Microchip software. 20 * 21 * THIS SOFTWARE IS SUPPLIED BY MICROCHIP "AS IS". NO WARRANTIES, 22 * WHETHER EXPRESS, IMPLIED OR STATUTORY, APPLY TO THIS SOFTWARE, 23 * INCLUDING ANY IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, 24 * AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL MICROCHIP BE 25 * LIABLE FOR ANY INDIRECT, SPECIAL, PUNITIVE, INCIDENTAL OR CONSEQUENTIAL 26 * LOSS, DAMAGE, COST OR EXPENSE OF ANY KIND WHATSOEVER RELATED TO THE 27 * SOFTWARE, HOWEVER CAUSED, EVEN IF MICROCHIP HAS BEEN ADVISED OF THE 28 * POSSIBILITY OR THE DAMAGES ARE FORESEEABLE. TO THE FULLEST EXTENT 29 * ALLOWED BY LAW, MICROCHIP'S TOTAL LIABILITY ON ALL CLAIMS IN ANY WAY 30 * RELATED TO THIS SOFTWARE WILL NOT EXCEED THE AMOUNT OF FEES, IF ANY, 31 * THAT YOU HAVE PAID DIRECTLY TO MICROCHIP FOR THIS SOFTWARE. 32 * 33 * \asf_license_stop 34 * 35 *****************************************************************************/ 36 /* 37 * Support and FAQ: visit <a href="https://www.microchip.com/support/">Microchip Support</a> 38 */ 39 40 41 #ifndef _POWER_CLOCKS_LIB_H_ 42 #define _POWER_CLOCKS_LIB_H_ 43 44 /** 45 * \defgroup group_avr32_drivers_pm_power_clocks_lib Power Clocks Library 46 * \ingroup group_avr32_drivers_pm 47 * 48 * \{ 49 */ 50 51 #ifdef __cplusplus 52 extern "C" { 53 #endif 54 55 #include <avr32/io.h> 56 #include "compiler.h" 57 58 #ifndef AVR32_PM_VERSION_RESETVALUE 59 // Support for UC3A, UC3A3, UC3B parts. 60 #include "pm.h" 61 #else 62 //! Device-specific data 63 #if UC3L 64 #include "pm_uc3l.h" 65 #include "scif_uc3l.h" 66 #include "flashcdw.h" 67 #elif UC3C 68 #include "pm_uc3c.h" 69 #include "scif_uc3c.h" 70 #include "flashc.h" 71 #elif UC3D 72 #include "pm_uc3d.h" 73 #include "scif_uc3d.h" 74 #include "flashcdw.h" 75 #endif 76 #endif 77 78 /*! \name Clocks Management 79 */ 80 //! @{ 81 82 //! The different oscillators 83 typedef enum 84 { 85 PCL_OSC0 = 0, 86 PCL_OSC1 = 1 87 } pcl_osc_t; 88 89 //! The different DFLLs 90 typedef enum 91 { 92 PCL_DFLL0 = 0, 93 PCL_DFLL1 = 1 94 } pcl_dfll_t; 95 96 //! Possible Main Clock Sources 97 typedef enum 98 { 99 PCL_MC_RCSYS, // Default main clock source, supported by all (aka Slow Clock) 100 PCL_MC_OSC0, // Supported by all 101 PCL_MC_OSC1, // Supported by UC3C only 102 PCL_MC_OSC0_PLL0, // Supported by UC3A, UC3B, UC3A3, UC3C (the main clock source is PLL0 with OSC0 as reference) 103 PCL_MC_OSC1_PLL0, // Supported by UC3A, UC3B, UC3A3, UC3C (the main clock source is PLL0 with OSC1 as reference) 104 PCL_MC_OSC0_PLL1, // Supported by UC3C (the main clock source is PLL1 with OSC0 as reference) 105 PCL_MC_OSC1_PLL1, // Supported by UC3C (the main clock source is PLL1 with OSC1 as reference) 106 PCL_MC_DFLL0, // Supported by UC3L 107 PCL_MC_DFLL1, // Not supported yet 108 PCL_MC_RC120M, // Supported by UC3L, UC3C 109 PCL_MC_RC8M, // Supported by UC3C 110 PCL_MC_CRIPOSC // Supported by UC3C 111 } pcl_mainclk_t; 112 113 //! Input and output parameters to configure clocks with pcl_configure_clocks(). 114 // NOTE: regarding the frequency settings, always abide by the datasheet rules and min & max supported frequencies. 115 #ifndef AVR32_PM_VERSION_RESETVALUE 116 // Support for UC3A, UC3A3, UC3B parts. 117 #define pcl_freq_param_t pm_freq_param_t // See pm.h 118 #else 119 // Support for UC3C, UC3L parts. 120 typedef struct 121 { 122 //! Main clock source selection (input argument). 123 pcl_mainclk_t main_clk_src; 124 125 //! Target CPU frequency (input/output argument). 126 unsigned long cpu_f; 127 128 //! Target PBA frequency (input/output argument). 129 unsigned long pba_f; 130 131 //! Target PBB frequency (input/output argument). 132 unsigned long pbb_f; 133 134 //! Target PBC frequency (input/output argument). 135 unsigned long pbc_f; 136 137 //! Oscillator 0's external crystal(or external clock) frequency (board dependant) (input argument). 138 unsigned long osc0_f; 139 140 //! Oscillator 0's external crystal(or external clock) startup time: AVR32_PM_OSCCTRL0_STARTUP_x_RCOSC (input argument). 141 unsigned long osc0_startup; 142 143 //! DFLL target frequency (input/output argument) (NOTE: the bigger, the most stable the frequency) 144 unsigned long dfll_f; 145 146 //! Other parameters that might be necessary depending on the device (implementation-dependent). 147 // For the UC3L DFLL setup, this parameter should be pointing to a structure of 148 // type (scif_gclk_opt_t *). 149 void *pextra_params; 150 } pcl_freq_param_t; 151 #endif 152 153 //! Define "not supported" for the lib. 154 #define PCL_NOT_SUPPORTED (-10000) 155 156 /*! \brief Automatically configure the CPU, PBA, PBB, and HSB clocks 157 * 158 * This function needs some parameters stored in a pcl_freq_param_t structure: 159 * - main_clk_src is the id of the main clock source to use, 160 * - cpu_f and pba_f and pbb_f are the wanted frequencies, 161 * - osc0_f is the oscillator 0's external crystal (or external clock) on-board frequency (e.g. FOSC0), 162 * - osc0_startup is the oscillator 0's external crystal (or external clock) startup time (e.g. OSC0_STARTUP). 163 * - dfll_f is the target DFLL frequency to set-up if main_clk_src is the dfll. 164 * 165 * The CPU, HSB and PBA frequencies programmed after configuration are stored back into cpu_f and pba_f. 166 * 167 * \note: since it is dynamically computing the appropriate field values of the 168 * configuration registers from the parameters structure, this function is not 169 * optimal in terms of code size. For a code size optimal solution, it is better 170 * to create a new function from pcl_configure_clocks() and modify it to use 171 * preprocessor computation from pre-defined target frequencies. 172 * 173 * \param param pointer on the configuration structure. 174 * 175 * \retval 0 Success. 176 * \retval <0 The configuration cannot be performed. 177 */ 178 extern long int pcl_configure_clocks(pcl_freq_param_t *param); 179 180 /*! \brief Automatically configure the CPU, PBA, PBB, and HSB clocks using the RCSYS osc as main source clock. 181 * 182 * This function needs some parameters stored in a pcl_freq_param_t structure: 183 * - cpu_f and pba_f and pbb_f are the wanted frequencies 184 * 185 * Supported main clock sources: PCL_MC_RCSYS 186 * 187 * Supported synchronous clocks frequencies: 188 * 115200Hz, 57600Hz, 28800Hz, 14400Hz, 7200Hz, 3600Hz, 1800Hz, 900Hz, 450Hz. 189 * 190 * \note: by default, this implementation doesn't perform thorough checks on the 191 * input parameters. To enable the checks, define AVR32SFW_INPUT_CHECK. 192 * 193 * \note: since it is dynamically computing the appropriate field values of the 194 * configuration registers from the parameters structure, this function is not 195 * optimal in terms of code size. For a code size optimal solution, it is better 196 * to create a new function from pcl_configure_clocks_rcsys() and modify it to use 197 * preprocessor computation from pre-defined target frequencies. 198 * 199 * \param param pointer on the configuration structure. 200 * 201 * \retval 0 Success. 202 * \retval <0 The configuration cannot be performed. 203 */ 204 extern long int pcl_configure_clocks_rcsys(pcl_freq_param_t *param); 205 206 /*! \brief Automatically configure the CPU, PBA, PBB, and HSB clocks using the RC120M osc as main source clock. 207 * 208 * This function needs some parameters stored in a pcl_freq_param_t structure: 209 * - cpu_f and pba_f and pbb_f are the wanted frequencies 210 * 211 * Supported main clock sources: PCL_MC_RC120M 212 * 213 * Supported synchronous clocks frequencies: 214 * 30MHz, 15MHz, 7.5MHz, 3.75MHz, 1.875MHz, 937.5kHz, 468.75kHz. 215 * 216 * \note: by default, this implementation doesn't perform thorough checks on the 217 * input parameters. To enable the checks, define AVR32SFW_INPUT_CHECK. 218 * 219 * \note: since it is dynamically computing the appropriate field values of the 220 * configuration registers from the parameters structure, this function is not 221 * optimal in terms of code size. For a code size optimal solution, it is better 222 * to create a new function from pcl_configure_clocks_rc120m() and modify it to 223 * use preprocessor computation from pre-defined target frequencies. 224 * 225 * \param param pointer on the configuration structure. 226 * 227 * \retval 0 Success. 228 * \retval <0 The configuration cannot be performed. 229 */ 230 extern long int pcl_configure_clocks_rc120m(pcl_freq_param_t *param); 231 232 /*! \brief Automatically configure the CPU, PBA, PBB, and HSB clocks using the OSC0 osc as main source clock 233 * 234 * This function needs some parameters stored in a pcl_freq_param_t structure: 235 * - cpu_f and pba_f and pbb_f are the wanted frequencies, 236 * - osc0_f is the oscillator 0's external crystal (or external clock) on-board frequency (e.g. FOSC0), 237 * - osc0_startup is the oscillator 0's external crystal (or external clock) startup time (e.g. OSC0_STARTUP). 238 * 239 * Supported main clock sources: PCL_MC_OSC0 240 * 241 * Supported synchronous clocks frequencies: 242 * (these obviously depend on the OSC0 frequency; we'll take 16MHz as an example) 243 * 16MHz, 8MHz, 4MHz, 2MHz, 1MHz, 500kHz, 250kHz, 125kHz, 62.5kHz. 244 * 245 * \note: by default, this implementation doesn't perform thorough checks on the 246 * input parameters. To enable the checks, define AVR32SFW_INPUT_CHECK. 247 * 248 * \note: since it is dynamically computing the appropriate field values of the 249 * configuration registers from the parameters structure, this function is not 250 * optimal in terms of code size. For a code size optimal solution, it is better 251 * to create a new function from pcl_configure_clocks_osc0() and modify it to use 252 * preprocessor computation from pre-defined target frequencies. 253 * 254 * \param param pointer on the configuration structure. 255 * 256 * \retval 0 Success. 257 * \retval <0 The configuration cannot be performed. 258 */ 259 extern long int pcl_configure_clocks_osc0(pcl_freq_param_t *param); 260 261 /*! \brief Automatically configure the CPU, PBA, PBB, and HSB clocks using the DFLL0 as main source clock 262 * 263 * This function needs some parameters stored in a pcl_freq_param_t structure: 264 * - cpu_f and pba_f and pbb_f are the wanted frequencies, 265 * - dfll_f is the target DFLL frequency to set-up 266 * 267 * \note: when the DFLL0 is to be used as main source clock for the synchronous clocks, 268 * the target frequency of the DFLL should be chosen to be as high as possible 269 * within the specification range (for stability reasons); the target cpu and pbx 270 * frequencies will then be reached by appropriate division ratio. 271 * 272 * Supported main clock sources: PCL_MC_DFLL0 273 * 274 * Supported synchronous clocks frequencies: 275 * (these obviously depend on the DFLL target frequency; we'll take 100MHz as an example) 276 * 50MHz, 25MHz, 12.5MHz, 6.25MHz, 3.125MHz, 1562.5kHz, 781.25kHz, 390.625kHz. 277 * 278 * \note: by default, this implementation doesn't perform thorough checks on the 279 * input parameters. To enable the checks, define AVR32SFW_INPUT_CHECK. 280 * 281 * \note: since it is dynamically computing the appropriate field values of the 282 * configuration registers from the parameters structure, this function is not 283 * optimal in terms of code size. For a code size optimal solution, it is better 284 * to create a new function from pcl_configure_clocks_dfll0() and modify it to 285 * use preprocessor computation from pre-defined target frequencies. 286 * 287 * \param param pointer on the configuration structure. 288 * 289 * \retval 0 Success. 290 * \retval <0 The configuration cannot be performed. 291 */ 292 extern long int pcl_configure_clocks_dfll0(pcl_freq_param_t *param); 293 294 /*! \brief Switch the main clock source to Osc0 configured in crystal mode 295 * 296 * \param osc The oscillator to enable and switch to. 297 * \param fcrystal Oscillator external crystal frequency (Hz) 298 * \param startup Oscillator startup time. 299 * 300 * \return Status. 301 * \retval 0 Success. 302 * \retval <0 An error occurred. 303 */ 304 extern long int pcl_switch_to_osc(pcl_osc_t osc, unsigned int fcrystal, unsigned int startup); 305 306 /*! \brief Enable the clock of a module. 307 * 308 * \param module The module to clock (use one of the defines in the part-specific 309 * header file under "toolchain folder"/avr32/inc(lude)/avr32/; depending on the 310 * clock domain, look for the sections "CPU clocks", "HSB clocks", "PBx clocks" 311 * or look in the module section). 312 * 313 * \return Status. 314 * \retval 0 Success. 315 * \retval <0 An error occurred. 316 */ 317 #ifndef AVR32_PM_VERSION_RESETVALUE 318 // Implementation for UC3A, UC3A3, UC3B parts. 319 #define pcl_enable_module(module) pm_enable_module(&AVR32_PM, module) 320 #else 321 // Implementation for UC3C, UC3L parts. 322 #define pcl_enable_module(module) pm_enable_module(module) 323 #endif 324 325 /*! \brief Disable the clock of a module. 326 * 327 * \param module The module to shut down (use one of the defines in the part-specific 328 * header file under "toolchain folder"/avr32/inc(lude)/avr32/; depending on the 329 * clock domain, look for the sections "CPU clocks", "HSB clocks", "PBx clocks" 330 * or look in the module section). 331 * 332 * \return Status. 333 * \retval 0 Success. 334 * \retval <0 An error occurred. 335 */ 336 #ifndef AVR32_PM_VERSION_RESETVALUE 337 // Implementation for UC3A, UC3A3, UC3B parts. 338 #define pcl_disable_module(module) pm_disable_module(&AVR32_PM, module) 339 #else 340 // Implementation for UC3C, UC3L parts. 341 #define pcl_disable_module(module) pm_disable_module(module) 342 #endif 343 344 /*! \brief Configure the USB Clock 345 * 346 * \return Status. 347 * \retval 0 Success. 348 * \retval <0 An error occurred. 349 */ 350 extern 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 */ 363 extern 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 */ 371 extern void pcl_write_gplp(unsigned long gplp, unsigned long value); 372 373 //! @} 374 375 #ifdef __cplusplus 376 } 377 #endif 378 379 /** 380 * \} 381 */ 382 383 #endif // _POWER_CLOCKS_LIB_H_ 384