github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-09-04 18:30:18 +00:00
Code Issues Projects Releases Wiki Activity

doc: hv: add comments to timer APIs for documentation

Browse Source 
This patch adds more comment to describe functions that are
interfaces to the other modules in the hypervisor. The comments
are in doxygen-style for document generation.

Tracked-On: #1595
Signed-off-by: Li, Fei1 <fei1.li@intel.com>
This commit is contained in:
Li, Fei1
2018-11-15 19:07:22 +08:00
committed by wenlingz
parent 2dbb0cbafc
commit 5fd6021dee
3 changed files with 108 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
hypervisor/include/arch/x86/timer.h
View File

@@ -7,36 +7,62 @@
#ifndef TIMER_H
#define TIMER_H
/**
* @brief Timer
*
* @defgroup timer ACRN Timer
* @{
*/
typedef void (*timer_handle_t)(void *data);
/**
* @brief Definition of timer tick mode
*/
enum tick_mode {
TICK_MODE_ONESHOT = 0,
TICK_MODE_PERIODIC,
TICK_MODE_ONESHOT = 0, /**< one-shot mode */
TICK_MODE_PERIODIC, /**< periodic mode */
};
/**
* @brief Definition of timers for per-cpu
*/
struct per_cpu_timers {
struct list_head timer_list; /* it's for runtime active timer list */
struct list_head timer_list; /**< it's for runtime active timer list */
};
/**
* @brief Definition of timer
*/
struct hv_timer {
struct list_head node; /* link all timers */
enum tick_mode mode; /* timer mode: one-shot or periodic */
uint64_t fire_tsc; /* tsc deadline to interrupt */
uint64_t period_in_cycle; /* period of the periodic timer in unit of TSC cycles */
timer_handle_t func; /* callback if time reached */
void *priv_data; /* func private data */
struct list_head node; /**< link all timers */
enum tick_mode mode; /**< timer mode: one-shot or periodic */
uint64_t fire_tsc; /**< tsc deadline to interrupt */
uint64_t period_in_cycle; /**< period of the periodic timer in unit of TSC cycles */
timer_handle_t func; /**< callback if time reached */
void *priv_data; /**< func private data */
};
/*
* Don't initialize a timer twice if it has been add to the timer list
* after call add_timer. If u want, delete the timer from the list first.
/* External Interfaces */
/**
* @brief Initialize a timer structure.
*
* @param[in] timer Pointer to timer.
* @param[in] func irq callback if time reached.
* @param[in] priv_data func private data.
* @param[in] fire_tsc tsc deadline to interrupt.
* @param[in] mode timer mode.
* @param[in] period_in_cycle period of the periodic timer in unit of TSC cycles.
*
* @remark Don't initialize a timer twice if it has been added to the timer list
* after calling add_timer. If you want to, delete the timer from the list first.
*
* @return None
*/
static inline void initialize_timer(struct hv_timer *timer,
timer_handle_t func,
void *priv_data,
uint64_t fire_tsc,
int mode,
uint64_t period_in_cycle)
timer_handle_t func, void *priv_data,
uint64_t fire_tsc, int mode, uint64_t period_in_cycle)
{
if (timer != NULL) {
timer->func = func;
@@ -48,19 +74,62 @@ static inline void initialize_timer(struct hv_timer *timer,
}
}
/**
* @brief Check a timer whether expired.
*
* @param[in] timer Pointer to timer.
*
* @retval true if the timer is expired, false otherwise.
*/
static inline bool timer_expired(const struct hv_timer *timer)
{
return ((timer->fire_tsc == 0UL) || (rdtsc() >= timer->fire_tsc));
}
/*
* Don't call add_timer/del_timer in the timer callback function.
/**
* @brief Add a timer.
*
* @param[in] timer Pointer to timer.
*
* @retval 0 on success
* @retval -EINVAL timer has an invalid value
*
* @remark Don't call it in the timer callback function or interrupt content.
*/
int add_timer(struct hv_timer *timer);
/**
* @brief Delete a timer.
*
* @param[in] timer Pointer to timer.
*
* @return None
*
* @remark Don't call it in the timer callback function or interrupt content.
*/
void del_timer(struct hv_timer *timer);
/**
* @brief Initialize timer.
*
* @return None
*/
void timer_init(void);
/**
* @brief Check tsc to make sure rdtsc is enabled.
*/
void check_tsc(void);
/**
* @brief Calibrate tsc.
*
* @return None
*/
void calibrate_tsc(void);
/**
* @}
*/
#endif /* TIMER_H */