|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [RFC PATCH 03/11] docs/doxygen: Add doxygen tags to xen.h
Add doxygen tags to comments for:
1) create List of hypercalls group
2) create Start-of-day shared data structure group
3) create Start-of-day memory layout group
4) create Dom0 console group
5) set inline documentation for macros and variables
Signed-off-by: Luca Fancellu <luca.fancellu@xxxxxxx>
---
xen/include/public/xen.h | 189 ++++++++++++++++++++++++++-------------
1 file changed, 129 insertions(+), 60 deletions(-)
diff --git a/xen/include/public/xen.h b/xen/include/public/xen.h
index 0255a5ce57..0b72888628 100644
--- a/xen/include/public/xen.h
+++ b/xen/include/public/xen.h
@@ -24,6 +24,11 @@
* Copyright (c) 2004, K A Fraser
*/
+/**
+ * @file
+ * @brief Guest OS interface to Xen.
+ */
+
#ifndef __XEN_PUBLIC_XEN_H__
#define __XEN_PUBLIC_XEN_H__
@@ -85,6 +90,11 @@ DEFINE_XEN_GUEST_HANDLE(xen_ulong_t);
* HYPERCALLS
*/
+/**
+ * @addtogroup list_of_hypercalls List of Hypercalls
+ * @{
+ */
+
/* `incontents 100 hcalls List of hypercalls
* ` enum hypercall_num { // __HYPERVISOR_* => HYPERVISOR_*()
*/
@@ -95,7 +105,7 @@ DEFINE_XEN_GUEST_HANDLE(xen_ulong_t);
#define __HYPERVISOR_stack_switch 3
#define __HYPERVISOR_set_callbacks 4
#define __HYPERVISOR_fpu_taskswitch 5
-#define __HYPERVISOR_sched_op_compat 6 /* compat since 0x00030101 */
+#define __HYPERVISOR_sched_op_compat 6 /**< compat since 0x00030101 */
#define __HYPERVISOR_platform_op 7
#define __HYPERVISOR_set_debugreg 8
#define __HYPERVISOR_get_debugreg 9
@@ -104,16 +114,16 @@ DEFINE_XEN_GUEST_HANDLE(xen_ulong_t);
#define __HYPERVISOR_multicall 13
#define __HYPERVISOR_update_va_mapping 14
#define __HYPERVISOR_set_timer_op 15
-#define __HYPERVISOR_event_channel_op_compat 16 /* compat since 0x00030202 */
+#define __HYPERVISOR_event_channel_op_compat 16 /**< compat since 0x00030202 */
#define __HYPERVISOR_xen_version 17
#define __HYPERVISOR_console_io 18
-#define __HYPERVISOR_physdev_op_compat 19 /* compat since 0x00030202 */
+#define __HYPERVISOR_physdev_op_compat 19 /**< compat since 0x00030202 */
#define __HYPERVISOR_grant_table_op 20
#define __HYPERVISOR_vm_assist 21
#define __HYPERVISOR_update_va_mapping_otherdomain 22
-#define __HYPERVISOR_iret 23 /* x86 only */
+#define __HYPERVISOR_iret 23 /**< x86 only */
#define __HYPERVISOR_vcpu_op 24
-#define __HYPERVISOR_set_segment_base 25 /* x86/64 only */
+#define __HYPERVISOR_set_segment_base 25 /**< x86/64 only */
#define __HYPERVISOR_mmuext_op 26
#define __HYPERVISOR_xsm_op 27
#define __HYPERVISOR_nmi_op 28
@@ -167,6 +177,10 @@ DEFINE_XEN_GUEST_HANDLE(xen_ulong_t);
#define __HYPERVISOR_dom0_op __HYPERVISOR_platform_op
#endif
+/**
+ * @}
+*/
+
/*
* VIRTUAL INTERRUPTS
*
@@ -744,60 +758,66 @@ typedef struct vcpu_info vcpu_info_t;
/*
* `incontents 200 startofday_shared Start-of-day shared data structure
- * Xen/kernel shared data -- pointer provided in start_info.
+ */
+
+/**
+ * @brief Xen/kernel shared data -- pointer provided in start_info.
*
* This structure is defined to be both smaller than a page, and the
* only data on the shared page, but may vary in actual size even within
* compatible Xen versions; guests should not rely on the size
* of this structure remaining constant.
+ *
+ * A domain can create "event channels" on which it can send and receive
+ * asynchronous event notifications. There are three classes of event that
+ * are delivered by this mechanism:
+ * 1. Bi-directional inter- and intra-domain connections. Domains must
+ * arrange out-of-band to set up a connection (usually by allocating
+ * an unbound 'listener' port and avertising that via a storage service
+ * such as xenstore).
+ * 2. Physical interrupts. A domain with suitable hardware-access
+ * privileges can bind an event-channel port to a physical interrupt
+ * source.
+ * 3. Virtual interrupts ('events'). A domain can bind an event-channel
+ * port to a virtual interrupt source, such as the virtual-timer
+ * device or the emergency console.
+ *
+ * Event channels are addressed by a "port index". Each channel is
+ * associated with two bits of information:
+ * 1. PENDING -- notifies the domain that there is a pending notification
+ * to be processed. This bit is cleared by the guest.
+ * 2. MASK -- if this bit is clear then a 0->1 transition of PENDING
+ * will cause an asynchronous upcall to be scheduled. This bit is only
+ * updated by the guest. It is read-only within Xen. If a channel
+ * becomes pending while the channel is masked then the 'edge' is lost
+ * (i.e., when the channel is unmasked, the guest must manually handle
+ * pending notifications as no upcall will be scheduled by Xen).
+ *
+ * To expedite scanning of pending notifications, any 0->1 pending
+ * transition on an unmasked channel causes a corresponding bit in a
+ * per-vcpu selector word to be set. Each bit in the selector covers a
+ * 'C long' in the PENDING bitfield array.
+ *
+ * Wallclock time: updated by control software or RTC emulation.
+ * Guests should base their gettimeofday() syscall on this
+ * wallclock-base value.
+ *
+ * The values of wc_sec and wc_nsec are offsets from the Unix epoch
+ * adjusted by the domain's 'time offset' (in seconds) as set either
+ * by XEN_DOMCTL_settimeoffset, or adjusted via a guest write to the
+ * emulated RTC.
+ *
+ * @addtogroup start_of_day_shared_data_structure Start-of-day shared data
structure
+ * @{
*/
+
struct shared_info {
struct vcpu_info vcpu_info[XEN_LEGACY_MAX_VCPUS];
- /*
- * A domain can create "event channels" on which it can send and receive
- * asynchronous event notifications. There are three classes of event that
- * are delivered by this mechanism:
- * 1. Bi-directional inter- and intra-domain connections. Domains must
- * arrange out-of-band to set up a connection (usually by allocating
- * an unbound 'listener' port and avertising that via a storage service
- * such as xenstore).
- * 2. Physical interrupts. A domain with suitable hardware-access
- * privileges can bind an event-channel port to a physical interrupt
- * source.
- * 3. Virtual interrupts ('events'). A domain can bind an event-channel
- * port to a virtual interrupt source, such as the virtual-timer
- * device or the emergency console.
- *
- * Event channels are addressed by a "port index". Each channel is
- * associated with two bits of information:
- * 1. PENDING -- notifies the domain that there is a pending notification
- * to be processed. This bit is cleared by the guest.
- * 2. MASK -- if this bit is clear then a 0->1 transition of PENDING
- * will cause an asynchronous upcall to be scheduled. This bit is only
- * updated by the guest. It is read-only within Xen. If a channel
- * becomes pending while the channel is masked then the 'edge' is lost
- * (i.e., when the channel is unmasked, the guest must manually handle
- * pending notifications as no upcall will be scheduled by Xen).
- *
- * To expedite scanning of pending notifications, any 0->1 pending
- * transition on an unmasked channel causes a corresponding bit in a
- * per-vcpu selector word to be set. Each bit in the selector covers a
- * 'C long' in the PENDING bitfield array.
- */
xen_ulong_t evtchn_pending[sizeof(xen_ulong_t) * 8];
xen_ulong_t evtchn_mask[sizeof(xen_ulong_t) * 8];
- /*
- * Wallclock time: updated by control software or RTC emulation.
- * Guests should base their gettimeofday() syscall on this
- * wallclock-base value.
- * The values of wc_sec and wc_nsec are offsets from the Unix epoch
- * adjusted by the domain's 'time offset' (in seconds) as set either
- * by XEN_DOMCTL_settimeoffset, or adjusted via a guest write to the
- * emulated RTC.
- */
- uint32_t wc_version; /* Version counter: see vcpu_time_info_t. */
+ uint32_t wc_version; /**< Version counter: see vcpu_time_info_t. */
uint32_t wc_sec;
uint32_t wc_nsec;
#if !defined(__i386__)
@@ -814,8 +834,16 @@ struct shared_info {
typedef struct shared_info shared_info_t;
#endif
+/**
+ * @}
+*/
+
/*
* `incontents 200 startofday Start-of-day memory layout
+ */
+
+/**
+ * @brief Start-of-day memory layout
*
* 1. The domain is started within contiguous virtual-memory region.
* 2. The contiguous region ends on an aligned 4MB boundary.
@@ -850,7 +878,11 @@ typedef struct shared_info shared_info_t;
* to the page table base is by two pages back. The initial domain if it is
* 32-bit and runs under a 64-bit hypervisor should _NOT_ use two of the
* pages preceding pt_base and mark them as reserved/unused.
+ *
+ * @addtogroup start_of_day_memory_layout Start-of-day memory layout
+ * @{
*/
+
#ifdef XEN_HAVE_PV_GUEST_ENTRY
struct start_info {
/* THE FOLLOWING ARE FILLED IN BOTH ON INITIAL BOOT AND ON RESUME. */
@@ -860,12 +892,23 @@ struct start_info {
uint32_t flags; /* SIF_xxx flags. */
xen_pfn_t store_mfn; /* MACHINE page number of shared page. */
uint32_t store_evtchn; /* Event channel for store communication. */
+#ifdef DOXYGEN
+ /* Workaround: Doxygen cannot handle anonymous union/struct */
+ union console {
+ struct domU {
+#else
union {
struct {
+#endif
xen_pfn_t mfn; /* MACHINE page number of console page. */
uint32_t evtchn; /* Event channel for console page. */
} domU;
+#ifdef DOXYGEN
+ /* Workaround: Doxygen cannot handle anonymous union/struct */
+ struct dom0 {
+#else
struct {
+#endif
uint32_t info_off; /* Offset of console_info struct. */
uint32_t info_size; /* Size of console_info struct from start.*/
} dom0;
@@ -902,6 +945,10 @@ typedef struct start_info start_info_t;
/* P->M making the 3 level tree obsolete? */
#define SIF_PM_MASK (0xFF<<8) /* reserve 1 byte for xen-pm options */
+/**
+ * @}
+*/
+
/*
* A multiboot module is a package containing modules very similar to a
* multiboot module array. The only differences are:
@@ -929,52 +976,70 @@ struct xen_multiboot_mod_list
};
/*
* `incontents 200 startofday_dom0_console Dom0_console
+ */
+
+/**
+ * @brief Dom0_console
*
* The console structure in start_info.console.dom0
*
* This structure includes a variety of information required to
* have a working VGA/VESA console.
+ *
+ * @addtogroup dom0_console Dom0 console
+ * @{
*/
+
typedef struct dom0_vga_console_info {
- uint8_t video_type; /* DOM0_VGA_CONSOLE_??? */
+ uint8_t video_type; /**< DOM0_VGA_CONSOLE_??? */
#define XEN_VGATYPE_TEXT_MODE_3 0x03
#define XEN_VGATYPE_VESA_LFB 0x23
#define XEN_VGATYPE_EFI_LFB 0x70
-
+#ifdef DOXYGEN
+ /* Workaround: Doxygen cannot handle anonymous union/struct */
+ union u {
+ struct text_mode_3 {
+#else
union {
struct {
- /* Font height, in pixels. */
+#endif
+ /** Font height, in pixels. */
uint16_t font_height;
- /* Cursor location (column, row). */
+ /** Cursor location (column, row). */
uint16_t cursor_x, cursor_y;
- /* Number of rows and columns (dimensions in characters). */
+ /** Number of rows and columns (dimensions in characters). */
uint16_t rows, columns;
} text_mode_3;
+#ifdef DOXYGEN
+ /* Workaround: Doxygen cannot handle anonymous union/struct */
+ struct vesa_lfb {
+#else
struct {
- /* Width and height, in pixels. */
+#endif
+ /** Width and height, in pixels. */
uint16_t width, height;
- /* Bytes per scan line. */
+ /** Bytes per scan line. */
uint16_t bytes_per_line;
- /* Bits per pixel. */
+ /** Bits per pixel. */
uint16_t bits_per_pixel;
- /* LFB physical address, and size (in units of 64kB). */
+ /** LFB physical address, and size (in units of 64kB). */
uint32_t lfb_base;
uint32_t lfb_size;
- /* RGB mask offsets and sizes, as defined by VBE 1.2+ */
+ /** RGB mask offsets and sizes, as defined by VBE 1.2+ */
uint8_t red_pos, red_size;
uint8_t green_pos, green_size;
uint8_t blue_pos, blue_size;
uint8_t rsvd_pos, rsvd_size;
#if __XEN_INTERFACE_VERSION__ >= 0x00030206
- /* VESA capabilities (offset 0xa, VESA command 0x4f00). */
+ /** VESA capabilities (offset 0xa, VESA command 0x4f00). */
uint32_t gbl_caps;
- /* Mode attributes (offset 0x0, VESA command 0x4f01). */
+ /** Mode attributes (offset 0x0, VESA command 0x4f01). */
uint16_t mode_attrs;
uint16_t pad;
#endif
#if __XEN_INTERFACE_VERSION__ >= 0x00040d00
- /* high 32 bits of lfb_base */
+ /** high 32 bits of lfb_base */
uint32_t ext_lfb_base;
#endif
} vesa_lfb;
@@ -983,6 +1048,10 @@ typedef struct dom0_vga_console_info {
#define xen_vga_console_info dom0_vga_console_info
#define xen_vga_console_info_t dom0_vga_console_info_t
+/**
+ * @}
+*/
+
typedef uint8_t xen_domain_handle_t[16];
__DEFINE_XEN_GUEST_HANDLE(uint8, uint8_t);
--
2.17.1
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |