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>
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
SEARCH_INCLUDES = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
SEARCH_INCLUDES = YES
+INCLUDE_PATH = hypervisor/include
INCLUDE_FILE_PATTERNS =
PREDEFINED = \
INCLUDE_FILE_PATTERNS =
PREDEFINED = \
__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);"
__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 = COMM_REGION_GENERIC_HEADER
SKIP_FUNCTION_MACROS = YES
TAGFILES =
GENERATE_TAGFILE =
SKIP_FUNCTION_MACROS = YES
TAGFILES =
GENERATE_TAGFILE =
#define __MAKE_UL(x) x ## UL
/**
#define __MAKE_UL(x) x ## UL
/**
+ * @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.
*/
extern bool jailhouse_use_vmcall;
*/
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;
struct jailhouse_comm_region {
COMM_REGION_GENERIC_HEADER;
+ /** I/O port address of the PM timer (x86-specific). */
+ /** Number of CPUs available to the cell (x86-specific). */
+/**
+ * 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;
static inline __u32 jailhouse_call(__u32 num)
{
__u32 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;
static inline __u32 jailhouse_call_arg1(__u32 num, unsigned long arg1)
{
__u32 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)
{
static inline __u32 jailhouse_call_arg2(__u32 num, unsigned long arg1,
unsigned long arg2)
{
+/**
+ * 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)
static inline void
jailhouse_send_msg_to_cell(struct jailhouse_comm_region *comm_region,
__u32 msg)
comm_region->msg_to_cell = msg;
}
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)
static inline void
jailhouse_send_reply_from_cell(struct jailhouse_comm_region *comm_region,
__u32 reply)
#define JAILHOUSE_CELL_SHUT_DOWN 2 /* terminal state */
#define JAILHOUSE_CELL_FAILED 3 /* terminal state */
#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>
#include <asm/jailhouse_hypercall.h>