// 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;
};