blob: 6583509c091c79d27c56e0f8ee7570eb3c653e78 [file] [log] [blame] [edit]
// 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): These syscalls don't match the general naming convention of
// zx_something_name(), they're just zx_name(), so NoProtocolPrefix tells the
// generator to exclude putting "Misc" in the name.
@transport("Syscall")
@no_protocol_prefix
closed protocol Misc {
/// ## Summary
///
/// High resolution sleep.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_nanosleep(zx_instant_mono_t deadline);
/// ```
///
/// ## Description
///
/// `zx_nanosleep()` suspends the calling thread execution until *deadline* passes
/// on `ZX_CLOCK_MONOTONIC`. *deadline* will be automatically adjusted according to the job's
/// [timer slack] policy.
///
/// To sleep for a duration, use [`zx_deadline_after()`] and the
/// `ZX_\<time-unit\>` helpers:
///
/// ```c
/// #include <zircon/syscalls.h> // zx_deadline_after, zx_nanosleep
/// #include <zircon/types.h> // ZX_MSEC et al.
///
/// // Sleep 50 milliseconds
/// zx_nanosleep(zx_deadline_after(ZX_MSEC(50)));
/// ```
///
/// ## Rights
///
/// None.
///
/// ## Return value
///
/// `zx_nanosleep()` always returns `ZX_OK`.
///
/// ## See also
///
/// - [timer slack]
/// - [`zx_deadline_after()`]
/// - [`zx_timer_cancel()`]
/// - [`zx_timer_create()`]
/// - [`zx_timer_set()`]
///
/// [timer slack]: /docs/concepts/kernel/timer_slack.md
/// [`zx_deadline_after()`]: deadline_after.md
/// [`zx_timer_cancel()`]: timer_cancel.md
/// [`zx_timer_create()`]: timer_create.md
/// [`zx_timer_set()`]: timer_set.md
@blocking
strict Nanosleep(struct {
deadline InstantMono;
}) -> () error Status;
/// ## Summary
///
/// Read the number of high-precision timer ticks since boot, not including
/// time spent suspended.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_instant_mono_ticks_t zx_ticks_get(void);
/// ```
///
/// ## Description
///
/// `zx_ticks_get()` returns the number of high-precision timer ticks since boot,
/// not including time spent suspended.
///
/// These ticks may be processor cycles, high speed timer, profiling timer, etc.
/// They are not guaranteed to continue advancing when the system is asleep.
///
/// ## Rights
///
/// TODO(https://fxbug.dev/42107318)
///
/// ## Return value
///
/// `zx_ticks_get()` returns the number of high-precision timer ticks since boot.
///
/// ## Errors
///
/// `zx_ticks_get()` does not report any error conditions.
///
/// ## Notes
///
/// The returned value may be highly variable. Factors that can affect it include:
///
/// - System sleep/wake (post implementation of
/// [RFC-0230](https://fuchsia.dev/fuchsia-src/contribute/governance/rfcs/0230_suspend_to_idle))
/// - Reset of the processor cycle counter
/// - Reordering of instructions (if required, use a memory barrier)
///
/// All Fuchsia systems use an invariant-rate ticks clock, which means that the
/// number of ticks per second is constant regardless of changes in processor
/// speed or migration between processors.
///
/// ## See also
///
/// [ticks_per_second](ticks_per_second.md)
@vdsocall
strict TicksGet() -> (@wrapped_return struct {
ticks InstantMonoTicks;
});
/// ## Summary
///
/// Read the number of high-precision timer ticks since boot, including any time spent in a
/// suspended state.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_instant_boot_ticks_t zx_ticks_get_boot(void);
/// ```
///
/// ## Description
///
/// `zx_ticks_get_boot()` returns the number of high-precision timer ticks since boot,
/// including any time spent in a suspended state.
///
/// These ticks may be processor cycles, high speed timer, profiling timer, etc.
///
/// ## Rights
///
/// None.
///
/// ## Return value
///
/// `zx_ticks_get_boot()` returns the number of high-precision timer ticks since boot.
///
/// ## Errors
///
/// `zx_ticks_get_boot()` does not report any error conditions.
///
/// ## Notes
///
/// The returned value may be highly variable. Factors that can affect it include:
///
/// - Reset of the processor cycle counter
/// - Reordering of instructions (if required, use a memory barrier)
///
/// All Fuchsia systems use an invariant-rate ticks clock, which means that the
/// number of ticks per second is constant regardless of changes in processor
/// speed or migration between processors.
///
/// ## See also
///
/// [ticks_per_second](ticks_per_second.md)
@vdsocall
strict TicksGetBoot() -> (@wrapped_return struct {
ticks InstantBootTicks;
});
/// ## Summary
///
/// Read the number of high-precision timer ticks in a second.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_ticks_t zx_ticks_per_second(void);
/// ```
///
/// ## Description
///
/// `zx_ticks_per_second()` returns the number of high-precision timer ticks in a
/// second.
///
/// This can be used together with [`zx_ticks_get()`] to calculate the amount of
/// time elapsed between two subsequent calls to [`zx_ticks_get()`].
///
/// This value can vary from boot to boot of a given system. Once booted,
/// this value is guaranteed not to change.
///
/// ## Rights
///
/// TODO(https://fxbug.dev/42107318)
///
/// ## Return value
///
/// `zx_ticks_per_second()` returns the number of high-precision timer ticks in a
/// second.
///
/// ## Errors
///
/// `zx_ticks_per_second()` does not report any error conditions.
///
/// ## EXAMPLES
///
/// ```c
/// zx_ticks_t ticks_per_second = zx_ticks_per_second();
/// zx_instant_mono_ticks_t ticks_start = zx_ticks_get();
///
/// // do some more work
///
/// zx_instant_mono_ticks_t ticks_end = zx_ticks_get();
/// double elapsed_seconds = (ticks_end - ticks_start) / (double)ticks_per_second;
/// ```
///
/// ## See also
///
/// - [`zx_ticks_get()`]
///
/// [`zx_ticks_get()`]: ticks_get.md
@const
@vdsocall
strict TicksPerSecond() -> (@wrapped_return struct {
ticks Ticks;
});
/// ## Summary
///
/// Convert a time relative to now to an absolute deadline.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_instant_mono_t zx_deadline_after(zx_duration_mono_t nanoseconds);
/// ```
///
/// ## Description
///
/// `zx_deadline_after()` is a utility for converting from now-relative durations
/// to absolute deadlines. If *nanoseconds* plus the current time is bigger than the
/// maximum value for `zx_instant_mono_t`, the output is clamped to `ZX_TIME_INFINITE`.
///
/// ## Rights
///
/// TODO(https://fxbug.dev/42107318)
///
/// ## Return value
///
/// `zx_deadline_after()` returns the absolute time (with respect to `ZX_CLOCK_MONOTONIC`)
/// that is *nanoseconds* nanoseconds from now.
///
/// ## Errors
///
/// `zx_deadline_after()` does not report any error conditions.
///
/// ## EXAMPLES
///
/// ```c
/// // Sleep 50 milliseconds
/// zx_instant_mono_t deadline = zx_deadline_after(ZX_MSEC(50));
/// zx_nanosleep(deadline);
/// ```
///
/// ## See also
///
/// [ticks_get](ticks_get.md)
@vdsocall
strict DeadlineAfter(struct {
nanoseconds DurationMono;
}) -> (@wrapped_return struct {
time InstantMono;
});
/// ## Summary
///
/// Unmap memory, close handle, exit.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// zx_status_t zx_vmar_unmap_handle_close_thread_exit(zx_handle_t vmar_handle,
/// zx_vaddr_t addr,
/// size_t size,
/// zx_handle_t close_handle);
/// ```
///
/// ## Description
///
/// `zx_vmar_unmap_handle_close_thread_exit()` does a sequence of three operations:
///
/// 1. `zx_vmar_unmap(vmar_handle, addr, size)`
/// 2. `zx_handle_close(close_handle)`
/// 3. `zx_thread_exit()`
///
/// The expectation is that the first operation unmaps a region including the
/// calling thread's own stack. (It's not required, but it's permitted.) This
/// is valid for this call, though it would be invalid for [`zx_vmar_unmap()`] or
/// any other call.
///
/// If the [`zx_vmar_unmap()`] operation is successful, then this call never returns.
/// If *close_handle* is an invalid handle so that the [`zx_handle_close()`] operation
/// fails, then the thread takes a trap (as if by `__builtin_trap();`).
///
/// ## Rights
///
/// TODO(https://fxbug.dev/42107318)
///
/// ## Return value
///
/// `zx_vmar_unmap_handle_close_thread_exit()` does not return on success.
///
/// ## Errors
///
/// Same as [`zx_vmar_unmap()`].
///
/// ## Notes
///
/// The intended use for this is for a dying thread to unmap its own stack,
/// close its own thread handle, and exit. The thread handle cannot be closed
/// beforehand because closing the last handle to a thread kills that thread.
/// The stack cannot be unmapped beforehand because the thread must have some
/// stack space on which to make its final system calls.
///
/// This call is used for detached threads, while
/// [`zx_futex_wake_handle_close_thread_exit()`]
/// is used for joinable threads.
///
/// ## See also
///
/// - [`zx_futex_wake_handle_close_thread_exit()`]
/// - [`zx_handle_close()`]
/// - [`zx_thread_exit()`]
/// - [`zx_vmar_unmap()`]
///
/// [`zx_futex_wake_handle_close_thread_exit()`]: futex_wake_handle_close_thread_exit.md
/// [`zx_handle_close()`]: handle_close.md
/// [`zx_thread_exit()`]: thread_exit.md
/// [`zx_vmar_unmap()`]: vmar_unmap.md
@vdsocall
strict VmarUnmapHandleCloseThreadExit(resource struct {
vmar_handle Handle:VMAR;
addr Vaddr;
size usize64;
@release
close_handle Handle;
}) -> () error Status;
/// ## Summary
///
/// Write to futex, wake futex, close handle, exit.
///
/// ## Declaration
///
/// ```c
/// #include <zircon/syscalls.h>
///
/// [[noreturn]] void zx_futex_wake_handle_close_thread_exit(
/// const zx_futex_t* value_ptr,
/// uint32_t wake_count,
/// int32_t new_value,
/// zx_handle_t close_handle);
/// ```
///
/// ## Description
///
/// `zx_futex_wake_handle_close_thread_exit()` does a sequence of four operations:
///
/// 1. `atomic_store_explicit(value_ptr, new_value, memory_order_release);`
/// 2. `zx_futex_wake(value_ptr, wake_count);`
/// 3. `zx_handle_close(close_handle);`
/// 4. `zx_thread_exit();`
///
/// The expectation is that as soon as the first operation completes,
/// other threads may unmap or reuse the memory containing the calling
/// thread's own stack. This is valid for this call, though it would be
/// invalid for plain [`zx_futex_wake()`] or any other call.
///
/// If any of the operations fail, then the thread takes a trap (as if by `__builtin_trap();`).
///
/// ## Rights
///
/// TODO(https://fxbug.dev/42107318)
///
/// ## Return value
///
/// `zx_futex_wake_handle_close_thread_exit()` does not return.
///
/// ## Errors
///
/// None.
///
/// ## Notes
///
/// The intended use for this is for a dying thread to alert another thread
/// waiting for its completion, close its own thread handle, and exit.
/// The thread handle cannot be closed beforehand because closing the last
/// handle to a thread kills that thread. The write to *value_ptr* can't be
/// done before this call because any time after the write, a joining thread might
/// reuse or deallocate this thread's stack, which may cause issues with calling
/// conventions into this function.
///
/// This call is used for joinable threads, while
/// [`zx_vmar_unmap_handle_close_thread_exit()`]
/// is used for detached threads.
///
/// ## See also
///
/// - [futex objects]
/// - [`zx_futex_wake()`]
/// - [`zx_handle_close()`]
/// - [`zx_thread_exit()`]
/// - [`zx_vmar_unmap_handle_close_thread_exit()`]
///
/// [futex objects]: /docs/reference/kernel_objects/futex.md
/// [`zx_futex_wake()`]: futex_wake.md
/// [`zx_handle_close()`]: handle_close.md
/// [`zx_thread_exit()`]: thread_exit.md
/// [`zx_vmar_unmap_handle_close_thread_exit()`]: vmar_unmap_handle_close_thread_exit.md
@noreturn
@vdsocall
strict FutexWakeHandleCloseThreadExit(resource struct {
@embedded_alias("zx/Futex")
value_ptr experimental_pointer<Futex>;
wake_count uint32;
new_value int32;
@release
close_handle Handle;
});
// Read the number of high-precision timer ticks since boot, but demand
// that the read be performed using a syscall, instead of a vdso call.
//
// Note that this is an internal syscall, not meant to be used by
// application code. By default, the vdso version of this syscall will do
// the proper thing, either directly reading from the hardware register
// backing the tick counter, or by making a syscall if the register is not
// accessible from user mode code (for whatever reason).
@internal
strict TicksGetViaKernel() -> (@wrapped_return struct {
ticks InstantMonoTicks;
});
// Read the number of high-precision timer ticks since boot including any
// time spent suspended, but demand that the read be performed using a
// syscall, instead of a vdso call.
//
// Note that this is an internal syscall, not meant to be used by
// application code. By default, the vdso version of this syscall will do
// the proper thing, either directly reading from the hardware register
// backing the tick counter, or by making a syscall if the register is not
// accessible from user mode code (for whatever reason).
@internal
strict TicksGetBootViaKernel() -> (@wrapped_return struct {
ticks InstantBootTicks;
});
};