zircon/vdso/system.fidl

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

const MAX_POWER_LEVELS usize64 = 256;
const MAX_POWER_LEVEL_TRANSITIONS usize64 = 65536; // MAX_POWER_LEVELS^2

type CpuSet = struct {
    // Sadly we can't do math in FIDL with constants to compute the array size.
    mask array<uint64, 8>;
};

type ProcessorPowerLevelOptions = flexible bits : uint64 {};

type ProcessorPowerControl = flexible enum : uint64 {};

type ProcessorPowerLevel = struct {
    options ProcessorPowerLevelOptions;
    processing_rate uint64;
    power_coefficient_nw uint64;
    control_interface ProcessorPowerControl;
    control_argument uint64;
    diagnostic_name string_array<MAX_NAME_LEN>;
    reserved array<uint8, 32>;
};

type ProcessorPowerLevelTransition = struct {
    latency Duration;
    energy_nj uint64;
    from uint8;
    to uint8;
    reserved array<uint8, 6>;
};

type SystemPowerctlArg = struct {
        // TODO(scottmg): More unnamed unions.
        //union {
        //  struct {
        //    uint8_t target_s_state; // Value between 1 and 5 indicating which S-state
        //    uint8_t sleep_type_a;   // Value from ACPI VM (SLP_TYPa)
        //    uint8_t sleep_type_b;   // Value from ACPI VM (SLP_TYPb)
        //  } acpi_transition_s_state;
        //  struct {
        //    uint32_t power_limit; // PL1 value in milliwatts
        //    uint32_t time_window; // PL1 time window in microseconds
        //    uint8_t clamp;        // PL1 clamping enable
        //    uint8_t enable;       // PL1 enable
        //  } x86_power_limit;
        //};
        };

type StringView = struct {
    c_str experimental_pointer<uchar>;
    length usize64;
};

@transport("Syscall")
closed protocol System {
    /// ## Summary
    ///
    /// TODO(https://fxbug.dev/42108078)
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// uint32_t zx_system_get_dcache_line_size(void);
    /// ```
    ///
    /// ## Description
    ///
    /// TODO(https://fxbug.dev/42108078)
    ///
    /// ## Rights
    ///
    /// TODO(https://fxbug.dev/42107318)
    ///
    /// ## Return value
    ///
    /// TODO(https://fxbug.dev/42108078)
    ///
    /// ## Errors
    ///
    /// TODO(https://fxbug.dev/42108078)
    ///
    /// ## See also
    ///
    /// TODO(https://fxbug.dev/42108078)
    @const
    @vdsocall
    strict GetDcacheLineSize() -> (@wrapped_return struct {
        size uint32;
    });

    /// ## Summary
    ///
    /// Get number of logical processors on the system.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// uint32_t zx_system_get_num_cpus(void);
    /// ```
    ///
    /// ## Description
    ///
    /// `zx_system_get_num_cpus()` returns the number of CPUs (logical processors)
    /// that exist on the system currently running.  This number cannot change
    /// during a run of the system, only at boot time.
    ///
    /// ## Rights
    ///
    /// TODO(https://fxbug.dev/42107318)
    ///
    /// ## Return value
    ///
    /// `zx_system_get_num_cpus()` returns the number of CPUs.
    ///
    /// ## Errors
    ///
    /// `zx_system_get_num_cpus()` cannot fail.
    ///
    /// ## Notes
    ///
    /// ## See also
    ///
    ///  - [`zx_system_get_physmem()`]
    ///
    /// [`zx_system_get_physmem()`]: system_get_physmem.md
    @const
    @vdsocall
    strict GetNumCpus() -> (@wrapped_return struct {
        count uint32;
    });

    /// ## Summary
    ///
    /// Get version string for system.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// zx_string_view_t zx_system_get_version_string(void);
    /// ```
    ///
    /// ## Description
    ///
    /// `zx_system_get_version_string()` returns a string identifying the version of
    /// the Zircon system currently running.
    ///
    /// The returned object is a simple pair of C string pointer and length.  The
    /// string is guaranteed to be NUL-terminated and to be valid UTF-8.  The length
    /// does not include the NUL terminator.  In C++ the return value can be coerced
    /// implicitly to `std::string_view`, `std::u8string_view`, or other types with
    /// equivalent two-argument constructor signatures.
    ///
    /// The string constant may be of any length.  It is in read-only memory provided
    /// by the [vDSO](../../concepts/kernel/vdso.md).  Thus it is always accessible at
    /// the same address for the life of the process and its contents never change.
    ///
    /// The first four characters identify the version scheme. An example of the string
    /// returned is "git-8a07d52603404521038d8866b297f99de36f9162".
    ///
    /// ## Rights
    ///
    /// TODO(https://fxbug.dev/42107318)
    ///
    /// ## Return value
    ///
    /// `zx_system_get_version_string()` returns a `zx_string_view_t` object.
    ///
    /// ## Errors
    ///
    /// `zx_system_get_version_string()` cannot fail.
    ///
    /// ## Notes
    ///
    /// ## See also
    ///
    @const
    @vdsocall
    strict GetVersionString() -> (StringView);

    /// ## Summary
    ///
    /// Get the page size for the system.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// uint32_t zx_system_get_page_size(void);
    /// ```
    ///
    /// ## Description
    ///
    /// `zx_system_get_page_size()` returns the base memory page size of the system in
    /// bytes. This number cannot change during a run of the system, only at boot time,
    /// and is guaranteed to be an exact power of 2.
    ///
    /// The page size represents the allocation and alignment granularity of VMOs in
    /// `zx_vmo_create()` and the smallest unit that can be mapped via `zx_vmar_map()`.
    ///
    /// For every architecture there are well defined minimum and maximum values,
    /// `ZX_MIN_PAGE_SIZE` and `ZX_MAX_PAGE_SIZE`, that this will return.
    ///
    /// | Architecture | `ZX_MIN_PAGE_SIZE` | `ZX_MAX_PAGE_SIZE` |
    /// | ------------ | ------------------ | ------------------ |
    /// | ARM          | 4KiB               | 64KiB              |
    /// | X86-64       | 4KiB               | 2MiB               |
    ///
    /// ## Rights
    ///
    /// TODO(https://fxbug.dev/42107318)
    ///
    /// ## Return value
    ///
    /// `zx_system_get_page_size()` returns the page size in bytes.
    ///
    /// ## Errors
    ///
    /// `zx_system_get_page_size()` cannot fail.
    ///
    /// ## Notes
    ///
    /// ## See also
    ///
    ///  - [`zx_vmar_map()`]
    ///  - [`zx_vmo_create()`]
    ///
    /// [`zx_vmar_map()`]: vmar_map.md
    /// [`zx_vmo_create()`]: vmo_create.md
    @const
    @vdsocall
    strict GetPageSize() -> (@wrapped_return struct {
        size uint32;
    });

    /// ## Summary
    ///
    /// Get amount of physical memory on the system.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// uint64_t zx_system_get_physmem(void);
    /// ```
    ///
    /// ## Description
    ///
    /// `zx_system_get_physmem()` returns the total size of physical memory on
    /// the machine, in bytes.
    ///
    /// ## Rights
    ///
    /// TODO(https://fxbug.dev/42107318)
    ///
    /// ## Return value
    ///
    /// `zx_system_get_physmem()` returns a number in bytes.
    ///
    /// ## Errors
    ///
    /// `zx_system_get_physmem()` cannot fail.
    ///
    /// ## Notes
    ///
    /// Currently the total size of physical memory cannot change during a run of
    /// the system, only at boot time.  This might change in the future.
    ///
    /// ## See also
    ///
    ///  - [`zx_system_get_num_cpus()`]
    ///
    /// [`zx_system_get_num_cpus()`]: system_get_num_cpus.md
    @vdsocall
    strict GetPhysmem() -> (@wrapped_return struct {
        physmem uint64;
    });

    // TODO(scottmg): "features" has a features attribute. I'm not sure if/how it's used.
    /// ## Summary
    ///
    /// Get supported hardware capabilities.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// zx_status_t zx_system_get_features(uint32_t kind, uint32_t* features);
    /// ```
    ///
    /// ## Description
    ///
    /// `zx_system_get_features()` populates *features* with a bit mask of
    /// hardware-specific features.  *kind* indicates the specific type of features
    /// to retrieve, e.g. `ZX_FEATURE_KIND_CPU`.  The supported kinds and the meaning
    /// of individual feature bits is hardware-dependent.  `ZX_FEATURE_KIND_VM` is not
    /// hardware-dependent and returns a bitset currently the only meaningful bit
    /// is `ZX_VM_FEATURE_CAN_MAP_XOM` which is 1 if the system can map pages with
    /// execute only permission.
    ///
    /// ## Rights
    ///
    /// TODO(https://fxbug.dev/42107318)
    ///
    /// ## Return value
    ///
    /// `zx_system_get_features()`  returns `ZX_OK` on success.
    ///
    /// ## Errors
    ///
    /// `ZX_ERR_NOT_SUPPORTED`  The requested feature kind is not available on this
    /// platform.
    ///
    /// ## Notes
    /// Refer to [Install Fuchsia on a device](/docs/development/hardware/README.md)
    /// for supported processor architectures.
    ///
    /// Refer to [zircon/features.h](/zircon/system/public/zircon/features.h) for kinds
    /// of features and individual feature bits.
    ///
    /// ## See also
    ///
    ///  - [`zx_system_get_num_cpus()`]
    ///  - [`zx_system_get_physmem()`]
    ///
    /// [`zx_system_get_num_cpus()`]: system_get_num_cpus.md
    /// [`zx_system_get_physmem()`]: system_get_physmem.md
    @vdsocall
    strict GetFeatures(struct {
        kind uint32;
    }) -> (struct {
        features uint32;
    }) error Status;

    /// ## Summary
    ///
    /// Retrieve a handle to a system event.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// zx_status_t zx_system_get_event(zx_handle_t root_job,
    ///                                 uint32_t kind,
    ///                                 zx_handle_t* event);
    /// ```
    ///
    /// ## Description
    ///
    /// *root_job* must be a handle to the root job of the system.
    ///
    /// *kind* must be one of the following:
    ///
    /// - `ZX_SYSTEM_EVENT_OUT_OF_MEMORY` - An *event* will be returned that will
    /// assert ZX_EVENT_SIGNALED when the system is in an out-of-memory situation.
    /// A process that is waiting on this event must quickly perform any important
    /// shutdown work. It is unspecified how much memory is available at the time this
    /// event is signaled, and unspecified how long the waiting process has to act
    /// before the kernel starts terminating processes or starting a full system reboot.
    ///
    /// - `ZX_SYSTEM_EVENT_IMMINENT_OUT_OF_MEMORY` - An *event* will be returned that
    /// will assert ZX_EVENT_SIGNALED when the system is nearing an out-of-memory
    /// situation. This event is signaled a little earlier than the
    /// ZX_SYSTEM_EVENT_OUT_OF_MEMORY event. The intent of this event is to allow the
    /// waiter to gather diagnostics related to the impending
    /// ZX_SYSTEM_EVENT_OUT_OF_MEMORY event, since it might be too late to do so
    /// reliably when ZX_SYSTEM_EVENT_OUT_OF_MEMORY is signaled.
    ///
    /// - `ZX_SYSTEM_EVENT_MEMORY_PRESSURE_CRITICAL` - An *event* will be returned
    /// that will assert ZX_EVENT_SIGNALED when available memory on the system is
    /// critically low. The memory pressure level in this case is less severe than in
    /// the case of ZX_SYSTEM_EVENT_OUT_OF_MEMORY. The exact amount of memory available
    /// at the time the event is signaled is unspecified.
    ///
    /// - `ZX_SYSTEM_EVENT_MEMORY_PRESSURE_WARNING` - An *event* will be returned
    /// that will assert ZX_EVENT_SIGNALED when available memory on the system is
    /// approaching the critically low range. The memory pressure level in this case is
    /// less severe than in the case of ZX_SYSTEM_EVENT_MEMORY_PRESSURE_CRITICAL. The
    /// exact amount of memory available at the time the event is signaled is
    /// unspecified.
    ///
    /// - `ZX_SYSTEM_EVENT_MEMORY_PRESSURE_NORMAL` - An *event* will be returned that
    /// will assert ZX_EVENT_SIGNALED when available memory on the system is
    /// healthy. The exact amount of memory available at the time the event is signaled
    /// is unspecified.
    ///
    /// The kernel will assert ZX_EVENT_SIGNALED on these five events in the following
    /// order of increasing severity: ZX_SYSTEM_EVENT_MEMORY_PRESSURE_NORMAL,
    /// ZX_SYSTEM_EVENT_MEMORY_PRESSURE_WARNING,
    /// ZX_SYSTEM_EVENT_MEMORY_PRESSURE_CRITICAL, ZX_SYSTEM_EVENT_IMMINENT_OUT_OF_MEMORY,
    /// and ZX_SYSTEM_EVENT_OUT_OF_MEMORY. Exactly one of these events will assert
    /// ZX_EVENT_SIGNALED at a given time.
    ///
    /// Both ZX_SYSTEM_EVENT_OUT_OF_MEMORY and ZX_SYSTEM_EVENT_MEMORY_PRESSURE_\*
    /// retrieve events corresponding to system memory pressure levels, but there is a
    /// key difference in the way these events are intended to be used. A process
    /// waiting on the any of the ZX_SYSTEM_EVENT_MEMORY_PRESSURE_\* events must
    /// undertake actions that free up memory and attempt to relieve the memory
    /// pressure on the system. On the other hand, a process waiting on the
    /// ZX_SYSTEM_EVENT_OUT_OF_MEMORY event must perform necessary actions in
    /// preparation for a clean shutdown - at this point it is too late to attempt
    /// recovery to a healthy memory pressure level.
    ///
    /// The ZX_SYSTEM_EVENT_IMMINENT_OUT_OF_MEMORY event can be seen as a companion event
    /// for ZX_SYSTEM_EVENT_OUT_OF_MEMORY, which does not trigger memory reclamation
    /// itself, but instead is used to capture memory diagnostics what will help debug
    /// the closely following ZX_SYSTEM_EVENT_OUT_OF_MEMORY event (if there is one).
    ///
    /// ## Rights
    ///
    /// None.
    ///
    /// ## Return value
    ///
    /// `zx_system_get_event()` returns ZX_OK on success, and *event* will be a valid
    /// handle, or an error code from below on failure.
    ///
    /// ## Errors
    ///
    /// `ZX_ERR_ACCESS_DENIED` The calling process' policy was invalid, the handle
    /// *root_job* did not have ZX_RIGHT_MANAGE_PROCESS rights for *kind*
    /// ZX_SYSTEM_EVENT_OUT_OF_MEMORY, *root_job* was not the
    /// root job of the system.
    ///
    /// `ZX_ERR_INVALID_ARGS` *kind* was not one of the supported values specified
    /// above.
    strict GetEvent(resource struct {
        root_job Handle:JOB;
        kind uint32;
    }) -> (resource struct {
        event Handle:EVENT;
    }) error Status;

    /// ## Summary
    ///
    /// Set CPU performance parameters.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// zx_status_t zx_system_set_performance_info(zx_handle_t resource,
    ///                                            uint32_t topic,
    ///                                            const void* info,
    ///                                            size_t count);
    /// ```
    ///
    /// ## Description
    ///
    /// `zx_system_set_performance_info()` sets CPU performance parameters maintained by the kernel. The
    /// *topic* parameter indicates what specific parameters are affected.
    ///
    /// *count* indicates the number of items to set. Topics may impose requirements on this value.
    ///
    /// *info* is a pointer to a buffer of sufficient size to accommodate *count* entries of the type
    /// specified by *topic*.
    ///
    /// [TOC]
    ///
    /// ## TOPICS
    ///
    /// ### ZX_CPU_PERF_SCALE
    ///
    /// *count*: Must be non-zero and less than or equal to the number of logical CPUs in the system.
    ///
    /// *info* type: `zx_cpu_performance_scale_t[count]`
    ///
    /// An array of `zx_cpu_performance_scale_t` with entries specifying the performance scales (scalar
    /// values representing relative operating points) of the respective logical CPUs in the system. Only
    /// the CPUs specified in the array are updated, other CPUs are not affected.
    ///
    /// Logical CPU numbers must be stored in increasing order in the array. The scale values are unsigned
    /// fixed point Q32.32 format. The scale values should indicate the relative performance of the CPUs,
    /// with 1.0 corresponding to the highest operating point of the fastest CPU in the system.
    ///
    /// See [RFC 0123](/docs/contribute/governance/rfcs/0123_cpu_performance_info.md)
    /// for further details on values and update protocols.
    ///
    /// ## Rights
    ///
    /// *resource* must have resource kind `ZX_RSRC_KIND_SYSTEM`.
    ///
    /// ## Return value
    ///
    /// `zx_system_set_performance_info()` returns `ZX_OK` on success. In the event of a failure, a
    /// negative error value is returned.
    ///
    /// ## Errors
    ///
    /// `ZX_ERR_BAD_HANDLE` *resource* is not a valid handle.
    ///
    /// `ZX_ERR_WRONG_TYPE` *resource* is not resource kind `ZX_RSRC_KIND_SYSTEM`.
    ///
    /// `ZX_ERR_OUT_OF_RANGE` *resource* is not in the range [`ZX_RSRC_SYSTEM_CPU_BASE`, `ZX_RSRC_SYSTEM_CPU_BASE`+1).
    ///
    /// `ZX_ERR_INVALID_ARGS` *topic* or *info* have invalid values or *info* has out-of-order entries.
    ///
    /// `ZX_ERR_OUT_OF_RANGE` *count* or *info* entry values do not meet the requirements of the topic.
    ///
    /// `ZX_ERR_NO_MEMORY` Failure due to lack of memory. There is no good way for userspace to handle this (unlikely) error. In a future build this error will no longer occur.
    ///
    /// ## See also
    ///
    /// - [RFC 0123: CPU performance info syscalls](/docs/contribute/governance/rfcs/0123_cpu_performance_info.md)
    ///
    ///  - [`zx_system_get_performance_info()`]
    ///
    /// [`zx_system_get_performance_info()`]: system_get_performance_info.md
    strict SetPerformanceInfo(resource struct {
        resource Handle:RESOURCE;
        topic uint32;
        // TODO(joshuaseaton): vector<byte>
        @voidptr
        info experimental_pointer<byte>;
        count usize64;
    }) -> () error Status;

    /// ## Summary
    ///
    /// Get CPU performance parameters.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// zx_status_t zx_system_get_performance_info(zx_handle_t resource,
    ///                                            uint32_t topic,
    ///                                            size_t count,
    ///                                            void* info,
    ///                                            size_t* output_count);
    /// ```
    ///
    /// ## Description
    ///
    /// `zx_system_get_performance_info()` requests CPU performance parameters maintained by the kernel. The
    /// *topic* parameter indicates what specific information is desired.
    ///
    /// *count* indicates the number of items to query. Topics may impose requirements on this value.
    ///
    /// *info* is a pointer to a buffer of sufficient size to accommodate *count* entries of the type
    /// specified by *topic*. The values stored in this array are undefined if the syscall returns an error.
    ///
    /// *output_count* is updated with the number of info entries populated by the kernel on success. The
    /// value stored in this memory location is undefined if the syscall returns an error.
    ///
    /// [TOC]
    ///
    /// ## TOPICS
    ///
    /// ### ZX_CPU_PERF_SCALE
    ///
    /// *count*: Must be equal to the number of logical CPUs in the system.
    ///
    /// *info* type: `zx_cpu_performance_scale_t[count]`
    ///
    /// Returns an array of `zx_cpu_performance_scale_t` with entries indicating the current performance
    /// scales (scalar values representing relative operating points) of each logical CPU in the system. The
    /// values reflect the most recent call to `zx_system_set_performance_info`, even if the values have not
    /// yet taken effect.
    ///
    /// See [RFC 0123](/docs/contribute/governance/rfcs/0123_cpu_performance_info.md)
    /// for further details on values and update protocols.
    ///
    /// ### ZX_CPU_DEFAULT_PERF_SCALE
    ///
    /// *count*: Must be equal to the number of logical CPUs in the system.
    ///
    /// *info* type: `zx_cpu_performance_scale_t[count]`
    ///
    /// Returns an array of `zx_cpu_performance_scale_t` with entries indicating the default performance
    /// scales used during boot of each logical CPU in the system.
    ///
    /// See [RFC 0123](/docs/contribute/governance/rfcs/0123_cpu_performance_info.md)
    /// for further details.
    ///
    /// ## Rights
    ///
    /// *resource* must have resource kind `ZX_RSRC_KIND_SYSTEM`.
    ///
    /// ## Return value
    ///
    /// `zx_system_get_performance_info()` returns `ZX_OK` on success. In the event of a failure, a
    /// negative error value is returned.
    ///
    /// ## Errors
    ///
    /// `ZX_ERR_BAD_HANDLE` *resource* is not a valid handle.
    ///
    /// `ZX_ERR_WRONG_TYPE` *resource* is not resource kind `ZX_RSRC_KIND_SYSTEM`.
    ///
    /// `ZX_ERR_ACCESS_DENIED` *resource* is not in the range [`ZX_RSRC_SYSTEM_CPU_BASE`, `ZX_RSRC_SYSTEM_CPU_BASE`+1).
    ///
    /// `ZX_ERR_INVALID_ARGS` *topic*, *info*, or *output_count* have invalid values.
    ///
    /// `ZX_ERR_OUT_OF_RANGE` *count* does not meet the requirements of the topic.
    ///
    /// `ZX_ERR_NO_MEMORY` Failure due to lack of memory. There is no good way for userspace to handle this (unlikely) error. In a future build this error will no longer occur.
    ///
    /// ## See also
    ///
    /// - [RFC 0123: CPU performance info syscalls](/docs/contribute/governance/rfcs/0123_cpu_performance_info.md)
    ///
    ///  - [`zx_system_set_performance_info()`]
    ///
    /// [`zx_system_set_performance_info()`]: system_set_performance_info.md
    strict GetPerformanceInfo(resource struct {
        resource Handle:RESOURCE;
        topic uint32;
        count usize64;
    }) -> (resource struct {
        // TODO(joshuaseaton): vector<byte>
        @voidptr
        info experimental_pointer<byte>;
        output_count usize64;
    }) error Status;

    /// ## Summary
    ///
    /// Soft reboot the system with a new kernel and bootimage.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// zx_status_t zx_system_mexec(zx_handle_t resource,
    ///                             zx_handle_t kernel_vmo,
    ///                             zx_handle_t bootimage_vmo);
    /// ```
    ///
    /// ## Description
    ///
    /// `zx_system_mexec()` accepts two vmo handles: *kernel_vmo* should contain a
    /// kernel image and *bootimage_vmo* should contain an initrd whose address shall
    /// be passed to the new kernel as a kernel argument.
    ///
    /// To supplant the running kernel, a *resource* of `ZX_RSRC_KIND_SYSTEM` with base
    /// `ZX_RSRC_SYSTEM_MEXEC_BASE` must be supplied.
    ///
    /// Upon success, `zx_system_mexec()` shall supplant the currently running kernel
    /// image with the kernel image contained within *kernel_vmo*, load the ramdisk
    /// contained within *bootimage_vmo* to a location in physical memory and branch
    /// directly into the new kernel while providing the address of the loaded initrd
    /// to the new kernel.
    ///
    /// To use the `zx_system_mexec()` function, you must specify
    /// `kernel.enable-debugging-syscalls=true` on the kernel command line. Otherwise,
    /// the function returns `ZX_ERR_NOT_SUPPORTED`.
    ///
    /// ## Rights
    ///
    /// *resource* must have resource kind `ZX_RSRC_KIND_SYSTEM` with base
    /// `ZX_RSRC_SYSTEM_MEXEC_BASE`.
    ///
    /// *kernel_vmo* must be of type `ZX_OBJ_TYPE_VMO` and have `ZX_RIGHT_READ`.
    ///
    /// *bootimage_vmo* must be of type `ZX_OBJ_TYPE_VMO` and have `ZX_RIGHT_READ`.
    ///
    /// ## Return value
    ///
    /// `zx_system_mexec()` shall not return upon success.
    ///
    /// `ZX_ERR_NOT_SUPPORTED`  `kernel.enable-debugging-syscalls` is not set to `true`
    /// on the kernel command line.
    ///
    /// ## See also
    ///
    ///  - [`zx_system_mexec_payload_get()`]
    ///
    /// [`zx_system_mexec_payload_get()`]: system_mexec_payload_get.md
    strict Mexec(resource struct {
        resource Handle:RESOURCE;
        kernel_vmo Handle:VMO;
        bootimage_vmo Handle:VMO;
    }) -> () error Status;

    /// ## Summary
    ///
    /// Return a ZBI containing ZBI entries necessary to boot this system.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// zx_status_t zx_system_mexec_payload_get(zx_handle_t resource,
    ///                                         void* buffer,
    ///                                         size_t buffer_size);
    /// ```
    ///
    /// ## Description
    ///
    /// `zx_system_mexec_payload_get()` accepts a resource handle and a
    /// pointer/length corresponding to an output buffer. The head of the buffer is
    /// overwritten with non-bootable ZBI containing a sequence of entries that should
    /// be appended to a ZBI before passing that image to [`zx_system_mexec()`]; the
    /// tail of the buffer is left untouched.
    ///
    /// *resource* must be of type `ZX_RSRC_KIND_SYSTEM` with base
    /// `ZX_RSRC_SYSTEM_MEXEC_BASE`.
    ///
    /// *buffer* and *buffer_size* must point to a buffer that is no longer than 16KiB.
    ///
    /// To use the `zx_system_mexec_payload_get()` function, you must specify
    /// `kernel.enable-debugging-syscalls=true` on the kernel command line. Otherwise,
    /// the function returns `ZX_ERR_NOT_SUPPORTED`.
    ///
    /// ## Rights
    ///
    /// *resource* must have resource kind `ZX_RSRC_KIND_SYSTEM` with base
    /// `ZX_RSRC_SYSTEM_MEXEC_BASE`.
    ///
    /// ## Return value
    ///
    /// `zx_system_mexec_payload_get()` returns `ZX_OK` on success.
    ///
    /// `ZX_ERR_NOT_SUPPORTED`  `kernel.enable-debugging-syscalls` is not set to `true`
    /// on the kernel command line.
    ///
    /// `ZX_ERR_BUFFER_TOO_SMALL`  If the provided buffer is too small for the ZBI.
    /// In this case, the caller is expected to make the syscall again with a larger
    /// buffer.
    ///
    /// ## See also
    ///
    ///  - [`zx_system_mexec()`]
    ///
    /// [`zx_system_mexec()`]: system_mexec.md
    strict MexecPayloadGet(resource struct {
        resource Handle:RESOURCE;
    }) -> (struct {
        @voidptr
        buffer vector<byte>:MAX;
    }) error Status;

    /// ## Summary
    ///
    /// TODO(https://fxbug.dev/42108078)
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// zx_status_t zx_system_powerctl(zx_handle_t resource,
    ///                                uint32_t cmd,
    ///                                const zx_system_powerctl_arg_t* arg);
    /// ```
    ///
    /// ## Description
    ///
    /// `zx_system_powerctl` changes the power state of the system based on the value of
    /// *cmd*.  Zircon may not be able to put the system in a given power state,
    /// depending on its level of support for the architecture being used.
    ///
    /// *arg* is an optional pointer to a struct which provides further information
    /// about the command to be executed.
    ///
    /// ## COMMANDS
    ///
    /// ### ZX_SYSTEM_POWERCTL_ENABLE_ALL_CPUS
    ///
    /// Sets all processor cores as active.
    ///
    /// *arg* type: `n/a`
    ///
    /// ### ZX_SYSTEM_POWERCTL_DISABLE_ALL_CPUS_BUT_PRIMARY
    ///
    /// Set only the primary CPU as active.
    ///
    /// *arg* type: `n/a`
    ///
    /// ### ZX_SYSTEM_POWERCTL_ACPI_TRANSITION_S_STATE
    ///
    /// Only defined for x86-64.
    ///
    /// Currently only transitions to the S3 state are supported.
    ///
    /// Before calling this syscall the following steps should be taken:
    /// 1. Enter ACPICA noncontested mode
    /// 2. Shut down the secondary CPUs
    /// 3. Execute the `_PTS` control method
    /// 4. (Optional) Execute the `_SST` control method
    /// 5. Clear the ACPI wake status bit register
    /// 6. Disable all ACPI GPEs
    /// 7. Enabled all ACPI wakeup GPEs
    ///
    /// *arg* type: `zx_system_powerctl_arg_t` with only the `acpi_transition_s_state`
    /// union element considered valid.
    ///
    /// ```
    /// struct {
    ///     uint8_t target_s_state;  // Value between 1 and 5 indicating which S-state
    ///     uint8_t sleep_type_a;    // Value from ACPI VM (SLP_TYPa)
    ///     uint8_t sleep_type_b;    // Value from ACPI VM (SLP_TYPb)
    /// } acpi_transition_s_state;
    /// ```
    ///
    /// Returns `ZX_ERR_INVALID_ARGS` if the target S state is not in the range 1-5.
    ///
    /// Returns `ZX_ERR_NOT_SUPPORTED` if transitioning to the target S state is not
    /// supported.
    ///
    /// Returns `ZX_ERR_BAD_STATE` if the target S state is not 5 and the secondary
    /// CPUs have not been shut down.
    ///
    /// Returns `ZX_ERR_NO_MEMORY` if there are not enough resources to run the
    /// thread.
    ///
    /// Returns `ZX_ERR_INTERNAL` if the S state transition fails.
    ///
    /// ### ZX_SYSTEM_POWERCTL_X86_SET_PKG_PL1
    ///
    /// Only defined for x86-64.
    ///
    /// Set CPU to power level 1.
    ///
    /// *arg* type: `zx_system_powerctl_arg_t` with only the `x86_power_limit` union
    /// element considered valid.
    ///
    /// ```
    /// struct {
    ///     uint32_t power_limit;  // PL1 value in milliwatts
    ///     uint32_t time_window;  // PL1 time window in microseconds
    ///     uint8_t clamp;         // PL1 clamping enable
    ///     uint8_t enable;        // PL1 enable
    ///     uint8_t padding2[2];
    /// } x86_power_limit;
    /// ```
    ///
    /// ### ZX_SYSTEM_POWERCTL_REBOOT
    ///
    /// Restart the system, control should go through any relevant firmware and
    /// bootloaders.
    ///
    /// *arg* type: `n/a`
    ///
    /// ### ZX_SYSTEM_POWERCTL_REBOOT_BOOTLOADER
    ///
    /// Restart the system, but stop in the bootloader instead of loading the operating
    /// system.
    ///
    /// *arg* type: `n/a`
    ///
    /// ### ZX_SYSTEM_POWERCTL_REBOOT_RECOVERY
    ///
    /// Restart the system, but load the recovery operating system instead of the
    /// primary OS.
    ///
    /// *arg* type: `n/a`
    ///
    /// ### ZX_SYSTEM_POWERCTL_SHUTDOWN
    ///
    /// Turn the system off.
    ///
    /// *arg* type: `n/a`
    ///
    /// ### ZX_SYSTEM_POWERCTL_ACK_KERNEL_INITIATED_REBOOT
    ///
    /// Used by userspace when it is ready for a reboot in response to a previous signal
    /// from the kernel that the kernel wanted to reboot the system.
    ///
    /// *arg* type: `n/a`
    ///
    /// Returns `ZX_ERR_BAD_STATE` if the kernel has not previously signaled a desire
    /// to reboot.
    ///
    /// ## Rights
    ///
    /// *resource* must have resource kind `ZX_RSRC_KIND_SYSTEM` with base `ZX_RSRC_SYSTEM_POWER_BASE`.
    ///
    /// ## Return value
    ///
    /// `ZX_OK`
    ///
    /// ## Errors
    ///
    /// Returns `ZX_ERR_INVALID_ARGS` when an unrecognized `cmd` value is supplied.
    ///
    /// ## See also
    ///
    /// TODO(https://fxbug.dev/42108078)
    strict Powerctl(resource struct {
        resource Handle:RESOURCE;
        cmd uint32;
        arg SystemPowerctlArg;
    }) -> () error Status;

    /// # Summary
    ///
    /// TODO(https://fxbug.dev/42182545): Document exact behavior and interface as it iterates.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls-next.h>
    ///
    /// zx_status_t zx_system_suspend_enter(zx_handle_t resource, zx_time_t resume_deadline);
    /// ```
    ///
    /// ## Description
    ///
    /// `zx_system_suspend_enter` suspends task execution on all online processors until the
    /// absolute time given by *resume_deadline*. Task execution is resumed on all online processors
    /// and the call to `zx_system_suspend_enter` returns when the resume deadline expires. Offline
    /// processor states are not affected.
    ///
    /// ## Return value
    ///
    /// `ZX_OK` when *resume_deadline* expires and the system resumes.
    ///
    /// ## Errors
    ///
    /// `ZX_ERR_TIMED_OUT` when *resume_deadline* is in the past.
    ///
    /// `ZX_ERR_BAD_HANDLE` *resource* is not a valid handle.
    ///
    /// `ZX_ERR_WRONG_TYPE` *resource* is not resource kind `ZX_RSRC_KIND_SYSTEM`.
    ///
    /// `ZX_ERR_OUT_OF_RANGE` *resource* is not in the range [`ZX_RSRC_SYSTEM_CPU_BASE`,
    /// `ZX_RSRC_SYSTEM_CPU_BASE`+1).
    ///
    @next
    strict SuspendEnter(resource struct {
        resource Handle:RESOURCE;
        resume_deadline Time;
    }) -> () error Status;

    /// ## Summary
    ///
    /// Informs the kernel of the processor power levels within a given power
    /// domain for energy-aware scheduling.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls-next.h>
    ///
    /// zx_status_t zx_system_set_processor_power_level_domain(
    ///     zx_handle_t resource,
    ///     uint64_t options,
    ///     const zx_cpu_set_t* cpus,
    ///     const zx_processor_power_level_t* power_levels,
    ///     size_t num_power_levels,
    ///     const zx_processor_power_level_transition_t* transitions,
    ///     size_t num_transitions);
    /// ```
    ///
    /// ## Description
    ///
    /// Enables energy-aware scheduling for a given processor power domain.
    ///
    /// Power levels are implicitly enumerated as the indices of `power_levels`.
    ///
    /// There are no ordering restrictions on `transformations` and the power
    /// levels they encode correspond to those defined by `power_levels`. An
    /// absent transformation between levels is assumed to indicate that there
    /// is no energy cost borne by perfoming it.
    ///
    /// ## Rights
    ///
    /// `resource` must be of `ZX_RSRC_KIND_SYSTEM` kind and
    /// `ZX_RSRC_SYSTEM_CPU_BASE` base.
    ///
    /// ## Return value
    ///
    /// `ZX_OK` is returned if and only if the processor power level domain
    /// was successfully registered.
    ///
    /// ## Errors
    ///
    /// `ZX_ERR_ACCESS_DENIED` if `resource` is not a valid handle.
    ///
    /// `ZX_ERR_WRONG_TYPE` if `resource` is not a valid resource handle of
    /// SYSTEM kind and CPU base.
    ///
    /// `ZX_ERR_OUT_OF_RANGE` if `num_power_levels` exceeds
    /// `ZX_MAX_POWER_LEVELS` or `num_transitions` exceeds
    /// `ZX_MAX_POWER_LEVEL_TRANSITIONS`.
    ///
    @next
    strict SetProcessorPowerLevelDomain(resource struct {
        resource Handle:RESOURCE;
        options uint64;
        cpus CpuSet;
        power_levels vector<ProcessorPowerLevel>:MAX_POWER_LEVELS;
        transitions vector<ProcessorPowerLevelTransition>:MAX_POWER_LEVEL_TRANSITIONS;
    }) -> () error Status;
};