git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_ATSAM3X_Atmel_Studio/src/asf/common/services/clock/sysclk.h

   1 /**\r
   2  * \file\r
   3  *\r
   4  * \brief System clock management\r
   5  *\r
   6  * Copyright (c) 2010-2012 Atmel Corporation. All rights reserved.\r
   7  *\r
   8  * \asf_license_start\r
   9  *\r
  10  * \page License\r
  11  *\r
  12  * Redistribution and use in source and binary forms, with or without\r
  13  * modification, are permitted provided that the following conditions are met:\r
  14  *\r
  15  * 1. Redistributions of source code must retain the above copyright notice,\r
  16  *    this list of conditions and the following disclaimer.\r
  17  *\r
  18  * 2. Redistributions in binary form must reproduce the above copyright notice,\r
  19  *    this list of conditions and the following disclaimer in the documentation\r
  20  *    and/or other materials provided with the distribution.\r
  21  *\r
  22  * 3. The name of Atmel may not be used to endorse or promote products derived\r
  23  *    from this software without specific prior written permission.\r
  24  *\r
  25  * 4. This software may only be redistributed and used in connection with an\r
  26  *    Atmel microcontroller product.\r
  27  *\r
  28  * THIS SOFTWARE IS PROVIDED BY ATMEL "AS IS" AND ANY EXPRESS OR IMPLIED\r
  29  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF\r
  30  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT ARE\r
  31  * EXPRESSLY AND SPECIFICALLY DISCLAIMED. IN NO EVENT SHALL ATMEL BE LIABLE FOR\r
  32  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\r
  33  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS\r
  34  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\r
  35  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,\r
  36  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN\r
  37  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE\r
  38  * POSSIBILITY OF SUCH DAMAGE.\r
  39  *\r
  40  * \asf_license_stop\r
  41  *\r
  42  */\r
  43 #ifndef SYSCLK_H_INCLUDED\r
  44 #define SYSCLK_H_INCLUDED\r
  45 \r
  46 #include "parts.h"\r
  47 #include "conf_clock.h"\r
  48 \r
  49 #if SAM3S\r
  50 # include "sam3s/sysclk.h"\r
  51 #elif SAM3U\r
  52 # include "sam3u/sysclk.h"\r
  53 #elif SAM3N\r
  54 # include "sam3n/sysclk.h"\r
  55 #elif SAM3XA\r
  56 # include "sam3x/sysclk.h"\r
  57 #elif SAM4S\r
  58 # include "sam4s/sysclk.h"\r
  59 #elif (UC3A0 || UC3A1)\r
  60 # include "uc3a0_a1/sysclk.h"\r
  61 #elif UC3A3\r
  62 # include "uc3a3_a4/sysclk.h"\r
  63 #elif UC3B\r
  64 # include "uc3b0_b1/sysclk.h"\r
  65 #elif UC3C\r
  66 # include "uc3c/sysclk.h"\r
  67 #elif UC3D\r
  68 # include "uc3d/sysclk.h"\r
  69 #elif UC3L\r
  70 # include "uc3l/sysclk.h"\r
  71 #elif XMEGA\r
  72 # include "xmega/sysclk.h"\r
  73 #else\r
  74 # error Unsupported chip type\r
  75 #endif\r
  76 \r
  77 /**\r
  78  * \defgroup clk_group Clock Management\r
  79  */\r
  80 \r
  81 /**\r
  82  * \ingroup clk_group\r
  83  * \defgroup sysclk_group System Clock Management\r
  84  *\r
  85  * See \ref sysclk_quickstart.\r
  86  *\r
  87  * The <em>sysclk</em> API covers the <em>system clock</em> and all\r
  88  * clocks derived from it. The system clock is a chip-internal clock on\r
  89  * which all <em>synchronous clocks</em>, i.e. CPU and bus/peripheral\r
  90  * clocks, are based. The system clock is typically generated from one\r
  91  * of a variety of sources, which may include crystal and RC oscillators\r
  92  * as well as PLLs.  The clocks derived from the system clock are\r
  93  * sometimes also known as <em>synchronous clocks</em>, since they\r
  94  * always run synchronously with respect to each other, as opposed to\r
  95  * <em>generic clocks</em> which may run from different oscillators or\r
  96  * PLLs.\r
  97  *\r
  98  * Most applications should simply call sysclk_init() to initialize\r
  99  * everything related to the system clock and its source (oscillator,\r
 100  * PLL or DFLL), and leave it at that. More advanced applications, and\r
 101  * platform-specific drivers, may require additional services from the\r
 102  * clock system, some of which may be platform-specific.\r
 103  *\r
 104  * \section sysclk_group_platform Platform Dependencies\r
 105  *\r
 106  * The sysclk API is partially chip- or platform-specific. While all\r
 107  * platforms provide mostly the same functionality, there are some\r
 108  * variations around how different bus types and clock tree structures\r
 109  * are handled.\r
 110  *\r
 111  * The following functions are available on all platforms with the same\r
 112  * parameters and functionality. These functions may be called freely by\r
 113  * portable applications, drivers and services:\r
 114  *   - sysclk_init()\r
 115  *   - sysclk_set_source()\r
 116  *   - sysclk_get_main_hz()\r
 117  *   - sysclk_get_cpu_hz()\r
 118  *   - sysclk_get_peripheral_bus_hz()\r
 119  *\r
 120  * The following functions are available on all platforms, but there may\r
 121  * be variations in the function signature (i.e. parameters) and\r
 122  * behavior. These functions are typically called by platform-specific\r
 123  * parts of drivers, and applications that aren't intended to be\r
 124  * portable:\r
 125  *   - sysclk_enable_peripheral_clock()\r
 126  *   - sysclk_disable_peripheral_clock()\r
 127  *   - sysclk_enable_module()\r
 128  *   - sysclk_disable_module()\r
 129  *   - sysclk_module_is_enabled()\r
 130  *   - sysclk_set_prescalers()\r
 131  *\r
 132  * All other functions should be considered platform-specific.\r
 133  * Enabling/disabling clocks to specific peripherals as well as\r
 134  * determining the speed of these clocks should be done by calling\r
 135  * functions provided by the driver for that peripheral.\r
 136  *\r
 137  * @{\r
 138  */\r
 139 \r
 140 //! \name System Clock Initialization\r
 141 //@{\r
 142 /**\r
 143  * \fn void sysclk_init(void)\r
 144  * \brief Initialize the synchronous clock system.\r
 145  *\r
 146  * This function will initialize the system clock and its source. This\r
 147  * includes:\r
 148  *   - Mask all synchronous clocks except for any clocks which are\r
 149  *     essential for normal operation (for example internal memory\r
 150  *     clocks).\r
 151  *   - Set up the system clock prescalers as specified by the\r
 152  *     application's configuration file.\r
 153  *   - Enable the clock source specified by the application's\r
 154  *     configuration file (oscillator or PLL) and wait for it to become\r
 155  *     stable.\r
 156  *   - Set the main system clock source to the clock specified by the\r
 157  *     application's configuration file.\r
 158  *\r
 159  * Since all non-essential peripheral clocks are initially disabled, it\r
 160  * is the responsibility of the peripheral driver to re-enable any\r
 161  * clocks that are needed for normal operation.\r
 162  */\r
 163 //@}\r
 164 \r
 165 //! @}\r
 166 \r
 167 #endif /* SYSCLK_H_INCLUDED */\r