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