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