uGFX/ugfx
2
0
Fork 0
Code Issues 2 Pull Requests Projects Releases Wiki Activity

more doxygen cleanup

Browse Source
This commit is contained in:
Joel Bodenmann 2012-12-19 19:48:12 +01:00
parent 7a6bf59b2b
commit e00f8593e8
3 changed files with 95 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
include/gevent/gevent.h
View File

@ -37,13 +37,9 @@
#if GFX_USE_GEVENT || defined(__DOXYGEN__)
/**
* @brief Data part of a static GListener initializer.
*/
/* Data part of a static GListener initializer */
#define _GLISTENER_DATA(name) { _SEMAPHORE_DATA(name.waitqueue, 0), _BSEMAPHORE_DATA(name.eventlock, FALSE), 0, 0, {0} }
/**
* @brief Static GListener initializer.
*/
/* Static GListener initializer */
#define GLISTENER_DECL(name) GListener name = _GLISTENER_DATA(name)
/*===========================================================================*/

101
include/gtimer/gtimer.h
View File

@ -36,6 +36,7 @@
*
* @{
*/
#ifndef _GTIMER_H
#define _GTIMER_H
@ -47,19 +48,13 @@
/* Type definitions */
/*===========================================================================*/
/**
* @brief Data part of a static GTimer initializer.
*/
/* Data part of a static GTimer initialiser */
#define _GTIMER_DATA() {0,0,0,0,0,0,0}
/**
* @brief Static GTimer initializer.
*/
/* Static GTimer initialiser */
#define GTIMER_DECL(name) GTimer name = _GTIMER_DATA()
/**
* @brief A callback function (executed in a thread context).
*/
/* A callback function (executed in a thread context) */
typedef void (*GTimerFunction)(void *param);
/**
@ -73,7 +68,7 @@ typedef struct GTimer_t {
uint16_t flags;
struct GTimer_t *next;
struct GTimer_t *prev;
} GTimer;
} GTimer;
/*===========================================================================*/
/* External declarations. */
@ -83,11 +78,97 @@ typedef struct GTimer_t {
extern "C" {
#endif
/**
* @brief Initialise a timer.
*
* @param[in] pt pointer to a GTimer structure
*
* @api
*/
void gtimerInit(GTimer *pt);
/**
* @brief Set a timer going or alter its properties if it is already going.
*
* @param[in] pt Pointer to a GTimer structure
* @param[in] fn The callback function
* @param[in] param The parameter to pass to the callback function
* @param[in] periodic Is the timer a periodic timer? FALSE is a once-only timer.
* @param[in] millisec The timer period. The following special values are allowed:
* TIME_IMMEDIATE causes the callback function to be called asap.
* A periodic timer with this value will fire once only.
* TIME_INFINITE never timeout (unless triggered by gtimerJab or gtimerJabI)
*
* @note If the timer is already active its properties are updated with the new parameters.
* The current period will be immediately canceled (without the callback function being
* called) and the timer will be restart with the new timer properties.
* @note The callback function should be careful not to over-run the thread stack.
* Define a new value for the macro GTIME_THREAD_STACK_SIZE if you want to
* change the default size.
* @note The callback function should return as quickly as possible as all
* timer callbacks are performed by a single thread. If a callback function
* takes too long it could affect the timer response for other timers.
* @note A timer callback function is not a replacement for a dedicated thread if the
* function wants to perform computationally expensive stuff.
* @note As the callback function is called on GTIMER's thread, the function must make sure it uses
* appropriate synchronisation controls such as semaphores or mutexes around any data
* structures it shares with other threads such as the main application thread.
*
* @api
*/
void gtimerStart(GTimer *pt, GTimerFunction fn, void *param, bool_t periodic, systime_t millisec);
/**
* @brief Stop a timer (periodic or otherwise)
*
* @param[in] pt Pointer to a GTimer structure
*
* @note If the timer is not active this does nothing.
*
* @api
*/
void gtimerStop(GTimer *pt);
/**
* @brief Test if a timer is currently active
*
* @param[in] pt Pointer to a GTimer structure
*
* @return TRUE if active, FALSE otherwise
*
* @api
*/
bool_t gtimerIsActive(GTimer *pt);
/**
* @brief Jab a timer causing the current period to immediate expire
* @details The callback function will be called as soon as possible.
*
* @pre Use from a normal thread context.
*
* @param[in] pt Pointer to a GTimer structure
*
* @note If the timer is not active this does nothing.
* @note Repeated Jabs before the callback function actually happens are ignored.
*
* @api
*/
void gtimerJab(GTimer *pt);
/**
* @brief Jab a timer causing the current period to immediate expire
* @details The callback function will be called as soon as possible.
*
* @pre Use from an interrupt routine context.
*
* @param[in] pt Pointer to a GTimer structure
*
* @note If the timer is not active this does nothing.
* @note Repeated Jabs before the callback function actually happens are ignored.
*
* @iclass
* @api
*/
void gtimerJabI(GTimer *pt);
#ifdef __cplusplus

84
src/gtimer/gtimer.c
View File

@ -43,7 +43,7 @@
/* Don't rework this macro to use a ternary operator - the gcc compiler stuffs it up */
#define TimeIsWithin(x, start, end) ((end >= start && x >= start && x <= end) || (end < start && (x >= start || x <= end)))
// This mutex protects access to our tables
/* This mutex protects access to our tables */
static MUTEX_DECL(mutex);
static Thread *pThread = 0;
static GTimer *pTimerHead = 0;
@ -141,46 +141,10 @@ static msg_t GTimerThreadHandler(void *arg) {
return 0;
}
/**
* @brief Initialise a timer.
*
* @param[in] pt pointer to a GTimer structure
*
* @api
*/
void gtimerInit(GTimer *pt) {
pt->flags = 0;
}
/**
* @brief Set a timer going or alter its properties if it is already going.
*
* @param[in] pt Pointer to a GTimer structure
* @param[in] fn The callback function
* @param[in] param The parameter to pass to the callback function
* @param[in] periodic Is the timer a periodic timer? FALSE is a once-only timer.
* @param[in] millisec The timer period. The following special values are allowed:
* TIME_IMMEDIATE causes the callback function to be called asap.
* A periodic timer with this value will fire once only.
* TIME_INFINITE never timeout (unless triggered by gtimerJab or gtimerJabI)
*
* @note If the timer is already active its properties are updated with the new parameters.
* The current period will be immediately canceled (without the callback function being
* called) and the timer will be restart with the new timer properties.
* @note The callback function should be careful not to over-run the thread stack.
* Define a new value for the macro GTIME_THREAD_STACK_SIZE if you want to
* change the default size.
* @note The callback function should return as quickly as possible as all
* timer callbacks are performed by a single thread. If a callback function
* takes too long it could affect the timer response for other timers.
* @note A timer callback function is not a replacement for a dedicated thread if the
* function wants to perform computationally expensive stuff.
* @note As the callback function is called on GTIMER's thread, the function must make sure it uses
* appropriate synchronisation controls such as semaphores or mutexes around any data
* structures it shares with other threads such as the main application thread.
*
* @api
*/
void gtimerStart(GTimer *pt, GTimerFunction fn, void *param, bool_t periodic, systime_t millisec) {
chMtxLock(&mutex);
@ -230,15 +194,6 @@ void gtimerStart(GTimer *pt, GTimerFunction fn, void *param, bool_t periodic, sy
chMtxUnlock();
}
/**
* @brief Stop a timer (periodic or otherwise)
*
* @param[in] pt Pointer to a GTimer structure
*
* @note If the timer is not active this does nothing.
*
* @api
*/
void gtimerStop(GTimer *pt) {
chMtxLock(&mutex);
if (pt->flags & GTIMER_FLG_SCHEDULED) {
@ -257,32 +212,10 @@ void gtimerStop(GTimer *pt) {
chMtxUnlock();
}
/**
* @brief Test if a timer is currently active
*
* @param[in] pt Pointer to a GTimer structure
*
* @return TRUE if active, FALSE otherwise
*
* @api
*/
bool_t gtimerIsActive(GTimer *pt) {
return (pt->flags & GTIMER_FLG_SCHEDULED) ? TRUE : FALSE;
}
/**
* @brief Jab a timer causing the current period to immediate expire
* @details The callback function will be called as soon as possible.
*
* @pre Use from a normal thread context.
*
* @param[in] pt Pointer to a GTimer structure
*
* @note If the timer is not active this does nothing.
* @note Repeated Jabs before the callback function actually happens are ignored.
*
* @api
*/
void gtimerJab(GTimer *pt) {
chMtxLock(&mutex);
@ -294,20 +227,6 @@ void gtimerJab(GTimer *pt) {
chMtxUnlock();
}
/**
* @brief Jab a timer causing the current period to immediate expire
* @details The callback function will be called as soon as possible.
*
* @pre Use from an interrupt routine context.
*
* @param[in] pt Pointer to a GTimer structure
*
* @note If the timer is not active this does nothing.
* @note Repeated Jabs before the callback function actually happens are ignored.
*
* @iclass
* @api
*/
void gtimerJabI(GTimer *pt) {
// Jab it!
pt->flags |= GTIMER_FLG_JABBED;
@ -318,3 +237,4 @@ void gtimerJabI(GTimer *pt) {
#endif /* GFX_USE_GTIMER */
/** @} */