HP OpenVMS Calling Standard

4.8.2.1 Invocation Context Block

The context of a specific procedure invocation is provided through the use of a data structure called an invocation context block (ICB). Table 4-16 describes the contents of the OpenVMS I64 invocation context block.

Table 4-16 Contents of the Invocation Context Block
Field Size Description

LIBICB$L_CONTEXT_LENGTH Longword Unsigned total length in bytes of the invocation context block. See Section 4.8.3.1.

LIBICB$V_FRAME_FLAGS 3 Bytes See Table 4-17.

LIBICB$B_BLOCK_VERSION Byte ICB version; initial value of 2 for OpenVMS I64 (1 is for OpenVMS Alpha). See Section 4.8.3.1.

LIBICB$IH_IREG 128 Quadwords Array of general registers (only those allocated; unallocated registers are uninitialized).
LIBICB$IH_IREG[0] is reserved.
IREG[1], the global data pointer, can be referenced using the symbol LIBICB$IH_GP.
IREG[12], the memory stack pointer, can be referenced using the symbol LIBICB$IH_SP.
IREG[13], the thread pointer, can be referenced using the symbol LIBICB$IH_TP.
IREG[25], the argument information register, can be referenced using the symbol LIBICB$IH_AI.

LIBICB$IH_GRNAT 2 Quadwords General register NaT collection. ¹

LIBICB$FO_F2_F31 30 Octawords Floating-point registers F2-F31. Array of floating-point register values in register format, as saved by a SPILL instruction.

LIBICB$PH_F32_F127 Quadword Pointer to array of floating point values in register format for registers F32-F127, as saved by SPILL instruction. A pointer value of 0 indicates that the contents of registers F32-F127 are not defined.

LIBICB$IH_BRANCH 8 Quadwords Array of branch registers.

LIBICB$IH_RSC Quadword Register Stack Configuration register.

LIBICB$IH_BSP Quadword Backing store pointer.

LIBICB$IH_BSPSTORE Quadword Backing store write pointer.

LIBICB$IH_RNAT Quadword RSE NaT collection register.

LIBICB$IH_CCV Quadword Compare and Exchange Value register.

LIBICB$IH_UNAT Quadword User NaT collection register.

LIBICB$IH_PFS Quadword Previous function state.

LIBICB$IH_LC Quadword Loop count register.

LIBICB$IH_EC Quadword Epilogue Count register.

LIBICB$IH_CSD Quadword Copy of the AR.CSD.

LIBICB$IH_SSD Quadword Copy of the AR.SSD.

LIBICB$Q_PRED Quadword Predicate collection register, P0-P63. This field is a bitvector with bit 0 reserved.

LIBICB$IH_PC Quadword Current instruction pointer; the slot number overlays <1:0>.

LIBICB$IH_CFM Quadword Current Frame Marker.

LIBICB$IH_UM Quadword User mask bits from PSR.

LIBICB$O_GR_VALID Octaword General Register validity mask. ²

LIBICB$L_FR_VALID Longword Floating-Point Register validity mask for registers F2-F31. ²

LIBICB$Q_BR_VALID Quadword Branch Register validity mask. ²

LIBICB$Q_AR_VALID Quadword Application Register validity mask. ²

LIBICB$Q_OTHER_VALID Quadword PC and CFM validity mask. ²

LIBICB$Q_PR_VALID Quadword Predicate Register validity mask. ²

LIBICB$IH_ORIGINAL_SPILL_ADDR Quadword Original address of the general register spill area
(normally &icb->LIBICB$IH_IREG[0]). ¹

LIBICB$IH_PSP Quadword Previous stack pointer.

LIBICB$IH_RETURN_PC Quadword Return PC.

LIBICB$IH_PREV_BSP Quadword Previous BSP

LIBICB$PH_CHFCTX_ADDR Quadword Pointer to condition handler facility context block.

LIBICB$IH_OSSD Quadword Copy of OSSD from Unwind Information Block.

LIBICB$IH_HANDLER_FV Quadword Condition Handler Function Value.

LIBICB$PH_LSDA Quadword Address of the Language Specific Data Area of the Unwind Information Block

Beginning of User Override Parameters (offset LIBICB$R_UO_BASE)

LIBICB$Q_UO_FLAGS Quadword Operational flags:
LIBICB$V_UO_FLAG_CACHE_UNWIND - Cache unwind information during a walk of the call stack. See Section 4.8.3.2.

LIBICB$IH_UO_IDENT Quadword User context variable; passed by value to the callback routines. See Section 4.8.5.

LIBICB$PH_UO_READ_MEM Quadword Pointer to user read memory routine. See Section 4.8.5.3.

LIBICB$PH_UO_GETUEINFO Quadword Pointer to user get unwind entry information routine. See Section 4.8.5.1.

LIBICB$PH_UO_GETCONTEXT Quadword Pointer to user get initial context routine. See Section 4.8.5.2.

LIBICB$PH_UO_WRITE_MEM Quadword Pointer to user write memory routine. See Section 4.8.5.4.

LIBICB$PH_UO_WRITE_REG Quadword Pointer to user write register routine. See Section 4.8.5.5.

LIBICB$PH_UO_MALLOC Quadword Pointer to user memory allocate routine. See Section 4.8.5.6.

LIBICB$PH_UO_FREE Quadword Pointer to user memory free routine. See Section 4.8.5.7.

End of user override parameters (length of LIBICB$K_UO_LENGTH)

LIBICB$L_ALERT_CODE Longword Stack walk detailed status. Alert codes are enumerated in the LIBICB include files (see Section 4.8.3.7).

LIBICB$IH_SYSTEM_DEFINED [n] n Quadwords Variable-sized area; unused and undefined at this time.

**Table 4-16 Contents of the Invocation Context Block**
Field	Size	Description
LIBICB$L_CONTEXT_LENGTH	Longword	Unsigned total length in bytes of the invocation context block. See Section 4.8.3.1.
LIBICB$V_FRAME_FLAGS	3 Bytes	See Table 4-17.
LIBICB$B_BLOCK_VERSION	Byte	ICB version; initial value of 2 for OpenVMS I64 (1 is for OpenVMS Alpha). See Section 4.8.3.1.
LIBICB$IH_IREG	128 Quadwords	Array of general registers (only those allocated; unallocated registers are uninitialized). LIBICB$IH_IREG[0] is reserved. IREG[1], the global data pointer, can be referenced using the symbol LIBICB$IH_GP. IREG[12], the memory stack pointer, can be referenced using the symbol LIBICB$IH_SP. IREG[13], the thread pointer, can be referenced using the symbol LIBICB$IH_TP. IREG[25], the argument information register, can be referenced using the symbol LIBICB$IH_AI.
LIBICB$IH_GRNAT	2 Quadwords	General register NaT collection. ¹
LIBICB$FO_F2_F31	30 Octawords	Floating-point registers F2-F31. Array of floating-point register values in register format, as saved by a SPILL instruction.
LIBICB$PH_F32_F127	Quadword	Pointer to array of floating point values in register format for registers F32-F127, as saved by SPILL instruction. A pointer value of 0 indicates that the contents of registers F32-F127 are not defined.
LIBICB$IH_BRANCH	8 Quadwords	Array of branch registers.
LIBICB$IH_RSC	Quadword	Register Stack Configuration register.
LIBICB$IH_BSP	Quadword	Backing store pointer.
LIBICB$IH_BSPSTORE	Quadword	Backing store write pointer.
LIBICB$IH_RNAT	Quadword	RSE NaT collection register.
LIBICB$IH_CCV	Quadword	Compare and Exchange Value register.
LIBICB$IH_UNAT	Quadword	User NaT collection register.
LIBICB$IH_PFS	Quadword	Previous function state.
LIBICB$IH_LC	Quadword	Loop count register.
LIBICB$IH_EC	Quadword	Epilogue Count register.
LIBICB$IH_CSD	Quadword	Copy of the AR.CSD.
LIBICB$IH_SSD	Quadword	Copy of the AR.SSD.
LIBICB$Q_PRED	Quadword	Predicate collection register, P0-P63. This field is a bitvector with bit 0 reserved.
LIBICB$IH_PC	Quadword	Current instruction pointer; the slot number overlays <1:0>.
LIBICB$IH_CFM	Quadword	Current Frame Marker.
LIBICB$IH_UM	Quadword	User mask bits from PSR.
LIBICB$O_GR_VALID	Octaword	General Register validity mask. ²
LIBICB$L_FR_VALID	Longword	Floating-Point Register validity mask for registers F2-F31. ²
LIBICB$Q_BR_VALID	Quadword	Branch Register validity mask. ²
LIBICB$Q_AR_VALID	Quadword	Application Register validity mask. ²
LIBICB$Q_OTHER_VALID	Quadword	PC and CFM validity mask. ²
LIBICB$Q_PR_VALID	Quadword	Predicate Register validity mask. ²
LIBICB$IH_ORIGINAL_SPILL_ADDR	Quadword	Original address of the general register spill area (normally &icb->LIBICB$IH_IREG[0]). ¹
LIBICB$IH_PSP	Quadword	Previous stack pointer.
LIBICB$IH_RETURN_PC	Quadword	Return PC.
LIBICB$IH_PREV_BSP	Quadword	Previous BSP
LIBICB$PH_CHFCTX_ADDR	Quadword	Pointer to condition handler facility context block.
LIBICB$IH_OSSD	Quadword	Copy of OSSD from Unwind Information Block.
LIBICB$IH_HANDLER_FV	Quadword	Condition Handler Function Value.
LIBICB$PH_LSDA	Quadword	Address of the Language Specific Data Area of the Unwind Information Block
Beginning of User Override Parameters (offset LIBICB$R_UO_BASE)
LIBICB$Q_UO_FLAGS	Quadword	Operational flags: LIBICB$V_UO_FLAG_CACHE_UNWIND - Cache unwind information during a walk of the call stack. See Section 4.8.3.2.
LIBICB$IH_UO_IDENT	Quadword	User context variable; passed by value to the callback routines. See Section 4.8.5.
LIBICB$PH_UO_READ_MEM	Quadword	Pointer to user read memory routine. See Section 4.8.5.3.
LIBICB$PH_UO_GETUEINFO	Quadword	Pointer to user get unwind entry information routine. See Section 4.8.5.1.
LIBICB$PH_UO_GETCONTEXT	Quadword	Pointer to user get initial context routine. See Section 4.8.5.2.
LIBICB$PH_UO_WRITE_MEM	Quadword	Pointer to user write memory routine. See Section 4.8.5.4.
LIBICB$PH_UO_WRITE_REG	Quadword	Pointer to user write register routine. See Section 4.8.5.5.
LIBICB$PH_UO_MALLOC	Quadword	Pointer to user memory allocate routine. See Section 4.8.5.6.
LIBICB$PH_UO_FREE	Quadword	Pointer to user memory free routine. See Section 4.8.5.7.
End of user override parameters (length of LIBICB$K_UO_LENGTH)
LIBICB$L_ALERT_CODE	Longword	Stack walk detailed status. Alert codes are enumerated in the LIBICB include files (see Section 4.8.3.7).
LIBICB$IH_SYSTEM_DEFINED [n]	n Quadwords	Variable-sized area; unused and undefined at this time.

¹Bits in the field LIBICB$IH_GRNAT represent the NaT bits for the general registers. The bit position for a given register is relative to its original spill location, the base address of which is stored at LIBICB$IH_ORIGINAL_SPILL_ADDR. The first quadword of LIBICB$IH_GRNAT contains the NaT bits for R0-R63, the second quadword contains the NaT bits for R64-R127. The formula for the bit corresponding to register Rn within each quadword is

uint64 * spill = (uint64 *)icb->LIBICB$IH_ORIGINAL_SPILL_ADDR;
uint64 bitpos = (((uint64)&spill[n]) >> 3) & 63;
uint64 bitmask = 1LL << bitpos;

²The valid bit mask indicates which registers have been realized for a given invocation context. Normally, scratch registers are not realizable except for a context immediately preceding an exception or AST frame. Refer to the LIBICB include files to find the bit position for the Application Registers, AR.RSC being bit 0.

Table 4-17 Flags in LIBICB$V_FRAME_FLAGS Field of the invocation context block
Flag Description

LIBICB$V_BOTTOM_OF_STACK Set to 1 if this is the bottom of the stack and there is absolutely no previous frame.

LIBICB$V_HANDLER_PRESENT Set to 1 if this frame has a condition handler.

LIBICB$V_IN_PROLOGUE Set to 1 if the PC is in a prologue region.

LIBICB$V_IN_EPILOGUE Set to 1 if the PC is in an epilogue region.

LIBICB$V_HAS_MEM_STK_FRAME Set to 1 if this frame has a memory stack.

LIBICB$V_HAS_REG_STK_FRAME Set to 1 if this frame has a register stack.

**Table 4-17 Flags in LIBICB$V_FRAME_FLAGS Field of the invocation context block**
Flag	Description
LIBICB$V_BOTTOM_OF_STACK	Set to 1 if this is the bottom of the stack and there is absolutely no previous frame.
LIBICB$V_HANDLER_PRESENT	Set to 1 if this frame has a condition handler.
LIBICB$V_IN_PROLOGUE	Set to 1 if the PC is in a prologue region.
LIBICB$V_IN_EPILOGUE	Set to 1 if the PC is in an epilogue region.
LIBICB$V_HAS_MEM_STK_FRAME	Set to 1 if this frame has a memory stack.
LIBICB$V_HAS_REG_STK_FRAME	Set to 1 if this frame has a register stack.

Static scratch registers, unless saved and described in the unwind table information, are not realizable except for an invocation context preceding an exception or AST frame.

4.8.2.2 Invocation Context Handle

To refer to a specific procedure invocation at run time, an invocation context handle (ICH) can be used. The invocation context handle is a quadword that uniquely identifies any one of the active frames on a call stack, even when one or more of the frames correspond to procedures that have no associated stack storage.

The characteristics of the caller are used to determine the invocation context handle. If the caller has a register frame, then the RSE Backing Store Pointer (BSP) is used as the handle; otherwise, the caller's Stack Pointer is used. (The caller's Stack Pointer is sometimes called Stack Pointer on Entry or Previous Stack Pointer (PSP).)

4.8.3 Invocation Context Block Access Routines

A thread can manipulate the invocation context of any procedure in the thread's virtual address space by calling the run-time library functions described in this section.

Note

The OpenVMS I64 stack tracing routines use heap storage during the analysis of unwind descriptors. The default heap storage mechanism uses a LIBRTL implementation of the C RTL function malloc, the use of which may result in virtual memory being expanded using the $EXPREG system service. See Section 4.8.5 on how to override the defaults. See also Section 4.8.3.12.

4.8.3.1 Initializing the Invocation Context Block

When allocating a new invocation context block, the user must perform the following steps prior to calling any of the routines described in Section 4.8.3:

Allocate the block on an octaword (16-byte) boundary.
Clear (set to all zero bytes) the entire block.
Initialize the LIBICB$L_CONTEXT_LENGTH field to LIBICB$K_INVO_CONTEXT_BLK_SIZE and the LIBICB$B_BLOCK_VERSION field to LIBICB$K_INVO_CONTEXT_VERSION.
Set any required parameters in the user override portion of the invocation context block.
Set the LIBICB$V_UO_FLAG_CACHE_UNWIND flag if appropriate. See also Section 4.8.3.2 and Section 4.8.3.12 regarding subsequent use of LIB$I64_PREV_INVO_END.

Failure to do so will cause these routines to return an error status. Note that this is a change from Alpha, where initialization was not necessary.

To simplify the initialization process, the following convenience routines are provided:

LIB$I64_CREATE_INVO_CONTEXT (see Section 4.8.3.3)
LIB$I64_FREE_INVO_CONTEXT (see Section 4.8.3.4)
LIB$I64_INIT_INVO_CONTEXT (see Section 4.8.3.5)

4.8.3.2 Walking the Call Stack

During the course of program execution, it is sometimes necessary to walk the call stack. Frame-based exception handling is one case where this is done. Call stack navigation is possible only in the reverse direction (in a latest-to-earliest or top-to-bottom sequence).

To walk the call stack, perform the following steps:

Given a program state (which contains a register set), build an invocation context.
For the current routine, an initial invocation context block can be obtained by calling the LIB$I64_GET_CURR_INVO_CONTEXT routine (see Section 4.8.3.7).
Repeatedly call the LIB$I64_GET_PREV_INVO_CONTEXT routine (see Section 4.8.3.8) until the desired invocation context, or the end of the call chain, has been reached.
LIB$I64_GET_PREV_INVO_CONTEXT indicates the end of the invocation call chain if either of the following conditions is true:
- The OSSD$V_BOTTOM_OF_STACK flag is set for the target frame (see Table A-14).
- The return address (IP) of the target frame is zero.

To make the stack walk more efficient, you can set the LIBICB$V_UO_FLAG_CACHE_UNWIND flag. This causes unwind information to be carried over from one call to LIB$I64_GET_PREV_INVO_CONTEXT to the next. At the conclusion of the stack walk, you must call LIB$I64_PREV_INVO_END to free any cached unwind information. This is the recommended practice, but not the default behavior.

Compilers are allowed to optimize high-level language procedure calls in such a way that they do not appear in the invocation chain. For example, inline procedures never appear in the invocation chain.

Make no assumptions about the relative positions of any memory used for procedure frame information. There is no guarantee that successive stack frames will always appear at higher addresses.

4.8.3.3 LIB$I64_CREATE_INVO_CONTEXT

This convenience routine simplifies creating and properly initializing an invocation context block. The routine allocates an invocation context block from heap storage and initializes it according to the steps described in Section 4.8.3.1. Users of this routine should call LIB$I64_FREE_INVO_CONTEXT when the invocation context block is no longer required.

This routine sets the cache unwind flag LIBICB$V_UO_FLAG_CACHE_UNWIND in the invocation context block to speed the stack walk. Do not use this routine in conjunction with LIB$I64_INIT_INVO_CONTEXT, as the same initialization is performed by both routines.

LIB$I64_CREATE_INVO_CONTEXT ([malloc] [, free] [, ident])

Argument OpenVMS Usage Type Access Mechanism

malloc function_value procedure read by value

free function_value procedure read by value

ident user_value quadword read by value

Argument	OpenVMS Usage	Type	Access	Mechanism
malloc	function_value	procedure	read	by value
free	function_value	procedure	read	by value
ident	user_value	quadword	read	by value

Arguments:

malloc
A procedure reference for a user callback routine that allocates memory. See Section 4.8.5.6 for details of this routine. This is an optional argument. The default is to use an implementation of the C RTL routine malloc. If specified, this routine is used to allocate the invocation context block and is also placed in the invocation context block field LIBICB$PH_UO_MALLOC for use during the stack walk.

free
A procedure reference for a user callback routine that deallocates memory. This value is placed in the invocation context block field LIBICB$PH_UO_FREE. See Section 4.8.5.7 for details on this routine. This is an optional argument; however, it must be specified if malloc is specified. The default is to use an implementation of the C RTL routine free.

ident
Specifies a user ident value to be placed in the invocation context block LIBICB$IH_UO_IDENT field. In turn, this value is passed to the malloc and free routines, described in Section 4.8.5.6 and Section 4.8.5.7 respectively. This is an optional argument; the default value is zero.

Function Value Returned:

invo_context
A non-zero value represents the address of the invocation context block allocated.
A value of 0 indicates failure.

4.8.3.4 LIB$I64_FREE_INVO_CONTEXT

Deallocates an invocation context block that was previously allocated using LIB$I64_CREATE_INVO_CONTEXT. This routine calls LIB$I64_PREV_INVO_END as a convenience.

LIB$I64_FREE_INVO_CONTEXT (invo_context)

Argument OpenVMS Usage Type Access Mechanism

invo_context invo_context_blk structure modify by reference

Argument	OpenVMS Usage	Type	Access	Mechanism
invo_context	invo_context_blk	structure	modify	by reference

Argument:

invo_context
Address of an invocation context block.

Function Value Returned:

None

4.8.3.5 LIB$I64_INIT_INVO_CONTEXT

Initializes an invocation context block that the user has already allocated (on the stack, or from heap, or other storage) in accordance with Section 4.8.3.1. Use this routine as an alternative to LIB$I64_CREATE_INVO_CONTEXT, which both allocates and initializes an invocation context block.

LIB$I64_INIT_INVO_CONTEXT (invo_context, invo_version [, cache_unwind_flag])

Argument OpenVMS Usage Type Access Mechanism

invo_context invo_context_blk structure modify by reference

invo_version version_number byte read by value

cache_unwind_flag flag longword read by value

Argument	OpenVMS Usage	Type	Access	Mechanism
invo_context	invo_context_blk	structure	modify	by reference
invo_version	version_number	byte	read	by value
cache_unwind_flag	flag	longword	read	by value

Arguments:

invo_context
Address of an invocation context block.

invo_version
The value LIBICB$K_INVO_CONTEXT_VERSION. This is used to verify the operating environment.

cache_unwind_flag
A flag indicating if the cache unwind flag, LIBICB$V_UO_FLAG_CACHE_UNWIND, should be set in the invocation context block. A value of zero clears the flag; a value of one sets the flag. This is an optional argument. The default is zero.

Function Value Returned:

status
A value of 1 indicates success.
A value of 0 indicates a version number mismatch.

Contents

Index

	malloc A procedure reference for a user callback routine that allocates memory. See Section 4.8.5.6 for details of this routine. This is an optional argument. The default is to use an implementation of the C RTL routine malloc. If specified, this routine is used to allocate the invocation context block and is also placed in the invocation context block field LIBICB$PH_UO_MALLOC for use during the stack walk.
	free A procedure reference for a user callback routine that deallocates memory. This value is placed in the invocation context block field LIBICB$PH_UO_FREE. See Section 4.8.5.7 for details on this routine. This is an optional argument; however, it must be specified if malloc is specified. The default is to use an implementation of the C RTL routine free.
	ident Specifies a user ident value to be placed in the invocation context block LIBICB$IH_UO_IDENT field. In turn, this value is passed to the malloc and free routines, described in Section 4.8.5.6 and Section 4.8.5.7 respectively. This is an optional argument; the default value is zero.

	invo_context Address of an invocation context block.
	invo_version The value LIBICB$K_INVO_CONTEXT_VERSION. This is used to verify the operating environment.
	cache_unwind_flag A flag indicating if the cache unwind flag, LIBICB$V_UO_FLAG_CACHE_UNWIND, should be set in the invocation context block. A value of zero clears the flag; a value of one sets the flag. This is an optional argument. The default is zero.