Documentation/hypervisor-interfaces.txt

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