The official µGFX library repository.

gtimer.h 5.5KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181
  1. /*
  2. * This file is subject to the terms of the GFX License. If a copy of
  3. * the license was not distributed with this file, you can obtain one at:
  4. *
  5. * http://ugfx.org/license.html
  6. */
  7. /**
  8. * @file src/gtimer/gtimer.h
  9. *
  10. * @addtogroup GTIMER
  11. *
  12. * @brief Module which provides software based timers for user-space applications
  13. *
  14. * @details The reason why uGFX has it's own timer abstraction is because
  15. * virtual timers provided by ChibiOS/RT are interrupt context only.
  16. * While great for what they are designed for, they make coding of the input
  17. * drivers much more complex.
  18. * For non-performance critical drivers like these input drivers, it would also
  19. * hog an in-ordinate amount of critical (interrupt locked) system time.
  20. * This contrary to the goals of a real-time operating system. So a user-land
  21. * (thread based) timer mechanism is also required.
  22. *
  23. * @pre GFX_USE_GTIMER must be set to TRUE in your gfxconf.h
  24. *
  25. * @{
  26. */
  27. #ifndef _GTIMER_H
  28. #define _GTIMER_H
  29. #include "../../gfx.h"
  30. #if GFX_USE_GTIMER || defined(__DOXYGEN__)
  31. /*===========================================================================*/
  32. /* Type definitions */
  33. /*===========================================================================*/
  34. /* Data part of a static GTimer initialiser */
  35. #define _GTIMER_DATA() {0,0,0,0,0,0,0}
  36. /* Static GTimer initialiser */
  37. #define GTIMER_DECL(name) GTimer name = _GTIMER_DATA()
  38. /* A callback function (executed in a thread context) */
  39. typedef void (*GTimerFunction)(void *param);
  40. /**
  41. * @brief A GTimer structure
  42. */
  43. typedef struct GTimer_t {
  44. GTimerFunction fn;
  45. void *param;
  46. systemticks_t when;
  47. systemticks_t period;
  48. uint16_t flags;
  49. struct GTimer_t *next;
  50. struct GTimer_t *prev;
  51. } GTimer;
  52. /*===========================================================================*/
  53. /* External declarations. */
  54. /*===========================================================================*/
  55. #ifdef __cplusplus
  56. extern "C" {
  57. #endif
  58. /**
  59. * @brief Initialise a timer
  60. *
  61. * @param[in] pt Pointer to a GTimer structure
  62. *
  63. * @api
  64. */
  65. void gtimerInit(GTimer* pt);
  66. /**
  67. * @brief Deinitialise a timer
  68. *
  69. * @param[in] pt Pointer to a GTimer structure
  70. *
  71. * @api
  72. */
  73. void gtimerDeinit(GTimer* pt);
  74. /**
  75. * @brief Set a timer going or alter its properties if it is already going.
  76. *
  77. * @param[in] pt Pointer to a GTimer structure
  78. * @param[in] fn The callback function
  79. * @param[in] param The parameter to pass to the callback function
  80. * @param[in] periodic Is the timer a periodic timer? FALSE is a once-only timer.
  81. * @param[in] millisec The timer period. The following special values are allowed:
  82. * TIME_IMMEDIATE causes the callback function to be called asap.
  83. * A periodic timer with this value will fire once only.
  84. * TIME_INFINITE never timeout (unless triggered by gtimerJab or gtimerJabI)
  85. *
  86. * @note If the timer is already active its properties are updated with the new parameters.
  87. * The current period will be immediately canceled (without the callback function being
  88. * called) and the timer will be restart with the new timer properties.
  89. * @note The callback function should be careful not to over-run the thread stack.
  90. * Define a new value for the macro GTIME_THREAD_STACK_SIZE if you want to
  91. * change the default size.
  92. * @note The callback function should return as quickly as possible as all
  93. * timer callbacks are performed by a single thread. If a callback function
  94. * takes too long it could affect the timer response for other timers.
  95. * @note A timer callback function is not a replacement for a dedicated thread if the
  96. * function wants to perform computationally expensive stuff.
  97. * @note As the callback function is called on GTIMER's thread, the function must make sure it uses
  98. * appropriate synchronisation controls such as semaphores or mutexes around any data
  99. * structures it shares with other threads such as the main application thread.
  100. *
  101. * @api
  102. */
  103. void gtimerStart(GTimer *pt, GTimerFunction fn, void *param, bool_t periodic, delaytime_t millisec);
  104. /**
  105. * @brief Stop a timer (periodic or otherwise)
  106. *
  107. * @param[in] pt Pointer to a GTimer structure
  108. *
  109. * @note If the timer is not active this does nothing.
  110. *
  111. * @api
  112. */
  113. void gtimerStop(GTimer *pt);
  114. /**
  115. * @brief Test if a timer is currently active
  116. *
  117. * @param[in] pt Pointer to a GTimer structure
  118. *
  119. * @return TRUE if active, FALSE otherwise
  120. *
  121. * @api
  122. */
  123. bool_t gtimerIsActive(GTimer *pt);
  124. /**
  125. * @brief Jab a timer causing the current period to immediate expire
  126. * @details The callback function will be called as soon as possible.
  127. *
  128. * @pre Use from a normal thread context.
  129. *
  130. * @param[in] pt Pointer to a GTimer structure
  131. *
  132. * @note If the timer is not active this does nothing.
  133. * @note Repeated Jabs before the callback function actually happens are ignored.
  134. *
  135. * @api
  136. */
  137. void gtimerJab(GTimer *pt);
  138. /**
  139. * @brief Jab a timer causing the current period to immediate expire
  140. * @details The callback function will be called as soon as possible.
  141. *
  142. * @pre Use from an interrupt routine context.
  143. *
  144. * @param[in] pt Pointer to a GTimer structure
  145. *
  146. * @note If the timer is not active this does nothing.
  147. * @note Repeated Jabs before the callback function actually happens are ignored.
  148. *
  149. * @iclass
  150. * @api
  151. */
  152. void gtimerJabI(GTimer *pt);
  153. #ifdef __cplusplus
  154. }
  155. #endif
  156. #endif /* GFX_USE_GTIMER */
  157. #endif /* _GTIMER_H */
  158. /** @} */