1 /** 2 * \file 3 * 4 * \brief Timer task functionality declaration. 5 * 6 * Copyright (C) 2014 - 2016 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 #ifndef _HAL_TIMER_H_INCLUDED 45 #define _HAL_TIMER_H_INCLUDED 46 47 #include <utils_list.h> 48 #include <hpl_timer.h> 49 50 #ifdef __cplusplus 51 extern "C" { 52 #endif 53 54 /** 55 * \addtogroup doc_driver_hal_timer 56 * 57 * @{ 58 */ 59 60 /** 61 * \brief Timer mode type 62 */ 63 enum timer_task_mode { TIMER_TASK_ONE_SHOT, TIMER_TASK_REPEAT }; 64 65 /** 66 * \brief Timer task descriptor 67 * 68 * The timer task descriptor forward declaration. 69 */ 70 struct timer_task; 71 72 /** 73 * \brief Timer task callback function type 74 */ 75 typedef void (*timer_cb_t)(const struct timer_task *const timer_task); 76 77 /** 78 * \brief Timer task structure 79 */ 80 struct timer_task { 81 struct list_element elem; /*! List element. */ 82 uint32_t time_label; /*! Absolute timer start time. */ 83 84 uint32_t interval; /*! Number of timer ticks before calling the task. */ 85 timer_cb_t cb; /*! Function pointer to the task. */ 86 enum timer_task_mode mode; /*! Task mode: one shot or repeat. */ 87 }; 88 89 /** 90 * \brief Timer structure 91 */ 92 struct timer_descriptor { 93 struct _timer_device device; 94 uint32_t time; 95 struct list_descriptor tasks; /*! Timer tasks list. */ 96 volatile uint8_t flags; 97 }; 98 99 /** 100 * \brief Initialize timer 101 * 102 * This function initializes the given timer. 103 * It checks if the given hardware is not initialized and if the given hardware 104 * is permitted to be initialized. 105 * 106 * \param[out] descr A timer descriptor to initialize 107 * \param[in] hw The pointer to the hardware instance 108 * \param[in] func The pointer to a set of function pointers 109 * 110 * \return Initialization status. 111 */ 112 int32_t timer_init(struct timer_descriptor *const descr, void *const hw, struct _timer_hpl_interface *const func); 113 114 /** 115 * \brief Deinitialize timer 116 * 117 * This function deinitializes the given timer. 118 * It checks if the given hardware is initialized and if the given hardware is 119 * permitted to be deinitialized. 120 * 121 * \param[in] descr A timer descriptor to deinitialize 122 * 123 * \return De-initialization status. 124 */ 125 int32_t timer_deinit(struct timer_descriptor *const descr); 126 127 /** 128 * \brief Start timer 129 * 130 * This function starts the given timer. 131 * It checks if the given hardware is initialized. 132 * 133 * \param[in] descr The timer descriptor of a timer to start 134 * 135 * \return Timer starting status. 136 */ 137 int32_t timer_start(struct timer_descriptor *const descr); 138 139 /** 140 * \brief Stop timer 141 * 142 * This function stops the given timer. 143 * It checks if the given hardware is initialized. 144 * 145 * \param[in] descr The timer descriptor of a timer to stop 146 * 147 * \return Timer stopping status. 148 */ 149 int32_t timer_stop(struct timer_descriptor *const descr); 150 151 /** 152 * \brief Set amount of clock cycles per timer tick 153 * 154 * This function sets the amount of clock cycles per timer tick for the given timer. 155 * It checks if the given hardware is initialized. 156 * 157 * \param[in] descr The timer descriptor of a timer to stop 158 * \param[in] clock_cycles The amount of clock cycles per tick to set 159 * 160 * \return Setting clock cycles amount status. 161 */ 162 int32_t timer_set_clock_cycles_per_tick(struct timer_descriptor *const descr, const uint32_t clock_cycles); 163 164 /** 165 * \brief Retrieve the amount of clock cycles in a tick 166 * 167 * This function retrieves how many clock cycles there are in a single timer tick. 168 * It checks if the given hardware is initialized. 169 * 170 * \param[in] descr The timer descriptor of a timer to convert ticks to 171 * clock cycles 172 * \param[out] cycles The amount of clock cycles 173 * 174 * \return The status of clock cycles retrieving. 175 */ 176 int32_t timer_get_clock_cycles_in_tick(const struct timer_descriptor *const descr, uint32_t *const cycles); 177 178 /** 179 * \brief Add timer task 180 * 181 * This function adds the given timer task to the given timer. 182 * It checks if the given hardware is initialized. 183 * 184 * \param[in] descr The timer descriptor of a timer to add task to 185 * \param[in] task A task to add 186 * 187 * \return Timer's task adding status. 188 */ 189 int32_t timer_add_task(struct timer_descriptor *const descr, struct timer_task *const task); 190 191 /** 192 * \brief Remove timer task 193 * 194 * This function removes the given timer task from the given timer. 195 * It checks if the given hardware is initialized. 196 * 197 * \param[in] descr The timer descriptor of a timer to remove task from 198 * \param[in] task A task to remove 199 * 200 * \return Timer's task removing status. 201 */ 202 int32_t timer_remove_task(struct timer_descriptor *const descr, const struct timer_task *const task); 203 204 /** 205 * \brief Retrieve the current driver version 206 * 207 * \return Current driver version. 208 */ 209 uint32_t timer_get_version(void); 210 /**@}*/ 211 212 #ifdef __cplusplus 213 } 214 #endif 215 216 #endif /* _HAL_TIMER_H_INCLUDED */ 217
