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  * Loop-generating macro for iterating over all registered cells.
  67  * @param cell          Iteration variable holding the reference to the current
  68  *                      cell (struct cell *).
  69  *
  70  * @see for_each_non_root_cell
  71  */
  72 #define for_each_cell(cell)                                     \
  73         for ((cell) = &root_cell; (cell); (cell) = (cell)->next)
  74
  75 /**
  76  * Loop-generating macro for iterating over all registered cells, expect the
  77  * root cell.
  78  * @param cell          Iteration variable holding the reference to the current
  79  *                      cell (struct cell *).
  80  *
  81  * @see for_each_cell
  82  */
  83 #define for_each_non_root_cell(cell) \
  84         for ((cell) = root_cell.next; (cell); (cell) = (cell)->next)
  85
  86 /**
  87  * Check if the CPU is assigned to the specified cell.
  88  * @param cell          Cell the CPU may belong to.
  89  * @param cpu_id        ID of the CPU.
  90  *
  91  * @return True if the CPU is assigned to the cell.
  92  */
  93 static inline bool cell_owns_cpu(struct cell *cell, unsigned int cpu_id)
  94 {
  95         return (cpu_id <= cell->cpu_set->max_cpu_id &&
  96                 test_bit(cpu_id, cell->cpu_set->bitmap));
  97 }
  98
  99 bool cpu_id_valid(unsigned long cpu_id);
 100
 101 int check_mem_regions(const struct jailhouse_cell_desc *config);
 102 int cell_init(struct cell *cell);
 103
 104 void config_commit(struct cell *cell_added_removed);
 105
 106 long hypercall(unsigned long code, unsigned long arg1, unsigned long arg2);
 107
 108 void __attribute__((noreturn)) panic_stop(void);
 109 void panic_park(void);
 110
 111 /**
 112  * Suspend a remote CPU.
 113  * @param cpu_id        ID of the target CPU.
 114  *
 115  * Suspension means that the target CPU is no longer executing cell code or
 116  * arbitrary hypervisor code. It may actively wait in the hypervisor context,
 117  * so the suspension time should be kept short.
 118  *
 119  * The function waits for the target CPU to enter suspended state.
 120  *
 121  * This service can be used to synchronize with other CPUs before performing
 122  * management tasks.
 123  *
 124  * @note This function must not be invoked for the caller's CPU.
 125  *
 126  * @see arch_resume_cpu
 127  * @see arch_reset_cpu
 128  * @see arch_park_cpu
 129  */
 130 void arch_suspend_cpu(unsigned int cpu_id);
 131
 132 /**
 133  * Resume a suspended remote CPU.
 134  * @param cpu_id        ID of the target CPU.
 135  *
 136  * @note This function must not be invoked for the caller's CPU.
 137  *
 138  * @see arch_suspend_cpu
 139  */
 140 void arch_resume_cpu(unsigned int cpu_id);
 141
 142 /**
 143  * Reset a suspended remote CPU and resumes its execution.
 144  * @param cpu_id        ID of the target CPU.
 145  *
 146  * Sets the target CPU into the architecture-specific reset set and resumes its
 147  * execution.
 148  *
 149  * @note This function must not be invoked for the caller's CPU or if the
 150  * target CPU is not in suspend state.
 151  *
 152  * @see arch_suspend_cpu
 153  */
 154 void arch_reset_cpu(unsigned int cpu_id);
 155
 156 /**
 157  * Park a suspended remote CPU.
 158  * @param cpu_id        ID of the target CPU.
 159  *
 160  * Parking means that the target CPU does not execute cell code but can handle
 161  * asynchronous events again. Parking is not implemented as busy-waiting and
 162  * may set the CPU into an appropriate power-saving mode. The CPU can therefore
 163  * be left in this state for an undefined time.
 164  *
 165  * Parking may destroy the cell-visible CPU state and cannot be used to resume
 166  * cell execution in the previous state without additional measures.
 167  *
 168  * @note This function must not be invoked for the caller's CPU or if the
 169  * target CPU is not in suspend state.
 170  *
 171  * @see arch_suspend_cpu
 172  */
 173 void arch_park_cpu(unsigned int cpu_id);
 174
 175 /**
 176  * Releases hypervisor control over the target CPU.
 177  * @param cpu_id        ID of the target CPU.
 178  *
 179  * @note This function must not be invoked for the caller's CPU.
 180  *
 181  * @note The target CPU need not be suspended before calling the function.
 182  *
 183  * @note The caller has to ensure that the target CPU has enough time to reach
 184  * the shutdown position before destroying the code path it has to take to get
 185  * there. This can be ensured by bringing the CPU online again under Linux
 186  * before cleaning up the hypervisor.
 187  */
 188 void arch_shutdown_cpu(unsigned int cpu_id);
 189
 190 /**
 191  * Performs the architecture-specific steps for mapping a memory region into a
 192  * cell's address space.
 193  * @param cell          Cell for which the mapping shall be done.
 194  * @param mem           Memory region to map.
 195  *
 196  * @return 0 on success, negative error code otherwise.
 197  *
 198  * @see arch_unmap_memory_region
 199  */
 200 int arch_map_memory_region(struct cell *cell,
 201                            const struct jailhouse_memory *mem);
 202
 203 /**
 204  * Performs the architecture-specific steps for unmapping a memory region from
 205  * a cell's address space.
 206  * @param cell          Cell for which the unmapping shall be done.
 207  * @param mem           Memory region to unmap.
 208  *
 209  * @return 0 on success, negative error code otherwise.
 210  *
 211  * @see arch_map_memory_region
 212  */
 213 int arch_unmap_memory_region(struct cell *cell,
 214                              const struct jailhouse_memory *mem);
 215
 216 /**
 217  * Performs the architecture-specific steps for invalidating memory caches
 218  * after memory regions have been unmapped from a cell.
 219  * This function should be called after memory got unmapped or memory access
 220  * got restricted, and the cell should keep running.
 221  * @param cell          Cell for which the caches should get flushed
 222  *
 223  * @see per_cpu::flush_vcpu_caches
 224  */
 225 void arch_flush_cell_vcpu_caches(struct cell *cell);
 226
 227 /**
 228  * Performs the architecture-specific steps for creating a new cell.
 229  * @param cell          Data structure of the new cell.
 230  *
 231  * @return 0 on success, negative error code otherwise.
 232  *
 233  * @see arch_cell_destroy
 234  */
 235 int arch_cell_create(struct cell *cell);
 236
 237 /**
 238  * Performs the architecture-specific steps for destroying a cell.
 239  * @param cell          Cell to be destroyed.
 240  *
 241  * @see arch_cell_create
 242  */
 243 void arch_cell_destroy(struct cell *cell);
 244
 245 /**
 246  * Performs the architecture-specific steps for applying configuration changes.
 247  * @param cell_added_removed    Cell that was added or removed to/from the
 248  *                              system or NULL.
 249  *
 250  * @see config_commit
 251  * @see pci_config_commit
 252  */
 253 void arch_config_commit(struct cell *cell_added_removed);
 254
 255 /**
 256  * Shutdown architecture-specific subsystems while disabling the hypervisor.
 257  */
 258 void arch_shutdown(void);
 259
 260 /**
 261  * Performs the architecture-specifc steps to stop the current CPU on panic.
 262  *
 263  * @note This function never returns.
 264  *
 265  * @see panic_stop
 266  */
 267 void __attribute__((noreturn)) arch_panic_stop(void);
 268
 269 /**
 270  * Performs the architecture-specific steps to park the current CPU on panic.
 271  *
 272  * @note This function only marks the CPU as parked and then returns to the
 273  * caller.
 274  *
 275  * @see panic_park
 276  */
 277 void arch_panic_park(void);
 278
 279 /** @} */