git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_M0+_Atmel_SAMD20_XPlained/RTOSDemo/src/ASF/sam0/drivers/system/system.h

   1 /**\r
   2  * \file\r
   3  *\r
   4  * \brief SAM D20 System related functionality\r
   5  *\r
   6  * Copyright (C) 2012-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 SYSTEM_H_INCLUDED\r
  44 #define SYSTEM_H_INCLUDED\r
  45 \r
  46 #include <compiler.h>\r
  47 #include <clock.h>\r
  48 #include <gclk.h>\r
  49 #include <pinmux.h>\r
  50 \r
  51 /**\r
  52  * \defgroup asfdoc_samd20_system_group SAM D20 System Driver (SYSTEM)\r
  53  *\r
  54  * This driver for SAM D20 devices provides an interface for the configuration\r
  55  * and management of the device's system relation functionality, necessary for\r
  56  * the basic device operation. This is not limited to a single peripheral, but\r
  57  * extends across multiple hardware peripherals,\r
  58  *\r
  59  * The following peripherals are used by this module:\r
  60  *\r
  61  * - SYSCTRL (System Control)\r
  62  * - PM (Power Manager)\r
  63  *\r
  64  * The outline of this documentation is as follows:\r
  65  *  - \ref asfdoc_samd20_system_prerequisites\r
  66  *  - \ref asfdoc_samd20_system_module_overview\r
  67  *  - \ref asfdoc_samd20_system_special_considerations\r
  68  *  - \ref asfdoc_samd20_system_extra_info\r
  69  *  - \ref asfdoc_samd20_system_examples\r
  70  *  - \ref asfdoc_samd20_system_api_overview\r
  71  *\r
  72  *\r
  73  * \section asfdoc_samd20_system_prerequisites Prerequisites\r
  74  *\r
  75  * There are no prerequisites for this module.\r
  76  *\r
  77  *\r
  78  * \section asfdoc_samd20_system_module_overview Module Overview\r
  79  *\r
  80  * The System driver provides a collection of interfaces between the user\r
  81  * application logic, and the core device functionality (such as clocks, reset\r
  82  * cause determination, etc.) that is required for all applications. It contains\r
  83  * a number of sub-modules that control one specific aspect of the device:\r
  84  *\r
  85  * - System Core (this module)\r
  86  * - \ref asfdoc_samd20_system_clock_group "System Clock Control" (sub-module)\r
  87  * - \ref asfdoc_samd20_system_interrupt_group "System Interrupt Control" (sub-module)\r
  88  * - \ref asfdoc_samd20_system_pinmux_group "System Pin Multiplexer Control" (sub-module)\r
  89  *\r
  90  *\r
  91  * \subsection asfdoc_samd20_system_module_overview_vref Voltage References\r
  92  * The various analog modules within the SAM D20 devices (such as AC, ADC and\r
  93  * DAC) require a voltage reference to be configured to act as a reference point\r
  94  * for comparisons and conversions.\r
  95  *\r
  96  * The SAM D20 devices contain multiple references, including an internal\r
  97  * temperature sensor, and a fixed band-gap voltage source. When enabled, the\r
  98  * associated voltage reference can be selected within the desired peripheral\r
  99  * where applicable.\r
 100  *\r
 101  * \subsection asfdoc_samd20_system_module_overview_reset_cause System Reset Cause\r
 102  * In some application there may be a need to execute a different program\r
 103  * flow based on how the device was reset. For example, if the cause of reset\r
 104  * was the Watchdog timer (WDT), this might indicate an error in the application\r
 105  * and a form of error handling or error logging might be needed.\r
 106  *\r
 107  * For this reason, an API is provided to retrieve the cause of the last system\r
 108  * reset, so that appropriate action can be taken.\r
 109  *\r
 110  * \subsection asfdoc_samd20_system_module_overview_sleep_mode Sleep Modes\r
 111  * The SAM D20 devices have several sleep modes, where the sleep mode controls\r
 112  * which clock systems on the device will remain enabled or disabled when the\r
 113  * device enters a low power sleep mode.\r
 114  * \ref asfdoc_samd20_system_module_sleep_mode_table "The table below" lists the\r
 115  * clock settings of the different sleep modes.\r
 116  *\r
 117  * \anchor asfdoc_samd20_system_module_sleep_mode_table\r
 118  * <table>\r
 119  *  <caption>SAM D20 Device Sleep Modes</caption>\r
 120  *      <tr>\r
 121  *              <th>Sleep mode</th>\r
 122  *              <th>CPU clock</th>\r
 123  *              <th>AHB clock</th>\r
 124  *              <th>APB clocks</th>\r
 125  *              <th>Clock sources</th>\r
 126  *              <th>System clock</th>\r
 127  *              <th>32KHz</th>\r
 128  *              <th>Reg mode</th>\r
 129  *              <th>RAM mode</th>\r
 130  *      </tr>\r
 131  *      <tr>\r
 132  *              <td>IDLE 0</td>\r
 133  *              <td>Stop</td>\r
 134  *              <td>Run</td>\r
 135  *              <td>Run</td>\r
 136  *              <td>Run</td>\r
 137  *              <td>Run</td>\r
 138  *              <td>Run</td>\r
 139  *              <td>Normal</td>\r
 140  *              <td>Normal</td>\r
 141  *      </tr>\r
 142  *      <tr>\r
 143  *              <td>IDLE 1</td>\r
 144  *              <td>Stop</td>\r
 145  *              <td>Stop</td>\r
 146  *              <td>Run</td>\r
 147  *              <td>Run</td>\r
 148  *              <td>Run</td>\r
 149  *              <td>Run</td>\r
 150  *              <td>Normal</td>\r
 151  *              <td>Normal</td>\r
 152  *      </tr>\r
 153  *      <tr>\r
 154  *              <td>IDLE 2</td>\r
 155  *              <td>Stop</td>\r
 156  *              <td>Stop</td>\r
 157  *              <td>Stop</td>\r
 158  *              <td>Run</td>\r
 159  *              <td>Run</td>\r
 160  *              <td>Run</td>\r
 161  *              <td>Normal</td>\r
 162  *              <td>Normal</td>\r
 163  *      </tr>\r
 164  *      <tr>\r
 165  *              <td>STANDBY</td>\r
 166  *              <td>Stop</td>\r
 167  *              <td>Stop</td>\r
 168  *              <td>Stop</td>\r
 169  *              <td>Stop</td>\r
 170  *              <td>Stop</td>\r
 171  *              <td>Stop</td>\r
 172  *              <td>Low Power</td>\r
 173  *              <td>Source/Drain biasing</td>\r
 174  *      </tr>\r
 175  * </table>\r
 176  *\r
 177  * To enter device sleep, one of the available sleep modes must be set, and the\r
 178  * function to enter sleep called. The device will automatically wake up in\r
 179  * response to an interrupt being generated or other device event.\r
 180  *\r
 181  * Some peripheral clocks will remain enabled during sleep, depending on their\r
 182  * configuration; if desired, modules can remain clocked during sleep to allow\r
 183  * them to continue to operate while other parts of the system are powered down\r
 184  * to save power.\r
 185  *\r
 186  *\r
 187  * \section asfdoc_samd20_system_special_considerations Special Considerations\r
 188  *\r
 189  * Most of the functions in this driver have device specific restrictions and\r
 190  * caveats; refer to your device datasheet.\r
 191  *\r
 192  *\r
 193  * \section asfdoc_samd20_system_extra_info Extra Information\r
 194  *\r
 195  * For extra information see \ref asfdoc_samd20_system_extra. This includes:\r
 196  *  - \ref asfdoc_samd20_system_extra_acronyms\r
 197  *  - \ref asfdoc_samd20_system_extra_dependencies\r
 198  *  - \ref asfdoc_samd20_system_extra_errata\r
 199  *  - \ref asfdoc_samd20_system_extra_history\r
 200  *\r
 201  *\r
 202  * \section asfdoc_samd20_system_examples Examples\r
 203  *\r
 204  * For SYSTEM module related examples, please refer to the sub-modules listed in\r
 205  * the \ref asfdoc_samd20_system_module_overview "system module overview".\r
 206  *\r
 207  *\r
 208  * \section asfdoc_samd20_system_api_overview API Overview\r
 209  * @{\r
 210  */\r
 211 \r
 212 /**\r
 213  * \brief Voltage references within the device.\r
 214  *\r
 215  * List of available voltage references (VREF) that may be used within the\r
 216  * device.\r
 217  */\r
 218 enum system_voltage_reference {\r
 219         /** Temperature sensor voltage reference. */\r
 220         SYSTEM_VOLTAGE_REFERENCE_TEMPSENSE,\r
 221         /** Bandgap voltage reference. */\r
 222         SYSTEM_VOLTAGE_REFERENCE_BANDGAP,\r
 223 };\r
 224 \r
 225 /**\r
 226  * \brief Device sleep modes.\r
 227  *\r
 228  * List of available sleep modes in the device. A table of clocks available in\r
 229  * different sleep modes can be found in \ref asfdoc_samd20_system_module_overview_sleep_mode.\r
 230  */\r
 231 enum system_sleepmode {\r
 232         /** IDLE 0 sleep mode. */\r
 233         SYSTEM_SLEEPMODE_IDLE_0,\r
 234         /** IDLE 1 sleep mode. */\r
 235         SYSTEM_SLEEPMODE_IDLE_1,\r
 236         /** IDLE 2 sleep mode. */\r
 237         SYSTEM_SLEEPMODE_IDLE_2,\r
 238         /** Standby sleep mode. */\r
 239         SYSTEM_SLEEPMODE_STANDBY,\r
 240 };\r
 241 \r
 242 /**\r
 243  * \brief Reset causes of the system.\r
 244  *\r
 245  * List of possible reset causes of the system.\r
 246  */\r
 247 enum system_reset_cause {\r
 248         /** The system was last reset by a software reset. */\r
 249         SYSTEM_RESET_CAUSE_SOFTWARE       = PM_RCAUSE_SYST,\r
 250         /** The system was last reset by the watchdog timer. */\r
 251         SYSTEM_RESET_CAUSE_WDT            = PM_RCAUSE_WDT,\r
 252         /** The system was last reset because the external reset line was pulled low. */\r
 253         SYSTEM_RESET_CAUSE_EXTERNAL_RESET = PM_RCAUSE_EXT,\r
 254         /** The system was last reset by the BOD33. */\r
 255         SYSTEM_RESET_CAUSE_BOD33          = PM_RCAUSE_BOD33,\r
 256         /** The system was last reset by the BOD12. */\r
 257         SYSTEM_RESET_CAUSE_BOD12          = PM_RCAUSE_BOD12,\r
 258         /** The system was last reset by the POR (Power on reset). */\r
 259         SYSTEM_RESET_CAUSE_POR            = PM_RCAUSE_POR,\r
 260 };\r
 261 \r
 262 /**\r
 263  * \name System identification\r
 264  * @{\r
 265  */\r
 266 \r
 267 /**\r
 268  * \brief Retrieve the device identification signature\r
 269  *\r
 270  * Retrieves the signature of the current device.\r
 271  *\r
 272  * \return Device ID signature as a 32-bit integer.\r
 273  */\r
 274 static inline uint32_t system_get_device_id(void)\r
 275 {\r
 276         return DSU->DID.reg;\r
 277 }\r
 278 \r
 279 /**\r
 280  * @}\r
 281  */\r
 282 \r
 283 \r
 284 /**\r
 285  * \name Voltage references\r
 286  * @{\r
 287  */\r
 288 \r
 289 /**\r
 290  * \brief Enable the selected voltage reference\r
 291  *\r
 292  * Enables the selected voltage reference source, making the voltage reference\r
 293  * available on a pin as well as an input source to the analog peripherals.\r
 294  *\r
 295  * \param[in] vref  Voltage reference to enable\r
 296  */\r
 297 static inline void system_voltage_reference_enable(\r
 298                 const enum system_voltage_reference vref)\r
 299 {\r
 300         switch (vref) {\r
 301                 case SYSTEM_VOLTAGE_REFERENCE_TEMPSENSE:\r
 302                         SYSCTRL->VREF.reg |= SYSCTRL_VREF_TSEN;\r
 303                         break;\r
 304 \r
 305                 case SYSTEM_VOLTAGE_REFERENCE_BANDGAP:\r
 306                         SYSCTRL->VREF.reg |= SYSCTRL_VREF_BGOUTEN;\r
 307                         break;\r
 308 \r
 309                 default:\r
 310                         Assert(false);\r
 311                         return;\r
 312         }\r
 313 }\r
 314 \r
 315 /**\r
 316  * \brief Disable the selected voltage reference\r
 317  *\r
 318  * Disables the selected voltage reference source.\r
 319  *\r
 320  * \param[in] vref  Voltage reference to disable\r
 321  */\r
 322 static inline void system_voltage_reference_disable(\r
 323                 const enum system_voltage_reference vref)\r
 324 {\r
 325         switch (vref) {\r
 326                 case SYSTEM_VOLTAGE_REFERENCE_TEMPSENSE:\r
 327                         SYSCTRL->VREF.reg &= ~SYSCTRL_VREF_TSEN;\r
 328                         break;\r
 329 \r
 330                 case SYSTEM_VOLTAGE_REFERENCE_BANDGAP:\r
 331                         SYSCTRL->VREF.reg &= ~SYSCTRL_VREF_BGOUTEN;\r
 332                         break;\r
 333 \r
 334                 default:\r
 335                         Assert(false);\r
 336                         return;\r
 337         }\r
 338 }\r
 339 \r
 340 /**\r
 341  * @}\r
 342  */\r
 343 \r
 344 \r
 345 /**\r
 346  * \name Device sleep\r
 347  * @{\r
 348  */\r
 349 \r
 350 /**\r
 351  * \brief Set the sleep mode of the device\r
 352  *\r
 353  * Sets the sleep mode of the device; the configured sleep mode will be entered\r
 354  * upon the next call of the \ref system_sleep() function.\r
 355  *\r
 356  * For an overview of which systems are disabled in sleep for the different\r
 357  * sleep modes, see \ref asfdoc_samd20_system_module_overview_sleep_mode.\r
 358  *\r
 359  * \param[in] sleep_mode  Sleep mode to configure for the next sleep operation\r
 360  *\r
 361  * \retval STATUS_OK               Operation completed successfully\r
 362  * \retval STATUS_ERR_INVALID_ARG  The requested sleep mode was invalid or not\r
 363  *                                 available\r
 364  */\r
 365 static inline enum status_code system_set_sleepmode(\r
 366         const enum system_sleepmode sleep_mode)\r
 367 {\r
 368         switch (sleep_mode) {\r
 369                 case SYSTEM_SLEEPMODE_IDLE_0:\r
 370                 case SYSTEM_SLEEPMODE_IDLE_1:\r
 371                 case SYSTEM_SLEEPMODE_IDLE_2:\r
 372                         SCB->SCR &= ~SCB_SCR_SLEEPDEEP_Msk;\r
 373                         PM->SLEEP.reg = sleep_mode;\r
 374                         break;\r
 375 \r
 376                 case SYSTEM_SLEEPMODE_STANDBY:\r
 377                         SCB->SCR |=  SCB_SCR_SLEEPDEEP_Msk;\r
 378                         break;\r
 379 \r
 380                 default:\r
 381                         return STATUS_ERR_INVALID_ARG;\r
 382         }\r
 383 \r
 384         return STATUS_OK;\r
 385 }\r
 386 \r
 387 /**\r
 388  * \brief Put the system to sleep waiting for interrupt\r
 389  *\r
 390  * Executes a device DSB (Data Synchronization Barrier) instruction to ensure\r
 391  * all ongoing memory accesses have completed, then a WFI (Wait For Interrupt)\r
 392  * instruction to place the device into the sleep mode specified by\r
 393  * \ref system_set_sleepmode until woken by an interrupt.\r
 394  */\r
 395 static inline void system_sleep(void)\r
 396 {\r
 397         __DSB();\r
 398         __WFI();\r
 399 }\r
 400 \r
 401 /**\r
 402  * @}\r
 403  */\r
 404 \r
 405 /**\r
 406  * \name Reset control\r
 407  * @{\r
 408  */\r
 409 \r
 410 /**\r
 411  * \brief Reset the MCU\r
 412  *\r
 413  * Resets the MCU and all associated peripherals and registers, except RTC, all 32kHz sources,\r
 414  * WDT (if ALWAYSON is set) and GCLK (if WRTLOCK is set).\r
 415  *\r
 416  */\r
 417 static inline void system_reset(void)\r
 418 {\r
 419         NVIC_SystemReset();\r
 420 }\r
 421 \r
 422 /**\r
 423  * \brief Return the reset cause\r
 424  *\r
 425  * Retrieves the cause of the last system reset.\r
 426  *\r
 427  * \return An enum value indicating the cause of the last system reset.\r
 428  */\r
 429 static inline enum system_reset_cause system_get_reset_cause(void)\r
 430 {\r
 431         return (enum system_reset_cause)PM->RCAUSE.reg;\r
 432 }\r
 433 \r
 434 /**\r
 435  * @}\r
 436  */\r
 437 \r
 438 \r
 439 /**\r
 440  * \name System initialization\r
 441  * @{\r
 442  */\r
 443 \r
 444 void system_init(void);\r
 445 \r
 446 /**\r
 447  * @}\r
 448  */\r
 449 \r
 450 \r
 451 /**\r
 452  * @}\r
 453  */\r
 454 \r
 455 /**\r
 456  * \page asfdoc_samd20_system_extra Extra Information for SYSTEM Driver\r
 457  *\r
 458  * \section asfdoc_samd20_system_extra_acronyms Acronyms\r
 459  * Below is a table listing the acronyms used in this module, along with their\r
 460  * intended meanings.\r
 461  *\r
 462  * <table>\r
 463  *  <tr>\r
 464  *      <th>Acronym</th>\r
 465  *      <th>Definition</th>\r
 466  *  </tr>\r
 467  *  <tr>\r
 468  *              <td>PM</td>\r
 469  *              <td>Power Manager</td>\r
 470  *  </tr>\r
 471  *  <tr>\r
 472  *              <td>SYSCTRL</td>\r
 473  *              <td>System control interface</td>\r
 474  *  </tr>\r
 475  * </table>\r
 476  *\r
 477  *\r
 478  * \section asfdoc_samd20_system_extra_dependencies Dependencies\r
 479  * This driver has the following dependencies:\r
 480  *\r
 481  *  - None\r
 482  *\r
 483  *\r
 484  * \section asfdoc_samd20_system_extra_errata Errata\r
 485  * There are no errata related to this driver.\r
 486  *\r
 487  *\r
 488  * \section asfdoc_samd20_system_extra_history Module History\r
 489  * An overview of the module history is presented in the table below, with\r
 490  * details on the enhancements and fixes made to the module since its first\r
 491  * release. The current version of this corresponds to the newest version in\r
 492  * the table.\r
 493  *\r
 494  * <table>\r
 495  *      <tr>\r
 496  *              <th>Changelog</th>\r
 497  *      </tr>\r
 498  *      <tr>\r
 499  *              <td>Added new \c system_reset() to reset the complete MCU with some exceptions</td>\r
 500  *      </tr>\r
 501  *      <tr>\r
 502  *              <td>Added new \c system_get_device_id() function to retrieved the device\r
 503  *          ID.</td>\r
 504  *      </tr>\r
 505  *      <tr>\r
 506  *              <td>Initial Release</td>\r
 507  *      </tr>\r
 508  * </table>\r
 509  *\r
 510  * \page asfdoc_samd20_system_document_revision_history Document Revision History\r
 511  *\r
 512  * <table>\r
 513  *      <tr>\r
 514  *              <th>Doc. Rev.</td>\r
 515  *              <th>Date</td>\r
 516  *              <th>Comments</td>\r
 517  *      </tr>\r
 518  *      <tr>\r
 519  *              <td>B</td>\r
 520  *              <td>06/2013</td>\r
 521  *              <td>Corrected documentation typos.</td>\r
 522  *      </tr>\r
 523  *      <tr>\r
 524  *              <td>A</td>\r
 525  *              <td>06/2013</td>\r
 526  *              <td>Initial release</td>\r
 527  *      </tr>\r
 528  * </table>\r
 529  */\r
 530 \r
 531 #endif /* SYSTEM_H_INCLUDED */\r