.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" 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
functions get and set the extended register state of the thread
.Fa lwpid
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 .
.Pp
Processes must be stopped prior to obtaining the register state of
individual threads.
Processes may be stopped with
.Xr Pstop 3PROC .
.Pp
The
.Sy prxregset_t
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
functions return
.Sy 0
and get or set the register state.
Otherwise,
.Sy -1
is returned and
.Sy errno
is set to indicate the error.
.Sh ERRORS
For a full list of possible errors see the
.Sy DIAGNOSTICS
section in
.Xr proc 5 .
.Pp
The
.Fn Plwp_getxregs
and
.Fn Plwp_setxregs
function will fail if:
.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
in
.Xr libproc 3LIB .
.Sh SEE ALSO
.Xr libproc 3LIB ,
.Xr Plwp_getfpregs 3PROC ,
.Xr Plwp_getregs 3PROC ,
.Xr Plwp_setfpregs 3PROC ,
.Xr Plwp_setregs 3PROC ,
.Xr Pstop 3PROC ,
.Xr proc 5