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

// TODO(fxb/39732): This should be read as "library zx".
library zz;

// TODO(scottmg): Apply rights spec from WaitMany on |items| to |handle| here,
// somehow.
struct WaitItem {
    handle handle;
    signals waitfor;
    signals pending;
};

[Transport = "Syscall"]
protocol object {
    /// Wait for signals on an object.
    /// Rights: handle must have ZX_RIGHT_WAIT.
    [blocking]
    object_wait_one(handle handle, signals signals, time deadline)
        -> (status status, optional_signals observed);

    /// Wait for signals on multiple objects.
    /// Rights: Every entry of items must have a handle field with ZX_RIGHT_WAIT.
    [blocking]
    object_wait_many(mutable_vector_WaitItem items, time deadline) -> (status status);

    /// Subscribe for signals on an object.
    /// Rights: handle must have ZX_RIGHT_WAIT.
    /// Rights: port must be of type ZX_OBJ_TYPE_PORT and have ZX_RIGHT_WRITE.
    object_wait_async(handle handle, handle<port> port, uint64 key, signals signals, uint32 options)
        -> (status status);

    /// Signal an object.
    /// Rights: handle must have ZX_RIGHT_SIGNAL.
    object_signal(handle handle, uint32 clear_mask, uint32 set_mask) -> (status status);

    /// Signal an object's peer.
    /// Rights: handle must have ZX_RIGHT_SIGNAL_PEER.
    object_signal_peer(handle handle, uint32 clear_mask, uint32 set_mask) -> (status status);

    /// Ask for various properties of various kernel objects.
    /// Rights: handle must have ZX_RIGHT_GET_PROPERTY.
    /// Rights: If property is ZX_PROP_PROCESS_DEBUG_ADDR, handle must be of type ZX_OBJ_TYPE_PROCESS.
    /// Rights: If property is ZX_PROP_PROCESS_BREAK_ON_LOAD, handle must be of type ZX_OBJ_TYPE_PROCESS.
    /// Rights: If property is ZX_PROP_PROCESS_VDSO_BASE_ADDRESS, handle must be of type ZX_OBJ_TYPE_PROCESS.
    /// Rights: If property is ZX_PROP_SOCKET_RX_THRESHOLD, handle must be of type ZX_OBJ_TYPE_SOCKET.
    /// Rights: If property is ZX_PROP_SOCKET_TX_THRESHOLD, handle must be of type ZX_OBJ_TYPE_SOCKET.
    object_get_property(handle handle, uint32 property) -> (status status, vector_void value);

    /// Set various properties of various kernel objects.
    /// Rights: handle must have ZX_RIGHT_SET_PROPERTY.
    /// Rights: If property is ZX_PROP_PROCESS_DEBUG_ADDR, handle must be of type ZX_OBJ_TYPE_PROCESS.
    /// Rights: If property is ZX_PROP_PROCESS_BREAK_ON_LOAD, handle must be of type ZX_OBJ_TYPE_PROCESS.
    /// Rights: If property is ZX_PROP_SOCKET_RX_THRESHOLD, handle must be of type ZX_OBJ_TYPE_SOCKET.
    /// Rights: If property is ZX_PROP_SOCKET_TX_THRESHOLD, handle must be of type ZX_OBJ_TYPE_SOCKET.
    /// Rights: If property is ZX_PROP_JOB_KILL_ON_OOM, handle must be of type ZX_OBJ_TYPE_JOB.
    object_set_property(handle handle, uint32 property, vector_void value) -> (status status);

    /// Query information about an object.
    /// Rights: If topic is ZX_INFO_PROCESS, handle must be of type ZX_OBJ_TYPE_PROCESS and have ZX_RIGHT_INSPECT.
    /// Rights: If topic is ZX_INFO_JOB, handle must be of type ZX_OBJ_TYPE_JOB and have ZX_RIGHT_INSPECT.
    /// Rights: If topic is ZX_INFO_PROCESS_THREADS, handle must be of type ZX_OBJ_TYPE_PROCESS and have ZX_RIGHT_ENUMERATE.
    /// Rights: If topic is ZX_INFO_JOB_CHILDREN, handle must be of type ZX_OBJ_TYPE_JOB and have ZX_RIGHT_ENUMERATE.
    /// Rights: If topic is ZX_INFO_JOB_PROCESSES, handle must be of type ZX_OBJ_TYPE_JOB and have ZX_RIGHT_ENUMERATE.
    /// Rights: If topic is ZX_INFO_THREAD, handle must be of type ZX_OBJ_TYPE_THREAD and have ZX_RIGHT_INSPECT.
    /// Rights: If topic is ZX_INFO_THREAD_EXCEPTION_REPORT, handle must be of type ZX_OBJ_TYPE_THREAD and have ZX_RIGHT_INSPECT.
    /// Rights: If topic is ZX_INFO_THREAD_STATS, handle must be of type ZX_OBJ_TYPE_THREAD and have ZX_RIGHT_INSPECT.
    /// Rights: If topic is ZX_INFO_TASK_STATS, handle must be of type ZX_OBJ_TYPE_PROCESS and have ZX_RIGHT_INSPECT.
    /// Rights: If topic is ZX_INFO_PROCESS_MAPS, handle must be of type ZX_OBJ_TYPE_PROCESS and have ZX_RIGHT_INSPECT.
    /// Rights: If topic is ZX_INFO_PROCESS_VMOS, handle must be of type ZX_OBJ_TYPE_PROCESS and have ZX_RIGHT_INSPECT.
    /// Rights: If topic is ZX_INFO_VMO, handle must be of type ZX_OBJ_TYPE_VMO.
    /// TODO(ZX-2967), Should this require INSPECT?
    /// Rights: If topic is ZX_INFO_VMAR, handle must be of type ZX_OBJ_TYPE_VMAR and have ZX_RIGHT_INSPECT.
    /// Rights: If topic is ZX_INFO_CPU_STATS, handle must have resource kind ZX_RSRC_KIND_ROOT.
    /// Rights: If topic is ZX_INFO_KMEM_STATS, handle must have resource kind ZX_RSRC_KIND_ROOT.
    /// Rights: If topic is ZX_INFO_RESOURCE, handle must be of type ZX_OBJ_TYPE_RESOURCE and have ZX_RIGHT_INSPECT.
    /// Rights: If topic is ZX_INFO_HANDLE_COUNT, handle must have ZX_RIGHT_INSPECT.
    /// Rights: If topic is ZX_INFO_BTI, handle must be of type ZX_OBJ_TYPE_BTI and have ZX_RIGHT_INSPECT.
    /// Rights: If topic is ZX_INFO_PROCESS_HANDLE_STATS, handle must be of type ZX_OBJ_TYPE_PROCESS and have ZX_RIGHT_INSPECT.
    /// Rights: If topic is ZX_INFO_SOCKET, handle must be of type ZX_OBJ_TYPE_SOCKET and have ZX_RIGHT_INSPECT.
    object_get_info(handle handle, uint32 topic)
        -> (status status, vector_void buffer, optional_usize actual, optional_usize avail);

    /// Given a kernel object with children objects, obtain a handle to the child specified by the provided kernel object id.
    /// Rights: handle must have ZX_RIGHT_ENUMERATE.
    object_get_child(handle handle, uint64 koid, rights rights) -> (status status, handle out);

    /// Apply a scheduling profile to a thread.
    /// Rights: handle must be of type ZX_OBJ_TYPE_THREAD and have ZX_RIGHT_MANAGE_THREAD.
    /// Rights: profile must be of type ZX_OBJ_TYPE_PROFILE and have ZX_RIGHT_APPLY_PROFILE.
    object_set_profile(handle<thread> handle, handle<profile> profile, uint32 options)
        -> (status status);
};