hypervisor/include/jailhouse/control.h

   1 /*
   2  * Jailhouse, a Linux-based partitioning hypervisor
   3  *
   4  * Copyright (c) Siemens AG, 2013
   5  *
   6  * Authors:
   7  *  Jan Kiszka <jan.kiszka@siemens.com>
   8  *
   9  * This work is licensed under the terms of the GNU GPL, version 2.  See
  10  * the COPYING file in the top-level directory.
  11  */
  12
  13 #include <asm/bitops.h>
  14 #include <asm/percpu.h>
  15 #include <jailhouse/cell-config.h>
  16
  17 #define SHUTDOWN_NONE                   0
  18 #define SHUTDOWN_STARTED                1
  19
  20 /**
  21  * @defgroup Control Control Subsystem
  22  *
  23  * The control subsystem provides services for managing cells and the
  24  * hypervisor during runtime. It implements the hypercall interface and
  25  * performs the required access control and parameter validation for it.
  26  *
  27  * @{
  28  */
  29
  30 extern struct jailhouse_system *system_config;
  31
  32 unsigned int next_cpu(unsigned int cpu, struct cpu_set *cpu_set,
  33                       int exception);
  34
  35 /**
  36  * Loop-generating macro for iterating over all CPUs in a set.
  37  * @param cpu           Iteration variable holding the current CPU ID
  38  *                      (unsigned int).
  39  * @param set           CPU set to iterate over (struct cpu_set).
  40  *
  41  * @see for_each_cpu_except
  42  */
  43 #define for_each_cpu(cpu, set)                                  \
  44         for ((cpu) = -1;                                        \
  45              (cpu) = next_cpu((cpu), (set), -1),                \
  46              (cpu) <= (set)->max_cpu_id;                        \
  47             )
  48
  49 /**
  50  * Loop-generating macro for iterating over all CPUs in a set, except the
  51  * specified one.
  52  * @param cpu           Iteration variable holding the current CPU ID
  53  *                      (unsigned int).
  54  * @param set           CPU set to iterate over (struct cpu_set).
  55  * @param exception     CPU to skip if it is part of the set.
  56  *
  57 * @see for_each_cpu
  58  */
  59 #define for_each_cpu_except(cpu, set, exception)                \
  60         for ((cpu) = -1;                                        \
  61              (cpu) = next_cpu((cpu), (set), (exception)),       \
  62              (cpu) <= (set)->max_cpu_id;                        \
  63             )
  64
  65 /**
  66  * Check if the CPU is assigned to the specified cell.
  67  * @param cell          Cell the CPU may belong to.
  68  * @param cpu_id        ID of the CPU.
  69  *
  70  * @return True if the CPU is assigned to the cell.
  71  */
  72 static inline bool cell_owns_cpu(struct cell *cell, unsigned int cpu_id)
  73 {
  74         return (cpu_id <= cell->cpu_set->max_cpu_id &&
  75                 test_bit(cpu_id, cell->cpu_set->bitmap));
  76 }
  77
  78 bool cpu_id_valid(unsigned long cpu_id);
  79
  80 int check_mem_regions(const struct jailhouse_cell_desc *config);
  81 int cell_init(struct cell *cell);
  82
  83 long hypercall(unsigned long code, unsigned long arg1, unsigned long arg2);
  84
  85 void __attribute__((noreturn)) panic_stop(void);
  86 void panic_park(void);
  87
  88 /**
  89  * Suspend a remote CPU.
  90  * @param cpu_id        ID of the target CPU.
  91  *
  92  * Suspension means that the target CPU is no longer executing cell code or
  93  * arbitrary hypervisor code. It may actively wait in the hypervisor context,
  94  * so the suspension time should be kept short.
  95  *
  96  * The function waits for the target CPU to enter suspended state.
  97  *
  98  * This service can be used to synchronize with other CPUs before performing
  99  * management tasks.
 100  *
 101  * @note This function must not be invoked for the caller's CPU.
 102  *
 103  * @see arch_resume_cpu
 104  * @see arch_reset_cpu
 105  * @see arch_park_cpu
 106  */
 107 void arch_suspend_cpu(unsigned int cpu_id);
 108
 109 /**
 110  * Resume a suspended remote CPU.
 111  * @param cpu_id        ID of the target CPU.
 112  *
 113  * @note This function must not be invoked for the caller's CPU.
 114  *
 115  * @see arch_suspend_cpu
 116  */
 117 void arch_resume_cpu(unsigned int cpu_id);
 118
 119 /**
 120  * Reset a suspended remote CPU and resumes its execution.
 121  * @param cpu_id        ID of the target CPU.
 122  *
 123  * Sets the target CPU into the architecture-specific reset set and resumes its
 124  * execution.
 125  *
 126  * @note This function must not be invoked for the caller's CPU or if the
 127  * target CPU is not in suspend state.
 128  *
 129  * @see arch_suspend_cpu
 130  */
 131 void arch_reset_cpu(unsigned int cpu_id);
 132
 133 /**
 134  * Park a suspended remote CPU.
 135  * @param cpu_id        ID of the target CPU.
 136  *
 137  * Parking means that the target CPU does not execute cell code but can handle
 138  * asynchronous events again. Parking is not implemented as busy-waiting and
 139  * may set the CPU into an appropriate power-saving mode. The CPU can therefore
 140  * be left in this state for an undefined time.
 141  *
 142  * Parking may destroy the cell-visible CPU state and cannot be used to resume
 143  * cell execution in the previous state without additional measures.
 144  *
 145  * @note This function must not be invoked for the caller's CPU or if the
 146  * target CPU is not in suspend state.
 147  *
 148  * @see arch_suspend_cpu
 149  */
 150 void arch_park_cpu(unsigned int cpu_id);
 151
 152 /**
 153  * Releases hypervisor control over the target CPU.
 154  * @param cpu_id        ID of the target CPU.
 155  *
 156  * @note This function must not be invoked for the caller's CPU.
 157  *
 158  * @note The target CPU need not be suspended before calling the function.
 159  *
 160  * @note The caller has to ensure that the target CPU has enough time to reach
 161  * the shutdown position before destroying the code path it has to take to get
 162  * there. This can be ensured by bringing the CPU online again under Linux
 163  * before cleaning up the hypervisor.
 164  */
 165 void arch_shutdown_cpu(unsigned int cpu_id);
 166
 167 /**
 168  * Performs the architecture-specific steps for mapping a memory region into a
 169  * cell's address space.
 170  * @param cell          Cell for which the mapping shall be done.
 171  * @param mem           Memory region to map.
 172  *
 173  * @return 0 on success, negative error code otherwise.
 174  *
 175  * @see arch_unmap_memory_region
 176  */
 177 int arch_map_memory_region(struct cell *cell,
 178                            const struct jailhouse_memory *mem);
 179
 180 /**
 181  * Performs the architecture-specific steps for unmapping a memory region from
 182  * a cell's address space.
 183  * @param cell          Cell for which the unmapping shall be done.
 184  * @param mem           Memory region to unmap.
 185  *
 186  * @return 0 on success, negative error code otherwise.
 187  *
 188  * @see arch_map_memory_region
 189  */
 190 int arch_unmap_memory_region(struct cell *cell,
 191                              const struct jailhouse_memory *mem);
 192
 193 /**
 194  * Performs the architecture-specific steps for creating a new cell.
 195  * @param cell          Data structure of the new cell.
 196  *
 197  * @return 0 on success, negative error code otherwise.
 198  *
 199  * @see arch_cell_destroy
 200  */
 201 int arch_cell_create(struct cell *cell);
 202
 203 /**
 204  * Performs the architecture-specific steps for destroying a cell.
 205  * @param cell          Cell to be destroyed.
 206  *
 207  * @see arch_cell_create
 208  */
 209 void arch_cell_destroy(struct cell *cell);
 210
 211 /**
 212  * Performs the architecture-specific steps for applying configuration changes.
 213  * @param cell_added_removed    Cell that was added or removed to/from the
 214  *                              system or NULL.
 215  *
 216  * @see pci_config_commit
 217  */
 218 void arch_config_commit(struct cell *cell_added_removed);
 219
 220 /**
 221  * Shutdown architecture-specific subsystems while disabling the hypervisor.
 222  */
 223 void arch_shutdown(void);
 224
 225 /**
 226  * Performs the architecture-specifc steps to stop the current CPU on panic.
 227  *
 228  * @note This function never returns.
 229  *
 230  * @see panic_stop
 231  */
 232 void __attribute__((noreturn)) arch_panic_stop(void);
 233
 234 /**
 235  * Performs the architecture-specific steps to park the current CPU on panic.
 236  *
 237  * @note This function only marks the CPU as parked and then returns to the
 238  * caller.
 239  *
 240  * @see panic_park
 241  */
 242 void arch_panic_park(void);
 243
 244 /** @} */