Google is committed to advancing racial equity for Black communities. See how.

zx_resource_create

NAME

Create a resource object.

SYNOPSIS

#include <zircon/syscalls.h>

zx_status_t zx_resource_create(zx_handle_t parent_rsrc,
                               uint32_t options,
                               uint64_t base,
                               size_t size,
                               const char* name,
                               size_t name_size,
                               zx_handle_t* resource_out);

DESCRIPTION

zx_resource_create() creates a resource object for use with other DDK syscalls. Resources are typically handed out to bus drivers and rarely need to be interacted with directly by drivers using driver protocols. Resource objects grant access to an address space range starting at base up to but not including base + size. Two special values for kind exist: ZX_RSRC_KIND_ROOT and ZX_RSRC_KIND_HYPERVISOR. These resources have no range associated with them and are used as a privilege check.

parent_rsrc must be a handle to a resource of kind ZX_RSRC_KIND_ROOT, or a resource that matches the requested kind and contains [base, base+size*] in its range.

options must specify which kind of resource to create and may contain optional flags. Valid kinds of resources are ZX_RSRC_KIND_MMIO, ZX_RSRC_KIND_IRQ, ZX_RSRC_KIND_IOPORT (x86 only), ZX_RSRC_KIND_ROOT, ZX_RSRC_KIND_HYPERVISOR, ZX_RSRC_KIND_VMEX, and ZX_RSRC_KIND_SMC (ARM only). ZX_RSRC_KIND_ROOT, ZX_RSRC_KIND_HYPERVISOR, and ZX_RSRC_KIND_VMEX must be paired with zero values for base and size, as they do not use an address space range. At this time the only optional flag is ZX_RSRC_FLAG_EXCLUSIVE. If ZX_RSRC_FLAG_EXCLUSIVE is provided then the syscall will attempt to exclusively reserve the requested address space region, preventing other resources creation from overlapping with it as long as it exists.

name and name_size are optional and truncated to ZX_MAX_NAME_LENGTH - 1. This name is provided for debugging / tool use only and is not used by the kernel.

On success, a valid resource handle is returned in resource_out.

RETURN VALUE

zx_resource_create() returns ZX_OK on success. In the event of failure, a negative error value is returned.

The returned handle will have ZX_RIGHT_TRANSFER (allowing it to be sent to another process via zx_channel_write()), ZX_RIGHT_DUPLICATE (allowing the handle to be duplicated), ZX_RIGHT_INSPECT (to allow inspection of the object with zx_object_get_info() and ZX_RIGHT_WRITE which is checked by zx_resource_create() itself.

RIGHTS

parent_rsrc must be of type ZX_OBJ_TYPE_RESOURCE and have ZX_RIGHT_WRITE.

ERRORS

ZX_ERR_BAD_HANDLE the parent_rsrc handle is invalid.

ZX_ERR_WRONG_TYPE the parent_rsrc handle is not a resource handle.

ZX_ERR_ACCESS_DENIED The parent_rsrc handle is not a resource of either kind or ZX_RSRC_KIND_ROOT.

ZX_ERR_INVALID_ARGS options contains an invalid kind or flag combination, name is an invalid pointer, or the kind specified is one of ZX_RSRC_KIND_ROOT or ZX_RSRC_KIND_HYPERVISOR but base and size are not 0.

ZX_ERR_NO_MEMORY Failure due to lack of memory. There is no good way for userspace to handle this (unlikely) error. In a future build this error will no longer occur.

SEE ALSO