1122780Salc# zx_vmo_create_physical
2142840Speter
3122780Salc## NAME
4122780Salc
5122780Salcvmo_create_physical- create a VM object referring to a specific contiguous range
6122780Salcof physical memory
7122780Salc
8122780Salc## SYNOPSIS
9122780Salc
10122780Salc```
11122780Salc#include <zircon/syscalls.h>
12122780Salc
13122780Salczx_status_t zx_vmo_create_physical(zx_handle_t resource, zx_paddr_t paddr,
14122780Salc                                   size_t size, zx_handle_t* out);
15122780Salc```
16122780Salc
17122780Salc## DESCRIPTION
18122780Salc
19122780Salc**vmo_create_physical**() creates a new virtual memory object (VMO), which represents the
20122780Salc*size* bytes of physical memory beginning at physical address *paddr*.
21122780Salc
22122780SalcOne handle is returned on success, representing an object with the requested
23122780Salcsize.
24122780Salc
25122780SalcThe following rights will be set on the handle by default:
26122780Salc
27122780Salc**ZX_RIGHT_DUPLICATE** - The handle may be duplicated.
28122780Salc
29122780Salc**ZX_RIGHT_TRANSFER** - The handle may be transferred to another process.
30122780Salc
31122780Salc**ZX_RIGHT_READ** - May be read from or mapped with read permissions.
32128384Salc
33128384Salc**ZX_RIGHT_WRITE** - May be written to or mapped with write permissions.
34128384Salc
35128384Salc**ZX_RIGHT_EXECUTE** - May be mapped with execute permissions.
36128384Salc
37128384Salc**ZX_RIGHT_MAP** - May be mapped.
38269577Sglebius
39122780Salc**ZX_RIGHT_GET_PROPERTY** - May get its properties using
40122780Salc[object_get_property](object_get_property).
41122780Salc
42128384Salc**ZX_RIGHT_SET_PROPERTY** - May set its properties using
43122780Salc[object_set_property](object_set_property).
44122780Salc
45269577SglebiusThe **ZX_VMO_ZERO_CHILDREN** signal is active on a newly created VMO. It becomes
46122780Salcinactive whenever a clone of the VMO is created and becomes active again when
47122780Salcall clones have been destroyed and no mappings of those clones into address
48122780Salcspaces exist.
49128384Salc
50122780Salc## NOTES
51122780Salc
52The VMOs created by this syscall are not usable with **vmo_read**() and
53**vmo_write**().
54
55## RIGHTS
56
57TODO(ZX-2399)
58
59## RETURN VALUE
60
61**vmo_create_physical**() returns **ZX_OK** on success. In the event
62of failure, a negative error value is returned.
63
64## ERRORS
65
66**ZER_ERR_WRONG_TYPE** *resource* is not a handle to a Resource object.
67
68**ZER_ERR_ACCESS_DENIED** *resource* does not grant access to the requested
69range of memory.
70
71**ZX_ERR_INVALID_ARGS**  *out* is an invalid pointer or NULL, or *paddr* or
72*size* are not page-aligned.
73
74**ZX_ERR_NO_MEMORY**  Failure due to lack of memory.
75There is no good way for userspace to handle this (unlikely) error.
76In a future build this error will no longer occur.
77
78## SEE ALSO
79
80[vmar_map](vmar_map.md).
81