| // Copyright 2019 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| library zx; |
| |
| @transport("Syscall") |
| closed protocol Resource { |
| /// ## Summary |
| /// |
| /// Create a resource object. |
| /// |
| /// ## Declaration |
| /// |
| /// ```c |
| /// #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_FRAMEBUFFER_BASE`, `ZX_RSRC_SYSTEM_PROFILE_BASE` and |
| /// `ZX_RSRC_SYSTEM_MSI_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_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 |
| /// |
| /// - [`zx_handle_close()`] |
| /// - [`zx_interrupt_create()`] |
| /// - [`zx_ioports_request()`] |
| /// - [`zx_vmo_create_physical()`] |
| /// |
| /// [`zx_channel_write()`]: channel_write.md |
| /// [`zx_handle_close()`]: handle_close.md |
| /// [`zx_interrupt_create()`]: interrupt_create.md |
| /// [`zx_ioports_request()`]: ioports_request.md |
| /// [`zx_object_get_info()`]: object_get_info.md |
| /// [`zx_vmo_create_physical()`]: vmo_create_physical.md |
| strict Create(resource struct { |
| parent_rsrc Handle:RESOURCE; |
| options uint32; |
| base uint64; |
| size usize64; |
| name vector<uchar>:MAX_NAME_LEN; |
| }) -> (resource struct { |
| resource_out Handle:RESOURCE; |
| }) error Status; |
| }; |