Document the non-obsoleted kernel interfaces used by libthr.

Reviewed by:	emaste
Sponsored by:	The FreeBSD Foundation
Differential revision:	https://reviews.freebsd.org/D6335

1 files changed, 228 insertions, 0 deletions

diff --git a/lib/libc/sys/thr_new.2 b/lib/libc/sys/thr_new.2
new file mode 100644
index 000000000000..44c468dec70c
--- /dev/null
+++ b/lib/libc/sys/thr_new.2
@@ -0,0 +1,228 @@
+.\" Copyright (c) 2016 The FreeBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This documentation was written by
+.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
+.\" from the FreeBSD Foundation.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd May 5, 2016
+.Dt THR_NEW 2
+.Os
+.Sh NAME
+.Nm thr_new
+.Nd create new thread of execution
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In sys/thr.h
+.Ft int
+.Fn thr_new "struct thr_param *param" "int param_size"
+.Sh DESCRIPTION
+The
+.Fn thr_new
+system call creates a new kernel-scheduled thread of execution in the context
+of the current process.
+The newly created thread shares all attributes of the process with the
+existing kernel-scheduled threads in the process, but has private processor
+execution state.
+The machine context for the new thread is copied from the creating thread's
+context, including coprocessor state.
+FPU state and specific machine registers are excluded from the copy.
+These are set according to ABI requirements and syscall parameters.
+The FPU state for new thread is reinitialized to clean.
+.Pp
+The
+.Fa param
+structure supplies parameters affecting the thread creation.
+The structure is defined in the
+.In sys/thr.h
+header as follows
+.Bd -literal
+struct thr_param {
+    void          (*start_func)(void *);
+    void          *arg;
+    char          *stack_base;
+    size_t        stack_size;
+    char          *tls_base;
+    size_t        tls_size;
+    long          *child_tid;
+    long          *parent_tid;
+    int           flags;
+    struct rtprio *rtp;
+};
+.Ed
+and contains the following fields:
+.Bl -tag -width ".Va parent_tid"
+.It Va start_func
+The pointer to the thread entry function.
+Kernel arranges for the new thread to start executing the function
+upon the first return to userspace.
+.It Va arg
+Opaque argument supplied to the entry function.
+.It Va stack_base
+Stack base address.
+The stack must be allocated by the caller.
+On some architectures, the ABI might require that system put information
+on the stack to ensure the execution environment for
+.Va start_func .
+.It Va stack_size
+Stack size.
+.It Va tls_base
+TLS base address.
+The value of TLS base is loaded to the ABI-defined machine register
+in the new thread context.
+.It Va tls_size
+TLS size.
+.It Va child_tid
+Address to store the new thread identifier, for the child's use.
+.It Va parent_tid
+Address to store the new thread identifier, for the parent's use.
+.Pp
+Both
+.Va child_tid
+and
+.Va parent_tid
+are provided, with the intent that
+.Va child_tid
+is used by the new thread to get its thread identifier without
+issuing the
+.Xr thr_self 2
+syscall, while
+.Va parent_tid
+is used by the thread creator.
+The later is separate from the
+.Va child_tid
+because new thread might exit and free its thread data before parent
+has a chance to execute far enough to access it.
+.It Va flags
+Thread creation flags.
+The
+.Va flags
+member may specify the following flags:
+.Bl -tag -width ".Dv THR_SYSTEM_SCOPE"
+.It Dv THR_SUSPENDED
+Create the new thread in the suspended state.
+The flag is not currently implemented.
+.It Dv THR_SYSTEM_SCOPE
+Create the system scope thread.
+The flag is not currently implemented.
+.El
+.It Va rtp
+Real-time scheduling priority for the new thread.
+May be NULL if thread should inherit the priority from the
+creating thread.
+.El
+.Pp
+The
+.Fa param_size
+argument should be set to the size of the
+.Fa param
+structure.
+.Pp
+After the first successful creation of an additional thread,
+the process is marked by the kernel as multi-threaded.
+In particular, the
+.Dv P_HADTHREADS
+flag is set in the process'
+.Dv p_flag
+(visible in the
+.Xr ps 1
+output), and several operations are executed in multi-threaded mode.
+For instance, the
+.Xr execve 2
+system call terminates all threads but the calling one on successful
+execution.
+.Sh RETURN VALUES
+If successful,
+.Fn thr_new
+will return zero, otherwise \-1 is returned, and
+.Va errno
+is set to indicate the error.
+.Sh ERRORS
+The
+.Fn thr_new
+operation returns the following errors:
+.Bl -tag -width Er
+.It Bq Er EFAULT
+The memory pointed to by the
+.Fa param
+argument is not valid.
+.It Bq Er EFAULT
+The memory pointed to by the
+.Fa param
+structure
+.Fa child_tid , parent_tid
+or
+.Fa rtp
+arguments is not valid.
+.It Bq Er EFAULT
+Specified stack base is invalid, or the kernel was unable to put required
+initial data on the stack.
+.It Bq Er EINVAL
+The
+.Fa param_size
+argument specifies negative value, or its value is greater than the
+largest
+.Fa struct param
+size the kernel can interpret.
+.It Bq Er EINVAL
+The
+.Fa rtp
+member is not NULL, but specifies invalid scheduling parameters.
+.It Bq Er EINVAL
+The specified TLS base is invalid.
+.It Bq Er EPROCLIM
+Creation of the new thread would exceed the
+.Dv RACCT_NTHR
+limit, see
+.Xr racct 2 .
+.It Bq Er EPROCLIM
+Creation of the new thread would exceed the
+.Dv kern.threads.max_threads_per_proc
+.Xr sysctl 2
+limit.
+.It Bq Er ENOMEM
+No kernel memory to allocate for the new thread structures.
+.El
+.Sh SEE ALSO
+.Xr ps 1 ,
+.Xr execve 2 ,
+.Xr racct 2 ,
+.Xr thr_exit 2 ,
+.Xr thr_kill 2 ,
+.Xr thr_kill2 2 ,
+.Xr thr_self 2 ,
+.Xr thr_set_name 2 ,
+.Xr _umtx_op 2
+.Sh STANDARDS
+The
+.Fn thr_new
+system call is non-standard and is used by the
+.Lb libthr
+to implement
+.St -p1003.1-2001
+.Xr pthread(3)
+functionality.