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