Documentation/hypervisor-interfaces.txt

   1 Hypervisor Interface for Cells
   2 ==============================
   3
   4 The Jailhouse hypervisor provides two kinds of interfaces to interact with its
   5 cells during runtime. One is a set of hypercalls which cells can be invoked
   6 synchronously by executing architecture specific instructions that switch to
   7 hypervisor mode. The other interface consists of variables located in a
   8 per-cell memory region that is shared between hypervisor and that particular
   9 cell.
  10
  11
  12 Hypercalls
  13 ----------
  14
  15 A hypercall is typically issued via a designated instruction that causes a
  16 context switch from guest to hypervisor mode. Before causing the mode switch, a
  17 cell has to prepare potential arguments of the call in predefined registers or
  18 a known memory location. A return code of the completed hypercall is passed via
  19 a similar channel. Details of the hypercall ABI are architecture specific and
  20 will be defined in the following.
  21
  22
  23 Intel x86-64 (IA-32e) ABI
  24 - - - - - - - - - - - - -
  25
  26 Instruction:    vmcall
  27 Hypercall code: RAX
  28 1. argument:    RDI
  29 2. argument:    RSI
  30 Return code:    RAX
  31
  32
  33 Hypercall "Disable" (code 0)
  34 - - - - - - - - - - - - - - -
  35
  36 Tries to destroy all non-Linux cells and then shuts down the hypervisor,
  37 returning full control over the hardware back to Linux.
  38
  39 This hypercall can only be issued on CPUs belonging to the Linux cell.
  40
  41 Arguments: None
  42
  43 Return code: 0 on success, negative error code otherwise
  44
  45     Possible errors are:
  46         -EPERM  (-1) - hypercall was issued over a non-Linux cell or an active
  47                        cell rejected the shutdown request
  48
  49
  50 Hypercall "Cell Create" (code 1)
  51 - - - - - - - - - - - - - - - - -
  52
  53 Creates a new cell according to the provided configuration. The cell's memory
  54 content will not be initialized, and the cell will be put in suspended state,
  55 i.e. no code is executed on its CPUs after this hypercall completed.
  56
  57 This hypercall can only be issued on CPUs belonging to the Linux cell.
  58
  59 Arguments: 1. Guest-physical address of cell configuration (see [2] for
  60               details)
  61
  62 Return code: Positive cell ID or negative error code
  63
  64     Possible errors are:
  65         -EPERM  (-1)  - hypercall was issued over a non-root cell or an active
  66                         cell locked the cell configurations
  67         -E2BIG  (-7)  - configuration data too large to process
  68         -ENOMEM (-12) - insufficient hypervisor-internal memory
  69         -EBUSY  (-16) - a resource of the new cell is already in use by another
  70                         non-root cell, or the caller's CPU is supposed to be
  71                         given to the new cell
  72         -EEXIST (-17) - a cell with the given name already exists
  73         -EINVAL (-22) - incorrect or inconsistent configuration data
  74
  75
  76 Hypercall "Cell Start" (code 2)
  77 - - - - - - - - - - - - - - - -
  78
  79 Sets all cell CPUs to an architecture-specific start state and resumes
  80 execution of the cell if it was previously suspended. At least one CPU will
  81 then execute the bootstrap code that must have been loaded into the cell's
  82 memory at the reset address before invoking this hypercall. See [1] for details
  83 on the start state of cell CPUs. In addition, access from the root cell to
  84 memory regions of this cell that are marked "loadable" [2] is revoked.
  85
  86 This hypercall can only be issued on CPUs belonging to the Linux cell.
  87
  88 Arguments: 1. ID of target cell
  89
  90 Return code: 0 on success or negative error code
  91
  92     Possible errors are:
  93         -EPERM  (-1)  - hypercall was issued over a non-root cell or the target
  94                         cell rejected the reset request
  95         -ENOENT (-2)  - cell with provided ID does not exist
  96         -EINVAL (-22) - root cell specified, which cannot be started
  97
  98
  99 Hypercall "Cell Set Loadable" (code 3)
 100 - - - - - - - - - - - - - - - - - - - -
 101
 102 Shuts down a running cell and enables (re-)loading of their memory regions that
 103 are marked "loadable" in the cell's configuration. This is achieved by mapping
 104 the marked regions into the root cell.
 105
 106 Arguments: 1. ID of target cell
 107
 108 Return code: 0 on success or negative error code
 109
 110     Possible errors are:
 111         -EPERM  (-1)  - hypercall was issued over a non-root cell or the target
 112                         cell rejected the shutdown request
 113         -ENOENT (-2)  - cell with provided ID does not exist
 114         -EINVAL (-22) - root cell specified, which cannot be set loadable
 115
 116
 117 Hypercall "Cell Destroy" (code 4)
 118 - - - - - - - - - - - - - - - - -
 119
 120 Destroys the cell of the provided name, returning its resources to the root
 121 cell if they are part of the system configuration, i.e. belonged to the root
 122 cell directly after hypervisor start.
 123
 124 This hypercall can only be issued on CPUs belonging to the root cell.
 125
 126 Arguments: 1. ID of cell to be destroyed
 127
 128 Return code: 0 on success, negative error code otherwise
 129
 130     Possible errors are:
 131         -EPERM  (-1)  - hypercall was issued over a non-root cell, the target
 132                         cell rejected the destruction request or another active
 133                         cell locked the cell configurations
 134         -ENOENT (-2)  - cell with provided ID does not exist
 135         -ENOMEM (-12) - insufficient hypervisor-internal memory for
 136                         reconfiguration
 137         -EINVAL (-22) - root cell specified, which cannot be destroyed
 138
 139 Note: The root cell uses ID 0. Passing this ID to "Cell Destroy" is illegal.
 140
 141
 142 Hypercall "Hypervisor Get Info" (code 5)
 143 - - - - - - - - - - - - - - - - - - - - -
 144
 145 Obtain information about specific hypervisor states.
 146
 147 Arguments: 1. Information type:
 148                0 - number of pages in hypervisor memory pool
 149                1 - used pages of hypervisor memory pool
 150                2 - number of pages in hypervisor remapping pool
 151                3 - used pages of hypervisor remapping pool
 152                4 - number of registered cells
 153
 154 Return code: Requested value (>=0) or negative error code
 155
 156     Possible errors are:
 157         -EINVAL (-22) - invalid information type
 158
 159
 160 Hypercall "Cell Get State" (code 6)
 161 - - - - - - - - - - - - - - - - - -
 162
 163 Obtain information about the state of a specific cell.
 164
 165 Arguments: 1. ID of cell to be queried
 166
 167 This hypercall can only be issued on CPUs belonging to the root cell.
 168
 169 Return code: Cell state (>=0) or negative error code
 170
 171     Valid cell states are:
 172         0 - Running
 173         1 - Shut down
 174         2 - Failed
 175
 176     Possible errors are:
 177         -EPERM  (-1)  - hypercall was issued over a non-root cell
 178         -EINVAL (-22) - cell state is invalid
 179
 180
 181 Hypercall "CPU Get Info" (code 7)
 182 - - - - - - - - - - - - - - - - -
 183
 184 Obtain information about a specific CPU.
 185
 186 Arguments: 1. Logical ID of CPU to be queried
 187            2. Information type:
 188                   0 - CPU state
 189                1000 - Total number of VM exits
 190                1001 - VM exits due to MMIO access
 191                1002 - VM exits due to PIO access
 192                1003 - VM exits due to IPI submissions
 193                1004 - VM exits due to management events
 194                1005 - VM exits due to hypercalls
 195
 196 Statistic counters are reset when a CPU is assigned to a different cell. The
 197 total number of VM exits may be different from the sum of all specific VM exit
 198 counters.
 199
 200 Return code: Requested value (>=0) or negative error code
 201
 202     Possible CPU states are:
 203         0 - Running
 204         2 - Failed
 205
 206     Possible errors are:
 207         -EPERM  (-1)  - hypercall was issued over a non-root cell and the CPU
 208                         does not belong to the issuing cell
 209         -EINVAL (-22) - invalid CPU ID
 210
 211
 212 Communication Region
 213 --------------------
 214
 215 The communication region is a per-cell shared memory area that both the
 216 hypervisor and the particular cell can read from and write to. It is an
 217 optional communication mechanism. If the region shall be used by a cell, it
 218 has to be mapped into the cell's address space via its configuration (see [2]
 219 for details).
 220
 221
 222 Communication region layout
 223 - - - - - - - - - - - - - -
 224
 225         +------------------------------+ - begin of communication region
 226         |   Message to Cell (32 bit)   |   (lower address)
 227         +------------------------------+
 228         |  Message from Cell (32 bit)  |
 229         +------------------------------+
 230         |     Cell State (32 bit)      |
 231         +------------------------------+ - higher address
 232
 233 All fields use the native endianness of the system.
 234
 235
 236 Logical Channel "Message"
 237 - - - - - - - - - - - - -
 238
 239 The first logical channel of the region is formed by the fields "Message to
 240 Cell" and "Message from Cell". The hypervisor uses this channel to inform the
 241 cell about specific state changes in the system or request permission to
 242 perform state changes that the cell can affect.
 243
 244 Before the hypervisor sends a new message, it first sets the "Message from
 245 Cell" field to 0. It then writes a non-zero message code in the "Message to
 246 Cell" field. Finally the hypervisor reads from the "Message from Cell" field
 247 in order to receive the cell's answer.
 248
 249 For answering a message, the cell first has to clear the "Message to Cell"
 250 field. It then has to write a non-zero reply code into the "Message from Cell"
 251 field. If a cell receives an unknown message code, it has to send the reply
 252 "Message unknown" (code 1).
 253
 254 Write ordering of all updates has to be ensured by both the hypervisor
 255 and the cell according to the requirements of the hardware architecture.
 256
 257 The hypervisor may wait for a message reply by spinning until the "Message from
 258 Cell" field becomes non-zero. Therefore, a cell should check for pending
 259 messages periodically and answer them as soon as possible. The hypervisor will
 260 not use a CPU assigned to non-root cell to wait for message replies, but long
 261 message responds times may still affect the root cell negatively.
 262
 263 The following messages and corresponding replies are defined:
 264
 265  - Shutdown Request (code 1):
 266         The cell is supposed to be shut down, either to destroy only the cell
 267         itself or to disable the hypervisor completely.
 268
 269    Possible replies:
 270         2 - Request denied
 271         3 - Request approved
 272
 273    Note: The hypervisor does not request shutdown permission from a cell if
 274          that cell has the "Passive Communication Region" flag set in its
 275          configuration (see also [2]) or if the cell state is set to "Shut
 276          Down" or "Failed" (see below).
 277
 278  - Reconfiguration Completed (code 2):
 279         A cell configuration was changed. This message is for information only
 280         but has to be confirmed on reception nevertheless.
 281
 282    Possible replies:
 283         4 - Message received
 284
 285    Note: The hypervisor does not expect reception confirmation from a cell if
 286          that cell has the "Passive Communication Region" flag set in its
 287          configuration (see also [2]) or if the cell state is set to "Shut
 288          Down" or "Failed" (see below).
 289
 290
 291 Logical Channel "Cell State"
 292 - - - - - - - - - - - - - - -
 293
 294 The cell state field provides the second logical channel. On cell startup, it
 295 is initialized by the hypervisor to the state "Running". From then on, the
 296 field becomes conceptually read-only for the hypervisor and will only be
 297 updated by the cell until a terminal state is reached. The following states are
 298 defined:
 299
 300  - Running (code 0)
 301  - Running, cell configurations locked (code 1)
 302  - Shut down (code 2), terminal state
 303  - Failed (code 3), terminal state
 304
 305 Once a cell declared to have reached a terminal state, the hypervisor is free
 306 to destroy or restart that cell. On restart, it will also reset the state field
 307 to "Running".
 308
 309
 310 References
 311 ----------
 312
 313 [1] Documentation/cell-environments.txt
 314 [2] Documentation/configuration-format.txt