core: Document setup subsystem

This adds doxygen-style documentation for public parts of the setup
subsystem, including the hypervisor header.

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

diff --git a/hypervisor/include/jailhouse/entry.h b/hypervisor/include/jailhouse/entry.h
index 0ed809591eeb0331ce80c850769a4f15a039f125..ca6e492e2abd42574bbfa7484d1f14493b1bfc01 100644 (file)
--- a/hypervisor/include/jailhouse/entry.h
+++ b/hypervisor/include/jailhouse/entry.h
@@ -33,18 +33,101 @@
 struct per_cpu;
 struct cell;
 
+/**
+ * @defgroup Setup Setup Subsystem
+ *
+ * This subsystem coordinates the handover from Linux to the hypervisor.
+ *
+ * @{
+ */
+
 extern struct jailhouse_header hypervisor_header;
 
+/**
+ * Architecture-specific entry point for enabling the hypervisor.
+ * @param cpu_id       Logical ID of the calling CPU.
+ *
+ * @return 0 on success, negative error code otherwise.
+ *
+ * The functions always returns the same value on each CPU it is invoked on.
+ *
+ * @note This function has to be called for every configures CPU or the setup
+ * will fail.
+ *
+ * @see entry
+ * @see jailhouse_entry
+ */
 int arch_entry(unsigned int cpu_id);
 
+/**
+ * Entry point for enabling the hypervisor.
+ * @param cpu_id       Logical ID of the calling CPU.
+ * @param cpu_data     Data structure of the calling CPU.
+ *
+ * @return 0 on success, negative error code otherwise.
+ *
+ * The functions is called by arch_entry(). It always returns the same value on
+ * each CPU it is invoked on.
+ *
+ * @note This function has to be called for every configures CPU or the setup
+ * will fail.
+ *
+ * @see arch_entry
+ */
 int entry(unsigned int cpu_id, struct per_cpu *cpu_data);
 
+/**
+ * Map the root cell's memory regions.
+ *
+ * @return 0 on success, negative error code otherwise.
+ *
+ * Invoked by the architecture-specific setup code.
+ */
 int map_root_memory_regions(void);
 
+/**
+ * Perform architecture-specific early setup steps.
+ *
+ * @return 0 on success, negative error code otherwise.
+ *
+ * @note This is called over the master CPU that performs CPU-unrelated setup
+ * steps.
+ */
 int arch_init_early(void);
+
+/**
+ * Perform architecture-specific CPU setup steps.
+ * @param cpu_data     Data structure of the calling CPU.
+ *
+ * @return 0 on success, negative error code otherwise.
+ */
 int arch_cpu_init(struct per_cpu *cpu_data);
+
+/**
+ * Perform architecture-specific late setup steps.
+ *
+ * @return 0 on success, negative error code otherwise.
+ *
+ * @note This is called over the master CPU that performs CPU-unrelated setup
+ * steps.
+ */
 int arch_init_late(void);
+
+/**
+ * Perform architecture-specific activation of the hypervisor mode.
+ * @param cpu_data     Data structure of the calling CPU.
+ *
+ * @note This function does not return to the caller but rather resumes Linux
+ * in guest mode at the point arch_entry() would return to.
+ */
 void __attribute__((noreturn)) arch_cpu_activate_vmm(struct per_cpu *cpu_data);
+
+/**
+ * Perform architecture-specific restoration of the CPU state on setup
+ * failures or after disabling the hypervisor.
+ * @param cpu_data     Data structure of the calling CPU.
+ */
 void arch_cpu_restore(struct per_cpu *cpu_data);
 
+/** @} */
 #endif /* !_JAILHOUSE_ENTRY_H */

diff --git a/hypervisor/include/jailhouse/header.h b/hypervisor/include/jailhouse/header.h
index 24c90a971e9a4a77679b78941ebc85cc6e06eb4f..f5931fefe58146e9cae710d864695bd8eaa5dbfd 100644 (file)
--- a/hypervisor/include/jailhouse/header.h
+++ b/hypervisor/include/jailhouse/header.h
@@ -12,14 +12,37 @@
 
 #define JAILHOUSE_SIGNATURE    "JAILHOUS"
 
+/**
+ * @ingroup Setup
+ * @{
+ */
+
+/**
+ * Hypervisor entry point.
+ *
+ * @see arch_entry
+ */
+typedef int (*jailhouse_entry)(unsigned int);
+
+/** Hypervisor description. */
 struct jailhouse_header {
-       /* filled at build time */
+       /** Signature "JAILHOUS".
+        * @note Filled at build time. */
        char signature[8];
+       /** Size of hypervisor core.
+        * @note Filled at build time. */
        unsigned long core_size;
+       /** Size of per-CPU data structure.
+        * @note Filled at build time. */
        unsigned long percpu_size;
+       /** Entry point (arch_entry()).
+        * @note Filled at build time. */
        int (*entry)(unsigned int);
 
-       /* filled by loader */
+       /** Configured maximum logical CPU ID + 1.
+        * @note Filled by Linux loader driver before entry. */
        unsigned int max_cpus;
+       /** Number of online CPUs that will call the entry function.
+        * @note Filled by Linux loader driver before entry. */
        unsigned int online_cpus;
 };

diff --git a/hypervisor/setup.c b/hypervisor/setup.c
index 54afa972c1c8a46ca03b5a8526b3623c40d11958..8b8c8eeb9f1c3700f9e9d96ee698ff9150b9dfb8 100644 (file)
--- a/hypervisor/setup.c
+++ b/hypervisor/setup.c
@@ -201,6 +201,7 @@ int entry(unsigned int cpu_id, struct per_cpu *cpu_data)
        arch_cpu_activate_vmm(cpu_data);
 }
 
+/** Hypervisor description header. */
 struct jailhouse_header __attribute__((section(".header")))
 hypervisor_header = {
        .signature = JAILHOUSE_SIGNATURE,