github/acrn-hypervisor
1
0
Fork 0
mirror of https://github.com/projectacrn/acrn-hypervisor.git synced 2025-09-07 03:40:27 +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

1
doc/acrn.doxyfile
View File

@@ -808,6 +808,7 @@ INPUT = custom-doxygen/mainpage.md \
../hypervisor/include/public/acrn_common.h \
../hypervisor/include/public/acrn_hv_defs.h \
../hypervisor/include/arch/x86/guest/vcpu.h \
../hypervisor/include/arch/x86/timer.h \
../hypervisor/arch/x86/trusty.c \
../devicemodel/include/virtio.h \
../hypervisor/include/arch/x86/ioapic.h \

48
doc/developer-guides/hld/hv-timer.rst
View File

@@ -24,37 +24,27 @@ tsc-deadline timer mode by writing the local APIC LVT register.
Data Structures and APIs
************************
.. note:: API link to hv_timer and per_cpu_timer structs in include/arch/x86/timer.h
And to the function APIs there too.
Interfaces Design
=================
Before adding a timer, we must initialize the timer with
*initialize_timer*. The processor generates a timer interrupt when the
value of timer-stamp counter is greater than or equal to the *fire_tsc*
field. If you want to add a periodic timer, you should also pass the
period (unit in tsc cycles), otherwise, period_in_cycle will be ignored.
When the timer interrupt is generated, it will call the callback
function *func* with parameter *priv_data*.
.. doxygenfunction:: initialize_timer
:project: Project ACRN
The *initialize_timer* function only initialize the timer data
structure; it will not program the ``IA32_TSC_DEADLINE_MSR`` to generate
the timer interrupt. If you want to generate a timer interrupt, you must
call *add_timer* to add the timer to the *per_cpu_timer* timer_list. In
return, we will chose the nearest expired timer on the timer_list and
program ``IA32_TSC_DEADLINE_MSR`` by writing its value to fire_ts. Then
when the fire_tsc expires, it raises the interrupt whose callback raises
a softirq. We will handle the software interrupt before the VM reenters
the guest. (Currently, the hypervisor only uses the timer for the
console).
.. doxygenfunction:: timer_expired
:project: Project ACRN
The timer softirq handler will check each expired timer on its
timer_list. Before calling the expired timer callback handler, it will
remove the timer from its logical cpu timer_list. After calling the
timer callback handler, it will re-add the timer to the timer_list if
it's a periodic timer. If you want to modify a timer before it expires,
you should call del_timer to remove the timer from the timer_list, then
call add_timer again after updating the timer fields.
.. doxygenfunction:: add_timer
:project: Project ACRN
.. note::
.. doxygenfunction:: del_timer
:project: Project ACRN
.. doxygenfunction:: timer_init
:project: Project ACRN
.. doxygenfunction:: check_tsc
:project: Project ACRN
.. doxygenfunction:: calibrate_tsc
:project: Project ACRN
Only call initialize_timer only once for each timer.
Don't call add_timer or del_timer in the timer callback function.