uc_access(3) uc_access(3)
Itanium(R)-based platforms only
NAME [Toc] [Back]
uc_access: __uc_get_reason(), __uc_get_grs(), __uc_set_grs(),
__uc_get_frs(), __uc_set_frs(), __uc_get_prs(), __uc_set_prs(),
__uc_get_brs(), __uc_set_brs(), __uc_get_ip(), __uc_set_ip(),
__uc_get_cfm(), __uc_set_cfm(), __uc_get_um(), __uc_set_um(),
__uc_get_ar_rsc(), __uc_set_ar_rsc(), __uc_get_ar_bsp(),
__uc_get_ar_bspstore(), __uc_get_ar_csd(), __uc_set_ar_csd(),
__uc_get_ar_ssd(), __uc_set_ar_ssd(), __uc_get_ar_ccv(),
__uc_set_ar_ccv(), __uc_get_ar_unat(), __uc_set_ar_unat(),
__uc_get_ar_fpsr(), __uc_set_ar_fpsr(), __uc_get_ar_pfs(),
__uc_set_ar_pfs(), __uc_get_ar_lc(), __uc_set_ar_lc(),
__uc_get_ar_ec(), __uc_set_ar_ec(), __uc_get_ed(), __uc_set_ed(),
__uc_get_rsebs(), __uc_set_rsebs(), __uc_get_rsebs64(),
__uc_set_rsebs64(), __uc_get_ar(), __uc_set_ar(), __uc_get_cr() -
ucontext_t (user context) access
SYNOPSIS [Toc] [Back]
cc [ flag... ] file... -luca [ library... ]
#include <sys/types.h>
#include <machine/sys/reg_struct.h>
#include <signal.h>
#include <uc_access.h>
int __uc_get_reason(const ucontext_t *ucp, uint16_t *value);
int __uc_get_grs(const ucontext_t *ucp, unsigned int first, unsigned
int count, uint64_t values[], unsigned int *NaT);
int __uc_set_grs(ucontext_t *ucp, unsigned int first, unsigned int
count, const uint64_t values[], unsigned int NaT);
int __uc_get_frs(const ucontext_t *ucp, unsigned int first, unsigned
int count, fp_regval_t values[]);
int __uc_set_frs(ucontext_t *ucp, unsigned int first, unsigned int
count, const fp_regval_t values[]);
int __uc_get_prs(const ucontext_t *ucp, uint64_t *values);
int __uc_set_prs(ucontext_t *ucp, uint64_t values);
int __uc_get_brs(const ucontext_t *ucp, unsigned int first, unsigned
int count, uint64_t values[]);
int __uc_set_brs(ucontext_t *ucp, unsigned int first, unsigned int
count, const uint64_t values[]);
int __uc_get_ip(const ucontext_t *ucp, uint64_t *value);
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
uc_access(3) uc_access(3)
Itanium(R)-based platforms only
int __uc_set_ip(ucontext_t *ucp, uint64_t value);
int __uc_get_cfm(const ucontext_t *ucp, uint64_t *value);
int __uc_set_cfm(ucontext_t *ucp, uint64_t value);
int __uc_get_um(const ucontext_t *ucp, uint64_t *value);
int __uc_set_um(ucontext_t *ucp, uint64_t value);
int __uc_get_ar_rsc(const ucontext_t *ucp, rsc_t *value);
int __uc_set_ar_rsc(ucontext_t *ucp, rsc_t value);
int __uc_get_ar_bsp(const ucontext_t *ucp, uint64_t *value);
int __uc_get_ar_bspstore(const ucontext_t *ucp, uint64_t *value);
int __uc_get_ar_csd(const ucontext_t *ucp, uint64_t *value);
int __uc_set_ar_csd(ucontext_t *ucp, uint64_t value);
int __uc_get_ar_ssd(const ucontext_t *ucp, uint64_t *value);
int __uc_set_ar_ssd(ucontext_t *ucp, uint64_t value);
int __uc_get_ar_ccv(const ucontext_t *ucp, uint64_t *value);
int __uc_set_ar_ccv(ucontext_t *ucp, uint64_t value);
int __uc_get_ar_unat(const ucontext_t *ucp, uint64_t *value);
int __uc_set_ar_unat(ucontext_t *ucp, uint64_t value);
int __uc_get_ar_fpsr(const ucontext_t *ucp, fpsr_t *value);
int __uc_set_ar_fpsr(ucontext_t *ucp, fpsr_t value);
int __uc_get_ar_pfs(const ucontext_t *ucp, pfs_t *value);
int __uc_set_ar_pfs(ucontext_t *ucp, pfs_t value);
int __uc_get_ar_lc(const ucontext_t *ucp, uint64_t *value);
int __uc_set_ar_lc(ucontext_t *ucp, uint64_t value);
int __uc_get_ar_ec(const ucontext_t *ucp, uint64_t *value);
int __uc_set_ar_ec(ucontext_t *ucp, uint64_t value);
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
uc_access(3) uc_access(3)
Itanium(R)-based platforms only
int __uc_get_ed(const ucontext_t *ucp, uint64_t *value);
int __uc_set_ed(ucontext_t *ucp, uint64_t value);
int __uc_get_rsebs(const ucontext_t *ucp, uint64_t *addr, unsigned int
count, uint64_t values[]);
int __uc_set_rsebs(ucontext_t *ucp, uint64_t *addr, unsigned int count,
const uint64_t values[]);
int __uc_get_rsebs64(const ucontext_t *ucp, ptr64_t addr, unsigned int
count, uint64_t values[]);
int __uc_set_rsebs64(ucontext_t *ucp, ptr64_t addr, unsigned int count,
const uint64_t values[]);
int __uc_get_ar(const ucontext_t *ucp, unsigned int reg, uint64_t
*value);
int __uc_set_ar(ucontext_t *ucp, unsigned int reg, uint64_t value);
int __uc_get_cr(const ucontext_t *ucp, unsigned int reg, uint64_t
*value);
DESCRIPTION [Toc] [Back]
The Ucontext Access interfaces allow an application to access
Itanium(R)-based register state contained inside the opaque mcontext_t
structure within the ucontext_t user context structure.
In all these interfaces, ucp is a pointer to a ucontext_t passed to
the application as the third argument to a signal handler, allocated
by the user and filled in with getcontext() or read from an
application core file.
Because a syscall occurs on a function call boundary, contexts created
in a syscall omit scratch registers and other specific values as
detailed below.
To use any of these functions, link in the ucontext access library by
specifying -luca on the compiler or linker command line.
Individual Interface Descriptions [Toc] [Back]
__uc_get_reason()
Returns (in the location referenced by the value argument)
zero if the context was created in a syscall or a non-zero
value if the context was created while handling an
interruption that occurred while running user code.
__uc_get_grs()
Returns (in the values[] array) the saved values of the
Static General Registers in the range first through first +
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
uc_access(3) uc_access(3)
Itanium(R)-based platforms only
count-1 inclusive, and (in the NaT argument) the
corresponding NaT bit values. Only Static General Registers
(GR1-GR31) may be read with this interface. Stacked General
Registers (GR32-GR127) must be read from the RSE backing
store, or the RSE Backing Store overflow area. (See
__uc_get_rsebs() below.)
The NaT bits corresponding to the requested General
Registers will be in the corresponding bits of NaT. For
example, NaT & (1 << 5) represents the Nat Bit for GR5.
If the context was created in a syscall, scratch registers
(GR2, GR3 and GR14-GR31) will read as values[X] == 0, (NaT
>> X) && 1 == 1.
__uc_set_grs()
Overwrites the saved values of the Static General Registers
in the range first through first + count-1 inclusive, with
the contents of the first count elements of the values[]
array, and overwrites the corresponding NaT bits with bits
from the NaT argument. Only Static General Registers
(GR1-GR31) may be written with this interface. Stacked
General Registers (GR32-GR127) must be written to the RSE
backing store, or the RSE Backing Store overflow area. (See
__uc_set_rsebs() below.)
The NaT bits corresponding to the specified General
Registers must be in the corresponding bits of NaT. e.g. the
NaT bit for GR5 will be overwritten with NaT & (1 << 5).
If the context was created in a syscall, an attempt to write
scratch registers (GR2, GR3 and GR14-GR31) will return
[EINVAL].
__uc_get_frs()
Returns (in the values[] array) the saved values of the
Floating-Point Registers in the range first through first +
count-1 inclusive.
If the context was created in a syscall, scratch registers
(FR6-FR15 and FR32-FR127) will read as 0.0.
__uc_set_frs()
Overwrites the saved values of the Floating-Point Registers
in the range first through first + count-1 inclusive, with
the contents of the first count elements of the values[]
array.
If the context was created in a syscall, an attempt to write
scratch registers (FR6-FR15 and FR32-FR127) will return
[EINVAL]. An attempt to set bits {127:82} of an FP value
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
uc_access(3) uc_access(3)
Itanium(R)-based platforms only
will return [EINVAL].
__uc_get_prs()
Returns (in the location referenced by the values argument)
the saved values of the Predicate Registers.
If the context was created in a syscall, scratch predicates
(PR6-PR15) will read as 0.
__uc_set_prs()
Overwrites the saved values of the Predicate Registers with
values.
If the context was created in a syscall, an attempt to set
scratch predicates (PR6-PR15) will return [EINVAL].
Attempts to clear PR[0] will be silently ignored.
__uc_get_brs()
Returns (in the values[] array) the saved values of the
Branch Registers in the range first through first + count-1
inclusive.
If the context was created in a syscall, scratch registers
(BR6-BR7) will read as 0.
__uc_set_brs()
Overwrites the saved values of the Branch Registers in the
range first through first + count-1 inclusive, with the
contents of the first count elements of the values[] array.
If the context was created in a syscall, an attempt to write
scratch registers (BR6-BR7) will return [EINVAL].
__uc_get_ip()
Returns (in the value argument) the saved value of the
Instruction Pointer Register.
If the context was created while handling an interruption,
value will be that of the next instruction to execute. The
instruction slot will be indicated by a value of 0, 1 or 2
in the low-order 2 bits of the value. For traps and
interrupts, it will point to the next instruction. For
faults, it will point to the faulting instruction. If the
context was created in a syscall, value will be the return
pointer from the system call. The low-order 2 bits of the
value will be 0.
__uc_set_ip()
Overwrites the saved value of the Instruction Pointer
Register with value.
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
uc_access(3) uc_access(3)
Itanium(R)-based platforms only
If the context was created while handling an interruption,
the instruction slot indicated by the 2 low-order bits of
value will be the next instruction to execute. If the
context was created in a syscall, an attempt to set the
instruction slot to a non-zero value will return [EINVAL].
__uc_get_cfm()
Returns (in the value argument) the saved value of the
Current Frame Marker Register.
If the context was created in a syscall, value will be the
frame marker corresponding to the function that called the
kernel.
__uc_set_cfm()
Overwrites the saved value of the Current Frame Marker
Register with value.
__uc_get_um()
Returns (in the value argument) the saved value of the User
Mask Register.
__uc_set_um()
Overwrites the saved User Mask Register with value. An
attempt to set reserved bits will return [EINVAL].
__uc_get_ed()
Returns (in the low-order bit of the value argument) the
saved value of the Exception Deferral Bit. This bit is only
saved in interruption contexts. An attempt to read it from
a context saved in a syscall will return [EINVAL].
__uc_set_ed()
Overwrites the saved Exception Deferral Bit value with the
low-order bit of the value specified. This bit is only
saved in interruption contexts. An attempt to write it in a
context saved in a syscall will return [EINVAL]. An attempt
to set it if CR.ISR.ED is not set will return [EINVAL].
__uc_get_ar_rsc()
Returns (in the value argument) the saved value of the
AR.RSC register.
__uc_set_ar_rsc()
Overwrites the saved value of the AR.RSC register with
value.
__uc_get_ar_bsp()
Returns (in the value argument) the saved value of the
AR.BSP register. By convention, this value reflects the
effects of the br.call instruction used to enter a syscall
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
uc_access(3) uc_access(3)
Itanium(R)-based platforms only
or the cover instruction used in handling an interruption.
To find the value that will be in AR.BSP when the next
instruction is executed the caller must:
1) Call __uc_get_reason() to determine whether the context
was created in a syscall or while handling an
interruption.
2) Call __uc_get_cfm() to fetch the current frame marker.
3) Adjust the AR.BSP value by CFM.sol (for a syscall
context) or CFM.sof (for an interruption context).
__uc_get_ar_bspstore()
Returns (in the value argument) the saved value of the
AR.BSPSTORE register.
__uc_get_ar_csd()
Returns (in the value argument) the saved value of the
AR.CSD register. If the context was created in a syscall,
the value is undefined.
__uc_set_ar_csd()
Overwrites the saved value of the AR.CSD register with
value. If the context was created in a syscall, this call
returns [EINVAL] with no other side-effects.
__uc_get_ar_ssd()
Returns (in the value argument) the saved value of the
AR.SSD register. If the context was created in a syscall,
the value is undefined.
__uc_set_ar_ssd()
Overwrites the saved value of the AR.SSD register with
value. If the context was created in a syscall, this call
returns [EINVAL] with no other side-effects.
__uc_get_ar_ccv()
Returns (in the value argument) the saved value of the
AR.CCV register. If the context was created in a syscall,
the value is undefined.
__uc_set_ar_ccv()
Overwrites the saved value of the AR.CCV register with
value. If the context was created in a syscall, this call
returns [EINVAL] with no other side-effects.
__uc_get_ar_unat()
Returns (in the value argument) the saved value of the
AR.UNAT register.
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003
uc_access(3) uc_access(3)
Itanium(R)-based platforms only
__uc_set_ar_unat()
Overwrites the saved value of the AR.UNAT register with
value.
__uc_get_ar_fpsr()
Returns (in the value argument) the saved value of the
AR.FPSR register.
__uc_set_ar_fpsr()
Overwrites the saved value of the AR.FPSR register with
value.
__uc_get_ar_pfs()
Returns (in the value argument) the saved value of the
AR.PFS register. In a syscall context, the value returned
is undefined. Use __uc_get_cfm() to read the current frame
marker and __uc_get_ar_ec() to read the current epilog
count.
__uc_set_ar_pfs()
Overwrites the saved value of the AR.PFS register with
value. If the context was created in a syscall,
__uc_set_ar_pfs() returns [EINVAL] with no other sideeffects.
__uc_get_ar_lc()
Returns (in the value argument) the saved value of the AR.LC
register.
__uc_set_ar_lc()
Overwrites the saved value of the AR.LC register with value.
__uc_get_ar_ec()
Returns (in the value argument) the saved value of the AR.EC
register.
__uc_set_ar_ec()
Overwrites the saved value of the AR.EC register with the
low-order 6 bits of value.
__uc_get_ar()
Returns (in the value argument) the saved value of the
Application Register specified by reg.
__uc_set_ar()
Overwrites the saved value of the Application Register
specified by reg with value.
The following Application Registers may be specified:
Hewlett-Packard Company - 8 - HP-UX 11i Version 2: August 2003
uc_access(3) uc_access(3)
Itanium(R)-based platforms only
_____________________________
|Reg |Register |Get |Set |
|____|_____________|____|____|
|16 |AR_RSC |X |X |
|____|_____________|____|____|
|17 |AR_BSP |X | |
|____|_____________|____|____|
|18 |AR_BSPSTORE |X |X |
|____|_____________|____|____|
|25 |AR_AR_CSD(*) |X |X |
|____|_____________|____|____|
|26 |AR_AR_SSD(*) |X |X |
|____|_____________|____|____|
|32 |AR_AR_CCV(*) |X |X |
|____|_____________|____|____|
|36 |AR_UNAT |X |X |
|____|_____________|____|____|
|40 |AR_FPSR |X |X |
|____|_____________|____|____|
|64 |AR_PFS(+) |X |X |
|____|_____________|____|____|
|65 |AR_LC |X |X |
|____|_____________|____|____|
|66 |AR_EC |X |X |
|____|_____________|____|____|
* AR_CSD, AR_SSD and AR_CCV are scratch registers. If the
context was created in a syscall, it will read as 0. An
attempt to write it will return [EINVAL].
+ Note the caller should consult the unwind information for
the function preceding the delivery of the signal to
determine if the AR.PFS register contained valid data.
__uc_get_cr()
Returns (in the values argument) the saved value of the
Control Register specified by reg.
Hewlett-Packard Company - 9 - HP-UX 11i Version 2: August 2003
uc_access(3) uc_access(3)
Itanium(R)-based platforms only
The following Control Registers may be specified:
________________________________________________________________
|Reg |Register |Notes |
|____|_________|________________________________________________|
|17 |CR_ISR | |
|____|_________|________________________________________________|
|20 |CR_IFA | Only valid for certain types of interruptions. |
|____|_________|________________________________________________|
|22 |CR_IIPA | |
|____|_________|________________________________________________|
If the context was created in a syscall, the control
registers will read as 0.
__uc_get_rsebs(), __uc_set_rsebs(),
__uc_get_rsebs64(), __uc_set_rsebs64
When a signal handler is invoked, the kernel attempts to
write all dirty RSE registers to the original RSE backing
store. If it is unable to do this (that is, if the memory
is not mapped) the kernel will write remaining dirty
registers to an overflow area within the ucontext_t. These
interfaces are provided to access those values saved in this
overflow area.
Use __uc_get_ar() to fetch the AR.BSP and AR.BSPSTORE
values.
____________________________________________________________________
|If the address of the value you want is |Use |
|__________________________________________|________________________|
|addr < AR.BSPSTORE |direct read/write |
|__________________________________________|________________________|
|AR.BSPSTORE <= addr < AR.BSP |__uc_[gs]et_rsebs{64}() |
|__________________________________________|________________________|
|Special case for the last NaT collection: |__uc_[gs]et_rsebs{64}() |
|addr == AR.BSP | 0x1f8 | |
|__________________________________________|________________________|
The NaT bits may be split between the AR.RNAT value and the
overflow area.
Hewlett-Packard Company - 10 - HP-UX 11i Version 2: August 2003
uc_access(3) uc_access(3)
Itanium(R)-based platforms only
___________________________________________________________________________
|Address |Where to find the NaT |
|______________________________________|___________________________________|
|addr < AR.BSPSTORE & ~0x1ff |direct read/write of backing store |
|______________________________________|___________________________________|
|AR.BSPSTORE & ~0x1ff <= addr < AR.BSP |__uc_[gs]et_rsebs{64}(addr|0x1f8) |
|______________________________________|___________________________________|
For 32-bit callers, __uc_get_rsebs() and __uc_set_rsebs()
will swizzle the addr argument.
__uc_[gs]et_rsebs64() are provided for 32-bit callers
reading a ucontext_t generated within a 64-bit application.
They differ from __uc_[gs]et_rsebs() in that the addr
argument will not be swizzled. __uc_[gs]et_rsebs64() are
only included in 32-bit versions of the library.
RETURN VALUE [Toc] [Back]
Upon successful completion, all the interfaces return 0 to indicate
success and return [EINVAL] if passed invalid arguments.
ERRORS [Toc] [Back]
The Ucontext Access interfaces will fail if any of the following
conditions are encountered:
[EINVAL] For any of the interfaces listed above, the ucp
argument is NULL, or points to a ucontext_t with
an invalid version or size.
[EINVAL] For the __uc_get_grs() or __uc_set_grs() calls the
range of registers specified by first and count
included a value outside the range 1 to 31
inclusive.
[EINVAL] For the __uc_set_grs() call, ucp was created by a
syscall and the range of registers specified by
first and count included a scratch register.
[EINVAL] For the __uc_get_frs() or __uc_set_frs() calls the
range of registers specified by first and count
included a value outside the range 2 to 127
inclusive.
[EINVAL] For the __uc_set_frs() call, ucp was created by a
syscall and the range of registers specified by
first and count included a scratch register or an
attempt is made to set bits {127:82} of an FP
value.
[EINVAL] For the __uc_set_prs() call, ucp was created by a
syscall and value included a set scratch bit or
Hewlett-Packard Company - 11 - HP-UX 11i Version 2: August 2003
uc_access(3) uc_access(3)
Itanium(R)-based platforms only
bits.
[EINVAL] For the __uc_get_brs() or __uc_set_brs() calls the
range of registers specified by first and count
included a value outside the range 0 to 7
inclusive.
[EINVAL] For the __uc_set_brs() call, ucp was created by a
syscall and the range of registers specified by
first and count included a scratch register.
[EINVAL] For the __uc_set_ip() call, ucp was created by a
syscall and the low-order two bits of value are
not zero, or ucp was not created by a syscall and
the low-order two bits of value are 0x3.
[EINVAL] For the __uc_set_cfm() call, bits outside the
range 37:0 are set.
[[EINVAL] For the __uc_set_um() call, bits outside the range
5:1 are set.
[EINVAL] For the __uc_set_ar_rsc(), __uc_set_ar_fpsr(), or
__uc_set_ar_pfs() calls, a reserved field is nonzero.
[EINVAL] For the __uc_get_ar(), __uc_set_ar(), or
__uc_get_cr() calls, an invalid register is
specified.
[EINVAL] For the __uc_set_ar() call, reg specifies a valid
register and value includes reserved bits that are
set.
[EINVAL] For the __uc_get_ed() or __uc_set_ed() calls, ucp
was created in a system call.
[EINVAL] For the __uc_set_ed() call, value includes bits
set other than the low-order bit or the low-order
bit is set and the saved CR.ISR.ED bit is clear.
[EINVAL] For the __uc_get_rsebs{64}() or
__uc_set_rsebs{64}() calls, the range of memory
locations specified by addr and count includes
values outside the range AR.BSPSTORE (inclusive)
and AR.BSP (exclusive) or if specifying the last
NaT collection location, count != 1
WARNINGS [Toc] [Back]
Only minimal argument checking is performed. The caller must take
care not to write invalid or out-of-range values to any register or
Hewlett-Packard Company - 12 - HP-UX 11i Version 2: August 2003
uc_access(3) uc_access(3)
Itanium(R)-based platforms only
register field. The effects of returning from a signal handler or
calling setcontext(2) after overwriting any register with invalid or
out-of-range values are undefined.
__uc_get_ar() is deprecated and should be used only by legacy
applications. __uc_get_ar_rsc(), __uc_get_ar_bsp(),
__uc_get_ar_bspstore(), __uc_get_ar_csd(), __uc_get_ar_ssd(),
__uc_get_ar_ccv(), __uc_get_ar_unat(), __uc_get_ar_fpsr(),
__uc_get_ar_pfs(), __uc_get_ar_lc(), and __uc_get_ar_ec() are the
recommended replacements.
__uc_set_ar() is deprecated and should be used only by legacy
applications. __uc_set_ar_rsc(), __uc_set_ar_csd(),
__uc_set_ar_ssd(), __uc_set_ar_ccv(), __uc_set_ar_unat(),
__uc_set_ar_fpsr(), __uc_set_ar_pfs(), __uc_set_ar_lc(), and
__uc_set_ar_ec() are the recommended replacements. __uc_get_cr() is
deprecated and should be used only by legacy applications.
AUTHOR [Toc] [Back]
The UContext Access library was developed by HP.
FILES [Toc] [Back]
/usr/include/uc_access.h prototypes for the interfaces
SEE ALSO [Toc] [Back]
core(4), getcontext(2), sigaction(2), signal(5), <ucontext.h>.
Hewlett-Packard Company - 13 - HP-UX 11i Version 2: August 2003 [ Back ] |
