git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_M4F_ATSAM4E_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-2013 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 SAM4E\r
  60 # include "sam4e/sysclk.h"\r
  61 #elif SAM4L\r
  62 # include "sam4l/sysclk.h"\r
  63 #elif SAM4N\r
  64 # include "sam4n/sysclk.h"\r
  65 #elif (UC3A0 || UC3A1)\r
  66 # include "uc3a0_a1/sysclk.h"\r
  67 #elif UC3A3\r
  68 # include "uc3a3_a4/sysclk.h"\r
  69 #elif UC3B\r
  70 # include "uc3b0_b1/sysclk.h"\r
  71 #elif UC3C\r
  72 # include "uc3c/sysclk.h"\r
  73 #elif UC3D\r
  74 # include "uc3d/sysclk.h"\r
  75 #elif UC3L\r
  76 # include "uc3l/sysclk.h"\r
  77 #elif XMEGA\r
  78 # include "xmega/sysclk.h"\r
  79 #elif MEGA\r
  80 # include "mega/sysclk.h"\r
  81 #else\r
  82 # error Unsupported chip type\r
  83 #endif\r
  84 \r
  85 /**\r
  86  * \defgroup clk_group Clock Management\r
  87  */\r
  88 \r
  89 /**\r
  90  * \ingroup clk_group\r
  91  * \defgroup sysclk_group System Clock Management\r
  92  *\r
  93  * See \ref sysclk_quickstart.\r
  94  *\r
  95  * The <em>sysclk</em> API covers the <em>system clock</em> and all\r
  96  * clocks derived from it. The system clock is a chip-internal clock on\r
  97  * which all <em>synchronous clocks</em>, i.e. CPU and bus/peripheral\r
  98  * clocks, are based. The system clock is typically generated from one\r
  99  * of a variety of sources, which may include crystal and RC oscillators\r
 100  * as well as PLLs.  The clocks derived from the system clock are\r
 101  * sometimes also known as <em>synchronous clocks</em>, since they\r
 102  * always run synchronously with respect to each other, as opposed to\r
 103  * <em>generic clocks</em> which may run from different oscillators or\r
 104  * PLLs.\r
 105  *\r
 106  * Most applications should simply call sysclk_init() to initialize\r
 107  * everything related to the system clock and its source (oscillator,\r
 108  * PLL or DFLL), and leave it at that. More advanced applications, and\r
 109  * platform-specific drivers, may require additional services from the\r
 110  * clock system, some of which may be platform-specific.\r
 111  *\r
 112  * \section sysclk_group_platform Platform Dependencies\r
 113  *\r
 114  * The sysclk API is partially chip- or platform-specific. While all\r
 115  * platforms provide mostly the same functionality, there are some\r
 116  * variations around how different bus types and clock tree structures\r
 117  * are handled.\r
 118  *\r
 119  * The following functions are available on all platforms with the same\r
 120  * parameters and functionality. These functions may be called freely by\r
 121  * portable applications, drivers and services:\r
 122  *   - sysclk_init()\r
 123  *   - sysclk_set_source()\r
 124  *   - sysclk_get_main_hz()\r
 125  *   - sysclk_get_cpu_hz()\r
 126  *   - sysclk_get_peripheral_bus_hz()\r
 127  *\r
 128  * The following functions are available on all platforms, but there may\r
 129  * be variations in the function signature (i.e. parameters) and\r
 130  * behavior. These functions are typically called by platform-specific\r
 131  * parts of drivers, and applications that aren't intended to be\r
 132  * portable:\r
 133  *   - sysclk_enable_peripheral_clock()\r
 134  *   - sysclk_disable_peripheral_clock()\r
 135  *   - sysclk_enable_module()\r
 136  *   - sysclk_disable_module()\r
 137  *   - sysclk_module_is_enabled()\r
 138  *   - sysclk_set_prescalers()\r
 139  *\r
 140  * All other functions should be considered platform-specific.\r
 141  * Enabling/disabling clocks to specific peripherals as well as\r
 142  * determining the speed of these clocks should be done by calling\r
 143  * functions provided by the driver for that peripheral.\r
 144  *\r
 145  * @{\r
 146  */\r
 147 \r
 148 //! \name System Clock Initialization\r
 149 //@{\r
 150 /**\r
 151  * \fn void sysclk_init(void)\r
 152  * \brief Initialize the synchronous clock system.\r
 153  *\r
 154  * This function will initialize the system clock and its source. This\r
 155  * includes:\r
 156  *   - Mask all synchronous clocks except for any clocks which are\r
 157  *     essential for normal operation (for example internal memory\r
 158  *     clocks).\r
 159  *   - Set up the system clock prescalers as specified by the\r
 160  *     application's configuration file.\r
 161  *   - Enable the clock source specified by the application's\r
 162  *     configuration file (oscillator or PLL) and wait for it to become\r
 163  *     stable.\r
 164  *   - Set the main system clock source to the clock specified by the\r
 165  *     application's configuration file.\r
 166  *\r
 167  * Since all non-essential peripheral clocks are initially disabled, it\r
 168  * is the responsibility of the peripheral driver to re-enable any\r
 169  * clocks that are needed for normal operation.\r
 170  */\r
 171 //@}\r
 172 \r
 173 //! @}\r
 174 \r
 175 #endif /* SYSCLK_H_INCLUDED */\r