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