uc_access(3)

NAME

uc_access: __uc_get_ar(), __uc_get_ar_bsp(), __uc_get_ar_bspstore(), __uc_get_ar_ccv(), __uc_get_ar_csd(), __uc_get_ar_ec(), __uc_get_ar_fpsr(), __uc_get_ar_lc(), __uc_get_ar_pfs(), __uc_get_ar_rsc(), __uc_get_ar_ssd(), __uc_get_ar_unat(), __uc_get_brs(), __uc_get_cfm(), __uc_get_cr(), __uc_get_ed(), __uc_get_frs(), __uc_get_grs(), __uc_get_ip(), __uc_get_prs(), __uc_get_reason(), __uc_get_rsebs(), __uc_get_rsebs64(), __uc_get_um(), __uc_set_ar(), __uc_set_ar_ccv(), __uc_set_ar_csd(), __uc_set_ar_ec(), __uc_set_ar_fpsr(), __uc_set_ar_lc(), __uc_set_ar_pfs(), __uc_set_ar_rsc(), __uc_set_ar_ssd(), __uc_set_ar_unat(), __uc_set_brs(), __uc_set_cfm(), __uc_set_ed(), __uc_set_frs(), __uc_set_grs(), __uc_set_ip(), __uc_set_prs(), __uc_set_rsebs(), __uc_set_rsebs64(), __uc_set_um() — user context access (ucontext_t)

SYNOPSIS

Command: 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);

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);

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

The Ucontext Access interfaces allow an application to access the Integrity 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

__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 + 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. For example, 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 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.

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 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.

__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 side-effects.

__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:

`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

.IP

* 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.

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.

`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

Upon successful completion, all the interfaces return 0 to indicate success and return EINVAL if passed invalid arguments.

ERRORS

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 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 non-zero.
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

Only minimal argument checking is performed. The caller must take care not to write invalid or out-of-range values to any register or 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

The UContext Access library was developed by HP.

FILES

/usr/include/uc_access.h: Prototypes for the interfaces