1# zx_vmo_create_physical
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7vmo_create_physical - create a VM object referring to a specific contiguous range of physical memory
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_vmo_create_physical(zx_handle_t resource,
17                                   zx_paddr_t paddr,
18                                   size_t size,
19                                   zx_handle_t* out);
20```
21
22## DESCRIPTION
23
24`zx_vmo_create_physical()` creates a new virtual memory object (VMO), which represents the
25*size* bytes of physical memory beginning at physical address *paddr*.
26
27One handle is returned on success, representing an object with the requested
28size.
29
30The following rights will be set on the handle by default:
31
32**ZX_RIGHT_DUPLICATE** - The handle may be duplicated.
33
34**ZX_RIGHT_TRANSFER** - The handle may be transferred to another process.
35
36**ZX_RIGHT_READ** - May be read from or mapped with read permissions.
37
38**ZX_RIGHT_WRITE** - May be written to or mapped with write permissions.
39
40**ZX_RIGHT_EXECUTE** - May be mapped with execute permissions.
41
42**ZX_RIGHT_MAP** - May be mapped.
43
44**ZX_RIGHT_GET_PROPERTY** - May get its properties using
45[object_get_property](object_get_property.md).
46
47**ZX_RIGHT_SET_PROPERTY** - May set its properties using
48[object_set_property](object_set_property.md).
49
50The **ZX_VMO_ZERO_CHILDREN** signal is active on a newly created VMO. It becomes
51inactive whenever a clone of the VMO is created and becomes active again when
52all clones have been destroyed and no mappings of those clones into address
53spaces exist.
54
55## NOTES
56
57The VMOs created by this syscall are not usable with [`zx_vmo_read()`] and
58[`zx_vmo_write()`].
59
60## RIGHTS
61
62<!-- Updated by update-docs-from-abigen, do not edit. -->
63
64*resource* must have resource kind **ZX_RSRC_KIND_MMIO**.
65
66## RETURN VALUE
67
68`zx_vmo_create_physical()` returns **ZX_OK** on success. In the event
69of failure, a negative error value is returned.
70
71## ERRORS
72
73**ZER_ERR_WRONG_TYPE** *resource* is not a handle to a Resource object.
74
75**ZER_ERR_ACCESS_DENIED** *resource* does not grant access to the requested
76range of memory.
77
78**ZX_ERR_INVALID_ARGS**  *out* is an invalid pointer or NULL, or *paddr* or
79*size* are not page-aligned.
80
81**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
82There is no good way for userspace to handle this (unlikely) error.
83In a future build this error will no longer occur.
84
85## SEE ALSO
86
87 - [`zx_vmar_map()`]
88
89<!-- References updated by update-docs-from-abigen, do not edit. -->
90
91[`zx_vmar_map()`]: vmar_map.md
92[`zx_vmo_read()`]: vmo_read.md
93[`zx_vmo_write()`]: vmo_write.md
94