Five macros are provided for locking pages into a working set.
These macros reside in SYS$LIBRARY:LIB.MLB. For a description
of how to use these macros, see the VSI OpenVMS MACRO Compiler
Porting and User's Guide.
Three macros are used for image initialization-time lockdown, and
two macros are used for on-the-fly lockdown.
NOTE
If the code is being locked because the IPL will be raised
above 2, where page faults cannot occur, make sure that
the delimited code does not call run-time library or other
procedures. The VAX MACRO compiler generates calls to
routines to emulate certain VAX instructions. An image that
uses these macros must link against the system base image so
that references to these routines are resolved by code in a
nonpageable executive image.
For OpenVMS I64 systems, these macros are still under
development and additional OpenVMS routines are being
provided to lock working sets. See the OpenVMS I64 Release
Notes for more information.
1 – $LOCK PAGE INIT
Required in the initialization routines of an image that is using
$LOCKED_PAGE_START and $LOCKED_PAGE_END to delineate areas to be
locked at initialization time.
Format
$LOCK_PAGE_INIT [error]
1.1 – Parameters
[error]
Address to which to branch if one of the $LKWSET calls fail. If
this address is reached, R0 reflects the status of the failed
call, and R1 contains 0 if the call to lock the code failed, or 1
if that call succeeded but the call to lock the linkage section
failed.
1.2 – Description
$LOCK_PAGE_INIT creates the necessary psects and issues the
$LWKSET calls to lock into the working set the code and linkage
sections that were declared by $LOCKED_PAGE_START and $LOCKED_
PAGE_END. R0 and R1 are destroyed by this macro.
The psects locked by this macro are $LOCK_PAGE_2 and $LOCK_
LINKAGE_2. If code sections in other modules, written in other
languages, use these psects, they will be locked by an invocation
of this macro in a VAX MACRO module.
2 – $LOCKED PAGE END
Marks the end of a section of code that may be locked at image
initialization time by the $LOCK_PAGE_INIT macro.
Format
$LOCKED_PAGE_END [link_sect]
2.1 – Parameters
[link_sect]
Psect to return to if the linkage psect in effect when the
$LOCKED_PAGE_START macro was executed was not the default linkage
psect, $LINKAGE.
2.2 – Description
$LOCKED_PAGE_END is used with $LOCKED_PAGE_START to delineate
code that may be locked at image initialization time by the
$LOCK_PAGE_INIT macro. The code delineated by these macros must
contain complete routines-execution cannot fall through either
macro, nor can you branch into or out of the locked code. Any
attempt to branch into or out of the locked code section or to
fall through the macros will be flagged by the compiler with an
error.
3 – $LOCKED PAGE START
Marks the start of a section of code that may be locked at image
initialization time by the $LOCK_PAGE_INIT macro.
Format
$LOCKED_PAGE_START
There are no parameters for this macro.
3.1 – Description
$LOCKED_PAGE_START is used with $LOCKED_PAGE_END to delineate
code that may be locked at image initialization time by the
$LOCK_PAGE_INIT macro. The code delineated by these macros must
contain complete routines-execution may not fall through either
macro, nor may the locked code be branched into or out of. Any
attempt to branch into or out of the locked code section or to
fall through the macros will be flagged by the compiler with an
error.
4 – $LOCK PAGE
Marks the beginning of a section of code to be locked on-the-fly.
Format
$LOCK_PAGE [error]
4.1 – Parameters
[error]
Address to branch to if one of the $LKWSET calls fail.
4.2 – Description
This macro is placed inline in executable code and must be
followed by the $UNLOCK_PAGE macro. The $LOCK_PAGE/$UNLOCK_PAGE
macro pair creates a separate routine in a separate psect. $LOCK_
PAGE locks the pages and linkage section of this separate routine
into the working set and JSRs to it. All code between this macro
and the matching $UNLOCK_PAGE macro is included in the locked
routine and is locked down.
All registers are preserved by this macro unless the error
address parameter is present and one of the calls fail. If that
happens, R0 reflects the status of the failed call. R1 then
contains 0 if the call to lock the code failed or 1 if that call
succeeded but the call to lock the linkage section failed.
If the ERROR parameter is used, the ERROR label must be placed
outside the scope of the $LOCK_PAGE and $UNLOCK_PAGE pair. This
is because the error routine is branched to before calling the
subroutine that the $LOCK_PAGE and $UNLOCK_PAGE routines create.
Note that since the locked code is made into a separate routine,
any references to local stack storage within the routine will
have to be changed, as the stack context is no longer the same.
Also, you cannot branch into or out of the locked code from the
rest of the routine.
5 – $UNLOCK PAGE
Marks the end of a section of code to be locked on-the-fly.
Format
$UNLOCK_PAGE [error][,LINK_SECT]
5.1 – Parameters
[error]
An error address to which to branch if one of the $ULKWSET calls
fail.
[link_sect]
Linkage psect to return to if the linkage psect in effect when
the $LOCK_PAGE macro was executed was not the default linkage
psect, $LINKAGE.
5.2 – Description
$UNLOCK_PAGE returns from the locked routine created by the
$LOCK_PAGE and $UNLOCK_PAGE macro pair and then unlocks the pages
and linkage section from the working set. This macro is placed
inline in executable code after a $LOCK_PAGE macro.
All registers are preserved by this macro unless the error
address parameter is present and one of the calls fail. If that
happens, R0 reflects the status of the failed call. R1 then
contains 0 if the call to unlock the code failed or 1 if that
call succeeded but the call to unlock the linkage section failed.
If the error parameter is used, the error label must be placed
outside the scope of the $LOCK_PAGE and $UNLOCK_PAGE pair. This
is because the error routine is branched to after returning
from the subroutine created by the $LOCK_PAGE and $UNLOCK_PAGE
routines.