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_os.h"
00027 #include "platform/Callback.h"
00028 #include "platform/toolchain.h"
00029 
00030 namespace rtos {
00031 /** \addtogroup rtos */
00032 /** @{*/
00033 
00034 /** The RtosTimer class allow creating and and controlling of timer functions in the system.
00035  A timer function is called when a time period expires whereby both on-shot and
00036  periodic timers are possible. A timer can be started, restarted, or stopped.
00037 
00038  Timers are handled in the thread osTimerThread.
00039  Callback functions run under control of this thread and may use CMSIS-RTOS API calls.
00040 
00041  @deprecated
00042  The RtosTimer has been superseded by the EventQueue. The RtosTimer and EventQueue duplicate
00043  the functionality of timing events outside of interrupt context, however the EventQueue
00044  has additional features to handle deferring other events to multiple contexts.
00045 
00046  For an example, the following code shows a simple use of the RtosTimer:
00047  @code
00048  DigitalOut led(LED1);
00049  void blink() {
00050      led = !led;
00051  }
00052 
00053  RtosTimer timer(&blink);
00054  int main() {
00055      timer.start(1000); // call blink every 1s
00056      wait_ms(5000);
00057      timer.stop(); // stop after 5s
00058  }
00059  @endcode
00060 
00061  This is the above example rewritten to use the EventQueue:
00062  @code
00063  DigitalOut led(LED1);
00064  void blink() {
00065      led = !led;
00066  }
00067 
00068  EventQueue queue(4*EVENTS_EVENT_SIZE);
00069  int main() {
00070     int blink_id = queue.call_every(1000, &blink); // call blink every 1s
00071     queue.dispatch(5000);
00072     queue.cancel(blink_id); // stop after 5s
00073  }
00074  @endcode
00075 */
00076 class RtosTimer {
00077 public:
00078     /** Create timer.
00079       @param   func      function to be executed by this timer.
00080       @param   type      osTimerOnce for one-shot or osTimerPeriodic for periodic behaviour. (default: osTimerPeriodic)
00081       @param   argument  argument to the timer call back function. (default: NULL)
00082       @deprecated Replaced with RtosTimer(Callback<void()>, os_timer_type)
00083       @deprecated
00084           The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details
00085      */
00086     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00087         "Replaced with RtosTimer(Callback<void()>, os_timer_type)")
00088     MBED_DEPRECATED_SINCE("mbed-os-5.2",
00089         "The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details")
00090     RtosTimer(void (*func)(void const *argument), os_timer_type type=osTimerPeriodic, void *argument=NULL) {
00091         constructor(mbed::callback((void (*)(void *))func, argument), type);
00092     }
00093     
00094     /** Create timer.
00095       @param   func      function to be executed by this timer.
00096       @param   type      osTimerOnce for one-shot or osTimerPeriodic for periodic behaviour. (default: osTimerPeriodic)
00097       @deprecated
00098           The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details
00099     */
00100     MBED_DEPRECATED_SINCE("mbed-os-5.2",
00101         "The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details")
00102     RtosTimer(mbed::Callback<void()> func, os_timer_type type=osTimerPeriodic) {
00103         constructor(func, type);
00104     }
00105     
00106     /** Create timer.
00107       @param   obj       pointer to the object to call the member function on.
00108       @param   method    member 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 constructor does not support cv-qualifiers. Replaced by
00112           RtosTimer(callback(obj, method), os_timer_type).
00113       @deprecated
00114           The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details
00115     */
00116     template <typename T, typename M>
00117     MBED_DEPRECATED_SINCE("mbed-os-5.1",
00118         "The RtosTimer constructor does not support cv-qualifiers. Replaced by "
00119         "RtosTimer(callback(obj, method), os_timer_type).")
00120     MBED_DEPRECATED_SINCE("mbed-os-5.2",
00121         "The RtosTimer has been superseded by the EventQueue. See RtosTimer.h for more details")
00122     RtosTimer(T *obj, M method, os_timer_type type=osTimerPeriodic) {
00123         constructor(mbed::callback(obj, method), type);
00124     }
00125 
00126     /** Stop the timer.
00127       @return  status code that indicates the execution status of the function.
00128     */
00129     osStatus stop(void);
00130 
00131     /** Start the timer.
00132       @param   millisec  time delay value of the timer.
00133       @return  status code that indicates the execution status of the function.
00134     */
00135     osStatus start(uint32_t millisec);
00136 
00137     ~RtosTimer();
00138 
00139 private:
00140     // Required to share definitions without
00141     // delegated constructors
00142     void constructor(mbed::Callback<void()> func, os_timer_type type);
00143     
00144     mbed::Callback<void()> _function;
00145     osTimerId _timer_id;
00146     osTimerDef_t _timer;
00147 #ifdef CMSIS_OS_RTX
00148     uint32_t _timer_data[6];
00149 #endif
00150 };
00151 
00152 }
00153 
00154 #endif
00155 
00156 /** @}*/