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 a624ddf6cd68ce4e215d6783ec6999e5ea0eedb7..7398fb9f9f8dd3c70548afe6244688777dae8b78 100644 (file)
--- 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 b128447cc45c229a35f08b3e97fe1cc8a6229561..ed72b2840658ad990ad00066e218cf989b266575 100644 (file)
--- 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 0087d661861e85db57427aca61efd9aecc559449..92c9fee1f9bf89ea80ca505736bd5d5aeb20e8c1 100644 (file)
--- 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>