1# zx_vcpu_create
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7vcpu_create - create a VCPU
8
9## SYNOPSIS
10
11<!-- Updated by update-docs-from-abigen, do not edit. -->
12
13```
14#include <zircon/syscalls.h>
15
16zx_status_t zx_vcpu_create(zx_handle_t guest,
17                           uint32_t options,
18                           zx_vaddr_t entry,
19                           zx_handle_t* out);
20```
21
22## DESCRIPTION
23
24`zx_vcpu_create()` creates a VCPU within a guest, which allows for execution
25within the virtual machine. One or more VCPUs may be created per guest, where
26the number of VCPUs does not need to match the number of physical CPUs on the
27machine.
28
29*entry* is the instruction pointer used to indicate where in guest physical
30memory execution of the VCPU should start.
31
32*out* is bound to the thread that created it, and all syscalls that operate on
33it must be called from the same thread, with the exception of
34[`zx_vcpu_interrupt()`].
35
36N.B. VCPU is an abbreviation of virtual CPU.
37
38The following rights will be set on the handle *out* by default:
39
40**ZX_RIGHT_DUPLICATE** &mdash; *out* may be duplicated.
41
42**ZX_RIGHT_TRANSFER** &mdash; *out* may be transferred over a channel.
43
44**ZX_RIGHT_EXECUTE** &mdash; *out* may have its execution resumed (or begun)
45
46**ZX_RIGHT_SIGNAL** &mdash; *out* may be interrupted
47
48**ZX_RIGHT_READ** &mdash; *out* may have its state read
49
50**ZX_RIGHT_WRITE** &mdash; may have its state written
51
52## RIGHTS
53
54<!-- Updated by update-docs-from-abigen, do not edit. -->
55
56*guest* must be of type **ZX_OBJ_TYPE_GUEST** and have **ZX_RIGHT_MANAGE_PROCESS**.
57
58## RETURN VALUE
59
60`zx_vcpu_create()` returns **ZX_OK** on success. On failure, an error value is
61returned.
62
63## ERRORS
64
65**ZX_ERR_ACCESS_DENIED** *guest* does not have the **ZX_RIGHT_MANAGE_PROCESS**
66right.
67
68**ZX_ERR_BAD_HANDLE** *guest* is an invalid handle.
69
70**ZX_ERR_INVALID_ARGS** *args* contains an invalid argument, or *out* is an
71invalid pointer, or *options* is nonzero.
72
73**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
74There is no good way for userspace to handle this (unlikely) error.
75In a future build this error will no longer occur.
76
77**ZX_ERR_WRONG_TYPE** *guest* is not a handle to a guest.
78
79## SEE ALSO
80
81 - [`zx_guest_create()`]
82 - [`zx_guest_set_trap()`]
83 - [`zx_vcpu_interrupt()`]
84 - [`zx_vcpu_read_state()`]
85 - [`zx_vcpu_resume()`]
86 - [`zx_vcpu_write_state()`]
87
88<!-- References updated by update-docs-from-abigen, do not edit. -->
89
90[`zx_guest_create()`]: guest_create.md
91[`zx_guest_set_trap()`]: guest_set_trap.md
92[`zx_vcpu_interrupt()`]: vcpu_interrupt.md
93[`zx_vcpu_read_state()`]: vcpu_read_state.md
94[`zx_vcpu_resume()`]: vcpu_resume.md
95[`zx_vcpu_write_state()`]: vcpu_write_state.md
96