system/public/zircon/syscalls.sysgen

# Copyright 2016 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.

#
# The syntax of each line is
#     syscall <name> [attributes] ([args])
#         [returns (<type> [attributes] [args])];
#
# with '[]' being optional and '<>' being required input.
#
# <name> is the syscall function name. It must be a valid C identifier.
#
# [attributes] can be empty or is a space separated list of words with
# meaning for a particular generator.
#
# [args] can be empty or is a comma separated list of
# '<aname>: <type> [attributes] [ctr]'
#
# <aname> is the argument name. It must be a valid C indentifier.
#
# <type> is the argument type. It must be a valid C indentifer with an optional
# array-spec which when present it must be "[number]" or "[aname]", with the
# number being an integer and aname the name of the argument that controls the
# array size.
#
# [ctr] can be empty or is an all-caps word to specify a argument constraint
# with valid values being one of: 'IN', 'OUT', 'INOUT'
#
# The 'returns (<type>)' is expected unless one of the attributes is 'noreturn'.
#
#
# To help the clang static analyzer identify handle related syscalls, 3
# attributes are available to describe handle behaviors. Which are
# handle_acquire, handle_release and handle_release_always.
#
#  handle_acquire        The handle will be allocated when this call is
#                        successful.
#
#  handle_release        The handle will be released/destroyed when this
#                        call is successful.
#
#  handle_release_always The handle will be released/destroyed; the only failure
#                        possible is for an invalid handle.
#
#

# Time

syscall time_get
    (clock_id: uint32_t)
    returns (zx_time_t);

syscall nanosleep blocking
    (deadline: zx_time_t)
    returns (zx_status_t);

syscall ticks_get vdsocall
    ()
    returns (uint64_t);

syscall ticks_per_second vdsocall const
    ()
    returns (uint64_t);

syscall deadline_after vdsocall
    (nanoseconds: zx_duration_t)
    returns (zx_time_t);

syscall clock_adjust
    (handle: zx_handle_t, clock_id: uint32_t, offset: int64_t)
    returns (zx_status_t);

# Global system information

syscall system_get_num_cpus vdsocall const
    ()
    returns (uint32_t);

syscall system_get_version vdsocall
    (version: char[version_len] OUT, version_len: uint32_t)
    returns (zx_status_t);

syscall system_get_physmem vdsocall
    ()
    returns (uint64_t);

# Abstraction of machine operations

syscall cache_flush vdsocall
    (addr: any[len] IN, len: size_t, options: uint32_t)
    returns (zx_status_t);

# Generic handle operations

syscall handle_close
    (handle: zx_handle_t handle_release_always)
    returns (zx_status_t);

syscall handle_duplicate
    (handle: zx_handle_t, rights: zx_rights_t)
    returns (zx_status_t, out: zx_handle_t handle_acquire);

syscall handle_replace
    (handle: zx_handle_t handle_release, rights: zx_rights_t)
    returns (zx_status_t, out: zx_handle_t handle_acquire);

# Generic object operations

syscall object_wait_one blocking
    (handle: zx_handle_t, waitfor: zx_signals_t, deadline: zx_time_t)
    returns (zx_status_t, observed: zx_signals_t optional);

syscall object_wait_many blocking
    (items: zx_wait_item_t[count] INOUT, count: uint32_t, deadline: zx_time_t)
    returns (zx_status_t);

syscall object_wait_async
    (handle: zx_handle_t, port_handle: zx_handle_t, key: uint64_t,
        signals: zx_signals_t, options: uint32_t)
    returns (zx_status_t);

syscall object_signal
    (handle: zx_handle_t, clear_mask: uint32_t, set_mask: uint32_t)
    returns (zx_status_t);

syscall object_signal_peer
    (handle: zx_handle_t, clear_mask: uint32_t, set_mask: uint32_t)
    returns (zx_status_t);

syscall object_get_property
    (handle: zx_handle_t, property: uint32_t, value: any[size] OUT, size: size_t)
    returns (zx_status_t);

syscall object_set_property
    (handle: zx_handle_t, property: uint32_t, value: any[size] IN, size: size_t)
    returns (zx_status_t);

syscall object_set_cookie
    (handle: zx_handle_t, scope: zx_handle_t, cookie: uint64_t)
    returns (zx_status_t);

syscall object_get_cookie
    (handle: zx_handle_t, scope: zx_handle_t)
    returns (zx_status_t, cookie: uint64_t);

syscall object_get_info
    (handle: zx_handle_t, topic: uint32_t,
        buffer: any[buffer_size] OUT, buffer_size: size_t)
    returns (zx_status_t, actual_count: size_t optional, avail_count: size_t optional);

syscall object_get_child
    (handle: zx_handle_t, koid: uint64_t, rights: zx_rights_t)
    returns (zx_status_t, out: zx_handle_t);

# IPC: Channels

syscall channel_create
    (options: uint32_t)
    returns (zx_status_t, out0: zx_handle_t handle_acquire,
        out1: zx_handle_t handle_acquire);

syscall channel_read
    (handle: zx_handle_t, options: uint32_t,
        bytes: any[num_bytes] OUT,
        handles: zx_handle_t[num_handles] OUT,
        num_bytes: uint32_t,
        num_handles: uint32_t)
    returns (zx_status_t, actual_bytes: uint32_t optional, actual_handles: uint32_t optional);

syscall channel_write
    (handle: zx_handle_t, options: uint32_t,
        bytes: any[num_bytes] IN, num_bytes: uint32_t,
        handles: zx_handle_t[num_handles] IN, num_handles: uint32_t)
    returns (zx_status_t);

syscall channel_call_noretry internal
    (handle: zx_handle_t, options: uint32_t, deadline: zx_time_t,
        args: zx_channel_call_args_t[1] IN)
    returns (zx_status_t, actual_bytes: uint32_t,
                actual_handles: uint32_t, read_status: zx_status_t optional);

syscall channel_call_finish internal
    (deadline: zx_time_t, args: zx_channel_call_args_t[1] IN)
    returns (zx_status_t, actual_bytes: uint32_t,
                actual_handles: uint32_t, read_status: zx_status_t optional);

syscall channel_call vdsocall
    (handle: zx_handle_t, options: uint32_t, deadline: zx_time_t,
        args: zx_channel_call_args_t[1] IN)
    returns (zx_status_t, actual_bytes: uint32_t,
                actual_handles: uint32_t, read_status: zx_status_t optional);

# IPC: Sockets

syscall socket_create
    (options: uint32_t)
    returns (zx_status_t, out0: zx_handle_t handle_acquire,
        out1: zx_handle_t handle_acquire);

syscall socket_write
    (handle: zx_handle_t, options: uint32_t,
        buffer: any[size] IN, size: size_t)
    returns (zx_status_t, actual: size_t optional);

syscall socket_read
    (handle: zx_handle_t, options: uint32_t,
        buffer: any[size] OUT, size: size_t)
    returns (zx_status_t, actual: size_t optional);

syscall socket_share
    (handle: zx_handle_t, socket_to_share: zx_handle_t)
    returns (zx_status_t);

syscall socket_accept
    (handle: zx_handle_t)
    returns (zx_status_t, out_socket: zx_handle_t);

# Threads

syscall thread_exit noreturn ();

syscall thread_create
    (process: zx_handle_t, name: char[name_len] IN, name_len: uint32_t,
        options: uint32_t)
    returns (zx_status_t, out: zx_handle_t handle_acquire);

syscall thread_start
    (handle: zx_handle_t, thread_entry: uintptr_t,
        stack: uintptr_t, arg1: uintptr_t, arg2: uintptr_t)
    returns (zx_status_t);

syscall thread_read_state
    (handle: zx_handle_t, kind: uint32_t,
        buffer: any[len] OUT, len: uint32_t)
    returns (zx_status_t, actual: uint32_t);

syscall thread_write_state
    (handle: zx_handle_t, kind: uint32_t, buffer: any[buffer_len] IN, buffer_len: uint32_t)
    returns (zx_status_t);

# NOTE: thread_set_priority is an experimental syscall.
# Do not use it.  It is going away very soon.  Just don't do it.  This is not
# the syscall you are looking for.  See ZX-940
syscall thread_set_priority
    (prio: int32_t)
    returns (zx_status_t);

# Processes

syscall process_exit noreturn
    (retcode: int);

syscall process_create
    (job: zx_handle_t, name: char[name_len] IN, name_len: uint32_t, options: uint32_t)
    returns (zx_status_t, proc_handle: zx_handle_t handle_acquire,
        vmar_handle: zx_handle_t handle_acquire);

syscall process_start
    (process_handle: zx_handle_t,
        thread_handle: zx_handle_t, entry: uintptr_t,
        stack: uintptr_t, arg_handle: zx_handle_t handle_release, arg2: uintptr_t)
    returns (zx_status_t);

syscall process_read_memory
    (proc: zx_handle_t, vaddr: uintptr_t,
    buffer: any[len] OUT, len: size_t)
    returns (zx_status_t, actual: size_t);

syscall process_write_memory
    (proc: zx_handle_t, vaddr: uintptr_t,
    buffer: any[len] IN, len: size_t)
    returns (zx_status_t, actual: size_t);

# Jobs

syscall job_create
    (parent_job: zx_handle_t, options: uint32_t)
    returns (zx_status_t, out: zx_handle_t handle_acquire);

syscall job_set_policy
    (job: zx_handle_t, options: uint32_t, topic: uint32_t, policy: any[count] IN, count: uint32_t)
    returns (zx_status_t);

# Shared between process and threads
syscall task_bind_exception_port
    (object: zx_handle_t, eport: zx_handle_t, key: uint64_t, options: uint32_t)
    returns (zx_status_t);

syscall task_suspend
    (task_handle: zx_handle_t)
    returns (zx_status_t);

syscall task_resume
    (task_handle: zx_handle_t, options: uint32_t)
    returns (zx_status_t);

syscall task_kill
    (task_handle: zx_handle_t)
    returns (zx_status_t);

# Synchronization

syscall event_create
    (options: uint32_t)
    returns (zx_status_t, out: zx_handle_t handle_acquire);

syscall eventpair_create
    (options: uint32_t)
    returns (zx_status_t,
        out0: zx_handle_t handle_acquire, out1: zx_handle_t handle_acquire);

syscall futex_wait blocking
    (value_ptr: zx_futex_t[1] IN, current_value: int, deadline: zx_time_t)
    returns (zx_status_t);

syscall futex_wake
    (value_ptr: zx_futex_t[1] IN, count: uint32_t)
    returns (zx_status_t);

syscall futex_requeue
    (wake_ptr: zx_futex_t[1] IN, wake_count: uint32_t, current_value: int,
        requeue_ptr: zx_futex_t[1] IN, requeue_count: uint32_t)
    returns (zx_status_t);

# Ports

syscall port_create
    (options: uint32_t)
    returns (zx_status_t, out: zx_handle_t handle_acquire);

syscall port_queue
    (handle: zx_handle_t, packet: zx_port_packet_t[1] IN, count: size_t)
    returns (zx_status_t);

syscall port_wait blocking
    (handle: zx_handle_t, deadline: zx_time_t, packet: zx_port_packet_t[1] OUT, count: size_t)
    returns (zx_status_t);

syscall port_cancel
    (handle: zx_handle_t, source: zx_handle_t, key: uint64_t)
    returns (zx_status_t);

# Timers

syscall timer_create
    (options: uint32_t, clock_id: uint32_t)
    returns (zx_status_t, out: zx_handle_t handle_acquire);

syscall timer_set
    (handle: zx_handle_t, deadline: zx_time_t, slack: zx_duration_t)
    returns (zx_status_t);

syscall timer_cancel
    (handle: zx_handle_t)
    returns (zx_status_t);

# Memory management

syscall vmo_create
    (size: uint64_t, options: uint32_t)
    returns (zx_status_t, out: zx_handle_t handle_acquire);

syscall vmo_read
    (handle: zx_handle_t, data: any[len] OUT, offset: uint64_t, len: size_t)
    returns (zx_status_t, actual: size_t);

syscall vmo_write
    (handle: zx_handle_t, data: any[len] IN, offset: uint64_t, len: size_t)
    returns (zx_status_t, actual: size_t);

syscall vmo_get_size
    (handle: zx_handle_t)
    returns (zx_status_t, size: uint64_t);

syscall vmo_set_size
    (handle: zx_handle_t, size: uint64_t)
    returns (zx_status_t);

syscall vmo_op_range
    (handle: zx_handle_t, op: uint32_t, offset: uint64_t, size: uint64_t,
        buffer: any[buffer_size] INOUT, buffer_size: size_t)
    returns (zx_status_t);

syscall vmo_clone
    (handle: zx_handle_t, options: uint32_t, offset: uint64_t, size: uint64_t)
    returns (zx_status_t, out: zx_handle_t handle_acquire);

syscall vmo_set_cache_policy
    (handle: zx_handle_t, cache_policy: uint32_t)
    returns (zx_status_t);

# Address space management

syscall vmar_allocate
    (parent_vmar_handle: zx_handle_t, offset: size_t, size: size_t, map_flags: uint32_t)
    returns (zx_status_t,
        child_vmar: zx_handle_t handle_acquire, child_addr: uintptr_t);

syscall vmar_destroy
    (vmar_handle: zx_handle_t)
    returns (zx_status_t);

syscall vmar_map
    (vmar_handle: zx_handle_t, vmar_offset: size_t,
        vmo_handle: zx_handle_t, vmo_offset: uint64_t,
        len: size_t, map_flags: uint32_t)
    returns (zx_status_t, mapped_addr: uintptr_t);

syscall vmar_unmap
    (vmar_handle: zx_handle_t, addr: uintptr_t, len: size_t)
    returns (zx_status_t);

syscall vmar_protect
    (vmar_handle: zx_handle_t, addr: uintptr_t, len: size_t,
        prot_flags: uint32_t)
    returns (zx_status_t);

# Random Number generator

syscall cprng_draw
    (buffer: any[len] OUT, len: size_t)
    returns (zx_status_t, actual: size_t);

syscall cprng_add_entropy
    (buffer: any[len] IN, len: size_t)
    returns (zx_status_t);

# Fifo

syscall fifo_create
    (elem_count: uint32_t, elem_size: uint32_t, options: uint32_t)
    returns (zx_status_t,
        out0: zx_handle_t handle_acquire, out1: zx_handle_t handle_acquire);

syscall fifo_read
    (handle: zx_handle_t, data: any[len] OUT, len: size_t)
    returns (zx_status_t, num_written: uint32_t);

syscall fifo_write
    (handle: zx_handle_t, data: any[len] IN, len: size_t)
    returns (zx_status_t, num_written: uint32_t);

# Multi-function

syscall vmar_unmap_handle_close_thread_exit vdsocall
    (vmar_handle: zx_handle_t, addr: uintptr_t, len: size_t,
        handle: zx_handle_t handle_release)
    returns (zx_status_t);

syscall futex_wake_handle_close_thread_exit vdsocall noreturn
    (value_ptr: zx_futex_t[1] IN, count: uint32_t, new_value: int,
        handle: zx_handle_t handle_release);

# ---------------------------------------------------------------------------------------
# Syscalls past this point are non-public
# Some currently do not require a handle to restrict access.
# Those will be modified or removed.
# These syscalls are *not* a stable API/ABI surface.
# ---------------------------------------------------------------------------------------

# Logging

syscall log_create
    (options: uint32_t)
    returns (zx_status_t, out: zx_handle_t);

syscall log_write
    (handle: zx_handle_t, len: uint32_t, buffer: any[len] IN, options: uint32_t)
    returns (zx_status_t);

syscall log_read
    (handle: zx_handle_t, len: uint32_t, buffer: any[len] OUT, options: uint32_t)
    returns (zx_status_t);


syscall debuglog_create
    (resource: zx_handle_t, options: uint32_t)
    returns (zx_status_t, out: zx_handle_t);

syscall debuglog_write
    (handle: zx_handle_t, options: uint32_t, buffer: any[len] IN, len: size_t)
    returns (zx_status_t);

syscall debuglog_read
    (handle: zx_handle_t, options: uint32_t, buffer: any[len] OUT, len: size_t)
    returns (zx_status_t);

# Tracing

syscall ktrace_read
    (handle: zx_handle_t, data: any[len] OUT, offset: uint32_t,
        len: uint32_t)
    returns (zx_status_t, actual: uint32_t);

syscall ktrace_control
    (handle: zx_handle_t, action: uint32_t, options: uint32_t, ptr: any[action] INOUT)
    returns (zx_status_t);

syscall ktrace_write
    (handle: zx_handle_t, id: uint32_t, arg0: uint32_t, arg1: uint32_t)
    returns (zx_status_t);

syscall mtrace_control
    (handle: zx_handle_t,
        kind: uint32_t, action: uint32_t, options: uint32_t,
        ptr: any[size] INOUT, size: uint32_t)
    returns (zx_status_t);

# Legacy LK debug syscalls

syscall debug_read
    (handle: zx_handle_t, buffer: any[length] OUT, length: uint32_t)
    returns (zx_status_t);

syscall debug_write
    (buffer: any[length] IN, length: uint32_t)
    returns (zx_status_t);

syscall debug_send_command
    (resource_handle: zx_handle_t, buffer: any[length] IN, length: uint32_t)
    returns (zx_status_t);

# DDK Syscalls: Interrupts

syscall interrupt_create
    (handle: zx_handle_t, vector: uint32_t, options: uint32_t)
    returns (zx_status_t, out_handle: zx_handle_t);

syscall interrupt_complete
    (handle: zx_handle_t)
    returns (zx_status_t);

syscall interrupt_wait blocking
    (handle: zx_handle_t)
    returns (zx_status_t);

syscall interrupt_signal
    (handle: zx_handle_t)
    returns (zx_status_t);

# DDK Syscalls: MMIO and Ports

syscall mmap_device_io
    (handle: zx_handle_t, io_addr: uint32_t, len: uint32_t)
    returns (zx_status_t);

syscall vmo_create_contiguous
    (rsrc_handle: zx_handle_t, size: size_t, alignment_log2: uint32_t)
    returns (zx_status_t, out: zx_handle_t);

syscall vmo_create_physical
    (rsrc_handle: zx_handle_t, paddr: zx_paddr_t, size: size_t)
    returns (zx_status_t, out: zx_handle_t);

# DDK Syscalls: Misc Info

syscall bootloader_fb_get_info
    ()
    returns (zx_status_t, format: uint32_t, width: uint32_t, height: uint32_t, stride: uint32_t);

syscall set_framebuffer
    (handle: zx_handle_t, vaddr: any[1] INOUT, len: uint32_t, format: uint32_t,
        width: uint32_t, height: uint32_t, stride: uint32_t)
    returns (zx_status_t);

syscall set_framebuffer_vmo
    (handle: zx_handle_t, vmo: zx_handle_t, len: uint32_t, format: uint32_t,
        width: uint32_t, height: uint32_t, stride: uint32_t)
    returns (zx_status_t);

# DDK Syscalls: PCI

syscall pci_get_nth_device
    (handle: zx_handle_t, index: uint32_t)
    returns (zx_status_t, out_info: zx_pcie_device_info_t, out_handle: zx_handle_t);

syscall pci_enable_bus_master
    (handle: zx_handle_t, enable: bool)
    returns (zx_status_t);

syscall pci_enable_pio
    (handle: zx_handle_t, enable: bool)
    returns (zx_status_t);

syscall pci_reset_device
    (handle: zx_handle_t)
    returns (zx_status_t);

syscall pci_config_read
    (handle: zx_handle_t, offset: uint16_t, width: size_t, out_val: uint32_t[1] OUT)
    returns (zx_status_t);

syscall pci_cfg_pio_rw
    (handle: zx_handle_t, bus: uint8_t, dev: uint8_t, func: uint8_t, offset: uint8_t,
        val: uint32_t[1] INOUT, width: size_t, write: bool)
    returns (zx_status_t);

syscall pci_get_bar
    (handle: zx_handle_t, bar_num: uint32_t, out_bar: zx_pci_resource_t[1] OUT)
    returns (zx_status_t);

syscall pci_get_config
    (handle: zx_handle_t, out_config: zx_pci_resource_t[1] OUT)
    returns (zx_status_t);

syscall pci_io_write
    (handle: zx_handle_t, bar_num: uint32_t, offset: uint32_t, len: uint32_t, value: uint32_t)
    returns (zx_status_t);

syscall pci_io_read
    (handle: zx_handle_t, bar_num: uint32_t,
        offset: uint32_t, len: uint32_t)
    returns (zx_status_t, out_value: uint32_t);

syscall pci_map_interrupt
    (handle: zx_handle_t, which_irq: int32_t)
    returns (zx_status_t, out_handle: zx_handle_t);

syscall pci_query_irq_mode_caps
    (handle: zx_handle_t, mode: uint32_t)
    returns (zx_status_t, out_max_irqs: uint32_t);

syscall pci_set_irq_mode
    (handle: zx_handle_t, mode: uint32_t, requested_irq_count: uint32_t)
    returns (zx_status_t);

syscall pci_init
    (handle: zx_handle_t, init_buf: zx_pci_init_arg_t[len] IN, len: uint32_t)
    returns (zx_status_t);

syscall pci_add_subtract_io_range
    (handle: zx_handle_t, mmio: bool, base: uint64_t, len: uint64_t, add: bool)
    returns (zx_status_t);

# DDK Syscalls: ACPI Glue

syscall acpi_uefi_rsdp
    (handle: zx_handle_t)
    returns (uint64_t);

# Resources

syscall resource_create
    (parent_handle: zx_handle_t, kind: uint32_t, low: uint64_t, high: uint64_t)
    returns (zx_status_t, resource_out: zx_handle_t);

# Hypervisor

syscall guest_create
    (resource: zx_handle_t, options: uint32_t, physmem_vmo: zx_handle_t)
    returns (zx_status_t, out: zx_handle_t handle_acquire);

syscall guest_set_trap
    (guest: zx_handle_t, kind: uint32_t, addr: zx_vaddr_t, len: size_t, port: zx_handle_t,
        key: uint64_t)
    returns (zx_status_t);

syscall vcpu_create
    (guest: zx_handle_t, options: uint32_t, args: zx_vcpu_create_args_t[1] IN)
    returns (zx_status_t, out: zx_handle_t handle_acquire);

syscall vcpu_resume
    (vcpu: zx_handle_t)
    returns (zx_status_t, packet: zx_port_packet_t OUT);

syscall vcpu_interrupt
    (vcpu: zx_handle_t, vector: uint32_t)
    returns (zx_status_t);

syscall vcpu_read_state
    (vcpu: zx_handle_t, kind: uint32_t, buffer: any[len] OUT, len: uint32_t)
    returns (zx_status_t);

syscall vcpu_write_state
    (vcpu: zx_handle_t, kind: uint32_t, buffer: any[len] IN, len: uint32_t)
    returns (zx_status_t);

# System Control

syscall system_mexec
   (kernel: zx_handle_t, bootimage: zx_handle_t, cmdline: zx_handle_t, cmdline_len: uint32_t)
   returns (zx_status_t);

syscall system_powerctl
   (root_rsrc: zx_handle_t, cmd: uint32_t, arg: zx_system_powerctl_arg_t[1] IN)
   returns (zx_status_t);

# Internal-only task syscalls

syscall job_set_relative_importance
    (root_resource: zx_handle_t,
        job: zx_handle_t, less_important_job: zx_handle_t)
    returns (zx_status_t);

# Test syscalls (keep at the end)

syscall syscall_test_0() returns (zx_status_t);
syscall syscall_test_1 test_category1 (a:int) returns (zx_status_t);
syscall syscall_test_2 test_category1 (a:int, b:int) returns (zx_status_t);
syscall syscall_test_3 test_category2 (a:int, b:int, c:int) returns (zx_status_t);
syscall syscall_test_4(a:int, b:int, c:int, d:int) returns (zx_status_t);
syscall syscall_test_5(a:int, b:int, c:int, d:int, e:int) returns (zx_status_t);
syscall syscall_test_6(a:int, b:int, c:int, d:int, e:int, f:int) returns (zx_status_t);
syscall syscall_test_7(a:int, b:int, c:int, d:int, e:int, f:int, g:int) returns (zx_status_t);
syscall syscall_test_8(a:int, b:int, c:int, d:int, e:int, f:int, g:int, h:int) returns (zx_status_t);
syscall syscall_test_wrapper(a:int, b:int, c:int) returns (zx_status_t);