// 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(scottmg): Apply rights spec from WaitMany on |items| to |handle| here,
// somehow.
type WaitItem = resource struct {
    handle handle;
    waitfor signals;
    pending signals;
};

@transport("Syscall")
protocol object {
    /// Wait for signals on an object.
    /// Rights: handle must have ZX_RIGHT_WAIT.
    @blocking
    object_wait_one(resource struct {
        handle handle;
        signals signals;
        deadline time;
    }) -> (struct {
        status status;
        observed optional_signals;
    });

    /// Wait for signals on multiple objects.
    /// Rights: Every entry of items must have a handle field with ZX_RIGHT_WAIT.
    @blocking
    object_wait_many(resource struct {
        items mutable_vector_WaitItem;
        deadline time;
    }) -> (struct {
        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(resource struct {
        handle handle;
        port handle:PORT;
        key uint64;
        signals signals;
        options uint32;
    }) -> (struct {
        status status;
    });

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

    /// Signal an object's peer.
    /// Rights: handle must have ZX_RIGHT_SIGNAL_PEER.
    object_signal_peer(resource struct {
        handle handle;
        clear_mask uint32;
        set_mask uint32;
    }) -> (struct {
        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(resource struct {
        handle handle;
        property uint32;
    }) -> (struct {
        status status;
        value vector_void;
    });

    /// 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(resource struct {
        handle handle;
        property uint32;
        value vector_void;
    }) -> (struct {
        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(fxbug.dev/32803), 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_GUEST_STATS, handle must have resource kind ZX_RSRC_KIND_SYSTEM with base ZX_RSRC_SYSTEM_INFO_BASE.
    /// Rights: If topic is ZX_INFO_CPU_STATS, handle must have resource kind ZX_RSRC_KIND_SYSTEM with base ZX_RSRC_SYSTEM_INFO_BASE.
    /// Rights: If topic is ZX_INFO_KMEM_STATS, handle must have resource kind ZX_RSRC_KIND_SYSTEM with base ZX_RSRC_SYSTEM_INFO_BASE.
    /// Rights: If topic is ZX_INFO_KMEM_STATS_EXTENDED, handle must have resource kind ZX_RSRC_KIND_SYSTEM with base ZX_RSRC_SYSTEM_INFO_BASE.
    /// 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.
    /// Rights: If topic is ZX_INFO_MSI, handle must be of type ZX_OBJ_TYPE_MSI and have ZX_RIGHT_INSPECT.
    /// Rights: 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.
    object_get_info(resource struct {
        handle handle;
        topic uint32;
    }) -> (struct {
        status status;
        buffer vector_void;
        actual optional_usize;
        avail optional_usize;
    });

    /// 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(resource struct {
        handle handle;
        koid uint64;
        rights rights;
    }) -> (resource struct {
        status status;
        out handle;
    });

    /// 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(resource struct {
        handle handle:THREAD;
        profile handle:PROFILE;
        options uint32;
    }) -> (struct {
        status status;
    });
};