15254 %ymm registers not restored after signal handler
15367 x86 getfpregs() summons corrupting %xmm ghosts
15333 want x86 /proc xregs support (libc_db, libproc, mdb, etc.)
15336 want libc functions for extended ucontext_t
15334 want ps_lwphandle-specific reg routines
15328 FPU_CW_INIT mistreats reserved bit
15335 i86pc fpu_subr.c isn't really platform-specific
15332 setcontext(2) isn't actually noreturn
15331 need <sys/stdalign.h>
Change-Id: I7060aa86042dfb989f77fc3323c065ea2eafa9ad
Conflicts:
    usr/src/uts/common/fs/proc/prcontrol.c
    usr/src/uts/intel/os/archdep.c
    usr/src/uts/intel/sys/ucontext.h
    usr/src/uts/intel/syscall/getcontext.c

@@ -1,26 +1,53 @@
 GETCONTEXT(2)                    System Calls                    GETCONTEXT(2)
 
 NAME
-     getcontext, setcontext - get and set current user context
+     getcontext, getcontext_extd, setcontext - get and set current user
+     context
 
 SYNOPSIS
      #include <ucontext.h>
 
      int
      getcontext(ucontext_t *ucp);
 
      int
+     getcontext_extd(ucontext_t *ucp, uint32_t flags);
+
+     int
      setcontext(const ucontext_t *ucp);
 
 DESCRIPTION
      The getcontext() function initializes the structure pointed to by ucp to
      the current user context of the calling process.  The ucontext_t type
      that ucp points to defines the user context and includes the contents of
      the calling process' machine registers, the signal mask, and the current
      execution stack.
 
+     The ucontext_t structure is a part of the system ABI.  However, most
+     architectures have added additional register states such as the extended
+     vector and floating point registers that are not part of that.  To
+     facilitate getting that state (such as the x86 xsave area) the
+     getcontext_extd() function exists.  Once called, the context will be
+     initialized and is suitable for use in other context operations just as
+     though one had called getcontext().
+
+     Unlike the getcontext() function, getcontext_extd() assumes that callers
+     have previously initialized ucp and thus it treats additional members
+     (such as the uc_xsave member on x86) as potentially valid.  To allow for
+     all extended states to be copied out, ucp must be allocated with
+     ucontext_alloc(3C).  Otherwise whether it is declared on the stack, as
+     global data, allocated dynamically, or part of a structure, ucp must be
+     zeroed through a call to bzero(3C) or memset(3C) prior to calling
+     getcontext_extd().  Improper initialization can lead to memory safety
+     bugs, making it critical that this is done.
+
+     The flags member must be zero and is present to allow for what is copied
+     out to change in the future.  This indicates that the system should
+     attempt to copy out all extended states, though if the ucontext_t was not
+     allocated with ucontext_alloc(3C), some extended states may not be.
+
      The setcontext() function restores the user context pointed to by ucp.  A
      successful call to setcontext() does not return; program execution
      resumes at the point specified by the ucp argument passed to
      setcontext().  The ucp argument should be created either by a prior call
      to getcontext(), or by being passed as an argument to a signal handler.

@@ -38,15 +65,20 @@
      The effects of passing a ucp argument obtained from any other source are
      unspecified.
 
 RETURN VALUES
      On successful completion, setcontext() does not return and getcontext()
-     returns 0.  Otherwise, -1 is returned.
+     and getcontext_extd() returns 0.  Otherwise, -1 is returned.
 
 ERRORS
-     No errors are defined.
+     No errors are defined for getcontext() or setcontext().
 
+     The getcontext_extd() function only sets errno in some circumstances when
+     it fails.  The function may fail if:
+
+     EINVAL             flags had invalid values.
+
 USAGE
      When a signal handler is executed, the current user context is saved and
      a new context is created.  If the thread leaves the signal handler via
      longjmp(3C), then it is unspecified whether the context at the time of
      the corresponding setjmp(3C) call is restored and thus whether future

@@ -64,9 +96,9 @@
 INTERFACE STABILITY
      Committed
 
 SEE ALSO
      sigaction(2), sigaltstack(2), sigprocmask(2), bsd_signal(3C),
-     makecontext(3C), setjmp(3C), sigsetjmp(3C), ucontext.h(3HEAD),
-     attributes(7), standards(7)
+     makecontext(3C), setjmp(3C), sigsetjmp(3C), ucontext_alloc(3C),
+     ucontext.h(3HEAD), attributes(7), standards(7)
 
-illumos                        November 24, 2022                       illumos
+illumos                        January 24, 2022                        illumos