1 /** 2 * \file 3 * 4 * \brief Oscillator 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 OSC_H_INCLUDED 47 #define OSC_H_INCLUDED 48 49 #include "parts.h" 50 #include "conf_clock.h" 51 52 #if SAM3S 53 # include "sam3s/osc.h" 54 #elif SAM3XA 55 # include "sam3x/osc.h" 56 #elif SAM3U 57 # include "sam3u/osc.h" 58 #elif SAM3N 59 # include "sam3n/osc.h" 60 #elif SAM4S 61 # include "sam4s/osc.h" 62 #elif SAM4E 63 # include "sam4e/osc.h" 64 #elif SAM4C 65 # include "sam4c/osc.h" 66 #elif SAM4CM 67 # include "sam4cm/osc.h" 68 #elif SAM4CP 69 # include "sam4cp/osc.h" 70 #elif SAM4L 71 # include "sam4l/osc.h" 72 #elif SAM4N 73 # include "sam4n/osc.h" 74 #elif SAMG 75 # include "samg/osc.h" 76 #elif SAMV71 77 # include "samv71/osc.h" 78 #elif SAMV70 79 # include "samv70/osc.h" 80 #elif SAME70 81 # include "same70/osc.h" 82 #elif SAMS70 83 # include "sams70/osc.h" 84 #elif (UC3A0 || UC3A1) 85 # include "uc3a0_a1/osc.h" 86 #elif UC3A3 87 # include "uc3a3_a4/osc.h" 88 #elif UC3B 89 # include "uc3b0_b1/osc.h" 90 #elif UC3C 91 # include "uc3c/osc.h" 92 #elif UC3D 93 # include "uc3d/osc.h" 94 #elif UC3L 95 # include "uc3l/osc.h" 96 #elif XMEGA 97 # include "xmega/osc.h" 98 #else 99 # error Unsupported chip type 100 #endif 101 102 /** 103 * \ingroup clk_group 104 * \defgroup osc_group Oscillator Management 105 * 106 * This group contains functions and definitions related to configuring 107 * and enabling/disabling on-chip oscillators. Internal RC-oscillators, 108 * external crystal oscillators and external clock generators are 109 * supported by this module. What all of these have in common is that 110 * they swing at a fixed, nominal frequency which is normally not 111 * adjustable. 112 * 113 * \par Example: Enabling an oscillator 114 * 115 * The following example demonstrates how to enable the external 116 * oscillator on XMEGA A and wait for it to be ready to use. The 117 * oscillator identifiers are platform-specific, so while the same 118 * procedure is used on all platforms, the parameter to osc_enable() 119 * will be different from device to device. 120 * \code 121 osc_enable(OSC_ID_XOSC); 122 osc_wait_ready(OSC_ID_XOSC); \endcode 123 * 124 * \section osc_group_board Board-specific Definitions 125 * If external oscillators are used, the board code must provide the 126 * following definitions for each of those: 127 * - \b BOARD_<osc name>_HZ: The nominal frequency of the oscillator. 128 * - \b BOARD_<osc name>_STARTUP_US: The startup time of the 129 * oscillator in microseconds. 130 * - \b BOARD_<osc name>_TYPE: The type of oscillator connected, i.e. 131 * whether it's a crystal or external clock, and sometimes what kind 132 * of crystal it is. The meaning of this value is platform-specific. 133 * 134 * @{ 135 */ 136 137 //! \name Oscillator Management 138 //@{ 139 /** 140 * \fn void osc_enable(uint8_t id) 141 * \brief Enable oscillator \a id 142 * 143 * The startup time and mode value is automatically determined based on 144 * definitions in the board code. 145 */ 146 /** 147 * \fn void osc_disable(uint8_t id) 148 * \brief Disable oscillator \a id 149 */ 150 /** 151 * \fn osc_is_ready(uint8_t id) 152 * \brief Determine whether oscillator \a id is ready. 153 * \retval true Oscillator \a id is running and ready to use as a clock 154 * source. 155 * \retval false Oscillator \a id is not running. 156 */ 157 /** 158 * \fn uint32_t osc_get_rate(uint8_t id) 159 * \brief Return the frequency of oscillator \a id in Hz 160 */ 161 162 #ifndef __ASSEMBLY__ 163 164 /** 165 * \brief Wait until the oscillator identified by \a id is ready 166 * 167 * This function will busy-wait for the oscillator identified by \a id 168 * to become stable and ready to use as a clock source. 169 * 170 * \param id A number identifying the oscillator to wait for. 171 */ 172 static inline void osc_wait_ready(uint8_t id) 173 { 174 while (!osc_is_ready(id)) { 175 /* Do nothing */ 176 } 177 } 178 179 #endif /* __ASSEMBLY__ */ 180 181 //@} 182 183 //! @} 184 185 #endif /* OSC_H_INCLUDED */ 186