tmk_core/tool/mbed/mbed-sdk/libraries/mbed/targets/hal/TARGET_Freescale/TARGET_KPSDK_MCUS/TARGET_KPSDK_CODE/utilities/sw_timer.h

   1 /*
   2  * Copyright (c) 2013 - 2014, Freescale Semiconductor, Inc.
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without modification,
   6  * are permitted provided that the following conditions are met:
   7  *
   8  * o Redistributions of source code must retain the above copyright notice, this list
   9  *   of conditions and the following disclaimer.
  10  *
  11  * o Redistributions in binary form must reproduce the above copyright notice, this
  12  *   list of conditions and the following disclaimer in the documentation and/or
  13  *   other materials provided with the distribution.
  14  *
  15  * o Neither the name of Freescale Semiconductor, Inc. nor the names of its
  16  *   contributors may be used to endorse or promote products derived from this
  17  *   software without specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  20  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  21  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  22  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
  23  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  24  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  25  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
  26  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  28  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29  */
  30
  31 #if !defined(__SW_TIMER_H__)
  32 #define __SW_TIMER_H__
  33
  34 #include <stdint.h>
  35 #include <stdbool.h>
  36
  37 /*! @addtogroup sw_timer Software Timer
  38  * @brief This module is used to interface with Abstract Timer HAL to generate periodical timeouts
  39  * required through different modules of the AOA protocol. This block will be based on 1ms
  40  * ticks for all the timeout calculations. The HAL Interface block used to communicate with
  41  * this must have the same 1ms timeout configured. This module can generate different
  42  * software timer channels based on the same 1ms.
  43  */
  44 /*! @{*/
  45
  46 /*! Definition of the possible status of a software channel timer. */
  47 typedef enum SwTimerChannelStatus
  48 {
  49     kSwTimerChannelExpired       = 0x00, /*!< Indicates the timer channel has counted the given ms*/
  50     kSwTimerChannelStillCounting = 0x01, /*!< Indicates the timeout of the channel has not expired
  51                                               and the timer is still counting.*/
  52     kSwTimerChannelIsDisable     = 0x02, /*!< Indicates the timer channel is not reserved. */
  53     kSwTimerChannelNotAvailable  = 0xFF  /*!< Indicates there are not available channels to reserve
  54                                               or the requested channel is not available.*/
  55 }sw_timer_channel_status_t;
  56
  57 /*! List of status and errors. */
  58 enum _sw_timer_errors
  59 {
  60     kSwTimerStatusSuccess,           /*!< The execution was successful.*/
  61     kSwTimerStatusFail,              /*!< The execution failed.*/
  62     kSwTimerStatusInvalidChannel     /*!< The given channel is not valid. Valid channels are 0 to
  63                                           (SW_TIMER_NUMBER_CHANNELS - 1). */
  64 };
  65
  66 /*!
  67  * Data type of the counter of each timer channel. If it is an int8_t the counter will count
  68  * up to 127ms, int16_t up to 32767ms and int32_t up to 2147483647ms.
  69  */
  70 typedef int32_t time_counter_t;
  71
  72 /*! Max timeout value according to size of the time counter */
  73 enum sw_timer_timeouts
  74 {
  75     kSwTimerMaxTimeout = 2147483647
  76 };
  77
  78 /*!
  79  * Data type of the free running counter. This data type should be unsigned and will count up to
  80  * 255ms if it is uint8_t, 65535ms for uint16_t and 4294967295ms for uint32_t.
  81  */
  82 typedef uint32_t time_free_counter_t;
  83
  84 #if defined(__cplusplus)
  85 extern "C" {
  86 #endif /* __cplusplus*/
  87
  88 /*!
  89  * @brief Initializes the software timer module. Prepares variables and HAL layer to provide timer
  90  *        services. Starts the free running counter which will be available to get its value any
  91  *        time while the service is running; it is useful whenever a module wants to keep track of
  92  *        time, but do not wants to reserve a channel.
  93  *
  94  * @return status_t        Returns software timer status after initialization.
  95  * @retval kSwTimerStatusSuccess  The initialization was successful and the software timer is ready
  96  *                                to provide services.
  97  * @retval kSwTimerStatusFail     The initialization failed.
  98  */
  99 uint32_t sw_timer_init_service(void);
 100
 101 /*!
 102  * @brief Deinitializes the software timer module. Shutdown HAL layer, so no timer service can be
 103  *        provided after the execution of this function.
 104  *
 105  * @return void
 106  */
 107 void sw_timer_shutdown_service(void);
 108
 109 /*!
 110  * @brief Reserves a free timer channel to be used by any module and returns its identifier.
 111  *
 112  * @return uint8_t        Returns the number of the channel that was reserved.
 113  * @retval Any value between 0 and SW_TIMER_NUMBER_CHANNELS is a valid channel. It indicates the
 114  *         channel was reserved and can be used.
 115  * @retval kSwTimerChannelNotAvailable  If there is not any available channel, because all
 116  *                                         channels are already reserved.
 117  */
 118 uint8_t sw_timer_reserve_channel(void);
 119
 120 /*!
 121  * @brief Returns the actual status of the given timer channel. The timer has to be previously
 122  *        started to return a valid status.
 123  *
 124  * @param timerChannel    [in] Indicates the timer channel which status is going to be returned.
 125  *
 126  * @return sw_timer_channel_status_t     Current status of the given timer channel.
 127  * @retval kSwTimerChannelExpired        Indicates the timer channel has counted the given ms.
 128  * @retval kSwTimerChannelStillCounting  Indicates the timeout of the channel has not expired and
 129                                          the timer is still counting.
 130  * @retval kSwTimerChannelIsDisable      Indicates the timer channel is not reserved.
 131  * @retval kSwTimerChannelNotAvailable   Indicates the timer channel is invalid.
 132  */
 133 sw_timer_channel_status_t sw_timer_get_channel_status(uint8_t timerChannel);
 134
 135 /*!
 136  * @brief Starts the count down of the given timer channel. The timer channel has to be previously
 137  *        reserved.
 138  *
 139  * @param timerChannel    [in] Indicates the timer channel that is going to be started.
 140  * @param timeout         [in] Time in ms that the timer channel will count. The timeout should be
 141                                a multiple of count unit of the timer, otherwise it will be taken
 142                                the integer part of the division and the exact count will not be
 143                                achieved
 144  *
 145  * @return status_t                        Reports failures in the execution of the function.
 146  * @retval kSwTimerStatusSuccess           A channel was started successfully.
 147  * @retval kSwTimerStatusInvalidChannel    The timer channel is invalid, it does not exist.
 148  */
 149 uint32_t sw_timer_start_channel(uint8_t timerChannel, time_counter_t timeout);
 150
 151 /*!
 152  * @brief Releases the given timer channel, so it can be used by someone else.
 153  *
 154  * @param timerChannel    [in] Identifier of the timer channel.
 155  *
 156  * @return status_t                        Reports failures in the execution of the function.
 157  * @retval kSwTimerStatusSuccess           A channel was released successfully.
 158  * @retval kSwTimerStatusInvalidChannel    The timer channel is invalid, it does not exist.
 159  */
 160 uint32_t sw_timer_release_channel(uint8_t timerChannel);
 161
 162 /*!
 163  * @brief Gets the current value of the free running counter. Any module can keep track of the time
 164  *        by reading this counter and calculates time difference. No reservation of timer channel
 165  *        is needed. Consider for calculations that when the counter overflows it will start from
 166  *        0 again.
 167  *
 168  * @return time_free_counter_t  Returns current count of the free running counter.
 169  */
 170 time_free_counter_t sw_timer_get_free_counter(void);
 171
 172 /*!
 173  * @brief This function is called every 1ms by the interruption and update count down values of all
 174  *        timer channels.
 175  *
 176  * @return void
 177  */
 178 void sw_timer_update_counters(void);
 179
 180
 181 #if defined(__cplusplus)
 182 }
 183 #endif /* __cplusplus*/
 184 /*! @}*/
 185 /*Group sw_timer*/
 186
 187 #endif  /* __SW_TIMER_H__ */
 188 /*******************************************************************************
 189  * EOF
 190  ******************************************************************************/
 191