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 (IA-32/32e) ABI
  24 - - - - - - - - - - - - -
  25
  26 Instruction:    vmcall
  27 Hypercall code: EAX
  28 1. argument:    RDI (IA-32e) / EDI (IA-32)
  29 2. argument:    RSI (IA-32e) / ESI (IA-32)
  30 Return code:    EAX
  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         +------------------------------+
 232         |      Reserved (32 bit)       |
 233         +------------------------------+
 234         :     Platform Information     :
 235         +------------------------------+ - higher address
 236
 237 All fields use the native endianness of the system. The format is of the
 238 Platform Information part is architecture-specific. Its content is filled by
 239 the hypervisor during cell creation and shall be considered read-only until
 240 cell destruction.
 241
 242
 243 Logical Channel "Message"
 244 - - - - - - - - - - - - -
 245
 246 The first logical channel of the region is formed by the fields "Message to
 247 Cell" and "Message from Cell". The hypervisor uses this channel to inform the
 248 cell about specific state changes in the system or request permission to
 249 perform state changes that the cell can affect.
 250
 251 Before the hypervisor sends a new message, it first sets the "Message from
 252 Cell" field to 0. It then writes a non-zero message code in the "Message to
 253 Cell" field. Finally the hypervisor reads from the "Message from Cell" field
 254 in order to receive the cell's answer.
 255
 256 For answering a message, the cell first has to clear the "Message to Cell"
 257 field. It then has to write a non-zero reply code into the "Message from Cell"
 258 field. If a cell receives an unknown message code, it has to send the reply
 259 "Message unknown" (code 1).
 260
 261 Write ordering of all updates has to be ensured by both the hypervisor
 262 and the cell according to the requirements of the hardware architecture.
 263
 264 The hypervisor may wait for a message reply by spinning until the "Message from
 265 Cell" field becomes non-zero. Therefore, a cell should check for pending
 266 messages periodically and answer them as soon as possible. The hypervisor will
 267 not use a CPU assigned to non-root cell to wait for message replies, but long
 268 message responds times may still affect the root cell negatively.
 269
 270 The following messages and corresponding replies are defined:
 271
 272  - Shutdown Request (code 1):
 273         The cell is supposed to be shut down, either to destroy only the cell
 274         itself or to disable the hypervisor completely.
 275
 276    Possible replies:
 277         2 - Request denied
 278         3 - Request approved
 279
 280    Note: The hypervisor does not request shutdown permission from a cell if
 281          that cell has the "Passive Communication Region" flag set in its
 282          configuration (see also [2]) or if the cell state is set to "Shut
 283          Down" or "Failed" (see below).
 284
 285  - Reconfiguration Completed (code 2):
 286         A cell configuration was changed. This message is for information only
 287         but has to be confirmed on reception nevertheless.
 288
 289    Possible replies:
 290         4 - Message received
 291
 292    Note: The hypervisor does not expect reception confirmation from a cell if
 293          that cell has the "Passive Communication Region" flag set in its
 294          configuration (see also [2]) or if the cell state is set to "Shut
 295          Down" or "Failed" (see below).
 296
 297
 298 Logical Channel "Cell State"
 299 - - - - - - - - - - - - - - -
 300
 301 The cell state field provides the second logical channel. On cell startup, it
 302 is initialized by the hypervisor to the state "Running". From then on, the
 303 field becomes conceptually read-only for the hypervisor and will only be
 304 updated by the cell until a terminal state is reached. The following states are
 305 defined:
 306
 307  - Running (code 0)
 308  - Running, cell configurations locked (code 1)
 309  - Shut down (code 2), terminal state
 310  - Failed (code 3), terminal state
 311
 312 Once a cell declared to have reached a terminal state, the hypervisor is free
 313 to destroy or restart that cell. On restart, it will also reset the state field
 314 to "Running".
 315
 316
 317 Platform Information for x86
 318 - - - - - - - - - - - - - - -
 319
 320         +------------------------------+ - begin of communication region
 321         :   generic part, see above    :   (lower address)
 322         +------------------------------+
 323         |   PM Timer Address (16 bit)  |
 324         +------------------------------+
 325         |   Number of CPUs (16 bit)    |
 326         +------------------------------+ - higher address
 327
 328
 329 References
 330 ----------
 331
 332 [1] Documentation/cell-environments.txt
 333 [2] Documentation/configuration-format.txt