1 /** 2 * \file 3 * 4 * \brief SAM Timer Counter (TC) driver. 5 * 6 * Copyright (c) 2011-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 47 #ifndef TC_H_INCLUDED 48 #define TC_H_INCLUDED 49 50 /** 51 * \defgroup asfdoc_sam_drivers_tc_group SAM3/4S/4L/4E/4N/4CM/4C/G Timer Counter (TC) Driver 52 * 53 * This driver for Atmel® | SMART ARM®-based microcontrollers 54 * provides an interface for the configuration and management of the 55 * device's Timer Counter functionality. 56 * 57 * The Timer Counter (TC) includes several identical 16-bit or 32-bit 58 * Timer Counter channels. Each channel can be independently programmed 59 * to perform a wide range of functions that includes frequency 60 * measurement, event counting, interval measurement, pulse generation, 61 * delay timing, and pulse width modulation. 62 * 63 * Devices from the following series can use this module: 64 * - Atmel | SMART SAM3 65 * - Atmel | SMART SAM4S 66 * - Atmel | SMART SAM4L 67 * - Atmel | SMART SAM4E 68 * - Atmel | SMART SAM4N 69 * - Atmel | SMART SAM4CM 70 * - Atmel | SMART SAM4C 71 * - Atmel | SMART SAMG 72 * 73 * The outline of this documentation is as follows: 74 * - \ref asfdoc_sam_drivers_tc_prerequisites 75 * - \ref asfdoc_sam_drivers_tc_module_overview 76 * - \ref asfdoc_sam_drivers_tc_special_considerations 77 * - \ref asfdoc_sam_drivers_tc_extra_info 78 * - \ref asfdoc_sam_drivers_tc_examples 79 * - \ref asfdoc_sam_drivers_tc_api_overview 80 * 81 * 82 * \section asfdoc_sam_drivers_tc_prerequisites Prerequisites 83 * 84 * There are no prerequisites for this module. 85 * 86 * 87 * \section asfdoc_sam_drivers_tc_module_overview Module Overview 88 * The Timer Counter (TC) includes several identical 16-bit or 32-bit Timer 89 * Counter channels. The number of TC channels is device specific, refer 90 * to the device-specific datasheet for more information. 91 * 92 * Each channel can be independently programmed to perform a wide range of 93 * functions that includes frequency measurement, event counting, interval measurement, 94 * pulse generation, delay timing, and pulse width modulation. 95 * 96 * Each channel has three external clock inputs, five internal clock inputs, 97 * and two multi-purpose input/output signals which can be configured by the user. 98 * Each channel drives an internal interrupt signal which can be programmed to 99 * generate processor interrupts. 100 * 101 * The Timer Counter (TC) embeds a quadrature decoder logic connected in front of 102 * the timers. When enabled, the quadrature decoder performs the input line 103 * filtering, decoding of quadrature signals and connects to the timers/counters 104 * in order to read the position and speed of the motor. 105 * 106 * 107 * \section asfdoc_sam_drivers_tc_special_considerations Special Considerations 108 * \subsection asfdoc_sam_drivers_tc_special_considerations_clock External Clock 109 * In all cases, if an external clock is used, the duration of each of its levels 110 * must be longer than the master clock (MCLK) period. The external clock frequency 111 * must be at least 2.5 times lower than the master clock. 112 * 113 * \subsection asfdoc_sam_drivers_tc_special_considerations_trigger External Trigger 114 * If an external trigger is used, the duration of its pulses must be longer than 115 * the master clock (MCLK) period in order to be detected. 116 * 117 * 118 * \section asfdoc_sam_drivers_tc_extra_info Extra Information 119 * 120 * For extra information, see \ref asfdoc_sam_drivers_tc_extra. This includes: 121 * - \ref asfdoc_sam_drivers_tc_extra_acronyms 122 * - \ref asfdoc_sam_drivers_tc_extra_dependencies 123 * - \ref asfdoc_sam_drivers_tc_extra_errata 124 * - \ref asfdoc_sam_drivers_tc_extra_history 125 * 126 * \section asfdoc_sam_drivers_tc_examples Examples 127 * 128 * For a list of examples related to this driver, see 129 * \ref asfdoc_sam_drivers_tc_exqsg. 130 * 131 * 132 * \section asfdoc_sam_drivers_tc_api_overview API Overview 133 * @{ 134 */ 135 136 #include <compiler.h> 137 138 /// @cond 139 /**INDENT-OFF**/ 140 #ifdef __cplusplus 141 extern "C" { 142 #endif 143 /**INDENT-ON**/ 144 /// @endcond 145 146 void tc_init(Tc *p_tc, uint32_t ul_Channel, uint32_t ul_Mode); 147 void tc_sync_trigger(Tc *p_tc); 148 void tc_set_block_mode(Tc *p_tc, uint32_t ul_blockmode); 149 150 #if (!SAM3U) || defined(__DOXYGEN__) 151 uint32_t tc_init_2bit_gray(Tc *p_tc, uint32_t ul_channel, 152 uint32_t ul_steppermode); 153 #endif /* (!SAM3U) || defined(__DOXYGEN__) */ 154 155 void tc_start(Tc *p_tc, uint32_t ul_channel); 156 void tc_stop(Tc *p_tc, uint32_t ul_channel); 157 158 uint32_t tc_read_cv(Tc *p_tc, uint32_t ul_channel); 159 uint32_t tc_read_ra(Tc *p_tc, uint32_t ul_channel); 160 uint32_t tc_read_rb(Tc *p_tc, uint32_t ul_channel); 161 uint32_t tc_read_rc(Tc *p_tc, uint32_t ul_channel); 162 163 void tc_write_ra(Tc *p_tc, uint32_t ul_channel, 164 uint32_t ul_value); 165 void tc_write_rb(Tc *p_tc, uint32_t ul_channel, 166 uint32_t ul_value); 167 void tc_write_rc(Tc *p_tc, uint32_t ul_channel, 168 uint32_t ul_value); 169 170 uint32_t tc_find_mck_divisor(uint32_t ul_freq, uint32_t ul_mck, 171 uint32_t *p_uldiv, uint32_t *ul_tcclks, uint32_t ul_boardmck); 172 void tc_enable_interrupt(Tc *p_tc, uint32_t ul_channel, 173 uint32_t ul_sources); 174 void tc_disable_interrupt(Tc *p_tc, uint32_t ul_channel, 175 uint32_t ul_sources); 176 uint32_t tc_get_interrupt_mask(Tc *p_tc, uint32_t ul_channel); 177 uint32_t tc_get_status(Tc *p_tc, uint32_t ul_channel); 178 #if (!SAM4L && !SAMG) || defined(__DOXYGEN__) 179 void tc_enable_qdec_interrupt(Tc *p_tc, uint32_t ul_sources); 180 void tc_disable_qdec_interrupt(Tc *p_tc, uint32_t ul_sources); 181 uint32_t tc_get_qdec_interrupt_mask(Tc *p_tc); 182 uint32_t tc_get_qdec_interrupt_status(Tc *p_tc); 183 #endif /* (!SAM4L && !SAMG) || defined(__DOXYGEN__) */ 184 185 #if (!SAM3U) 186 void tc_set_writeprotect(Tc *p_tc, uint32_t ul_enable); 187 #endif /* (!SAM3U) */ 188 189 #if SAM4L || defined(__DOXYGEN__) 190 uint32_t tc_get_feature(Tc *p_tc); 191 uint32_t tc_get_version(Tc *p_tc); 192 #endif /* SAM4L || defined(__DOXYGEN__) */ 193 194 /// @cond 195 /**INDENT-OFF**/ 196 #ifdef __cplusplus 197 } 198 #endif 199 /**INDENT-ON**/ 200 /// @endcond 201 202 /** @} */ 203 204 /** 205 * \page asfdoc_sam_drivers_tc_extra Extra Information for Timer Counter Driver 206 * 207 * \section asfdoc_sam_drivers_tc_extra_acronyms Acronyms 208 * Below is a table listing the acronyms used in this module, along with their 209 * intended meanings. 210 * 211 * <table> 212 * <tr> 213 * <th>Acronym</th> 214 * <th>Definition</th> 215 * </tr> 216 * <tr> 217 * <td>MCK</td> 218 * <td>Master Clock</td> 219 * </tr> 220 * <tr> 221 * <td>PBA</td> 222 * <td>Peripheral Bus A clock</td> 223 * </tr> 224 * <tr> 225 * <td>PHA</td> 226 * <td>Quadrature Decoder input signal Phase A</td> 227 * </tr> 228 * <tr> 229 * <td>PHB</td> 230 * <td>Quadrature Decoder input signal Phase B</td> 231 * </tr> 232 * <tr> 233 * <td>QDEC</td> 234 * <td>Quadrature Decoder</td> 235 * </tr> 236 * <tr> 237 * <td>QSG</td> 238 * <td>Quick Start Guide</td> 239 * </tr> 240 * <tr> 241 * <td>RA</td> 242 * <td>Register A</td> 243 * </tr> 244 * <tr> 245 * <td>RB</td> 246 * <td>Register B</td> 247 * </tr> 248 * <tr> 249 * <td>RC</td> 250 * <td>Register C</td> 251 * </tr> 252 * <tr> 253 * <td>TIOB</td> 254 * <td>Timer Input Output B</td> 255 * </tr> 256 * </table> 257 * 258 * 259 * \section asfdoc_sam_drivers_tc_extra_dependencies Dependencies 260 * This driver has the following dependencies: 261 * 262 * - \ref clk_group "System Clock Management (sysclock)" 263 * - \ref asfdoc_sam_drivers_gpio_group "General Purpose I/O (GPIO) driver" 264 * - \ref asfdoc_sam_drivers_pmc_group "Power Manager Controller (PMC) driver" 265 * 266 * 267 * \section asfdoc_sam_drivers_tc_extra_errata Errata 268 * There are no errata related to this driver. 269 * 270 * 271 * \section asfdoc_sam_drivers_tc_extra_history Module History 272 * An overview of the module history is presented in the table below, with 273 * details on the enhancements and fixes made to the module since its first 274 * release. The current version of this corresponds to the newest version in 275 * the table. 276 * 277 * <table> 278 * <tr> 279 * <th>Changelog</th> 280 * </tr> 281 * <tr> 282 * <td>Initial document release</td> 283 * </tr> 284 * </table> 285 */ 286 287 /** 288 * \page asfdoc_sam_drivers_tc_exqsg Examples for Timer Counter 289 * 290 * This is a list of the available Quick Start Guides (QSGs) and example 291 * applications for \ref asfdoc_sam_drivers_tc_group. QSGs are simple examples with 292 * step-by-step instructions to configure and use this driver in a selection of 293 * use cases. Note that a QSG can be compiled as a standalone application or be 294 * added to the user application. 295 * 296 * - \subpage asfdoc_sam_drivers_tc_qsg 297 * - \subpage asfdoc_sam_drivers_tc_example 298 * 299 * \page asfdoc_sam_drivers_tc_document_revision_history Document Revision History 300 * 301 * <table> 302 * <tr> 303 * <th>Doc. Rev.</td> 304 * <th>Date</td> 305 * <th>Comments</td> 306 * </tr> 307 * <tr> 308 * <td>42301B</td> 309 * <td>07/2015</td> 310 * <td>Updated title of application note and added list of supported devices</td> 311 * </tr> 312 * <tr> 313 * <td>42301A</td> 314 * <td>05/2014</td> 315 * <td>Initial document release</td> 316 * </tr> 317 * </table> 318 * 319 */ 320 321 /** 322 * \page asfdoc_sam_drivers_tc_qsg Quick Start Guide for the TC driver 323 * 324 * This is the quick start guide for the \ref asfdoc_sam_drivers_tc_group, with 325 * step-by-step instructions on how to configure and use the driver for 326 * a specific use case. The code examples can be copied into the main 327 * application loop or any other function that will need to control the 328 * AST module. 329 * 330 * \section asfdoc_sam_drivers_tc_qsg_use_cases Use Cases 331 * - \ref asfdoc_sam_drivers_tc_qsg_basic_capture 332 * - \ref asfdoc_sam_drivers_tc_qsg_basic_waveform 333 * 334 * \section asfdoc_sam_drivers_tc_qsg_basic_capture TC Capture Mode Basic Usage 335 * 336 * This use case will demonstrate how to initialize the TC module to 337 * operate in capture mode using interrupts. Note, that the macros 338 * used to select the TC channel are device specific. Refer to the 339 * appropriate device-specific datasheet for more information. 340 * 341 * 342 * \section asfdoc_sam_drivers_tc_qsg_basic_capture_setup Setup Steps 343 * 344 * \subsection asfdoc_sam_tc_qsg_basic_capture_prereq Prerequisites 345 * 346 * This module requires the following services: 347 * - \ref clk_group "System Clock Management (sysclock)" 348 * - \ref asfdoc_sam_drivers_gpio_group "General Purpose I/O (GPIO) driver" 349 * 350 * \subsection asfdoc_sam_drivers_tc_qsg_basic_capture_setup_code Setup Code 351 * 352 * Add these macros to the top of your main application C-file: 353 * \snippet conf_board.h tc_define_peripheral 354 * \snippet conf_board.h tc_define_ch2 355 * \snippet conf_board.h tc_define_irq_handler 356 * 357 * Add this macro and functions to your main application C-file: 358 * \snippet tc_capture_waveform_example.c tc_capture_selection 359 * \snippet tc_capture_waveform_example.c tc_capture_init 360 * \snippet tc_capture_waveform_example.c tc_capture_irq_handler_start 361 * \snippet tc_capture_waveform_example.c tc_capture_irq_handler_end 362 * 363 * \subsection asfdoc_sam_drivers_tc_qsg_basic_capture_setup_workflow Workflow 364 * 365 * -# Enable the TC module's capture pin: 366 * \snippet tc_capture_waveform_example.c tc_capture_gpio 367 * -# Initialize the capture channel to the following: 368 * - Load RA on the rising edge of TIOA 369 * - Load RB on the falling edge of TIOA 370 * - Set the external trigger to TIOA 371 * - Set the external trigger to falling edge 372 * \snippet tc_capture_waveform_example.c tc_capture_init_call 373 * -# Enable the TC interrupt using NVIC: 374 * \snippet tc_capture_waveform_example.c tc_capture_init_irq 375 * -# Enable the capture channel interrupt: 376 * \snippet tc_capture_waveform_example.c tc_capture_init_module_irq 377 * -# In the \ref TC_Handler_null "TC_Handler()" function, the load. 378 * RB interrupt can be checked by: 379 * \snippet tc_capture_waveform_example.c tc_capture_irq_handler_status 380 * \code } \endcode 381 * -# In the \ref TC_Handler_null "TC_Handler()" function, the RA value. 382 * can be read by: 383 * \code uint32_t gs_ul_captured_ra; \endcode 384 * \snippet tc_capture_waveform_example.c tc_capture_irq_handler_read_ra 385 * -# In the \ref TC_Handler_null "TC_Handler()" function, the RB value. 386 * can be read by: 387 * \code uint32_t gs_ul_captured_rb; \endcode 388 * \snippet tc_capture_waveform_example.c tc_capture_irq_handler_read_rb 389 * 390 * \section asfdoc_sam_drivers_tc_qsg_basic_waveform TC Waveform Mode Basic Usage 391 * 392 * This use case will demonstrate how to initialize the TC module to 393 * operate in waveform mode. Note, that the macros used to select 394 * the TC channel are device specific. Refer to the appropriate 395 * device-specific datasheet for more information. 396 * 397 * 398 * \section asfdoc_sam_drivers_tc_qsg_basic_waveform_setup Setup Steps 399 * 400 * \subsection asfdoc_sam_tc_qsg_basic_waveform_prereq Prerequisites 401 * 402 * This module requires the following services: 403 * - \ref clk_group "System Clock Management (sysclock)" 404 * - \ref asfdoc_sam_drivers_gpio_group "General Purpose I/O (GPIO) driver" 405 * 406 * \subsection asfdoc_sam_drivers_tc_qsg_basic_waveform_setup_code Setup Code 407 * 408 * Add these macros to the top of your main application C-file: 409 * \snippet conf_board.h tc_define_peripheral 410 * \snippet conf_board.h tc_define_ch1 411 * 412 * Add these macros and function to your main application C-file: 413 * \code #define TC_WAVEFORM_TIMER_SELECTION TC_CMR_TCCLKS_TIMER_CLOCK4 \endcode 414 * \code #define TC_WAVEFORM_DIVISOR 128 \endcode 415 * \code #define TC_WAVEFORM_FREQUENCY 178 \endcode 416 * \code #define TC_WAVEFORM_DUTY_CYCLE 30 \endcode 417 * \code 418 * static void tc_waveform_initialize(void) 419 * { 420 * uint32_t ra, rc; 421 * 422 * // Configure the PMC to enable the TC module. 423 * sysclk_enable_peripheral_clock(ID_TC_WAVEFORM); 424 * 425 * // Init TC to waveform mode. 426 * tc_init(TC, TC_CHANNEL_WAVEFORM, 427 * TC_WAVEFORM_TIMER_SELECTION // Waveform Clock Selection 428 * | TC_CMR_WAVE // Waveform mode is enabled 429 * | TC_CMR_ACPA_SET // RA Compare Effect: set 430 * | TC_CMR_ACPC_CLEAR // RC Compare Effect: clear 431 * | TC_CMR_CPCTRG // UP mode with automatic trigger on RC Compare 432 * ); 433 * 434 * // Configure waveform frequency and duty cycle. 435 * rc = (sysclk_get_peripheral_bus_hz(TC) / 436 * TC_WAVEFORM_DIVISOR / 437 * TC_WAVEFORM_FREQUENCY; 438 * tc_write_rc(TC, TC_CHANNEL_WAVEFORM, rc); 439 * ra = (100 - TC_WAVEFORM_FREQUENCY_DUTY_CYCLE * rc / 100; 440 * tc_write_ra(TC, TC_CHANNEL_WAVEFORM, ra); 441 * 442 * // Enable TC TC_CHANNEL_WAVEFORM. 443 * tc_start(TC, TC_CHANNEL_WAVEFORM); 444 * } \endcode 445 * 446 * \subsection asfdoc_sam_drivers_tc_qsg_basic_waveform_setup_workflow Workflow 447 * 448 * -# Enable the TC module's waveform pin: 449 * \snippet tc_capture_waveform_example.c tc_waveform_gpio 450 * -# Initialize the waveform channel to the following: 451 * - Output frequency of 178Hz, with a duty-cycle of 30% 452 * - Use TC_CMR_TCCLKS_TIMER_CLOCK4, with a divisor of 128 453 * \snippet tc_capture_waveform_example.c tc_waveform_init_call 454 */ 455 #endif /* TC_H_INCLUDED */ 456