RtosTimer.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2012 ARM Limited
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a copy
00005  * of this software and associated documentation files (the "Software"), to deal
00006  * in the Software without restriction, including without limitation the rights
00007  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00008  * copies of the Software, and to permit persons to whom the Software is
00009  * furnished to do so, subject to the following conditions:
00010  *
00011  * The above copyright notice and this permission notice shall be included in
00012  * all copies or substantial portions of the Software.
00013  *
00014  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00015  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00016  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00017  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00018  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00019  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
00020  * SOFTWARE.
00021  */
00022 #ifndef RTOS_TIMER_H
00023 #define RTOS_TIMER_H
00024 
00025 #include <stdint.h>
00026 #include "cmsis_os2.h"
00027 #include "mbed_rtos_storage.h"
00028 #include "platform/Callback.h"
00029 #include "platform/NonCopyable.h"
00030 #include "platform/mbed_toolchain.h"
00031 #include "mbed_rtos1_types.h"
00032 
00033 namespace rtos {
00034 /** \addtogroup rtos */
00035 /** @{*/
00036 /**
00037  * \defgroup rtos_RtosTimer RtosTimer class
00038  * @{
00039  */
00040  
00041 /** The RtosTimer class allow creating and and controlling of timer functions in the system.
00042  A timer function is called when a time period expires whereby both on-shot and
00043  periodic timers are possible. A timer can be started, restarted, or stopped.
00044 
00045  Timers are handled in the thread osTimerThread.
00046  Callback functions run under control of this thread and may use CMSIS-RTOS API calls.
00047 
00048  @deprecated
00049  The RtosTimer has been superseded by the EventQueue. The RtosTimer and EventQueue duplicate
00050  the functionality of timing events outside of interrupt context, however the EventQueue
00051  has additional features to handle deferring other events to multiple contexts.
00052 
00053  For an example, the following code shows a simple use of the RtosTimer:
00054  @code
00055  DigitalOut led(LED1);
00056  void blink() {
00057      led = !led;
00058  }
00059 
00060  RtosTimer timer(&blink);
00061  int main() {
00062      timer.start(1000); // call blink every 1s
00063      wait_ms(5000);
00064      timer.stop(); // stop after 5s
00065  }
00066  @endcode
00067 
00068  This is the above example rewritten to use the EventQueue:
00069  @code
00070  DigitalOut led(LED1);
00071  void blink() {
00072      led = !led;
00073  }
00074 
00075  EventQueue queue(4*EVENTS_EVENT_SIZE);
00076  int main() {
00077     int blink_id = queue.call_every(1000, &blink); // call blink every 1s
00078     queue.dispatch(5000);
00079     queue.cancel(blink_id); // stop after 5s
00080  }
00081  @endcode
00082 
00083  @note
00084  Memory considerations: The timer control structures will be created on current thread's stack, both for the mbed OS
00085  and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
00086 */
00087 class RtosTimer : private mbed::NonCopyable<RtosTimer> {
00088 public:
00089     /** Create timer.
00090       @param   func      function to be executed by this timer.
00091       @param   type      osTimerOnce for one-shot or osTimerPeriodic for periodic behaviour. (default: osTimerPeriodic)
00092       @param   argument  argument to the timer call back function. (default: NULL)
00093       @deprecated Replaced with RtosTimer(Callback<void()>, os_timer_type)
00094       @deprecated
00095           The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details
00096 
00097       @note You cannot call this function from ISR context.
00098      */
00099     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00100         "Replaced with RtosTimer(Callback<void()>, os_timer_type)")
00101     MBED_DEPRECATED_SINCE("mbed-os-5.2",
00102         "The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details")
00103     RtosTimer(void (*func)(void const *argument), os_timer_type type=osTimerPeriodic, void *argument=NULL) {
00104         constructor(mbed::callback((void (*)(void *))func, argument), type);
00105     }
00106     
00107     /** Create timer.
00108       @param   func      function to be executed by this timer.
00109       @param   type      osTimerOnce for one-shot or osTimerPeriodic for periodic behaviour. (default: osTimerPeriodic)
00110       @deprecated
00111           The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details
00112 
00113       @note You cannot call this function from ISR context.
00114     */
00115     MBED_DEPRECATED_SINCE("mbed-os-5.2",
00116         "The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details")
00117     RtosTimer(mbed::Callback<void()> func, os_timer_type type=osTimerPeriodic) {
00118         constructor(func, type);
00119     }
00120     
00121     /** Create timer.
00122       @param   obj       pointer to the object to call the member function on.
00123       @param   method    member function to be executed by this timer.
00124       @param   type      osTimerOnce for one-shot or osTimerPeriodic for periodic behaviour. (default: osTimerPeriodic)
00125       @deprecated
00126           The RtosTimer constructor does not support cv-qualifiers. Replaced by
00127           RtosTimer(callback(obj, method), os_timer_type).
00128       @deprecated
00129           The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details
00130 
00131       @note You cannot call this function from ISR context.
00132     */
00133     template <typename T, typename M>
00134     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00135         "The RtosTimer constructor does not support cv-qualifiers. Replaced by "
00136         "RtosTimer(callback(obj, method), os_timer_type).")
00137     MBED_DEPRECATED_SINCE("mbed-os-5.2",
00138         "The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details")
00139     RtosTimer(T *obj, M method, os_timer_type type=osTimerPeriodic) {
00140         constructor(mbed::callback(obj, method), type);
00141     }
00142 
00143     /** Stop the timer.
00144       @return  status code that indicates the execution status of the function:
00145           @a osOK the timer has been stopped.
00146           @a osErrorISR @a stop cannot be called from interrupt service routines.
00147           @a osErrorParameter internal error.
00148           @a osErrorResource the timer is not running.
00149 
00150       @note You cannot call this function from ISR context.
00151     */
00152     osStatus stop(void);
00153 
00154     /** Start or restart the timer.
00155       @param   millisec  non-zero value of the timer.
00156       @return  status code that indicates the execution status of the function:
00157           @a osOK the timer has been started or restarted.
00158           @a osErrorISR @a start cannot be called from interrupt service routines.
00159           @a osErrorParameter internal error or incorrect parameter value.
00160           @a osErrorResource internal error (the timer is in an invalid timer state).
00161 
00162       @note You cannot call this function from ISR context.
00163     */
00164     osStatus start(uint32_t millisec);
00165 
00166     /** RtosTimer destructor
00167      *
00168      * @note You cannot call this function from ISR context.
00169      */
00170     ~RtosTimer();
00171 
00172 private:
00173     // Required to share definitions without
00174     // delegated constructors
00175     void constructor(mbed::Callback<void()> func, os_timer_type type);
00176 
00177     osTimerId_t _id;
00178     mbed_rtos_storage_timer_t _obj_mem;
00179     mbed::Callback<void()> _function;
00180 };
00181 /** @}*/
00182 /** @}*/
00183 
00184 }
00185 
00186 #endif
00187 
00188