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 State" (code 7)
 182 - - - - - - - - - - - - - - - - - -
 183
 184 Obtain information about the state of a specific CPU.
 185
 186 Arguments: 1. logical ID of CPU to be queried
 187
 188 Return code: CPU state (>=0) or negative error code
 189
 190     Possible CPU states are:
 191         0 - Running
 192         2 - Failed
 193
 194     Possible errors are:
 195         -EPERM  (-1)  - hypercall was issued over a non-root cell and the CPU
 196                         does not belong to the issuing cell
 197         -EINVAL (-22) - invalid CPU ID
 198
 199
 200 Communication Region
 201 --------------------
 202
 203 The communication region is a per-cell shared memory area that both the
 204 hypervisor and the particular cell can read from and write to. It is an
 205 optional communication mechanism. If the region shall be used by a cell, it
 206 has to be mapped into the cell's address space via its configuration (see [2]
 207 for details).
 208
 209
 210 Communication region layout
 211 - - - - - - - - - - - - - -
 212
 213         +------------------------------+ - begin of communication region
 214         |   Message to Cell (32 bit)   |   (lower address)
 215         +------------------------------+
 216         |  Message from Cell (32 bit)  |
 217         +------------------------------+
 218         |     Cell State (32 bit)      |
 219         +------------------------------+ - higher address
 220
 221 All fields use the native endianness of the system.
 222
 223
 224 Logical Channel "Message"
 225 - - - - - - - - - - - - -
 226
 227 The first logical channel of the region is formed by the fields "Message to
 228 Cell" and "Message from Cell". The hypervisor uses this channel to inform the
 229 cell about specific state changes in the system or request permission to
 230 perform state changes that the cell can affect.
 231
 232 Before the hypervisor sends a new message, it first sets the "Message from
 233 Cell" field to 0. It then writes a non-zero message code in the "Message to
 234 Cell" field. Finally the hypervisor reads from the "Message from Cell" field
 235 in order to receive the cell's answer.
 236
 237 For answering a message, the cell first has to clear the "Message to Cell"
 238 field. It then has to write a non-zero reply code into the "Message from Cell"
 239 field. If a cell receives an unknown message code, it has to send the reply
 240 "Message unknown" (code 1).
 241
 242 Write ordering of all updates has to be ensured by both the hypervisor
 243 and the cell according to the requirements of the hardware architecture.
 244
 245 The hypervisor may wait for a message reply by spinning until the "Message from
 246 Cell" field becomes non-zero. Therefore, a cell should check for pending
 247 messages periodically and answer them as soon as possible. The hypervisor will
 248 not use a CPU assigned to non-root cell to wait for message replies, but long
 249 message responds times may still affect the root cell negatively.
 250
 251 The following messages and corresponding replies are defined:
 252
 253  - Shutdown Request (code 1):
 254         The cell is supposed to be shut down, either to destroy only the cell
 255         itself or to disable the hypervisor completely.
 256
 257    Possible replies:
 258         2 - Request denied
 259         3 - Request approved
 260
 261    Note: The hypervisor does not request shutdown permission from a cell if
 262          that cell has the "Passive Communication Region" flag set in its
 263          configuration (see also [2]) or if the cell state is set to "Shut
 264          Down" or "Failed" (see below).
 265
 266  - Reconfiguration Completed (code 2):
 267         A cell configuration was changed. This message is for information only
 268         but has to be confirmed on reception nevertheless.
 269
 270    Possible replies:
 271         4 - Message received
 272
 273    Note: The hypervisor does not expect reception confirmation 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
 279 Logical Channel "Cell State"
 280 - - - - - - - - - - - - - - -
 281
 282 The cell state field provides the second logical channel. On cell startup, it
 283 is initialized by the hypervisor to the state "Running". From then on, the
 284 field becomes conceptually read-only for the hypervisor and will only be
 285 updated by the cell until a terminal state is reached. The following states are
 286 defined:
 287
 288  - Running (code 0)
 289  - Running, cell configurations locked (code 1)
 290  - Shut down (code 2), terminal state
 291  - Failed (code 3), terminal state
 292
 293 Once a cell declared to have reached a terminal state, the hypervisor is free
 294 to destroy or restart that cell. On restart, it will also reset the state field
 295 to "Running".
 296
 297
 298 References
 299 ----------
 300
 301 [1] Documentation/cell-environments.txt
 302 [2] Documentation/configuration-format.txt