base-ij-webrev Cdiff usr/src/man/man3proc/Plwp

Print this page

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


*** 8,41 ****
  .\" source.  A copy of the CDDL is also available via the Internet at
  .\" http://www.illumos.org/license/CDDL.
  .\"
  .\"
  .\" Copyright 2015 Joyent, Inc.
  .\"
! .Dd May 11, 2016
  .Dt PLWP_GETXREGS 3PROC
  .Os
  .Sh NAME
  .Nm Plwp_getxregs ,
! .Nm Plwp_setxregs
  .Nd get and set extended register state
  .Sh LIBRARY
  .Lb libproc
  .Sh SYNOPSIS
  .In libproc.h
  .Ft int
  .Fo Plwp_getxregs
  .Fa "struct ps_prochandle *P"
  .Fa "lwpid_t lwpid"
  .Fa "prxregset_t *xregs"
  .Fc
  .Ft int
  .Fo Plwp_setxregs
  .Fa "struct ps_prochandle *P"
  .Fa "lwpid_t lwpid"
  .Fa "const prxregset_t *xregs"
  .Fc
  .Sh DESCRIPTION
  The
  .Fn Plwp_getxregs
  and
  .Fn Plwp_setxregs
--- 8,64 ----
  .\" source.  A copy of the CDDL is also available via the Internet at
  .\" http://www.illumos.org/license/CDDL.
  .\"
  .\"
  .\" Copyright 2015 Joyent, Inc.
+ .\" Copyright 2023 Oxide Computer Company
  .\"
! .Dd January 19, 2023
  .Dt PLWP_GETXREGS 3PROC
  .Os
  .Sh NAME
  .Nm Plwp_getxregs ,
! .Nm Plwp_freexregs ,
! .Nm Plwp_setxregs ,
! .Nm Lgetxregs ,
! .Nm Lsetxregs
  .Nd get and set extended register state
  .Sh LIBRARY
  .Lb libproc
  .Sh SYNOPSIS
  .In libproc.h
  .Ft int
  .Fo Plwp_getxregs
  .Fa "struct ps_prochandle *P"
  .Fa "lwpid_t lwpid"
+ .Fa "prxregset_t **xregsp"
+ .Fa "size_t *sizep"
+ .Fc
+ .Ft int
+ .Fo Plwp_freexregs
+ .Fa "struct ps_prochandle *P"
+ .Fa "lwpid_t lwpid"
  .Fa "prxregset_t *xregs"
+ .Fa "size_t size"
  .Fc
  .Ft int
  .Fo Plwp_setxregs
  .Fa "struct ps_prochandle *P"
  .Fa "lwpid_t lwpid"
  .Fa "const prxregset_t *xregs"
  .Fc
+ .Ft int
+ .Fo Lgetxregs
+ .Fa "struct ps_lwphandle *L"
+ .Fa "prxregset_t **xregsp"
+ .Fa "size_t *sizep"
+ .Fc
+ .Ft int
+ .Fo Lsetxregs
+ .Fa "struct ps_lwphandle *L"
+ .Fa "const prxregset_t *xregs"
+ .Fc
  .Sh DESCRIPTION
  The
  .Fn Plwp_getxregs
  and
  .Fn Plwp_setxregs
*** 44,64 ****
  in the process handle
  .Fa P .
  .Pp
  The extended register state is defined by the architecture.
  These registers may refer to optional registers that have become common on the
! platform, but are not part of the standard ABI and thus not covered by
  functions such as
  .Xr Plwp_getregs 3PROC
  and
  .Xr Plwp_getfpregs 3PROC .
  .Pp
  The
  .Fn Plwp_getxregs
! function gets the extended register state information and places it into
! .Fa xregs .
! Where as the
  .Fn Plwp_setxregs
  function sets the extended register state information in
  .Fa xregs
  for the process handle
  .Fa P .
--- 67,115 ----
  in the process handle
  .Fa P .
  .Pp
  The extended register state is defined by the architecture.
  These registers may refer to optional registers that have become common on the
! platform, but are not part of the traditional ABI and thus not covered by
  functions such as
  .Xr Plwp_getregs 3PROC
  and
  .Xr Plwp_getfpregs 3PROC .
+ Support for the extended registers varies based on the architecture and
+ varies based on the specific system.
+ For example, on x86 based CPUs the xregs functionality requires the x86
+ xsave functionality to be supported.
  .Pp
  The
  .Fn Plwp_getxregs
! function gets the extended register state information, allocates the
! appropriate sized buffer for it, and places a pointer to that buffer
! into
! .Fa xregs
! and updates
! .Fa sizep
! to indicate the size of the allocated structure.
! Due to the fact that hardware has varying sized extended register sets,
! the exact size of the structure can vary between different running
! systems and core files.
! It is also possible that some processor extensions are enabled at
! process runtime, leading for this to further be different between
! different processes on the same system.
! As such, all of the different platform instantiations of the
! .Vt prxregset_t
! end up generally being opaque structures that can be cast to something
! more specific that also includes its size.
! .Pp
! The obtained
! .Vt prxregset_t
! in
! .Fa xregsp
! must be freed by the caller with the
! .Fn Plwp_freexregs
! function.
! .Pp
! The
  .Fn Plwp_setxregs
  function sets the extended register state information in
  .Fa xregs
  for the process handle
  .Fa P .
*** 73,82 ****
--- 124,151 ----
  structure is described in
  .Xr proc 5 .
  .Pp
  One may not set the register values of a process that is not an active
  process, e.g. a process handle that refers to a file or a core file.
+ .Pp
+ The
+ .Fn Lgetxregs
+ and
+ .Fn Lsetxregs
+ functions are equivalent to the
+ .Fn Plwp_getxregs
+ and
+ .Fn Plwp_setxregs
+ functions except that they operate on a specific thread identified by
+ the handle
+ .Fa L
+ and only require that the thread in question be stopped.
+ Data allocated with the
+ .Fn Lgetxregs
+ functions should be freed with the
+ .Fn Plwp_freexregs
+ function.
  .Sh RETURN VALUES
  Upon successful completion, the
  .Fn Plwp_getxregs
  and
  .Fn Plwp_setxregs
*** 102,134 ****
  .Bl -tag -width Er
  .It Er ENODATA
  The process handle
  .Fa P
  does not have any extended register state information.
  .It Er EBUSY
  The process handle
  .Fa P
  refers to a live process and it is not stopped.
  .It Er ENOENT
! The process handle
! .Fa P
! refers to a live process and there is no thread with id
! .Fa lwpid .
! .It Er EINVAL
! The process handle
! .Fa P
! refers to a core file and there is no thread with id
! .Fa lwpid .
  .El
- .Sh ARCHITECTURE
  The
! .Fn Plwp_getxregs
  and
! .Fn Plwp_setxregs
! functions are only available on
! .Sy SPARC
! platforms.
  .Sh INTERFACE STABILITY
  .Sy Uncommitted
  .Sh MT-LEVEL
  See
  .Sy LOCKING
--- 171,207 ----
  .Bl -tag -width Er
  .It Er ENODATA
  The process handle
  .Fa P
  does not have any extended register state information.
+ This generally happens because the platform does not support it.
  .It Er EBUSY
  The process handle
  .Fa P
  refers to a live process and it is not stopped.
  .It Er ENOENT
! There is no thread with id
! .Fa lwpid
! in the process handle
! .Fa P .
  .El
  The
! .Fn Lgetxregs
  and
! .Fn Lsetxregs
! function will fail if:
! .Bl -tag -width Er
! .It Er ENODATA
! The thread handle
! .Fa L
! does not have any extended register state information.
! This generally happens because the platform does not support it.
! .It Er EBUSY
! The thread handle
! .Fa L
! refers to a live process and the thread is not stopped.
! .El
  .Sh INTERFACE STABILITY
  .Sy Uncommitted
  .Sh MT-LEVEL
  See
  .Sy LOCKING