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 Argument:       RDI
  29 Return code:    RAX
  30
  31
  32 Hypercall "Disable" (code 0)
  33 - - - - - - - - - - - - - - -
  34
  35 Tries to destroy all non-Linux cells and then shuts down the hypervisor,
  36 returning full control over the hardware back to Linux.
  37
  38 This hypercall can only be issued on CPUs belonging to the Linux cell.
  39
  40 Argument: none
  41
  42 Return code: 0 on success, negative error code otherwise
  43
  44     Possible errors are:
  45         -EPERM  (-1) - hypercall was issued over a non-Linux cell or an active
  46                        cell rejected the shutdown request
  47
  48
  49 Hypercall "Cell Create" (code 1)
  50 - - - - - - - - - - - - - - - - -
  51
  52 Creates a new cell according to the provided configuration. The cell's memory
  53 content will not be initialized, and the cell will be put in suspended state,
  54 i.e. no code is executed on its CPUs after this hypercall completed.
  55
  56 This hypercall can only be issued on CPUs belonging to the Linux cell.
  57
  58 Argument: guest-physical address of cell configuration (see [2] for details)
  59
  60 Return code: positive cell ID or negative error code
  61
  62     Possible errors are:
  63         -EPERM  (-1)  - hypercall was issued over a non-root cell or an active
  64                         cell denied system reconfiguration
  65         -E2BIG  (-7)  - configuration data too large to process
  66         -ENOMEM (-12) - insufficient hypervisor-internal memory
  67         -EBUSY  (-16) - a resource of the new cell is already in use by another
  68                         non-root cell, or the caller's CPU is supposed to be
  69                         given to the new cell
  70         -EEXIST (-17) - a cell with the given name already exists
  71         -EINVAL (-22) - incorrect or inconsistent configuration data
  72
  73
  74 Hypercall "Cell Start" (code 2)
  75 - - - - - - - - - - - - - - - -
  76
  77 Sets all cell CPUs to an architecture-specific start state and resumes
  78 execution of the cell if it was previously suspended. At least one CPU will
  79 then execute the bootstrap code that must have been loaded into the cell's
  80 memory at the reset address before invoking this hypercall. See [1] for details
  81 on the start state of cell CPUs.
  82
  83 This hypercall can only be issued on CPUs belonging to the Linux cell.
  84
  85 Argument: ID of target cell
  86
  87 Return code: 0 on success or negative error code
  88
  89     Possible errors are:
  90         -EPERM  (-1)  - hypercall was issued over a non-root cell or the target
  91                         cell rejected the reset request
  92         -ENOENT (-2)  - cell with provided ID does not exist
  93         -EINVAL (-22) - root cell specified, which cannot be started
  94
  95
  96 Hypercall "Cell Destroy" (code 4)
  97 - - - - - - - - - - - - - - - - -
  98
  99 Destroys the cell of the provided name, returning its resources to the root
 100 cell if they are part of the system configuration, i.e. belonged to the root
 101 cell directly after hypervisor start.
 102
 103 This hypercall can only be issued on CPUs belonging to the root cell.
 104
 105 Argument: ID of cell to be destroyed
 106
 107 Return code: 0 on success, negative error code otherwise
 108
 109     Possible errors are:
 110         -EPERM  (-1)  - hypercall was issued over a non-root cell, the target
 111                         cell rejected the destruction request or another active
 112                         cell denied system reconfiguration
 113         -ENOENT (-2)  - cell with provided ID does not exist
 114         -ENOMEM (-12) - insufficient hypervisor-internal memory for
 115                         reconfiguration
 116         -EINVAL (-22) - root cell specified, which cannot be destroyed
 117
 118 Note: The root cell uses ID 0. Passing this ID to "Cell Destroy" is illegal.
 119
 120
 121 Hypercall "Hypervisor Get Info" (code 5)
 122 - - - - - - - - - - - - - - - - - - - - -
 123
 124 Obtain information about specific hypervisor states.
 125
 126 Argument: Information type:
 127         0 - number of pages in hypervisor memory pool
 128         1 - used pages of hypervisor memory pool
 129         2 - number of pages in hypervisor remapping pool
 130         3 - used pages of hypervisor remapping pool
 131         4 - number of registered cells
 132
 133 Return code: requested value (>=0) or negative error code
 134
 135     Possible errors are:
 136         -EINVAL (-22) - invalid information type
 137
 138
 139 Hypercall "Cell Get State" (code 6)
 140 - - - - - - - - - - - - - - - - - -
 141
 142 Obtain information about the state of a specific cell.
 143
 144 Argument: ID of cell to be queried
 145
 146 This hypercall can only be issued on CPUs belonging to the root cell.
 147
 148 Return code: cell state (>=0) or negative error code
 149
 150     Valid cell states are:
 151         0 - Running
 152         1 - Shut down
 153         2 - Failed
 154
 155     Possible errors are:
 156         -EPERM  (-1)  - hypercall was issued over a non-root cell
 157         -EINVAL (-22) - cell state is invalid
 158
 159
 160 Hypercall "CPU Get State" (code 7)
 161 - - - - - - - - - - - - - - - - - -
 162
 163 Obtain information about the state of a specific CPU.
 164
 165 Argument: logical ID of CPU to be queried
 166
 167 Return code: CPU state (>=0) or negative error code
 168
 169     Possible CPU states are:
 170         0 - Running
 171         2 - Failed
 172
 173     Possible errors are:
 174         -EPERM  (-1)  - hypercall was issued over a non-root cell and the CPU
 175                         does not belong to the issuing cell
 176         -EINVAL (-22) - invalid CPU ID
 177
 178
 179 Communication Region
 180 --------------------
 181
 182 The communication region is a per-cell shared memory area that both the
 183 hypervisor and the particular cell can read from and write to. It is an
 184 optional communication mechanism. If the region shall be used by a cell, it
 185 has to be mapped into the cell's address space via its configuration (see [2]
 186 for details).
 187
 188
 189 Communication region layout
 190 - - - - - - - - - - - - - -
 191
 192         +------------------------------+ - begin of communication region
 193         |   Message to Cell (32 bit)   |   (lower address)
 194         +------------------------------+
 195         |  Message from Cell (32 bit)  |
 196         +------------------------------+
 197         |     Cell State (32 bit)      |
 198         +------------------------------+ - higher address
 199
 200 All fields use the native endianness of the system.
 201
 202
 203 Logical Channel "Message"
 204 - - - - - - - - - - - - -
 205
 206 The first logical channel of the region is formed by the fields "Message to
 207 Cell" and "Message from Cell". The hypervisor uses this channel to inform the
 208 cell about specific state changes in the system or request permission to
 209 perform state changes that the cell can affect.
 210
 211 Before the hypervisor sends a new message, it first sets the "Message from
 212 Cell" field to 0. It then writes a non-zero message code in the "Message to
 213 Cell" field. Finally the hypervisor reads from the "Message from Cell" field
 214 in order to receive the cell's answer.
 215
 216 For answering a message, the cell first has to clear the "Message to Cell"
 217 field. It then has to write a non-zero reply code into the "Message from Cell"
 218 field.
 219
 220 Write ordering of all updates has to be ensured by both the hypervisor
 221 and the cell according to the requirements of the hardware architecture.
 222
 223 The hypervisor may wait for a message reply by spinning until the "Message from
 224 Cell" field becomes non-zero. Therefore, a cell should check for pending
 225 messages periodically and answer them as soon as possible. The hypervisor will
 226 not use a CPU assigned to non-root cell to wait for message replies, but long
 227 message responds times may still affect the root cell negatively.
 228
 229 The following messages and corresponding replies are defined:
 230
 231  - Shutdown Requested (code 1):
 232         The cell is supposed to be shut down, either to destroy only the cell
 233         itself or to disable the hypervisor completely.
 234
 235    Possible replies:
 236         1 - Shutdown denied
 237         2 - Shutdown OK
 238
 239 Note: The hypervisor does not request shutdown permission from a cell if that
 240       cell has the "Passive Communication Region" flag set in its configuration
 241       (see also [2]) or if the cell state is set to "Shut Down" or "Failed"
 242       (see below).
 243
 244
 245 Logical Channel "Cell State"
 246 - - - - - - - - - - - - - - -
 247
 248 The cell state field provides the second logical channel. On cell startup, it
 249 is initialized by the hypervisor to the state "Running". From then on, the
 250 field becomes conceptually read-only for the hypervisor and will only be
 251 updated by the cell until a terminal state is reached. The following states are
 252 defined:
 253
 254  - Running (code 0)
 255  - Shut down (code 1), terminal state
 256  - Failed (code 2), terminal state
 257
 258 Once a cell declared to have reached a terminal state, the hypervisor is free
 259 to destroy or restart that cell. On restart, it will also reset the state field
 260 to "Running".
 261
 262
 263 References
 264 ----------
 265
 266 [1] Documentation/cell-environments.txt
 267 [2] Documentation/configuration-format.txt