From: Jan Kiszka <jan.kiszka@siemens.com>
Date: Wed, 29 Jul 2015 06:37:13 +0000 (+0200)
Subject: Documentation: Improve hypercall subsystem description
X-Git-Url: https://rtime.felk.cvut.cz/gitweb/jailhouse.git/commitdiff_plain/78282af0baf3501f9a399c06fadaf6ddc9e86bc3

Documentation: Improve hypercall subsystem description

Describe so far undocumented functions and also the communication region
structure.

For the latter, we have to expand the generic COMM_REGION_GENERIC_HEADER
macro during a doxygen run. This is achieved by including the generic
header from within the arch-specific one, but only for doxygen
processing. This special treatment is required because doxygen processes
each file directly, even if it should have been processed indirectly
already (here asm/jailhouse_hypercall.h via jailhouse/hypercall.h).

Signed-off-by: Jan Kiszka <jan.kiszka@siemens.com>
---

diff --git a/Documentation/Doxyfile b/Documentation/Doxyfile
index a624ddf..7398fb9 100644
--- a/Documentation/Doxyfile
+++ b/Documentation/Doxyfile
@@ -259,14 +259,15 @@ ENABLE_PREPROCESSING   = YES
 MACRO_EXPANSION        = YES
 EXPAND_ONLY_PREDEF     = YES
 SEARCH_INCLUDES        = YES
-INCLUDE_PATH           =
+INCLUDE_PATH           = hypervisor/include
 INCLUDE_FILE_PATTERNS  =
 PREDEFINED             = \
+	DOXYGEN_CPP \
 	__attribute__(x)= \
 	DEFINE_SPINLOCK(s)="spinlock_t s" \
 	DEFINE_MMIO_READ(s)="static inline u##s mmio_read##s(void *address);" \
 	DEFINE_MMIO_WRITE(s)="static inline void mmio_write##s(void *address, u##s value);"
-EXPAND_AS_DEFINED      =
+EXPAND_AS_DEFINED      = COMM_REGION_GENERIC_HEADER
 SKIP_FUNCTION_MACROS   = YES
 TAGFILES               =
 GENERATE_TAGFILE       =
diff --git a/hypervisor/arch/x86/include/asm/jailhouse_hypercall.h b/hypervisor/arch/x86/include/asm/jailhouse_hypercall.h
index b128447..ed72b28 100644
--- a/hypervisor/arch/x86/include/asm/jailhouse_hypercall.h
+++ b/hypervisor/arch/x86/include/asm/jailhouse_hypercall.h
@@ -78,10 +78,10 @@
 #define __MAKE_UL(x)	x ## UL
 
 /**
- * @defgroup Hypercalls
+ * @defgroup Hypercalls Hypercall Subsystem
  *
- * The hypercall subsystem provides an interface for cells
- * to call into Jailhouse.
+ * The hypercall subsystem provides an interface for cells to invoke Jailhouse
+ * services and interact via the communication region.
  *
  * @{
  */
@@ -97,13 +97,27 @@
  */
 extern bool jailhouse_use_vmcall;
 
+#ifdef DOXYGEN_CPP
+/* included to expand COMM_REGION_GENERIC_HEADER */
+#include <jailhouse/hypercall.h>
+#endif
+
+/** Communication region between hypervisor and a cell. */
 struct jailhouse_comm_region {
 	COMM_REGION_GENERIC_HEADER;
 
+	/** I/O port address of the PM timer (x86-specific). */
 	__u16 pm_timer_address;
+	/** Number of CPUs available to the cell (x86-specific). */
 	__u16 num_cpus;
 };
 
+/**
+ * Invoke a hypervisor without additional arguments.
+ * @param num		Hypercall number.
+ *
+ * @return Result of the hypercall, semantic depends on the invoked service.
+ */
 static inline __u32 jailhouse_call(__u32 num)
 {
 	__u32 result;
@@ -115,6 +129,13 @@ static inline __u32 jailhouse_call(__u32 num)
 	return result;
 }
 
+/**
+ * Invoke a hypervisor with one argument.
+ * @param num		Hypercall number.
+ * @param arg1		First argument.
+ *
+ * @return Result of the hypercall, semantic depends on the invoked service.
+ */
 static inline __u32 jailhouse_call_arg1(__u32 num, unsigned long arg1)
 {
 	__u32 result;
@@ -127,6 +148,14 @@ static inline __u32 jailhouse_call_arg1(__u32 num, unsigned long arg1)
 	return result;
 }
 
+/**
+ * Invoke a hypervisor with two arguments.
+ * @param num		Hypercall number.
+ * @param arg1		First argument.
+ * @param arg2		Second argument.
+ *
+ * @return Result of the hypercall, semantic depends on the invoked service.
+ */
 static inline __u32 jailhouse_call_arg2(__u32 num, unsigned long arg1,
 					unsigned long arg2)
 {
@@ -140,6 +169,11 @@ static inline __u32 jailhouse_call_arg2(__u32 num, unsigned long arg1,
 	return result;
 }
 
+/**
+ * Send a message from the hypervisor to a cell via the communication region.
+ * @param comm_region	Pointer to Communication Region.
+ * @param msg		Message to be sent.
+ */
 static inline void
 jailhouse_send_msg_to_cell(struct jailhouse_comm_region *comm_region,
 			   __u32 msg)
@@ -150,6 +184,12 @@ jailhouse_send_msg_to_cell(struct jailhouse_comm_region *comm_region,
 	comm_region->msg_to_cell = msg;
 }
 
+/**
+ * Send a reply message from a cell to the hypervisor via the communication
+ * region.
+ * @param comm_region	Pointer to Communication Region.
+ * @param reply		Reply to be sent.
+ */
 static inline void
 jailhouse_send_reply_from_cell(struct jailhouse_comm_region *comm_region,
 			       __u32 reply)
diff --git a/hypervisor/include/jailhouse/hypercall.h b/hypervisor/include/jailhouse/hypercall.h
index 0087d66..92c9fee 100644
--- a/hypervisor/include/jailhouse/hypercall.h
+++ b/hypervisor/include/jailhouse/hypercall.h
@@ -88,11 +88,16 @@
 #define JAILHOUSE_CELL_SHUT_DOWN		2 /* terminal state */
 #define JAILHOUSE_CELL_FAILED			3 /* terminal state */
 
-#define COMM_REGION_GENERIC_HEADER		\
-	volatile __u32 msg_to_cell;		\
-	volatile __u32 reply_from_cell;		\
-	volatile __u32 cell_state;		\
-	volatile __u32 padding
+#define COMM_REGION_GENERIC_HEADER					\
+	/** Message code sent from hypervisor to cell. */		\
+	volatile __u32 msg_to_cell;					\
+	/** Reply code sent from cell to hypervisor. */			\
+	volatile __u32 reply_from_cell;					\
+	/** Cell state, initialized by hypervisor, updated by cell. */	\
+	volatile __u32 cell_state;					\
+	/** \privatesection */						\
+	volatile __u32 padding;						\
+	/** \publicsection */
 
 #include <asm/jailhouse_hypercall.h>