1 Hypervisor Interface for Cells
2 ==============================
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.
15 This interface is useful for cell code that should work not only inside a
16 Jailhouse cell. The ABI is architecture specific.
22 On x86, Jailhouse modifies the register values returned when executing the
23 cpuid instruction as follows:
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
32 Note: A cell should first check if bit 31 is set in ECX before querying the
33 signature function 0x40000000.
36 Function (EAX): 0x40000000 (signature)
37 Result in EAX: highest supported hypervisor function, currently 0x40000001
38 EBX: 0x6c69614a ("Jail")
39 ECX: 0x73756f68 ("hous")
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
48 Function (EAX): 0x40000001 (features)
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.
66 Intel x86 (IA-32/32e) ABI
67 - - - - - - - - - - - - -
71 1. argument: RDI (IA-32e) / EDI (IA-32)
72 2. argument: RSI (IA-32e) / ESI (IA-32)
76 Hypercall "Disable" (code 0)
77 - - - - - - - - - - - - - - -
79 Tries to destroy all non-Linux cells and then shuts down the hypervisor,
80 returning full control over the hardware back to Linux.
82 This hypercall can only be issued on CPUs belonging to the Linux cell.
86 Return code: 0 on success, negative error code otherwise
89 -EPERM (-1) - hypercall was issued over a non-Linux cell or an active
90 cell rejected the shutdown request
93 Hypercall "Cell Create" (code 1)
94 - - - - - - - - - - - - - - - - -
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.
100 This hypercall can only be issued on CPUs belonging to the Linux cell.
102 Arguments: 1. Guest-physical address of cell configuration (see [2] for
105 Return code: Positive cell ID or negative error code
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
119 Hypercall "Cell Start" (code 2)
120 - - - - - - - - - - - - - - - -
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.
129 This hypercall can only be issued on CPUs belonging to the Linux cell.
131 Arguments: 1. ID of target cell
133 Return code: 0 on success or negative error code
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
142 Hypercall "Cell Set Loadable" (code 3)
143 - - - - - - - - - - - - - - - - - - - -
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.
149 Arguments: 1. ID of target cell
151 Return code: 0 on success or negative error code
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
160 Hypercall "Cell Destroy" (code 4)
161 - - - - - - - - - - - - - - - - -
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.
167 This hypercall can only be issued on CPUs belonging to the root cell.
169 Arguments: 1. ID of cell to be destroyed
171 Return code: 0 on success, negative error code otherwise
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
180 -EINVAL (-22) - root cell specified, which cannot be destroyed
182 Note: The root cell uses ID 0. Passing this ID to "Cell Destroy" is illegal.
185 Hypercall "Hypervisor Get Info" (code 5)
186 - - - - - - - - - - - - - - - - - - - - -
188 Obtain information about specific hypervisor states.
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
197 Return code: Requested value (>=0) or negative error code
200 -EINVAL (-22) - invalid information type
203 Hypercall "Cell Get State" (code 6)
204 - - - - - - - - - - - - - - - - - -
206 Obtain information about the state of a specific cell.
208 Arguments: 1. ID of cell to be queried
210 This hypercall can only be issued on CPUs belonging to the root cell.
212 Return code: Cell state (>=0) or negative error code
214 Valid cell states are:
220 -EPERM (-1) - hypercall was issued over a non-root cell
221 -EINVAL (-22) - cell state is invalid
224 Hypercall "CPU Get Info" (code 7)
225 - - - - - - - - - - - - - - - - -
227 Obtain information about a specific CPU.
229 Arguments: 1. Logical ID of CPU to be queried
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
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
243 Return code: Requested value (>=0) or negative error code
245 Possible CPU states 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
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]
265 Communication region layout
266 - - - - - - - - - - - - - -
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
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
286 Logical Channel "Message"
287 - - - - - - - - - - - - -
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.
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.
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).
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.
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.
313 The following messages and corresponding replies are defined:
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.
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).
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.
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).
341 Logical Channel "Cell State"
342 - - - - - - - - - - - - - - -
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
351 - Running, cell configurations locked (code 1)
352 - Shut down (code 2), terminal state
353 - Failed (code 3), terminal state
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
360 Platform Information for x86
361 - - - - - - - - - - - - - - -
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
375 [1] Documentation/cell-environments.txt
376 [2] Documentation/configuration-format.txt