Google Git
Sign in
fuchsia / fuchsia / refs/heads/main / . / zircon / vdso / object.fidl
blob: 875608e8864186de5f87c8d18d0420f9b9650309 [file] [log] [blame]
// 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;
// TODO(https://fxbug.dev/42061412): This should be modeled as a `bits`, but more thought
// needs to be given to the public/private split of the current C definition.
alias Signals = uint32;
const WAIT_MANY_MAX_ITEMS usize64 = 64;
// TODO(scottmg): Apply rights spec from WaitMany on |items| to |handle| here,
// somehow.
type WaitItem = resource struct {
handle Handle;
waitfor Signals;
pending Signals;
};
@transport("Syscall")
closed protocol Object {
/// ## Summary
///
/// Wait for signals on an object.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_object_wait_one(zx_handle_t handle,
/// zx_signals_t signals,
/// zx_time_t deadline,
/// zx_signals_t* observed);
/// ```
///
/// ## Description
///
/// `zx_object_wait_one()` is a blocking syscall that causes the caller to wait
/// until either the *deadline* passes or the object to which *handle* refers
/// asserts at least one [signal][signals] specified by the bitmask *signals*. If
/// the object is already asserting at least one of the specified *signals*, the
/// wait ends immediately with `ZX_OK`.
///
/// Upon return, if non-NULL, *observed* is a bitmap of *all* of the signals
/// asserted on the object. If one of the specified *signals* was asserted,
/// *observed* will be the set of signals asserted at the moment the specified
/// signal was first asserted. Otherwise, if *deadline* passes or *handle* is
/// closed, *observed* will contain the state of the object's signals at the time
/// the `zx_object_wait_one` syscall completed.
///
/// The *deadline* parameter specifies a deadline with respect to
/// `ZX_CLOCK_MONOTONIC` and will be automatically adjusted according to the job's
/// [timer slack] policy.
///
/// * `ZX_TIME_INFINITE` is a special value meaning wait forever.
/// * `ZX_TIME_INFINITE_PAST` (or any value before the current time in
/// `ZX_CLOCK_MONOTONIC`) will query the current value of the signal(s).
///
/// ## Rights
///
/// *handle* must have `ZX_RIGHT_WAIT`.
///
/// ## Return value
///
/// `zx_object_wait_one()` returns `ZX_OK` if any of *signals* were active when
/// the call was made, or observed on the object before *deadline* passes.
///
/// In the event of `ZX_ERR_TIMED_OUT`, *observed* may reflect state changes
/// that occurred after the deadline passed, but before the syscall returned.
///
/// In the event of `ZX_ERR_CANCELED`, *handle* has been closed,
/// and *observed* will have the `ZX_SIGNAL_HANDLE_CLOSED` bit set.
///
/// For any other return value, *observed* is undefined.
///
/// ## Errors
///
/// `ZX_ERR_INVALID_ARGS` *observed* is an invalid pointer.
///
/// `ZX_ERR_BAD_HANDLE` *handle* is not a valid handle.
///
/// `ZX_ERR_ACCESS_DENIED` *handle* does not have `ZX_RIGHT_WAIT` and may
/// not be waited upon.
///
/// `ZX_ERR_CANCELED` *handle* was invalidated (e.g., closed) during the wait.
///
/// `ZX_ERR_TIMED_OUT` The specified deadline passed before any of the specified
/// *signals* are observed on *handle*.
///
/// `ZX_ERR_NOT_SUPPORTED` *handle* is a handle that cannot be waited on
/// (for example, a Port handle).
///
/// ## Notes
///
/// See [signals] for more information about signals and their terminology.
///
/// ## See also
///
/// - [signals]
/// - [timer slack]
/// - [`zx_object_wait_async()`]
/// - [`zx_object_wait_many()`]
///
/// [signals]: /docs/concepts/kernel/signals.md
/// [timer slack]: /docs/concepts/kernel/timer_slack.md
/// [`zx_object_wait_async()`]: object_wait_async.md
/// [`zx_object_wait_many()`]: object_wait_many.md
@blocking
strict WaitOne(resource struct {
handle Handle;
signals Signals;
deadline Time;
}) -> (struct {
observed Signals;
}) error Status;
/// ## Summary
///
/// Wait for signals on multiple objects.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_object_wait_many(zx_wait_item_t* items,
/// size_t num_items,
/// zx_time_t deadline);
/// ```
///
/// ## Description
///
/// `zx_object_wait_many()` is a blocking syscall that causes the caller to wait
/// until either the *deadline* passes or at least one object referred to in
/// *items* has a specified [signal][signals] asserted. If an object is already
/// asserting at least one of the specified signals, the wait ends immediately with
/// `ZX_OK`.
///
/// ```
/// typedef struct {
/// zx_handle_t handle;
/// zx_signals_t waitfor;
/// zx_signals_t pending;
/// } zx_wait_item_t;
/// ```
///
/// The caller must provide *count* `zx_wait_item_t`s in the *items* array,
/// containing the handle and signals bitmask to wait for for each item.
/// Each item should contain a valid *handle* referring to an object to
/// wait for, and a bitmask *waitfor* indicating which signals should wake
/// the calling thread.
///
/// The *deadline* parameter specifies a deadline with respect to
/// `ZX_CLOCK_MONOTONIC` and will be automatically adjusted according to the job's
/// [timer slack] policy. `ZX_TIME_INFINITE` is a special value meaning wait
/// forever.
///
/// Upon return, the *pending* field of *items* is filled with bitmaps indicating
/// which signals are pending for each item.
///
/// The maximum number of items that may be waited upon is `ZX_WAIT_MANY_MAX_ITEMS`,
/// which is 64. To wait on more objects at once use [Ports](/docs/reference/kernel_objects/port.md).
///
/// ## Rights
///
/// Every entry of *items* must have a *handle* field with `ZX_RIGHT_WAIT`.
///
/// ## Return value
///
/// `zx_object_wait_many()` returns `ZX_OK` if any of *waitfor* signals were
/// active when the call was made, or observed on their respective object before
/// *deadline* passed.
///
/// In the event of `ZX_ERR_TIMED_OUT`, *items* may reflect state changes
/// that occurred after the deadline passed, but before the syscall returned.
///
/// In the event of `ZX_ERR_CANCELED`, one or more of the items being waited
/// upon have had their handles closed, and the *pending* field for those items
/// will have the `ZX_SIGNAL_HANDLE_CLOSED` bit set.
///
/// For any other return value, the *pending* fields of *items* are undefined.
///
/// ## Errors
///
/// `ZX_ERR_INVALID_ARGS` *items* isn't a valid pointer.
///
/// `ZX_ERR_OUT_OF_RANGE` *count* is greater than `ZX_WAIT_MANY_MAX_ITEMS`.
///
/// `ZX_ERR_BAD_HANDLE` one of *items* contains an invalid handle.
///
/// `ZX_ERR_ACCESS_DENIED` One or more of the provided *handles* does not
/// have `ZX_RIGHT_WAIT` and may not be waited upon.
///
/// `ZX_ERR_CANCELED` One or more of the provided *handles* was invalidated
/// (e.g., closed) during the wait.
///
/// `ZX_ERR_TIMED_OUT` The specified deadline passed before any of the specified
/// signals are observed on any of the specified handles. Note that calls with a
/// *count* of 0 will still wait until *deadline* has passed before returning.
///
/// `ZX_ERR_NOT_SUPPORTED` One of the *items* contains a handle that cannot
/// be waited one (for example, a Port handle).
///
/// `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.
///
/// ## BUGS
///
/// *pending* more properly should be called *observed*.
///
/// ## Notes
///
/// See [signals] for more information about signals and their terminology.
///
/// ## See also
///
/// - [signals]
/// - [timer slack]
/// - [`zx_object_wait_async()`]
/// - [`zx_object_wait_one()`]
///
/// [signals]: /docs/concepts/kernel/signals.md
/// [timer slack]: /docs/concepts/kernel/timer_slack.md
/// [`zx_object_wait_async()`]: object_wait_async.md
/// [`zx_object_wait_one()`]: object_wait_one.md
@blocking
strict WaitMany(resource struct {
@inout
items vector<WaitItem>:WAIT_MANY_MAX_ITEMS;
deadline Time;
}) -> () error Status;
/// ## Summary
///
/// Subscribe for signals on an object.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_object_wait_async(zx_handle_t handle,
/// zx_handle_t port,
/// uint64_t key,
/// zx_signals_t signals,
/// uint32_t options);
/// ```
///
/// ## Description
///
/// `zx_object_wait_async()` is a non-blocking syscall that causes packets to be
/// enqueued on *port* when the object specified by *handle* has one or more of the
/// specified [signals] asserted. Use [`zx_port_wait()`] to retrieve the packets.
///
/// *handle* points to the object that is to be watched for changes and must be a waitable object.
///
/// The *options* argument can be 0 or it can be one or more of
///
/// * ZX_WAIT_ASYNC_TIMESTAMP which causes the system to capture a timestamp when
/// the wait triggered.
/// * ZX_WAIT_ASYNC_EDGE causes the port to not enqueue a packet for signals active
/// at the time of the `zx_object_wait_async()` call.
///
/// The *signals* argument is a bitmask indicating which [signals] on the object
/// specified by *handle* will cause a packet to be enqueued.
///
/// Without `ZX_WAIT_ASYNC_EDGE`, if `any` of the signals in *signals* are active
/// when `zx_object_wait_async()` is called or become active afterwards, a packet will
/// be enqueued on *port*.
///
/// With `ZX_WAIT_ASYNC_EDGE`, a packet will be enqueued on *port* only after one or more
/// signals in *signals* have transitioned from inactive to active. When using this option,
/// care should be taken that an inactive signal becomes unexpectedly active before
/// the call `zx_object_wait_async()` has completed. In such cases the transition can be missed
/// and no packet will ever be queued to the port. For example, this is often used
/// before performing non-blocking I/O until the signal becomes inactive, ensuring that
/// a subsequent transition from inactive to active will cause a packet to be queued.
///
/// When a packet is enqueued, it will contain all of the currently-asserted signals
/// (not just the ones listed in the *signals* argument). Once a packet has been enqueued
/// the asynchronous waiting ends. No further packets will be enqueued. Note that signals
/// are OR'd into the state maintained by the port thus you may see any combination of requested
/// signals when [`zx_port_wait()`] returns.
///
/// Each call to `zx_object_wait_async()` creates a new asynchronous wait operation,
/// or observer. These operations are not deduplicated in any way. That is, if
/// `zx_object_wait_async()` is called twice with the same arguments, two operations
/// will be created. And if an asserted signal matches those operations, two packets
/// will be enqueued, one for each operation.
///
/// There is a limit to the number of operations each port may have. When the limit
/// is exceeded, a job policy exception (`ZX_EXCP_POLICY_CODE_PORT_TOO_MANY_OBSERVERS`)
/// is raised by the process that crossed the limit.
///
/// [`zx_port_cancel()`] will terminate all asynchronous wait operations with
/// *handle* and *port* that have the specified *key*. In addition, any packets in
/// the queue generated by those operations will be removed from the queue.
///
/// If *handle* is closed, the operations associated with it will also be
/// terminated, but packets already in the queue are not affected.
///
/// Packets generated via this syscall will have *type* set to `ZX_PKT_TYPE_SIGNAL_ONE`
/// and the union is of type `zx_packet_signal_t`:
///
/// ```
/// typedef struct zx_packet_signal {
/// zx_signals_t trigger;
/// zx_signals_t observed;
/// uint64_t count;
/// zx_time_t timestamp; // depends on ZX_WAIT_ASYNC_TIMESTAMP
/// uint64_t reserved1;
/// } zx_packet_signal_t;
/// ```
///
/// *trigger* is the signals used in the call to `zx_object_wait_async()`,
/// *observed* is the signals actually observed, and *timestamp* is clock-monotonic
/// time when the object state transitioned to meet the trigger condition. If
/// options does not include ZX_WAIT_ASYNC_TIMESTAMP the timestamp is reported as 0.
///
/// Use the `zx_port_packet_t`'s *key* member to track what object this packet corresponds.
///
/// ## Rights
///
/// *handle* must have `ZX_RIGHT_WAIT`.
///
/// *port* must be of type `ZX_OBJ_TYPE_PORT` and have `ZX_RIGHT_WRITE`.
///
/// ## Return value
///
/// `zx_object_wait_async()` returns `ZX_OK` if the subscription succeeded.
///
/// ## Errors
///
/// `ZX_ERR_INVALID_ARGS` *options* has bits other than `ZX_WAIT_ASYNC_TIMESTAMP`
/// and `ZX_WAIT_ASYNC_EDGE` set.
///
/// `ZX_ERR_BAD_HANDLE` *handle* is not a valid handle or *port* is not a valid handle.
///
/// `ZX_ERR_WRONG_TYPE` *port* is not a Port handle.
///
/// `ZX_ERR_ACCESS_DENIED` *handle* does not have `ZX_RIGHT_WAIT` or *port*
/// does not have `ZX_RIGHT_WRITE`.
///
/// `ZX_ERR_NOT_SUPPORTED` *handle* is a handle that cannot be waited on.
///
/// `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.
///
/// ## Notes
///
/// See [signals] for more information about signals and their terminology.
///
/// ## See also
///
/// - [signals]
/// - [`zx_object_wait_many()`]
/// - [`zx_object_wait_one()`]
/// - [`zx_port_cancel()`]
/// - [`zx_port_queue()`]
/// - [`zx_port_wait()`]
///
/// [signals]: /docs/concepts/kernel/signals.md
/// [`zx_object_wait_many()`]: object_wait_many.md
/// [`zx_object_wait_one()`]: object_wait_one.md
/// [`zx_port_cancel()`]: port_cancel.md
/// [`zx_port_queue()`]: port_queue.md
/// [`zx_port_wait()`]: port_wait.md
strict WaitAsync(resource struct {
handle Handle;
port Handle:PORT;
key uint64;
signals Signals;
options uint32;
}) -> () error Status;
/// ## Summary
///
/// Signal an object.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_object_signal(zx_handle_t handle,
/// uint32_t clear_mask,
/// uint32_t set_mask);
/// ```
///
/// ## Description
///
/// `zx_object_signal()` asserts and deasserts the userspace-accessible signal
/// bits on an object.
///
/// Most of the 32 signals are reserved for system use and are assigned to
/// per-object functions, like `ZX_CHANNEL_READABLE` or `ZX_TASK_TERMINATED`. There
/// are 8 signal bits available for userspace processes to use as they see fit:
/// `ZX_USER_SIGNAL_0` through `ZX_USER_SIGNAL_7`.
///
/// *Event* objects also allow control over the `ZX_EVENT_SIGNALED` bit.
///
/// *Eventpair* objects also allow control over the `ZX_EVENTPAIR_SIGNALED` bit.
///
/// The *clear_mask* is first used to clear any bits indicated, and then the
/// *set_mask* is used to set any bits indicated.
///
/// ## Rights
///
/// *handle* must have `ZX_RIGHT_SIGNAL`.
///
/// ## Return value
///
/// `zx_object_signal()` returns `ZX_OK` on success. In the event of failure, a
/// negative error value is returned.
///
/// ## Errors
///
/// `ZX_ERR_BAD_HANDLE` *handle* is not a valid handle.
///
/// `ZX_ERR_ACCESS_DENIED` *handle* lacks the right `ZX_RIGHT_SIGNAL`.
///
/// `ZX_ERR_INVALID_ARGS` *clear_mask* or *set_mask* contain bits that are not allowed.
///
/// ## See also
///
/// - [`zx_event_create()`]
/// - [`zx_eventpair_create()`]
/// - [`zx_object_signal_peer()`]
///
/// [`zx_event_create()`]: event_create.md
/// [`zx_eventpair_create()`]: eventpair_create.md
/// [`zx_object_signal_peer()`]: object_signal_peer.md
strict Signal(resource struct {
handle Handle;
clear_mask uint32;
set_mask uint32;
}) -> () error Status;
/// ## Summary
///
/// Signal an object's peer.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_object_signal_peer(zx_handle_t handle,
/// uint32_t clear_mask,
/// uint32_t set_mask);
/// ```
///
/// ## Description
///
/// `zx_object_signal_peer()` asserts and deasserts the userspace-accessible
/// signal bits on the object's peer. A object peer is the opposite endpoint of a
/// *channel*, *socket*, *fifo*, or *eventpair*.
///
/// Most of the 32 signals are reserved for system use and are assigned to
/// per-object functions, like `ZX_CHANNEL_READABLE` or `ZX_TASK_TERMINATED`. There
/// are 8 signal bits available for userspace processes to use as they see fit:
/// `ZX_USER_SIGNAL_0` through `ZX_USER_SIGNAL_7`.
///
/// *Eventpair* objects also allow control over the `ZX_EVENTPAIR_SIGNALED` bit.
///
/// The *clear_mask* is first used to clear any bits indicated, and then the
/// *set_mask* is used to set any bits indicated.
///
/// ## Rights
///
/// *handle* must have `ZX_RIGHT_SIGNAL_PEER`.
///
/// ## Return value
///
/// `zx_object_signal_peer()` returns `ZX_OK` on success. In the event of
/// failure, a negative error value is returned.
///
/// ## Errors
///
/// `ZX_ERR_BAD_HANDLE` *handle* is not a valid handle.
///
/// `ZX_ERR_ACCESS_DENIED` *handle* lacks the right `ZX_RIGHT_SIGNAL_PEER`.
///
/// `ZX_ERR_INVALID_ARGS` *clear_mask* or *set_mask* contain bits that are not allowed.
///
/// `ZX_ERR_NOT_SUPPORTED` Used on an object lacking a peer.
///
/// `ZX_ERR_PEER_CLOSED` Called on an object with a closed peer.
///
/// ## See also
///
/// - [`zx_eventpair_create()`]
/// - [`zx_object_signal()`]
///
/// [`zx_event_create()`]: event_create.md
/// [`zx_eventpair_create()`]: eventpair_create.md
/// [`zx_object_signal()`]: object_signal.md
strict SignalPeer(resource struct {
handle Handle;
clear_mask uint32;
set_mask uint32;
}) -> () error Status;
/// ## Summary
///
/// Ask for various properties of various kernel objects.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_object_get_property(zx_handle_t handle,
/// uint32_t property,
/// void* value,
/// size_t value_size);
/// ```
///
/// ## Description
///
/// `zx_object_get_property()` requests the value of a kernel object's property.
/// Getting a property requires `ZX_RIGHT_GET_PROPERTY` rights on the handle.
///
/// The *handle* parameter indicates the target kernel object. Different properties
/// only work on certain types of kernel objects, as described below.
///
/// The *property* parameter indicates which property to get/set. Property values
/// have the prefix `ZX_PROP_`, and are described below.
///
/// The *value* parameter holds the property value, and must be a pointer to a
/// buffer of *value_size* bytes. Different properties expect different value
/// types/sizes as described below.
///
/// ## PROPERTIES
///
/// Property values have the prefix `ZX_PROP_`, and are defined in
///
/// ```
/// #include <zircon/syscalls/object.h>
/// ```
///
/// ### ZX_PROP_NAME
///
/// *handle* type: `Any of the following`
/// - Job
/// - Process
/// - Thread
/// - Resource
/// - Virtual Memory Object (VMO)
/// - Bus Transaction Initiator (BTI)
///
/// *value* type: `char[ZX_MAX_NAME_LEN]`
///
/// Allowed operations: `get`, `set`
///
/// The name of the object, as a NUL-terminated string.
///
/// Attempting to get or set the name of a thread that has exited will fail with `ZX_ERR_BAD_STATE`.
///
/// ### ZX_PROP_REGISTER_FS and ZX_PROP_REGISTER_GS
///
/// *handle* type: `Thread`
///
/// *value* type: `uintptr_t`
///
/// Allowed operations: `get`, `set`
///
/// The value of the x86 FS.BASE or GS.BASE register, respectively. `value` must
/// be a canonical address. Attempting to set a noncanonical address will fail with
/// `ZX_ERR_INVALID_ARGS`.
///
/// This is a software substitute for the `rdfsbase`, `wrfsbase` and `rdgsbase`,
/// `wrgsbase` instruction pairs supported on newer x86-64 CPUs, and should behave
/// exactly the same as using the CPU instructions directly (except that
/// attempting to set a noncanonical address as the value just gets an error
/// return rather than generating a machine exception). When using a CPU that
/// supports these instructions (as reported by the `cpuid` instruction), it's
/// more efficient and simpler to use the machine instructions directly.
///
/// Only defined for x86-64. Returns `ZX_ERR_NOT_SUPPORTED` on other architectures.
/// Returns `ZX_ERR_ACCESS_DENIED` if not invoked from the current thread.
///
/// ### ZX_PROP_PROCESS_DEBUG_ADDR
///
/// *handle* type: `Process`
///
/// *value* type: `uintptr_t`
///
/// Allowed operations: `get`, `set`
///
/// The value of ld.so's `_dl_debug_addr`. This can be used by debuggers to
/// interrogate the state of the dynamic loader.
///
/// ### ZX_PROP_PROCESS_BREAK_ON_LOAD
///
/// *handle* type: `Process`
///
/// *value* type: `uintptr_t`
///
/// Allowed operations: `get`, `set`
///
/// Determines whether the dynamic loader will issue a debug trap on every load of a
/// shared library. If set before the first thread of a process runs, it will also
/// trigger a debug trap for the initial load.
///
/// The dynamic loader sets the expected value of `ZX_PROP_PROCESS_DEBUG_ADDR` before
/// triggering this debug trap. Exception handlers can use this property to query the
/// dynamic loader's state.
///
/// When the dynamic loader issues the debug trap, it also sets the value of
/// `ZX_PROP_PROCESS_BREAK_ON_LOAD` to the address of the debug trap, so that
/// a debugger could compare the value with the address of the exception to
/// determine whether the debug trap was triggered by the dynamic loader.
///
/// Any non-zero value is considered to activate this feature. Setting this property to
/// zero will disable it. A debugger could also use this property to detect whether
/// there's already another debugger attached to the same process.
///
/// Note: Depending on the architecture, the address reported by the exception might be
/// different that the one reported by this property. For example, an x64 platform reports
/// the instruction pointer *after* it executes the instruction. This means that an x64
/// platform reports an instruction pointer one byte higher than this property.
///
/// ### ZX_PROP_PROCESS_VDSO_BASE_ADDRESS
///
/// *handle* type: `Process`
///
/// *value* type: `uintptr_t`
///
/// Allowed operations: `get`
///
/// The base address of the vDSO mapping, or zero.
///
/// ### ZX_PROP_PROCESS_HW_TRACE_CONTEXT_ID
///
/// *handle* type: `Process`
///
/// *value* type: `uintptr_t`
///
/// Allowed operations: `get`
///
/// The context ID distinguishes different processes in hardware instruction tracing.
/// On Intel X86-64 this is the value of register CR3.
///
/// To obtain `ZX_PROP_PROCESS_HW_TRACE_CONTEXT_ID`, you must specify
/// `kernel.enable-debugging-syscalls=true` on the kernel command line. Otherwise,
/// the function returns `ZX_ERR_NOT_SUPPORTED`.
///
/// Currently only defined for X86.
///
/// ### ZX_PROP_SOCKET_RX_THRESHOLD
///
/// *handle* type: `Socket`
///
/// *value* type: `size_t`
///
/// Allowed operations: `get`, `set`
///
/// The size of the read threshold of a socket, in bytes. Setting this will
/// assert `ZX_SOCKET_READ_THRESHOLD` if the amount of data that can be read
/// is greater than or equal to the threshold. Setting this property to zero
/// will result in the deasserting of `ZX_SOCKET_READ_THRESHOLD`.
///
/// Setting to a value larger than the maximum permissible size supported by
/// sockets will fail with `ZX_ERR_INVALID_ARGS`.
///
/// ### ZX_PROP_SOCKET_TX_THRESHOLD
///
/// *handle* type: `Socket`
///
/// *value* type: `size_t`
///
/// Allowed operations: `get`, `set`
///
/// The size of the write threshold of a socket, in bytes. Setting this will
/// assert `ZX_SOCKET_WRITE_THRESHOLD` if the amount of space available for writing
/// is greater than or equal to the threshold. Setting this property to zero
/// will result in the deasserting of `ZX_SOCKET_WRITE_THRESHOLD`. Setting the
/// write threshold after the peer has closed is an error, and results in a
/// `ZX_ERR_PEER_CLOSED` error being returned.
///
/// Setting to a value larger than the maximum permissible size supported by
/// sockets will fail with `ZX_ERR_INVALID_ARGS`.
///
/// ### ZX_PROP_JOB_KILL_ON_OOM
///
/// *handle* type: `Job`
///
/// *value* type: `size_t`
///
/// Allowed operations: `set`
///
/// The value of 1 means the Job and its children will be terminated if the
/// system finds itself in a system-wide low memory situation. Called with 0
/// (which is the default) opts out the job from being terminated in this
/// scenario. Setting to any other value will fail with `ZX_ERR_INVALID_ARGS`.
///
/// ### ZX_PROP_EXCEPTION_STATE
///
/// *handle* type: `Exception`
///
/// *value* type: `uint32_t`
///
/// Allowed operations: `get`, `set`
///
/// When set to `ZX_EXCEPTION_STATE_HANDLED`, closing the exception handle will
/// finish exception processing and resume the underlying thread.
/// When set to `ZX_EXCEPTION_STATE_TRY_NEXT`, closing the exception handle will
/// continue exception processing by trying the next handler in order.
/// When set to `ZX_EXCEPTION_STATE_THREAD_EXIT`, closing the exception handle will
/// cause the thread that generated the exception to exit.
/// Setting to any other value will fail with `ZX_ERR_INVALID_ARGS`.
///
/// ### ZX_PROP_EXCEPTION_STRATEGY
///
/// *handle* type: `Exception`
///
/// *value* type: `uint32_t`
///
/// Allowed operations: `get`, `set`
///
/// If `ZX_EXCEPTION_STRATEGY_SECOND_CHANCE` is set, then the debugger gets a 'second
/// chance' at handling the exception if the process-level handler fails to do so.
/// If `ZX_EXCEPTION_STRATEGY_FIRST_CHANCE` is set, then the debugger does not get a
/// second chance at handling the exception.
/// Setting to any other value will fail with `ZX_ERR_INVALID_ARGS`.
///
/// This property can only be set when the handle corresponds to a debugger process
/// exception channel. Attempting to set this property when the exception channel
/// is any other type will result in `ZX_ERR_BAD_STATE`.
///
/// ### ZX_PROP_STREAM_MODE_APPEND
///
/// *handle* type: `Stream`
///
/// *value* type: `uint8_t`
///
/// Allowed operations: `get`, `set`
///
/// This property will have a value of `1` when the Stream is in append mode and a
/// value of `0` the Stream is not in append mode. A stream in append mode will
/// atomically set the seek offset of the stream to the content size of the stream
/// prior to writing data in `zx_stream_writev()`.
///
/// ## Rights
///
/// *handle* must have `ZX_RIGHT_GET_PROPERTY`, and must be of a supported `ZX_OBJ_TYPE_`
/// for the *property*, as documented above in the description of individual properties.
///
/// ## Return value
///
/// `zx_object_get_property()` returns `ZX_OK` on success. In the event of
/// failure, a negative error value is returned.
///
/// ## Errors
///
/// Specific errors for individual *property* values are documented in their description above.
/// Common errors are listed below:
///
/// `ZX_ERR_BAD_HANDLE`: *handle* is not a valid handle.
///
/// `ZX_ERR_WRONG_TYPE`: *handle* is not an appropriate type for *property*.
///
/// `ZX_ERR_ACCESS_DENIED`: *handle* does not have the necessary rights for the
/// operation.
///
/// `ZX_ERR_INVALID_ARGS`: *value* is an invalid pointer.
///
/// `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.
///
/// `ZX_ERR_BUFFER_TOO_SMALL`: *value_size* is too small for *property*.
///
/// `ZX_ERR_NOT_SUPPORTED`: *property* does not exist.
///
/// ## See also
///
/// - [`zx_object_set_property()`]
///
/// [`zx_object_set_property()`]: object_set_property.md
strict GetProperty(resource struct {
handle Handle;
property uint32;
}) -> (struct {
@voidptr
value vector<byte>:MAX;
}) error Status;
/// ## Summary
///
/// Set various properties of various kernel objects.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_object_set_property(zx_handle_t handle,
/// uint32_t property,
/// const void* value,
/// size_t value_size);
/// ```
///
/// ## Description
///
/// `zx_object_set_property()` modifies the value of a kernel object's property.
/// Setting a property requires `ZX_RIGHT_SET_PROPERTY` rights on the handle.
///
/// See [`zx_object_get_property()`] for a full description.
///
/// ## Rights
///
/// *handle* must have `ZX_RIGHT_SET_PROPERTY`, and must be of a supported `ZX_OBJ_TYPE_`
/// for the *property*, as documented in [`zx_object_get_property()`].
///
/// ## See also
///
/// - [`zx_object_get_property()`]
///
/// [`zx_object_get_property()`]: object_get_property.md
strict SetProperty(resource struct {
handle Handle;
property uint32;
@voidptr
value vector<byte>:MAX;
}) -> () error Status;
/// ## Summary
///
/// Query information about an object.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_object_get_info(zx_handle_t handle,
/// uint32_t topic,
/// void* buffer,
/// size_t buffer_size,
/// size_t* actual,
/// size_t* avail);
/// ```
///
/// ## Description
///
/// `zx_object_get_info()` requests information about the provided handle (or the
/// object the handle refers to). The *topic* parameter indicates what specific
/// information is desired.
///
/// *buffer* is a pointer to a buffer of size *buffer_size* to return the
/// information.
///
/// *actual* is an optional pointer to return the number of records that were
/// written to buffer.
///
/// *avail* is an optional pointer to return the number of records that are
/// available to read.
///
/// If the buffer is insufficiently large, *avail* will be larger than *actual*.
///
/// [TOC]
///
/// ## TOPICS
///
/// ### ZX_INFO_HANDLE_VALID
///
/// *handle* type: `Any`
///
/// *buffer* type: `n/a`
///
/// Returns `ZX_OK` if *handle* is valid, or `ZX_ERR_BAD_HANDLE` otherwise. No
/// records are returned and *buffer* may be NULL.
///
/// ### ZX_INFO_HANDLE_BASIC
///
/// *handle* type: `Any`
///
/// *buffer* type: `zx_info_handle_basic_t[1]`
///
/// ```
/// typedef struct zx_info_handle_basic {
/// // The unique id assigned by kernel to the object referenced by the
/// // handle.
/// zx_koid_t koid;
///
/// // The immutable rights assigned to the handle. Two handles that
/// // have the same koid and the same rights are equivalent and
/// // interchangeable.
/// zx_rights_t rights;
///
/// // The object type: channel, event, socket, etc.
/// uint32_t type; // zx_obj_type_t;
///
/// // If the object referenced by the handle is related to another (such
/// // as the other end of a channel, or the parent of a job) then
/// // |related_koid| is the koid of that object, otherwise it is zero.
/// // This relationship is immutable: an object's |related_koid| does
/// // not change even if the related object no longer exists.
/// zx_koid_t related_koid;
/// } zx_info_handle_basic_t;
/// ```
///
/// ### ZX_INFO_HANDLE_COUNT
///
/// *handle* type: `Any`
///
/// *buffer* type: `zx_info_handle_count_t[1]`
///
/// ```
/// typedef struct zx_info_handle_count {
/// // The number of outstanding handles to a kernel object.
/// uint32_t handle_count;
/// } zx_info_handle_count_t;
/// ```
///
/// The *handle_count* should only be used as a debugging aid. Do not use it to
/// check that an untrusted processes cannot modify a kernel object. Due to
/// asynchronous nature of the system scheduler, there might be a time window during
/// which it is possible for an object to be modified by a previous handle owner
/// even as the last handle is transferred from one process to another.
///
/// ### ZX_INFO_PROCESS_HANDLE_STATS
///
/// *handle* type: `Process`
///
/// *buffer* type: `zx_info_process_handle_stats_t[1]`
///
/// ```
/// typedef struct zx_info_process_handle_stats {
/// // The number of outstanding handles to kernel objects of each type.
/// uint32_t handle_count[ZX_OBJ_TYPE_UPPER_BOUND];
/// } zx_info_process_handle_stats_t;
/// ```
///
/// ### ZX_INFO_HANDLE_TABLE
///
/// *handle* type: `Process`
///
/// *buffer* type: `zx_info_handle_extended_t[n]`
///
/// Returns an array of `zx_info_handle_extended_t` one for each handle in the
/// Process at the moment of the call. The kernel ensures that the handles returned
/// are consistent.
///
/// ```
/// typedef struct zx_info_handle_extended {
/// // The object type: channel, event, socket, etc.
/// zx_obj_type_t type;
///
/// // The handle value, which is only valid for the process that
/// // was passed to ZX_INFO_HANDLE_TABLE.
/// zx_handle_t handle_value;
///
/// // The immutable rights assigned to the handle. Two handles that
/// // have the same koid and the same rights are equivalent and
/// // interchangeable.
/// zx_rights_t rights;
///
/// uint32_t reserved;
///
/// // The unique id assigned by kernel to the object referenced by the
/// // handle.
/// zx_koid_t koid;
///
/// // If the object referenced by the handle is related to another (such
/// // as the other end of a channel, or the parent of a job) then
/// // |related_koid| is the koid of that object, otherwise it is zero.
/// // This relationship is immutable: an object's |related_koid| does
/// // not change even if the related object no longer exists.
/// zx_koid_t related_koid;
///
/// // If the object referenced by the handle has a peer, like the
/// // other end of a channel, then this is the koid of the process
/// // which currently owns it.
/// zx_koid_t peer_owner_koid;
/// } zx_info_handle_extended_t;
/// ```
///
/// Note that a process might have live references to objects for which the process
/// does not have a handle to. For example, running threads for which all handles
/// have been closed.
///
/// ### ZX_INFO_JOB
///
/// *handle* type: `Job`
///
/// *buffer* type: `zx_info_job_t[1]`
///
/// ```
/// typedef struct zx_info_job {
/// // The job's return code; only valid if |exited| is true.
/// // If the job was killed, it will be one of the ZX_TASK_RETCODE values.
/// int64_t return_code;
///
/// // If true, the job has exited and |return_code| is valid.
/// bool exited;
///
/// // True if the ZX_PROP_JOB_KILL_ON_OOM property was set.
/// bool kill_on_oom;
///
/// // True if a debugger is attached to the job.
/// bool debugger_attached;
/// } zx_info_job_t;
/// ```
///
/// Note that |exited| will immediately report that the job has exited following a
/// |zx_task_kill| or equivalent (e.g. an OOM kill), but child jobs and processes
/// may still be in the process of exiting.
///
/// ### ZX_INFO_PROCESS
///
/// *handle* type: `Process`
///
/// *buffer* type: `zx_info_process_t[1]`
///
/// ```
/// typedef struct zx_info_process {
/// // The process's return code; only valid if the
/// // |ZX_PROCESS_INFO_FLAG_EXITED| flag is set. If the process was killed, it
/// // will be one of the |ZX_TASK_RETCODE| values.
/// int64_t return_code;
///
/// // The monotonic time at which `zx_process_start()` was called, only valid
/// // if the |ZX_INFO_PROCESS_FLAG_STARTED| flag is set.
/// zx_time_t start_time;
///
/// // Bitwise OR of ZX_INFO_PROCESS_FLAG_* values.
/// uint32_t flags;
/// } zx_info_process_t;
/// ```
///
/// Note that |flags| will immediately report that the process has exited (i.e. it
/// will contain ZX_INFO_PROCESS_FLAG_EXITED) following a |zx_task_kill|, but child
/// threads may still be in the process of exiting.
///
/// ### ZX_INFO_PROCESS_THREADS
///
/// *handle* type: `Process`
///
/// *buffer* type: `zx_koid_t[n]`
///
/// Returns an array of `zx_koid_t`, one for each running thread in the Process at
/// that moment in time.
///
/// N.B. Getting the list of threads is inherently racy. This can be somewhat
/// mitigated by first suspending all the threads, but note that an external thread
/// can create new threads. *actual* will contain the number of threads returned in
/// *buffer*. *avail* will contain the total number of threads of the process at the
/// time the list of threads was obtained, it could be larger than *actual*.
///
/// ### ZX_INFO_THREAD
///
/// *handle* type: `Thread`
///
/// *buffer* type: `zx_info_thread_t[1]`
///
/// ```
/// typedef struct zx_info_thread {
/// // One of ZX_THREAD_STATE_* values.
/// uint32_t state;
///
/// // If |state| is ZX_THREAD_STATE_BLOCKED_EXCEPTION, the thread has gotten
/// // an exception and is waiting for the exception to be handled by the
/// // specified channel.
/// // The value is one of ZX_EXCEPTION_CHANNEL_TYPE_*.
/// uint32_t wait_exception_channel_type;
///
/// // CPUs this thread may be scheduled on, as specified by
/// // a profile object applied to this thread.
/// //
/// // The kernel may not internally store invalid CPUs in the mask, so
/// // this may not exactly match the mask applied to the thread for
/// // CPUs beyond what the system is able to use.
/// zx_cpu_set_t cpu_affinity_mask;
/// } zx_info_thread_t;
/// ```
///
/// The values in this struct are mainly for informational and debugging purposes at
/// the moment.
///
/// The various `ZX_THREAD_STATE_` values are defined by
///
/// ```
/// #include <zircon/syscalls/object.h>
/// ```
///
/// * `ZX_THREAD_STATE_NEW`: The thread has been created but it has not started
/// running yet.
/// * `ZX_THREAD_STATE_RUNNING`: The thread is running user code normally.
/// * `ZX_THREAD_STATE_SUSPENDED`: Stopped due to [`zx_task_suspend()`].
/// * `ZX_THREAD_STATE_BLOCKED`: In a syscall or handling an exception. This
/// value is never returned by itself. See `ZX_THREAD_STATE_BLOCKED_\`* below.
/// * `ZX_THREAD_STATE_DYING`: The thread is in the process of being terminated,
/// but it has not been stopped yet.
/// * `ZX_THREAD_STATE_DEAD`: The thread has stopped running.
///
/// When a thread is stopped inside a blocking syscall, or stopped in an exception,
/// the value returned in `state` is one of the following:
///
/// * `ZX_THREAD_STATE_BLOCKED_EXCEPTION`: The thread is stopped in an
/// exception.
/// * `ZX_THREAD_STATE_BLOCKED_SLEEPING`: The thread is stopped in
/// [`zx_nanosleep()`].
/// * `ZX_THREAD_STATE_BLOCKED_FUTEX`: The thread is stopped in
/// [`zx_futex_wait()`].
/// * `ZX_THREAD_STATE_BLOCKED_PORT`: The thread is stopped in
/// [`zx_port_wait()`].
/// * `ZX_THREAD_STATE_BLOCKED_CHANNEL`: The thread is stopped in
/// [`zx_channel_call()`].
/// * `ZX_THREAD_STATE_BLOCKED_WAIT_ONE`: The thread is stopped in
/// [`zx_object_wait_one()`].
/// * `ZX_THREAD_STATE_BLOCKED_WAIT_MANY`: The thread is stopped in
/// [`zx_object_wait_many()`].
/// * `ZX_THREAD_STATE_BLOCKED_INTERRUPT`: The thread is stopped in
/// [`zx_interrupt_wait()`].
///
/// The various `ZX_EXCEPTION_CHANNEL_TYPE_` values are defined by
///
/// ```
/// #include <zircon/syscalls/exception.h>
/// ```
///
/// * `ZX_EXCEPTION_CHANNEL_TYPE_NONE`
/// * `ZX_EXCEPTION_CHANNEL_TYPE_DEBUGGER`
/// * `ZX_EXCEPTION_CHANNEL_TYPE_THREAD`
/// * `ZX_EXCEPTION_CHANNEL_TYPE_PROCESS`
/// * `ZX_EXCEPTION_CHANNEL_TYPE_JOB`
/// * `ZX_EXCEPTION_CHANNEL_TYPE_JOB_DEBUGGER`
///
/// ### ZX_INFO_THREAD_EXCEPTION_REPORT
///
/// *handle* type: `Thread`
///
/// *buffer* type: `zx_exception_report_t[1]`
///
/// ```
/// #include <zircon/syscalls/exception.h>
/// ```
///
/// If the thread is currently in an exception and is waiting for an exception
/// response, then this returns the exception report as a single
/// `zx_exception_report_t`, with status `ZX_OK`.
///
/// Returns `ZX_ERR_BAD_STATE` if the thread is not in an exception and waiting
/// for an exception response.
///
/// ### ZX_INFO_THREAD_STATS {#zx-info-thread-stats}
///
/// *handle* type: `Thread`
///
/// *buffer* type: `zx_info_thread_stats[1]`
///
/// ```
/// typedef struct zx_info_thread_stats {
/// // Total accumulated running time of the thread.
/// //
/// // Note: See zx_info_task_runtime for queue time in addition to runtime.
/// zx_duration_t total_runtime;
///
/// // CPU number that this thread was last scheduled on, or ZX_INFO_INVALID_CPU
/// // if the thread has never been scheduled on a CPU. By the time this call
/// // returns, the thread may have been scheduled elsewhere, so this
/// // information should only be used as a hint or for statistics.
/// uint32_t last_scheduled_cpu;
/// } zx_info_thread_stats_t;
/// ```
///
/// Returns `ZX_ERR_BAD_STATE` if the thread has exited.
///
/// ### ZX_INFO_GUEST_STATS
///
/// *handle* type: `Resource` (Specifically, the info resource)
///
/// *buffer* type: `zx_info_guest_stats_t[1]`
///
/// ```
/// // Each machine has its own format for the same ZX_INFO_GUEST_STATS topic.
/// // In each build, zx_info_guest_stats_t is a typedef alias for the type.
/// // Cross-tools can select the machine-specific type to use based on the
/// // source of the data they are working with.
/// typedef struct zx_arm64_info_guest_stats {
/// uint32_t cpu_number;
/// uint32_t flags;
/// uint64_t vm_entries;
/// uint64_t vm_exits;
/// uint64_t wfi_wfe_instructions;
/// uint64_t instruction_aborts;
/// uint64_t data_aborts;
/// uint64_t system_instructions;
/// uint64_t smc_instructions;
/// uint64_t interrupts;
/// } zx_arm64_info_guest_stats_t;
///
/// typedef struct zx_x86_64_info_guest_stats {
/// uint32_t cpu_number;
/// uint32_t flags;
/// uint64_t vm_entries;
/// uint64_t vm_exits;
/// uint64_t interrupts;
/// uint64_t interrupt_windows;
/// uint64_t cpuid_instructions;
/// uint64_t hlt_instructions;
/// uint64_t control_register_accesses;
/// uint64_t io_instructions;
/// uint64_t rdmsr_instructions;
/// uint64_t wrmsr_instructions;
/// uint64_t ept_violations;
/// uint64_t xsetbv_instructions;
/// uint64_t pause_instructions;
/// uint64_t vmcall_instructions;
/// } zx_x86_64_info_guest_stats;
/// ```
///
/// ### ZX_INFO_CPU_STATS
///
/// Note: many values of this topic are being retired in favor of a different
/// mechanism.
///
/// *handle* type: `Resource` (Specifically, the info resource)
///
/// *buffer* type: `zx_info_cpu_stats_t[1]`
///
/// ```
/// typedef struct zx_info_cpu_stats {
/// uint32_t cpu_number;
/// uint32_t flags;
///
/// zx_duration_t idle_time;
///
/// // kernel scheduler counters
/// uint64_t reschedules;
/// uint64_t context_switches;
/// uint64_t irq_preempts;
/// uint64_t preempts;
/// uint64_t yields;
///
/// // cpu level interrupts and exceptions
/// uint64_t ints; // hardware interrupts, minus timer interrupts
/// // inter-processor interrupts
/// uint64_t timer_ints; // timer interrupts
/// uint64_t timers; // timer callbacks
/// uint64_t page_faults; // (deprecated, returns 0)
/// uint64_t exceptions; // (deprecated, returns 0)
/// uint64_t syscalls;
///
/// // inter-processor interrupts
/// uint64_t reschedule_ipis;
/// uint64_t generic_ipis;
/// } zx_info_cpu_stats_t;
/// ```
///
/// ### ZX_INFO_VMAR
///
/// *handle* type: `VM Address Region`
///
/// *buffer* type: `zx_info_vmar_t[1]`
///
/// ```
/// typedef struct zx_info_vmar {
/// // Base address of the region.
/// uintptr_t base;
///
/// // Length of the region, in bytes.
/// size_t len;
/// } zx_info_vmar_t;
/// ```
///
/// This returns a single `zx_info_vmar_t` that describes the range of address space
/// that the VMAR occupies.
///
/// ### ZX_INFO_VMO
///
/// *handle* type: `VM Object`
///
/// *buffer* type: `zx_info_vmo_t[1]`
///
/// ```
/// typedef struct zx_info_vmo {
/// // The koid of this VMO.
/// zx_koid_t koid;
///
/// // The name of this VMO.
/// char name[ZX_MAX_NAME_LEN];
///
/// // The size of this VMO; i.e., the amount of virtual address space it
/// // would consume if mapped.
/// uint64_t size_bytes;
///
/// // If this VMO is a child , the koid of its parent. Otherwise, zero.
/// // See |flags| for the type of child.
/// zx_koid_t parent_koid;
///
/// // The number of children of this VMO, if any.
/// size_t num_children;
///
/// // The number of times this VMO is currently mapped into VMARs.
/// // Note that the same process will often map the same VMO twice,
/// // and both mappings will be counted here. (I.e., this is not a count
/// // of the number of processes that map this VMO; see share_count.)
/// size_t num_mappings;
///
/// // An estimate of the number of unique address spaces that
/// // this VMO is mapped into. Every process has its own address space,
/// // and so does the kernel.
/// size_t share_count;
///
/// // Bitwise OR of ZX_INFO_VMO_* values.
/// uint32_t flags;
///
/// // If |ZX_INFO_VMO_TYPE(flags) == ZX_INFO_VMO_TYPE_PAGED|, the amount of
/// // memory currently allocated to this VMO; i.e., the amount of physical
/// // memory it consumes. Undefined otherwise.
/// uint64_t committed_bytes;
///
/// // If |flags & ZX_INFO_VMO_VIA_HANDLE|, the handle rights.
/// //
/// // If |flags & ZX_INFO_VMO_VIA_IOB_HANDLE|, the effective combined
/// // handle rights for the IOB region and containing IOB.
/// //
/// // Undefined otherwise.
/// zx_rights_t handle_rights;
///
/// // VMO mapping cache policy. One of ZX_CACHE_POLICY_*
/// uint32_t cache_policy;
///
/// // Amount of kernel memory, in bytes, allocated to track metadata
/// // associated with this VMO.
/// uint64_t metadata_bytes;
///
/// // Running counter of the number of times the kernel, without user request,
/// // performed actions on this VMO that would have caused |committed_bytes| to
/// // report a different value.
/// uint64_t committed_change_events;
///
/// // If |ZX_INFO_VMO_TYPE(flags) == ZX_INFO_VMO_TYPE_PAGED|, the amount of
/// // content that has been populated and is being tracked by this vmo. This
/// // can be greater than |committed_bytes| where content might be compressed
/// // or otherwise tracked in a way that does not correlate directly to being
/// // committed.
/// uint64_t populated_bytes;
/// } zx_info_vmo_t;
/// ```
///
/// This returns a single `zx_info_vmo_t` that describes various attributes of the
/// VMO.
///
/// ### ZX_INFO_SOCKET
///
/// *handle* type: `Socket`
///
/// *buffer* type: `zx_info_socket_t[1]`
///
/// ```
/// typedef struct zx_info_socket {
/// // The options passed to zx_socket_create().
/// uint32_t options;
///
/// // The maximum size of the receive buffer of a socket, in bytes.
/// //
/// // The receive buffer may become full at a capacity less than the maximum
/// // due to overhead.
/// size_t rx_buf_max;
///
/// // The size of the receive buffer of a socket, in bytes.
/// size_t rx_buf_size;
///
/// // The amount of data, in bytes, that is available for reading in a single
/// // zx_socket_read call.
/// //
/// // For stream sockets, this value will match |rx_buf_size|. For datagram
/// // sockets, this value will be the size of the next datagram in the receive
/// // buffer.
/// size_t rx_buf_available;
///
/// // The maximum size of the transmit buffer of a socket, in bytes.
/// //
/// // The transmit buffer may become full at a capacity less than the maximum
/// // due to overhead.
/// //
/// // Will be zero if the peer endpoint is closed.
/// size_t tx_buf_max;
///
/// // The size of the transmit buffer of a socket, in bytes.
/// //
/// // Will be zero if the peer endpoint is closed.
/// size_t tx_buf_size;
/// } zx_info_socket_t;
/// ```
///
/// ### ZX_INFO_TIMER
///
/// *handle* type: `Timer`
///
/// *buffer* type: `zx_info_timer_t[1]`
///
/// ```
/// typedef struct zx_info_timer {
/// // The options passed to zx_timer_create().
/// uint32_t options;
///
/// // The deadline with respect to ZX_CLOCK_MONOTONIC at which the timer will
/// // fire next.
/// //
/// // This value will be zero if the timer is not set to fire.
/// zx_time_t deadline;
///
/// // Specifies a range from deadline - slack to deadline + slack during which
/// // the timer is allowed to fire. The system uses this parameter as a hint to
/// // coalesce nearby timers.
/// //
/// // The precise coalescing behavior is controlled by the options parameter
/// // specified when the timer was created.
/// //
/// // This value will be zero if the timer is not set to fire.
/// zx_duration_t slack;
/// } zx_info_timer_t;
/// ```
///
/// ### ZX_INFO_JOB_CHILDREN
///
/// *handle* type: `Job`
///
/// *buffer* type: `zx_koid_t[n]`
///
/// Returns an array of `zx_koid_t`, one for each direct child Job of the provided
/// Job handle.
///
/// ### ZX_INFO_JOB_PROCESSES
///
/// *handle* type: `Job`
///
/// *buffer* type: `zx_koid_t[n]`
///
/// Returns an array of `zx_koid_t`, one for each direct child Process of the
/// provided Job handle.
///
/// ### ZX_INFO_TASK_STATS
///
/// *handle* type: `Process`
///
/// *buffer* type: `zx_info_task_stats_t[1]`
///
/// Returns statistics about resources (e.g., memory) used by a task.
///
/// ```
/// typedef struct zx_info_task_stats {
/// // The total size of mapped memory ranges in the task.
/// // Not all will be backed by physical memory.
/// size_t mem_mapped_bytes;
///
/// // For the fields below, a byte is considered committed if it's backed by
/// // physical memory. Some of the memory may be double-mapped, and thus
/// // double-counted.
///
/// // Committed memory that is only mapped into this task.
/// size_t mem_private_bytes;
///
/// // Committed memory that is mapped into this and at least one other task.
/// size_t mem_shared_bytes;
///
/// // A number that estimates the fraction of mem_shared_bytes that this
/// // task is responsible for keeping alive.
/// //
/// // An estimate of:
/// // For each shared, committed byte:
/// // mem_scaled_shared_bytes += 1 / (number of tasks mapping this byte)
/// //
/// // This number is strictly smaller than mem_shared_bytes.
/// size_t mem_scaled_shared_bytes;
/// } zx_info_task_stats_t;
/// ```
///
/// Additional errors:
///
/// * `ZX_ERR_BAD_STATE`: If the target process has terminated
///
/// ### ZX_INFO_TASK_RUNTIME
///
/// *handle* type: `Job`, `Process`, or `Thread`
///
/// *buffer* type: `zx_info_task_runtime_t[1]`
///
/// Returns statistics about the runtime of a task.
///
/// ```
/// // Info on the runtime of a task.
/// typedef struct zx_info_task_runtime {
/// // The total amount of time this task and its children were
/// // running on a CPU (not blocked).
/// // * Threads include only their own runtime.
/// // * Processes include the runtime for all of their threads (including threads that previously
/// // exited).
/// // * Jobs include the runtime for all of their processes (including processes that previously
/// // exited).
/// zx_duration_t cpu_time;
///
/// // The total amount of time this task and its children were queued
/// // to run (ready) but not actually using a CPU.
/// // * Threads include only their own queue time.
/// // * Processes include the queue time for all of their threads (including threads that
/// // previously exited).
/// // * Jobs include the queue time for all of their processes (including processes that previously
/// // exited).
/// zx_duration_t queue_time;
///
/// // The total amount of time this task and its children spent handling page faults.
/// // * Threads include only their own page fault handling time.
/// // * Processes include the page fault time for all of their threads (including threads that
/// // previously exited).
/// // * Jobs include the page fault time for all of their processes (including processes that
/// // previously exited).
/// zx_duration_t page_fault_time;
///
/// // The total amount of time this task and its children spent waiting on contended kernel locks.
/// // * Threads include only their own wait time.
/// // * Processes include the wait time for all of their threads (including threads that
/// // previously exited).
/// // * Jobs include the wait time for all of their processes (including processes that
/// // previously exited).
/// zx_duration_t lock_contention_time;
/// } zx_info_task_runtime_t;
/// ```
///
/// The run time of a task does not include the time spent suspended or blocked
/// waiting on events or I/O. These stats may be used to:
///
/// 1. Estimate how much CPU time a task has used.
/// 2. Estimate how much latency a task is experiencing due to other tasks (queue
/// time), page fault handlers, and kernel lock contention.
///
/// ### ZX_INFO_PROCESS_MAPS
///
/// *handle* type: `Process`, with `ZX_RIGHT_READ`
///
/// *buffer* type: `zx_info_maps_t[n]`
///
/// The `zx_info_maps_t` array is a depth-first pre-order walk of the target
/// process's Aspace/VMAR/Mapping tree. As per the pre-order traversal base
/// addresses will be in ascending order.
///
/// ```
/// typedef struct zx_info_maps {
/// // Name if available; empty string otherwise.
/// char name[ZX_MAX_NAME_LEN];
/// // Base address.
/// zx_vaddr_t base;
/// // Size in bytes.
/// size_t size;
///
/// // The depth of this node in the tree.
/// // Can be used for indentation, or to rebuild the tree from an array
/// // of zx_info_maps_t entries, which will be in depth-first pre-order.
/// size_t depth;
/// // The type of this entry; indicates which union entry is valid.
/// uint32_t type; // zx_info_maps_type_t
/// union {
/// zx_info_maps_mapping_t mapping;
/// // No additional fields for other types.
/// } u;
/// } zx_info_maps_t;
///
/// typedef struct zx_info_maps_mapping {
/// // MMU flags for the mapping.
/// // Bitwise OR of ZX_VM_PERM_{READ,WRITE,EXECUTE} values.
/// zx_vm_option_t mmu_flags;
/// uint8_t padding1[4];
/// // koid of the mapped VMO or IOB region.
/// zx_koid_t vmo_koid;
/// // Offset into the above VMO or IOB region.
/// uint64_t vmo_offset;
/// // The number of PAGE_SIZE pages in the mapped region of the VMO or
/// // IOB region that are backed by physical memory.
/// size_t committed_pages;
/// // The number of PAGE_SIZE pages of content that have been populated and are
/// // being tracked in the mapped region of the VMO or IOB region. This can be
/// // greater than |committed_pages| where pages might be compressed or otherwise
/// // tracked in a way that does not correlate directly to being committed.
/// size_t populated_pages;
/// } zx_info_maps_mapping_t;
/// ```
///
/// The *depth* field of each entry describes its relationship to the nodes that
/// come before it. Depth 0 is the root Aspace, depth 1 is the root VMAR, and all
/// other entries have depth 2 or greater.
///
/// To get a full picture of how a process uses its VMOs and how a VMO is used by
/// various processes, you may need to combine this information with
/// ZX_INFO_PROCESS_VMOS.
///
/// See the `vmaps` command-line tool for an example user of this topic, and to dump
/// the maps of arbitrary processes by koid.
///
/// Additional errors:
///
/// * `ZX_ERR_ACCESS_DENIED`: If the appropriate rights are missing.
/// * `ZX_ERR_BAD_STATE`: If the target process has terminated, or if its
/// address space has been destroyed
///
/// ### ZX_INFO_PROCESS_VMOS
///
/// *handle* type: `Process`, with `ZX_RIGHT_READ`
///
/// *buffer* type: `zx_info_vmo_t[n]`
///
/// The `zx_info_vmo_t` array is list of all VMOs pointed to by the target
/// process. Some VMOs are mapped, some are pointed to by VMO or IOB
/// handles, and some are a combination of these. The `flags`
/// field of the returned struct will indicate one of
/// ZX_INFO_VMO_VIA_HANDLE, ZX_INFO_VMO_VIA_IOB_HANDLE, or
/// ZX_INFO_VMO_VIA_MAPPING to allow differentiation.
///
/// Note: The same VMO may appear multiple times due to multiple mappings or
/// handles, or because a handle to the VMO has been removed and then readded
/// concurrently with this call. VMOs can change as the target process runs, which
/// may result in the same VMO having different values each time it appears. The
/// caller must resolve any duplicate values.
///
/// To get a full picture of how a process uses its VMOs and how a VMO is used by
/// various processes, you may need to combine this information with
/// ZX_INFO_PROCESS_MAPS.
///
/// ```
/// // Describes a VMO.
/// typedef struct zx_info_vmo {
/// // The koid of this VMO.
/// zx_koid_t koid;
///
/// // The name of this VMO.
/// char name[ZX_MAX_NAME_LEN];
///
/// // The size of this VMO; i.e., the amount of virtual address space it
/// // would consume if mapped.
/// uint64_t size_bytes;
///
/// // If this VMO is a child , the koid of its parent. Otherwise, zero.
/// // See |flags| for the type of child.
/// zx_koid_t parent_koid;
///
/// // The number of children of this VMO, if any.
/// size_t num_children;
///
/// // The number of times this VMO is currently mapped into VMARs.
/// // Note that the same process will often map the same VMO twice,
/// // and both mappings will be counted here. (I.e., this is not a count
/// // of the number of processes that map this VMO; see share_count.)
/// size_t num_mappings;
///
/// // An estimate of the number of unique address spaces that
/// // this VMO is mapped into. Every process has its own address space,
/// // and so does the kernel.
/// size_t share_count;
///
/// // Bitwise OR of ZX_INFO_VMO_* values.
/// uint32_t flags;
///
/// // If |ZX_INFO_VMO_TYPE(flags) == ZX_INFO_VMO_TYPE_PAGED|, the amount of
/// // memory currently allocated to this VMO; i.e., the amount of physical
/// // memory it consumes. Undefined otherwise.
/// uint64_t committed_bytes;
///
/// // If |flags & ZX_INFO_VMO_VIA_HANDLE|, the handle rights.
/// //
/// // If |flags & ZX_INFO_VMO_VIA_IOB_HANDLE|, the effective combined
/// // handle rights for the IOB region and containing IOB.
/// //
/// // Undefined otherwise.
/// zx_rights_t handle_rights;
///
/// // VMO mapping cache policy. One of ZX_CACHE_POLICY_*
/// uint32_t cache_policy;
///
/// // Amount of kernel memory, in bytes, allocated to track metadata
/// // associated with this VMO.
/// uint64_t metadata_bytes;
///
/// // Running counter of the number of times the kernel, without user request,
/// // performed actions on this VMO that would have caused |committed_bytes| to
/// // report a different value.
/// uint64_t committed_change_events;
///
/// // If |ZX_INFO_VMO_TYPE(flags) == ZX_INFO_VMO_TYPE_PAGED|, the amount of
/// // content that has been populated and is being tracked by this vmo. This
/// // can be greater than |committed_bytes| where content might be compressed
/// // or otherwise tracked in a way that does not correlate directly to being
/// // committed.
/// uint64_t populated_bytes;
/// } zx_info_vmo_t;
/// ```
///
/// See the `vmos` command-line tool for an example user of this topic, and to dump
/// the VMOs of arbitrary processes by koid.
///
/// ### ZX_INFO_KMEM_STATS
///
/// *handle* type: `Resource` (Specifically, the info resource)
///
/// *buffer* type: `zx_info_kmem_stats_t[1]`
///
/// Returns information about kernel memory usage.
///
/// ```
/// typedef struct zx_info_kmem_stats {
/// // The total amount of physical memory available to the system.
/// // Note, the values below may not exactly add up to this total.
/// size_t total_bytes;
///
/// // The amount of unallocated memory.
/// size_t free_bytes;
///
/// // The amount of memory reserved by and mapped into the kernel for reasons
/// // not covered by other fields in this struct. Typically for readonly data
/// // like the ram disk and kernel image, and for early-boot dynamic memory.
/// size_t wired_bytes;
///
/// // The amount of memory allocated to the kernel heap.
/// size_t total_heap_bytes;
///
/// // The portion of |total_heap_bytes| that is not in use.
/// size_t free_heap_bytes;
///
/// // The amount of memory committed to VMOs, both kernel and user.
/// // A superset of all userspace memory.
/// // Does not include certain VMOs that fall under |wired_bytes|.
/// size_t vmo_bytes;
///
/// // The amount of memory used for architecture-specific MMU metadata
/// // like page tables.
/// size_t mmu_overhead_bytes;
///
/// // Non-free memory that isn't accounted for in any other field.
/// size_t other_bytes;
/// } zx_info_kmem_stats_t;
/// ```
///
/// ### ZX_INFO_KMEM_STATS_EXTENDED
///
/// *handle* type: `Resource` (Specifically, the info resource)
///
/// *buffer* type: `zx_info_kmem_stats_extended_t[1]`
///
/// Returns information about kernel memory usage - includes information returned by
/// the ZX_INFO_KMEM_STATS topic, plus some additional information that is more
/// expensive to collect.
///
/// ```
/// typedef struct zx_info_kmem_stats_extended {
/// // The total amount of physical memory available to the system.
/// uint64_t total_bytes;
///
/// // The amount of unallocated memory.
/// uint64_t free_bytes;
///
/// // The amount of memory reserved by and mapped into the kernel for reasons
/// // not covered by other fields in this struct. Typically for readonly data
/// // like the ram disk and kernel image, and for early-boot dynamic memory.
/// uint64_t wired_bytes;
///
/// // The amount of memory allocated to the kernel heap.
/// uint64_t total_heap_bytes;
///
/// // The portion of |total_heap_bytes| that is not in use.
/// uint64_t free_heap_bytes;
///
/// // The amount of memory committed to VMOs, both kernel and user.
/// // A superset of all userspace memory.
/// // Does not include certain VMOs that fall under |wired_bytes|.
/// uint64_t vmo_bytes;
///
/// // The amount of memory committed to pager-backed VMOs.
/// uint64_t vmo_pager_total_bytes;
///
/// // The amount of memory committed to pager-backed VMOs, that has been most
/// // recently accessed, and would not be eligible for eviction by the kernel
/// // under memory pressure.
/// uint64_t vmo_pager_newest_bytes;
///
/// // The amount of memory committed to pager-backed VMOs, that has been least
/// // recently accessed, and would be the first to be evicted by the kernel
/// // under memory pressure.
/// uint64_t vmo_pager_oldest_bytes;
///
/// // The amount of memory committed to discardable VMOs that is currently
/// // locked, or unreclaimable by the kernel under memory pressure.
/// uint64_t vmo_discardable_locked_bytes;
///
/// // The amount of memory committed to discardable VMOs that is currently
/// // unlocked, or reclaimable by the kernel under memory pressure.
/// uint64_t vmo_discardable_unlocked_bytes;
///
/// // The amount of memory used for architecture-specific MMU metadata
/// // like page tables.
/// uint64_t mmu_overhead_bytes;
///
/// // The amount of memory in use by IPC.
/// uint64_t ipc_bytes;
///
/// // Non-free memory that isn't accounted for in any other field.
/// uint64_t other_bytes;
///
/// // The amount of memory in VMOs that would otherwise be tracked for
/// // reclamation, but has had reclamation disabled.
/// uint64_t vmo_reclaim_disabled_bytes;
/// } zx_info_kmem_stats_extended_t;
/// ```
///
/// ### ZX_INFO_KMEM_STATS_COMPRESSION
///
/// *handle* type: `Resource` (Specifically, the info resource)
///
/// *buffer* type: `zx_info_kmem_stats_compression_t[1]`
///
/// Returns information about kernel memory usage as it pertains to the compressed
/// memory subsystem.
///
/// ```
/// typedef struct zx_info_kmem_stats_compression {
/// // Size in bytes of the content that is currently being compressed and stored.
/// uint64_t uncompressed_storage_bytes;
///
/// // Size in bytes of all memory, including metadata, fragmentation and other
/// // overheads, of the compressed memory area. Note that due to base book
/// // keeping overhead this could be non-zero, even when
/// // |uncompressed_content_bytes| is zero.
/// uint64_t compressed_storage_bytes;
///
/// // Size in bytes of any fragmentation in the compressed memory area.
/// uint64_t compressed_fragmentation_bytes;
///
/// // Total amount of CPU time spent on compression across all threads.
/// // Compression may happen in parallel and so this can be larger than
/// // wall clock time.
/// zx_duration_t compression_time;
///
/// // Total amount of time decompression has spent on a CPU across all threads.
/// // Decompression may happen in parallel and so this can increase faster than
/// // wall clock time.
/// zx_duration_t decompression_time;
///
/// // Total number of times compression has been done on a page, regardless of
/// // whether the compressed result was ultimately retained.
/// uint64_t total_page_compression_attempts;
///
/// // How many of the total compression attempts were considered failed and
/// // were not stored. An example reason for failure would be a page not being
/// // compressed sufficiently to be considered worth storing.
/// uint64_t failed_page_compression_attempts;
///
/// // Number of times pages have been decompressed.
/// uint64_t total_page_decompressions;
///
/// // Number of times a page was removed from storage without needing to be
/// // decompressed. An example that would cause this is a VMO being destroyed.
/// uint64_t compressed_page_evictions;
///
/// // How many pages compressed due to the page being inactive, but without
/// // there being memory pressure.
/// uint64_t eager_page_compressions;
///
/// // How many pages compressed due to general memory pressure. This excludes pages
/// // compressed due to critical memory pressure.
/// uint64_t memory_pressure_page_compressions;
///
/// // How many pages compressed due to attempting to avoid OOM or near OOM
/// // scenarios.
/// uint64_t critical_memory_page_compressions;
///
/// // The nanoseconds in the base unit of time for
/// // |pages_decompressed_within_log_time|.
/// uint64_t pages_decompressed_unit_ns;
///
/// // How long pages spent compressed before being decompressed, grouped in log
/// // buckets. Pages that got evicted, and hence were not decompressed, are not
/// // counted here. Buckets are in |pages_decompressed_unit_ns| and round up
/// // such that:
/// // 0: Pages decompressed in <1 unit
/// // 1: Pages decompressed between 1 and 2 units
/// // 2: Pages decompressed between 2 and 4 units
/// // ...
/// // 7: Pages decompressed between 64 and 128 units
/// // How many pages are held compressed for longer than 128 units can be
/// // inferred by subtracting from |total_page_decompressions|.
/// uint64_t pages_decompressed_within_log_time[8];
/// } zx_info_kmem_stats_compression_t;
/// ```
///
/// ### ZX_INFO_RESOURCE
///
/// *handle* type: `Resource`
///
/// *buffer* type: `zx_info_resource_t[1]`
///
/// Returns information about a resource object via its handle.
///
/// ```
/// typedef struct zx_info_resource {
/// // The resource kind; resource object kinds are described in resource.md
/// uint32_t kind;
/// // Resource's creation flags
/// uint32_t flags;
/// // Resource's base value (inclusive)
/// uint64_t base;
/// // Resource's length value
/// size_t size;
/// char name[ZX_MAX_NAME_LEN];
/// } zx_info_resource_t;
/// ```
///
/// The resource kind is one of
///
/// * `ZX_RSRC_KIND_ROOT`
/// * `ZX_RSRC_KIND_MMIO`
/// * `ZX_RSRC_KIND_IOPORT`
/// * `ZX_RSRC_KIND_IRQ`
/// * `ZX_RSRC_KIND_SMC`
/// * `ZX_RSRC_KIND_SYSTEM`
///
/// ### ZX_INFO_BTI
///
/// *handle* type: `Bus Transaction Initiator`
///
/// *buffer* type: `zx_info_bti_t[1]`
///
/// ```
/// typedef struct zx_info_bti {
/// // zx_bti_pin will always be able to return addresses that are contiguous for at
/// // least this many bytes. E.g. if this returns 1MB, then a call to
/// // zx_bti_pin() with a size of 2MB will return at most two physically-contiguous runs.
/// // If the size were 2.5MB, it will return at most three physically-contiguous runs.
/// uint64_t minimum_contiguity;
///
/// // The number of bytes in the device's address space (UINT64_MAX if 2^64).
/// uint64_t aspace_size;
///
/// // The count of the pinned memory object tokens. Requesting this count is
/// // racy, so this should only be used for informative reasons.
/// uint64_t pmo_count;
///
/// // The count of the quarantined pinned memory object tokens. Requesting this count is
/// // racy, so this should only be used for informative reasons.
/// uint64_t quarantine_count;
/// } zx_info_bti_t;
/// ```
///
/// ### Topic ZX_INFO_IOB
///
/// *handle* type: `IOBuffer`
///
/// *buffer* type: `zx_info_iob_t[1]`
///
/// Returns information about the overall IOB instance.
///
/// ```
/// typedef struct zx_info_iob {
/// // The value of the *options* parameter passed to `zx_iob_create`.
/// uint64_t options;
/// // The number of regions in the IOB.
/// uint32_t region_count;
/// // Reserved for future extensions.
/// uint8_t padding[4];
/// } zx_info_iob_t;
/// ```
///
/// ### Topic ZX_INFO_IOB_REGIONS
///
/// Returns information about each region of an IOB as an array of `zx_iob_region_info_t`
///
/// *handle* type: `IOBuffer`
///
/// *buffer* type: `zx_iob_region_info_t[n]`
///
/// struct zx_iob_region_info_t {
/// // The region description, with potentially swapped access bits.
/// zx_iob_region_t region;
/// /// The koid of the underlying memory object.
/// zx_koid_t koid;
/// };
///
/// Access modifier bits are swapped, such that the Ep0 access bits reflect
/// the access of the endpoint making the query and the Ep1 bits reflect the
/// access of the other endpoint, making it possible to determine the access
/// of the local and remote handles without knowing which handles were Ep0
/// and Ep1 when created.
///
/// ## Rights
///
/// If *topic* is `ZX_INFO_PROCESS`, *handle* must be of type `ZX_OBJ_TYPE_PROCESS` and have `ZX_RIGHT_INSPECT`.
///
/// If *topic* is `ZX_INFO_JOB`, *handle* must be of type `ZX_OBJ_TYPE_JOB` and have `ZX_RIGHT_INSPECT`.
///
/// If *topic* is `ZX_INFO_PROCESS_THREADS`, *handle* must be of type `ZX_OBJ_TYPE_PROCESS` and have `ZX_RIGHT_ENUMERATE`.
///
/// If *topic* is `ZX_INFO_JOB_CHILDREN`, *handle* must be of type `ZX_OBJ_TYPE_JOB` and have `ZX_RIGHT_ENUMERATE`.
///
/// If *topic* is `ZX_INFO_JOB_PROCESSES`, *handle* must be of type `ZX_OBJ_TYPE_JOB` and have `ZX_RIGHT_ENUMERATE`.
///
/// If *topic* is `ZX_INFO_THREAD`, *handle* must be of type `ZX_OBJ_TYPE_THREAD` and have `ZX_RIGHT_INSPECT`.
///
/// If *topic* is `ZX_INFO_THREAD_EXCEPTION_REPORT`, *handle* must be of type `ZX_OBJ_TYPE_THREAD` and have `ZX_RIGHT_INSPECT`.
///
/// If *topic* is `ZX_INFO_THREAD_STATS`, *handle* must be of type `ZX_OBJ_TYPE_THREAD` and have `ZX_RIGHT_INSPECT`.
///
/// If *topic* is `ZX_INFO_TASK_STATS`, *handle* must be of type `ZX_OBJ_TYPE_PROCESS` and have `ZX_RIGHT_INSPECT`.
///
/// If *topic* is `ZX_INFO_PROCESS_MAPS`, *handle* must be of type `ZX_OBJ_TYPE_PROCESS` and have `ZX_RIGHT_INSPECT`.
///
/// If *topic* is `ZX_INFO_PROCESS_VMOS`, *handle* must be of type `ZX_OBJ_TYPE_PROCESS` and have `ZX_RIGHT_INSPECT`.
///
/// If *topic* is `ZX_INFO_VMO`, *handle* must be of type `ZX_OBJ_TYPE_VMO`.
///
/// If *topic* is `ZX_INFO_VMAR`, *handle* must be of type `ZX_OBJ_TYPE_VMAR` and have `ZX_RIGHT_INSPECT`.
///
/// If *topic* is `ZX_INFO_GUEST_STATS`, *handle* must have resource kind `ZX_RSRC_KIND_SYSTEM` with base `ZX_RSRC_SYSTEM_INFO_BASE`.
///
/// If *topic* is `ZX_INFO_CPU_STATS`, *handle* must have resource kind `ZX_RSRC_KIND_SYSTEM` with base `ZX_RSRC_SYSTEM_INFO_BASE`.
///
/// If *topic* is `ZX_INFO_KMEM_STATS`, *handle* must have resource kind `ZX_RSRC_KIND_SYSTEM` with base `ZX_RSRC_SYSTEM_INFO_BASE`.
///
/// If *topic* is `ZX_INFO_KMEM_STATS_EXTENDED`, *handle* must have resource kind `ZX_RSRC_KIND_SYSTEM` with base `ZX_RSRC_SYSTEM_INFO_BASE`.
///
/// If *topic* is `ZX_INFO_RESOURCE`, *handle* must be of type `ZX_OBJ_TYPE_RESOURCE` and have `ZX_RIGHT_INSPECT`.
///
/// If *topic* is `ZX_INFO_HANDLE_COUNT`, *handle* must have `ZX_RIGHT_INSPECT`.
///
/// If *topic* is `ZX_INFO_BTI`, *handle* must be of type `ZX_OBJ_TYPE_BTI` and have `ZX_RIGHT_INSPECT`.
///
/// If *topic* is `ZX_INFO_PROCESS_HANDLE_STATS`, *handle* must be of type `ZX_OBJ_TYPE_PROCESS` and have `ZX_RIGHT_INSPECT`.
///
/// If *topic* is `ZX_INFO_SOCKET`, *handle* must be of type `ZX_OBJ_TYPE_SOCKET` and have `ZX_RIGHT_INSPECT`.
///
/// If *topic* is `ZX_INFO_MSI`, *handle* must be of type `ZX_OBJ_TYPE_MSI` and have `ZX_RIGHT_INSPECT`.
///
/// If *topic* is `ZX_INFO_TASK_RUNTIME`, *handle* must be of type `ZX_OBJ_TYPE_THREAD`, `ZX_OBJ_TYPE_PROCESS`, or `ZX_OBJ_TYPE_JOB`, and have `ZX_RIGHT_INSPECT`.
///
/// ## Return value
///
/// `zx_object_get_info()` returns `ZX_OK` on success. In the event of failure, a
/// negative error value is returned.
///
/// ## Errors
///
/// `ZX_ERR_BAD_HANDLE` *handle* is not a valid handle.
///
/// `ZX_ERR_WRONG_TYPE` *handle* is not an appropriate type for *topic*
///
/// `ZX_ERR_ACCESS_DENIED`: If *handle* does not have the necessary rights for the
/// operation.
///
/// `ZX_ERR_INVALID_ARGS` *buffer*, *actual*, or *avail* are invalid pointers.
///
/// `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.
///
/// `ZX_ERR_BUFFER_TOO_SMALL` The *topic* returns a fixed number of records, but
/// the provided buffer is not large enough for these records.
///
/// `ZX_ERR_NOT_SUPPORTED` *topic* does not exist.
///
/// ## EXAMPLES
///
/// ```
/// bool is_handle_valid(zx_handle_t handle) {
/// return zx_object_get_info(
/// handle, ZX_INFO_HANDLE_VALID, NULL, 0, NULL, NULL) == ZX_OK;
/// }
///
/// zx_koid_t get_object_koid(zx_handle_t handle) {
/// zx_info_handle_basic_t info;
/// if (zx_object_get_info(handle, ZX_INFO_HANDLE_BASIC,
/// &info, sizeof(info), NULL, NULL) != ZX_OK) {
/// return 0;
/// }
/// return info.koid;
/// }
///
/// void examine_threads(zx_handle_t proc) {
/// zx_koid_t threads[128];
/// size_t count, avail;
///
/// if (zx_object_get_info(proc, ZX_INFO_PROCESS_THREADS, threads,
/// sizeof(threads), &count, &avail) != ZX_OK) {
/// // Error!
/// } else {
/// if (avail > count) {
/// // More threads than space in array;
/// // could call again with larger array.
/// }
/// for (size_t n = 0; n < count; n++) {
/// do_something(thread[n]);
/// }
/// }
/// }
/// ```
///
/// ## See also
///
/// - [`zx_handle_close()`]
/// - [`zx_handle_duplicate()`]
/// - [`zx_handle_replace()`]
/// - [`zx_object_get_child()`]
///
/// [`zx_channel_call()`]: channel_call.md
/// [`zx_futex_wait()`]: futex_wait.md
/// [`zx_handle_close()`]: handle_close.md
/// [`zx_handle_duplicate()`]: handle_duplicate.md
/// [`zx_handle_replace()`]: handle_replace.md
/// [`zx_interrupt_wait()`]: interrupt_wait.md
/// [`zx_nanosleep()`]: nanosleep.md
/// [`zx_object_get_child()`]: object_get_child.md
/// [`zx_object_wait_many()`]: object_wait_many.md
/// [`zx_object_wait_one()`]: object_wait_one.md
/// [`zx_port_wait()`]: port_wait.md
/// [`zx_task_suspend()`]: task_suspend.md
strict GetInfo(resource struct {
handle Handle;
topic uint32;
}) -> (struct {
@voidptr
buffer vector<byte>:MAX;
actual usize64;
avail usize64;
}) error Status;
/// ## Summary
///
/// Given a kernel object with children objects, obtain a handle to the child specified by the provided kernel object id.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_object_get_child(zx_handle_t handle,
/// uint64_t koid,
/// zx_rights_t rights,
/// zx_handle_t* out);
/// ```
///
/// ## Description
///
/// `zx_object_get_child()` attempts to find a child of the object referred to
/// by *handle* which has the kernel object id specified by *koid*. If such an
/// object exists, and the requested *rights* are not greater than those provided
/// by the *handle* to the parent, a new handle to the specified child object is
/// returned.
///
/// *rights* may be `ZX_RIGHT_SAME_RIGHTS` which will result in rights equivalent
/// to the those on the *handle*.
///
/// If the object is a *Process*, the *Threads* it contains may be obtained by
/// this call.
///
/// If the object is a *Job*, its (immediate) child *Jobs* and the *Processes*
/// it contains may be obtained by this call.
///
/// ## Rights
///
/// *handle* must have `ZX_RIGHT_ENUMERATE`.
///
/// ## Return value
///
/// On success, `ZX_OK` is returned and a handle to the desired child object is returned via *out*.
///
/// ## Errors
///
/// `ZX_ERR_BAD_HANDLE` *handle* is not a valid handle.
///
/// `ZX_ERR_WRONG_TYPE` *handle* is not a *Process*, *Job*, or *Resource*.
///
/// `ZX_ERR_ACCESS_DENIED` *handle* lacks the right `ZX_RIGHT_ENUMERATE` or *rights* specifies
/// rights that are not present on *handle*.
///
/// `ZX_ERR_NOT_FOUND` *handle* does not have a child with the kernel object id *koid*.
///
/// `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.
///
/// `ZX_ERR_INVALID_ARGS` *out* is an invalid pointer.
///
/// ## See also
///
/// - [`zx_handle_close()`]
/// - [`zx_handle_duplicate()`]
/// - [`zx_handle_replace()`]
/// - [`zx_object_get_info()`]
///
/// [`zx_handle_close()`]: handle_close.md
/// [`zx_handle_duplicate()`]: handle_duplicate.md
/// [`zx_handle_replace()`]: handle_replace.md
/// [`zx_object_get_info()`]: object_get_info.md
strict GetChild(resource struct {
handle Handle;
koid uint64;
rights Rights;
}) -> (resource struct {
out Handle;
}) error Status;
/// ## Summary
///
/// Apply a scheduling profile to a thread.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_object_set_profile(zx_handle_t handle,
/// zx_handle_t profile,
/// uint32_t options);
/// ```
///
/// ## Description
///
/// `zx_object_set_profile()` applies a [profile] to the object specified by *target*.
///
/// The parameter *profile* is a handle to a [profile] object created with [`zx_profile_create()`].
///
/// *options* is currently ignored, and should be set to `0` by callers.
///
/// Currently, the the only two supported *target* object types are [thread] and [vmar]. Other
/// object types may be supported in the future.
///
/// [profile]: /docs/reference/kernel_objects/profile.md
/// [thread]: /docs/reference/kernel_objects/thread.md
/// [vmar]: /docs/reference/kernel_objects/vm_address_region.md
///
/// ## Rights
///
/// *handle* must be of type `ZX_OBJ_TYPE_THREAD` and have `ZX_RIGHT_MANAGE_THREAD`.
///
/// *profile* must be of type `ZX_OBJ_TYPE_PROFILE` and have `ZX_RIGHT_APPLY_PROFILE`.
///
/// ## Return value
///
/// Returns `ZX_OK` on success. In the event of failure, a negative error value is returned.
///
/// ## Errors
///
/// `ZX_ERR_BAD_HANDLE` *target* is not a valid handle.
///
/// `ZX_ERR_WRONG_TYPE` *target* is not a thread or vmar handle.
///
/// `ZX_ERR_ACCESS_DENIED` *target* does not have `ZX_RIGHT_MANAGE_THREAD` right.
///
/// `ZX_ERR_BAD_STATE` When *target* is a thread that is still being created, is dying, or dead, and
/// cannot have a *profile* applied to it, or *target* is a VMAR and *profile* contains an
/// invalid priority.
///
/// ## See also
///
/// - [`zx_profile_create()`]
///
/// [`zx_profile_create()`]: profile_create.md
strict SetProfile(resource struct {
handle Handle;
profile Handle:PROFILE;
options uint32;
}) -> () error Status;
};