NAME
resource - Address space rights and accounting
SYNOPSIS
A resource is an immutable object that is used to validate access to syscalls that create objects backed by address space, or permit access to address space. These include vm objects, interrupts, and x86 ioports.
DESCRIPTION
Resources are used to gate access to specific regions of address space and are required to create VMOs and IRQs, as well as accessing x86 ioports.
A resource object consists of a single resource kind, with base address and len parameters that define a range of address space the holder of the resource is granted access to. The range covers base up to but not including base + len. These objects are immutable after creation. Valid kind values are ZX_RSRC_KIND_ROOT, ZX_RSRC_KIND_MMIO, ZX_RSRC_KIND_IOPORT, ZX_RSRC_KIND_IRQ, ZX_RSRC_KIND_SMC, and ZX_RSRC_KIND_SYSTEM.
The system resource is a special case that contains other resources, all of which have len one. These resources each have their own base within the system resource. Valid base values for the system resource 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_FRAMEBUFFER_BASE, ZX_RSRC_SYSTEM_PROFILE_BASE, ZX_RSRC_SYSTEM_MSI_BASE, and ZX_SYSTEM_DEBUGLOG_BASE.
New resources may be created with an appropriate parent resource by calling
zx_resource_create(). An initial resource of each kind is created by the kernel
during boot and handed off to the first userspace process started by userboot.
Appropriate parent resources are the root resource, or a resource whose own range from base to base+len contains the range requested for the new resource. The kind of a parent resource must match the kind of the resource being created. At this time, exclusive resources cannot be used to create new resources. After creation there is no relation between the resource parent used and the new resource created.
Resource allocations can be either shared or exclusive. A shared resource grants the permission to access the given address space, but does not reserve that address space exclusively for the owner of the resource. An exclusive resource grants access to the region to only the holder of the exclusive resource. Exclusive and shared resource ranges may not overlap.
Resources are lifecycle tracked and upon the last handle being closed will be freed. In the case of exclusive resources this means the given address range will be released back to the allocator for the given kind of resource. Objects created through a resource do not hold a reference to the resource and thus do not keep it alive.
NOTES
Resources are typically private to the DDK and platform bus drivers. Presently, this means ACPI and platform bus hold the root resource respectively and hand out more fine-grained resources to other drivers.