zx_thread_start

Summary

Start execution on a thread.

Declaration

#include <zircon/syscalls.h>

zx_status_t zx_thread_start(zx_handle_t handle,
                            zx_vaddr_t thread_entry,
                            zx_vaddr_t stack,
                            uintptr_t arg1,
                            uintptr_t arg2);

Description

zx_thread_start() causes a thread to begin execution at the program counter specified by thread_entry and with the stack pointer set to stack. The arguments arg1 and arg2 are arranged to be in the architecture specific registers used for the first two arguments of a function call before the thread is started. All other registers are zero upon start.

When the last handle to a thread is closed, the thread is destroyed.

Thread handles may be waited on and will assert the signal ZX_THREAD_TERMINATED when the thread stops executing (due to zx_thread_exit() being called).

thread_entry shall point to a function that must call zx_thread_exit() or zx_futex_wake_handle_close_thread_exit() or zx_vmar_unmap_handle_close_thread_exit() before reaching the last instruction. Below is an example:

void thread_entry(uintptr_t arg1, uintptr_t arg2) __attribute__((noreturn)) {
  // do work here.

  zx_thread_exit();
}

Failing to call one of the exit functions before reaching the end of the function will cause an architecture / toolchain specific exception.

Rights

handle must be of type ZX_OBJ_TYPE_THREAD and have ZX_RIGHT_MANAGE_THREAD.

Return value

zx_thread_start() returns ZX_OK on success. In the event of failure, a negative error value is returned.

Errors

ZX_ERR_BAD_HANDLE thread is not a valid handle.

ZX_ERR_WRONG_TYPE thread is not a thread handle.

ZX_ERR_ACCESS_DENIED The handle thread lacks ZX_RIGHT_WRITE.

ZX_ERR_BAD_STATE thread is not ready to run or the process thread is part of is no longer alive.

ZX_ERR_INVALID_ARGS thread_entry is not a userspace address, is not a canonical address, or is not 0.