Summary
Create a resource object.
Declaration
#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_SYSTEM. The root resource has no range associated with it. The system resource is a ranged resource which is the parent of a number of resources, all of size 1, which are used as privileged checks for syscalls.
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_SMC (ARM only), and ZX_RSRC_KIND_SYSTEM. Valid bases for ZX_RSRC_KIND_SYSTEM are ZX_RSRC_SYSTEM_HYPERVISOR_BASE, ZX_RSRC_SYSTEM_VMEX_BASE, ZX_RSRC_SYSTEM_DEBUG_BASE, ZX_RSRC_SYSTEM_INFO_BASE, ZX_RSRC_SYSTEM_CPU_BASE, ZX_RSRC_SYSTEM_POWER_BASE, ZX_RSRC_SYSTEM_MEXEC_BASE, ZX_RSRC_SYSTEM_ENERGY_INFO_BASE, ZX_RSRC_SYSTEM_IOMMU_BASE, ZX_RSRC_SYSTEM_PROFILE_BASE, / ZX_RSRC_SYSTEM_MSI_BASE, ZX_RSRC_SYSTEM_DEBUGLOG_BASE and ZX_RSRC_SYSTEM_STALL_BASE. These all have size 1. ZX_RSRC_KIND_ROOT must be paired with zero values for base and size, as it does not use an address space range.
The ZX_RSRC_FLAG_EXCLUSIVE flag is optional. 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 ZX_RSRC_KIND_ROOT but base and size are not 0.
ZX_ERR_NOT_FOUND A suitable resource allocation was not found. This happens if the address range is not valid, if the range is already owned by an exclusive resource, or if a regular resource exists and the caller is trying to create an exclusive resource in the same range.
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.