1# zx_resource_create
2
3## NAME
4
5<!-- Updated by update-docs-from-abigen, do not edit. -->
6
7resource_create - create a resource object
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_resource_create(zx_handle_t parent_rsrc,
17                               uint32_t options,
18                               uint64_t base,
19                               size_t size,
20                               const char* name,
21                               size_t name_size,
22                               zx_handle_t* resource_out);
23```
24
25## DESCRIPTION
26
27`zx_resource_create()` creates an resource object for use with other DDK
28syscalls. Resources are typically handed out to bus drivers and rarely need to
29be interacted with directly by drivers using driver protocols. Resource objects
30grant access to an address space range starting at *base* up to but not
31including *base* + *size*. Two special values for *kind* exist:
32**ZX_RSRC_KIND_ROOT** and **ZX_RSRC_KIND_HYPERVISOR**. These resources have no
33range associated with them and are used as a privilege check.
34
35*parent_rsrc* must be a handle to a resource of *kind* **ZX_RSRC_KIND_ROOT**.
36
37*options* must specify which kind of resource to create and may contain optional
38flags. Valid kinds of resources are **ZX_RSRC_KIND_MMIO**, **ZX_RSRC_KIND_IRQ**,
39**ZX_RSRC_KIND_IOPORT** (x86 only), **ZX_RSRC_KIND_ROOT**,
40**ZX_RSRC_KIND_HYPERVISOR**, **ZX_RSRC_KIND_VMEX**, and **ZX_RSRC_KIND_SMC**
41(ARM only).
42**ZX_RSRC_KIND_ROOT**, **ZX_RSRC_KIND_HYPERVISOR**, and **ZX_RSRC_KIND_VMEX**
43must be paired with zero values for *base* and *size*, as they do not use
44an address space range.
45At this time the only optional flag is **ZX_RSRC_FLAG_EXCLUSIVE**. If
46**ZX_RSRC_FLAG_EXCLUSIVE** is provided then the syscall will attempt to
47exclusively reserve the requested address space region, preventing other
48resources creation from overlapping with it as long as it exists.
49
50*name* and *name_size* are optional and truncated to **ZX_MAX_NAME_LENGTH** - 1.
51This name is provided for debugging / tool use only and is not used by the
52kernel.
53
54On success, a valid resource handle is returned in *resource_out*.
55
56## RETURN VALUE
57
58`zx_resource_create()` returns **ZX_OK** on success. In the event of failure, a
59negative error value is returned.
60
61The returned handle will have **ZX_RIGHT_TRANSFER** (allowing it to be sent to
62another process via channel write), **ZX_RIGHT_DUPLICATE** (allowing the handle
63to be duplicated), **ZX_RIGHT_INSPECT** (to allow inspection of the object with
64[object_get_info](object_get_info.md) and **ZX_RIGHT_WRITE** which is checked by
65`zx_resource_create()` itself.
66
67## RIGHTS
68
69<!-- Updated by update-docs-from-abigen, do not edit. -->
70
71*parent_rsrc* must be of type **ZX_OBJ_TYPE_RESOURCE** and have **ZX_RIGHT_WRITE**.
72
73## ERRORS
74
75**ZX_ERR_BAD_HANDLE** the *src_obj* handle is invalid.
76
77**ZX_ERR_WRONG_TYPE** the *src_obj* handle is not a resource handle.
78
79**ZX_ERR_ACCESS_DENIED** The *src_obj* handle is not a resource of *kind*
80**ZX_RSRC_KIND_ROOT**.
81
82**ZX_ERR_INVALID_ARGS** *options* contains an invalid kind or flag combination,
83*name* is an invalid pointer, or the kind specified is one of
84**ZX_RSRC_KIND_ROOT** or **ZX_RSRC_KIND_HYPERVISOR** but *base* and *size* are
85not 0.
86
87**ZX_ERR_NO_MEMORY** Failure due to lack of memory. There is no good way for
88userspace to handle this (unlikely) error. In a future build this error will no
89longer occur.
90
91## SEE ALSO
92
93 - [`zx_handle_close()`]
94 - [`zx_interrupt_create()`]
95 - [`zx_ioports_request()`]
96 - [`zx_vmo_create_physical()`]
97
98<!-- References updated by update-docs-from-abigen, do not edit. -->
99
100[`zx_handle_close()`]: handle_close.md
101[`zx_interrupt_create()`]: interrupt_create.md
102[`zx_ioports_request()`]: ioports_request.md
103[`zx_vmo_create_physical()`]: vmo_create_physical.md
104