Document revision date: 30 March 2001

## OpenVMS Alpha Guide to Upgrading Privileged-Code Applications

Previous | Contents | Index

### 2.4.3 Scheduling Routines

Code that calls any of the scheduling routines that previously took the current PCB as a parameter must be changed to pass the current KTB. These scheduling routines are as follows:

EXE$KERNEL_WAIT | SCH$WAIT_PROC
EXE$KERNEL_WAIT_PS | SCH$UNWAIT
SCH$RESOURCE_WAIT | RPTEVT macro
SCH$RESOURCE_WAIT_PS | SCH$REPORT_EVENT
SCH$RESOURCE_WAIT_SETUP | SCH$CHANGE_CUR_PRIORITY
SCH$CHSE | SCH$REQUIRE_CAPABILITY
SCH$CHSEP | SCH$RELEASE_CAPABILITY

Code that calls any of the scheduling routines that previously took the process PID as a parameter must be changed to pass the thread's PID. These scheduling routines are as follows:

SCH$POSTEF | SCH$WAKE

### 2.4.4 New MWAIT State

A thread that is waiting for ownership of the inner-mode semaphore may be put into MWAIT. The KTB$L_EFWM field contains a process-specific MWAIT code. The low word of the field contains RSN$_INNER_MODE, and the upper word contains the process index from the PID.

### 2.4.5 System Services Dispatching

The system services dispatcher has historically passed the PCB address to the inner-mode services. This is still true with kernel threads. The current KTB is not passed to the services.

### 2.4.6 Asynchronous System Traps (ASTs)

The ACB$L_PID field in the ACB should represent the kernel thread to which the AST is targeted. All other AST context is the same.

Inner-mode ASTs can be delivered on whichever kernel thread is currently in inner mode. ASTs that have the ACB$V_THREAD_SAFE bit set will always be delivered to the targeted thread, regardless of other-inner mode activity. Use extreme care if this is used. Attempted thread-safe AST delivery to a kernel thread that has been deleted is delivered to the initial thread.

### 2.4.7 TB Invalidation and Macros

With the kernel threads implementation, the address space for a process can be active on multiple CPUs at the same time. Any privileged code that creates or deletes process virtual address space "by hand" must do the proper invalidation across all CPUs. A set of macros have been created for BLISS, C, and MACRO-32 to facilitate translation buffer invalidation. The macros are as follows:

- TBI_DATA_64
- TBI_SINGLE
- TBI_ALL

Table 2-1 describes the arguments for the TBI_DATA_64 and TBI_SINGLE macros. Note that the difference between TBI_DATA_64 and TBI_SINGLE is that the former invalidates an entry from the data translation buffer only, while the latter invalidates an entry from both the data and the instruction translation buffers.

Table 2-1 Arguments for TBI_DATA_64 and TBI_SINGLE
Keyword | Value | Meaning
--- | --- | ---
ADDR | = The virtual address to be invalidated. The address can be either a 64-bit VA or a sign-extended 32-bit VA. For MACRO-32, the address must be specified in a register. |
ENVIRON | = THIS_CPU_ONLY | Indicates that this invocation of TBIS is to be executed strictly within the context of the local CPU only. Thus, no attempt is made whatsoever to extend the TBIS request to any CPU or other "processor" that might exist within the system.
| = ASSUME_PRIVATE | Indicates that this is a threads environment and that the address should be treated as a private address and not be checked. Therefore, in an SMP environment, it is necessary to do the invalidate to other CPUs that are running a kernel thread from this process. This argument is used for system space addresses that should be treated as private to the process.
| = ASSUME_SHARED | Indicates that this invocation of TBIS should be broadcast to all other CPUs in the system. ASSUME_SHARED is the opposite of THIS_CPU_ONLY.
| = LOCAL | This is now obsolete and generates an error.
| = anything other than the above | Forces the TB invalidate to be extended to all components of the system that may have cached PTEs.
PCBADDR | = Address of current process control block. Default is NO_PCB, which means that a PCB address does not need to be specified. The default is R31 for the MACRO-32 macros. | This argument must be specified if the address to be invalidated is process-private (either ENVIRON=ASSUME_PRIVATE or no keyword for the ENVIRON qualifier was specified).

Table 2-2 describes the arguments for the TBI_ALL macro.

Table 2-2 Arguments for TBI_ALL
Keyword | Value | Meaning
--- | --- | ---
ENVIRON | = THIS_CPU_ONLY | Indicates that this invocation of TBI_ALL is to be executed strictly within the context of the local CPU. No attempt is made to extend the TBIA request to any CPU or other "processor" that might exist within the system.
| = LOCAL | This is now obsolete and generates an error.
| = anything other than the above | Forces the TB invalidate to be extended to all components of the system that may have cached PTEs.

### 2.4.8 New PCB/KTB Fields

Table 2-3 shows the new PCB and KTB fields as defined by PCBDEF.

Table 2-3 New PCB/KTB Fields
Field | Meaning
--- | ---
PCB$K_MAX_KT_COUNT | Maximum number of kernel threads
PCB$L_ACTIVE_CPUS | CPUs owned by this process
PCB$L_TQUANTUM | Per-user thread quantum
PCB$L_MULTITHREAD | Maximum thread count
PCB$L_KT_COUNT | Current thread count
PCB$L_KT_HIGH | Highest KTB vector entry used
PCB$L_KTBVEC | KTB vector address
PCB$L_IM_ASTQFL_SPK | Special kernel AST queue forward link (head)
PCB$L_IM_ASTQBL_SPK | Special kernel AST queue back link (tail)
PCB$L_IM_ASTQFL_K | Kernel AST queue forward link (head)
PCB$L_IM_ASTQBL_K | Kernel AST queue back link (tail)
PCB$L_IM_ASTQFL_E | Executive AST queue forward link (head)
PCB$L_IM_ASTQBL_E | Executive AST queue back link (tail)
PCB$L_INITIAL_KTB | Initital KTB, overlays KTB$L_PCB
KTB$L_PCB | PCB address, overlays PCB$L_INITIAL_KTB
KTB$L_FRED | Address of FRED block
KTB$L_PER_KT_AREA | Address of per-kernel thread data area
KTB$L_TQUANT | Remaining per-user thread quantum
KTB$L_QUANT | Remaining per-kernel thread quantum
KTB$L_TM_CALLBACKS | Address of thread manager callback vector

### 2.4.9 CTL$AL_STACK and CTL$AL_STACKLIM

The two arrays containing stack bounds information are now quadwords. The arrays are now CTL$AQ_STACK and CTL$AQ_STACKLIM and are still indexed by access mode. The entries are QUADWORDS.

The arrays pointed to by these two data cells represent only the stack pointers for the initial kernel thread. For a process with multiple kernel threads, the stack arrays are in the per-kernel thread data area. The address of this structure can be found using the KTB$L_PER_KT_AREA field. These fields are defined in PKTADEF. The initial thread has a permanent per-kernel thread, so no distinction is needed between the initial thread and other threads when accessing this data. Table 2-4 shows the stack arrays.

Table 2-4 Stack Arrays
Array | Meaning
--- | ---
PKTA$Q_STACK | STACK pointer array
PKTA$Q_STACKLIM | STACK limit pointer array

### 2.4.10 Floating-Point Register and Execution Data Blocks (FREDs)

The FRED is defined by FREDDEF. The KTB$L_FRED field in the KTB points to the FRED block. The section of the PHD that contains the HWPCB and floating-point register save area for the initial thread is identical to the layout of the FRED. Therefore, no distinction is needed between the initial thread and other threads when accessing this data.

## 2.5 Registering Images That Have Version Dependencies

Note The information in this section does not apply to device drivers, nor to any images that reference the following data structures: BOD CDRP CXB DCBE FDT IRP IRPE PFN PHD UCB VCRP

The need for change in any image (including device drivers, as well as privileged applications linked against SYS$BASE_IMAGE.EXE) is normally detected by a system version check. That check is designed to prevent an application that may need change from producing incorrect results or causing system failures.

The version checks do not necessarily mean that the applications require any change. Compaq recommends that you perform some analysis to determine compatibility for privileged images before you run them on Version 7.0 systems.

OpenVMS Alpha Version 7.0 provides an Image Registry facility that may obviate the need for relinking images when you upgrade from previous versions of OpenVMS Alpha. The Image Registry is a central registry of images (including layered products, customer applications, and third-party software) that have version dependencies but have been identified as being compatible with the OpenVMS operating system software. The products in the registry are exempted from version checking.

The Image Registry facility has several benefits, particularly when you have only image files, not source or object files. In addition, it eases version compatibility problems on mixed-version clusters because the same images can be used on all nodes. It also simplifies the addition of third-party software and device drivers to the system.

The registry is a file that contains registered images. These images include main images (images that you can run directly), shared libraries, and device drivers that are identified by name, the image identification string, and the link time of the image. The registered images bypass normal system version checking in the INSTALL, system image loader, and image activator phases. With the Image Registry facility, images for different versions of applications can be registered independently.

Images linked as part of installation need not be registered because they match the version of the running system. However, linking during installation cannot ensure the absence of system version dependencies.

### 2.5.1 Version Identification (ID) Number Change to Three Subsystems

The OpenVMS executive defines 18 logical subsystems. Each of these subsystems contains its own version identification (ID) number. This modularization makes it possible for OpenVMS releases to include changes to a portion of the executive, impacting only those privileged programs which use that portion of the executive.

For OpenVMS ALpha Version 7.0, the following 3 subsystems have changed, and their version IDs have been incremented:

> I/O
> Memory Management
> Process Scheduling

Developers should check privileged code (that is, any image linked against the system symbol table SYS$BASE_IMAGE.EXE) to determine whether the image is affected by the changes to the subsystems. If the code is affected, the developer should make any necessary changes.

## Chapter 3
Replacements for Removed Privileged Symbols

This chapter describes the closest equivalent mechanism to a number of internal routines, data structure cells, and system data cells that have been removed in OpenVMS Alpha Version 7.0.

Each table lists the previous name, any replacements, and a brief explanation.

Important The internal data structure fields, routines, macros, and data cells described in this chapter should not be interpreted as being part of the documented interfaces that drivers or other privileged software should routinely depend on. If you were using the removed mechanism correctly, this chapter will assist you in using the closest equivalent in OpenVMS Alpha Version 7.0. However, you should not use this as an opportunity to start using these mechanisms. Doing so is likely to increase the work required to maintain compatibility of your privileged software with future releases of OpenVMS.

## 3.1 Removed Date Structure Fields

Table 3-1 lists the data structure fields that have been removed as of OpenVMS Alpha Version 7.0.

Table 3-1 Removed Date Structure Fields
Removed Field | Replacement | Comments
--- | --- | ---
BOD$L_BASEPVA | BOD$PQ_BASEPVA | 64-bit process virtual address of buffer mapped by the buffer object. See Appendix A.
CDRP$L_AST | cdrp$pq_acb64_ast | Increased to a quadword and renamed.
CDRP$L_ASTPRM | CDRP$Q_A | See Appendix A.
CDRP$L_IOSB | CDRP$PQ_IOSB | See Appendix A.
CPT$L_IOVA | CPT$PQ_IOVA | Increased to a quadword and renamed.
DMP$M_BITS_12_15 | Still have this field. | Same value.
DMP$S_BITS_12_15 | Still have this field. | Same value.
DMP$V_BITS_12_15 | Still have this field. | Same value.
DYN$C_F64_F64DATA | TBS---Dollar |
DYN$C_NET_TIM_TEB | DYN$C_NET_TIM_NTEB | Renamed because the DECnet structure it indicates (network timer element block) was renamed from TEB to NTEB.
FDT_CONTEXT$L_QIO_R1_VALUE | FDT_CONTEXT$Q_QIO_R1_VALUE | See Appendix A.
IRP$L_AST | IRP$PQ_ACB64_AST | Removed to ensure that any reference to the $QIO `astadr` via a 32-bit address and `astprm` as a 32-bit value are detected at compile-time or link-time.
IRP$L_ASTPRM | IRP$Q_ACB64_ASTPRM | Removed to ensure that any reference to the $QIO `astadr` via a 32-bit address and `astprm` as a 32-bit value are detected at compile-time or link-time.
IRP$L_IOSB | IRP$PQ_IOSB | Removed to ensure that any reference to the $QIO `iosb` via a 32-bit address is detected at compile-time or link-time.
IRPE$L_BCNT1 | IRPE$L_BCNT | See Appendix A.
IRPE$L_BCNT2 | None. | Removed.
IRPE$L_BOFF1 | IRPE$L_BOFF | See Appendix A.
IRPE$L_BOFF2 | None. | Removed.
IRPE$L_SVAPTE1 | IRPE$L_SVAPTE |
IRPE$L_SVAPTE2 | None. | Removed.
LCKCTX$L_CPLADR | LCKCTX$PQ_CPLADR | Increased in length to quadword.
LCKCTX$L_CPLPRM | LCKCTX$Q_CPLPRM | Increased in length to quadword.
LCKCTX$L_CR3 | LCKCTX$Q_CR3 | Increased in length to quadword.
LCKCTX$L_CR4 | LCKCTX$Q_CR4 | Increased in length to quadword.
LCKCTX$L_CR5 | LCKCTX$Q_CR5 | Increased in length to quadword.
LCKCTX$L_CRETADR | LCKCTX$PQ_CREADR | Increased in length to quadword.
LCKCTX$L_CTX_PRM1 | LCKCTX$Q_CTX_PRM1 | Increased in length to quadword.
LCKCTX$L_CTX_PRM2 | LCKCTX$Q_CTX_PRM2 | Increased in length to quadword.
LCKCTX$L_CTX_PRM3 | LCKCTX$Q_CTX_PRM3 | Increased in length to quadword.
LCKCTX$L_RET1 | LCKCTX$PQ_RET1 | Increased in length to quadword.
LCKCTX$L_TMP1 | LCKCTX$Q_TMP1 | Increased in length to quadword.
LKB$C_ACBLEN | Removed. |
LKB$K_ACBLEN | Removed. |
LKB$L_AST | LKB$PQ_AST | Increased in length to quadword.
LKB$L_ASTPRM | LKB$Q_ASTPRM | Increased in length to quadword.
LKB$L_BLKASTADR | LKB$PQ_CPLASTADR | Increased in length to quadword.
LKB$L_CPLASTADR | LKB$PQ_CPLASTADR | Increased in length to quadword.
LKB$L_LKSB | LKB$PQ_LKSB | Increased in length to quadword.
LKB$L_OLDASTPRM | LKB$Q_OLDASTPRM | Increased in length to quadword.
LKB$L_OLDBLKAST | LKB$PQ_OLDBLKAST | Increased in length to quadword.
LMB$C_GBL | No name change. | Value changed from 2 to 3.
LMB$C_PROCESS | No name change. | Value changed from 3 to 4.
LMB$C_S0 | LMB$C_S0S1 | Value = 1
LMB$C_SPT | LMB$C_SPTW | Not guaranteed to be in a dump.
LMB$L_BAD_MEM_END | LMB$PQ_BAD_MEM_END | Supports a 64-bit address.
LMB$L_BAD_MEM_START | LMB$PQ_BAD_MEM_START | Supports a 64-bit address.
LMB$L_HOLE_START_VA | LMB$PQ_BAD_MEM_START | Supports a 64-bit address.
LMB$L_HOLE_TOTAL_PAGES | LMB$Q_HOLE_TOTAL_PAGES | Supports a 64-bit address.
MMG$C_PTSPACE_OFFSET MMG$K_PTSPACE_OFFSET | MMG$GL_L1_INDEX | Compile-time constant that defined a fixed base address for page table address space. This has been replaced by a run-time mechanism which chooses a base address for page table address space during bootstrap, with the index of level 1 page table entry used to map the page tables stored in the new data cell.
PCB$L_ADB_LINK | None | Supported a feature that was never implemented.
PCB$L_PSX_ACTPRM | PCB$Q_PSX_ACTPRM | Increased in length to quadword.
PCB$L_TOTAL_EVTAST | None | Supported a feature that was never implemented.
PFN$C_ENTRY_SHIFT_SIZE | None | The size of a single PFN database entry was formerly a power of two. As of Version 7.0, that is no longer true and the symbol was deleted.
PFN$L_PTE |  | This offset in the PFN database was replaced with a new PTE backpointer mechanism that is capable of supporting page table entries that reside in 64-bit virtual address space. Any code that formerly touched PFN$L_PTE must be recoded to use one of the following macros supplied in LIB.MLB: ACCESS_BACKPOINTER ESTABLISH_BACKPOINTER TEST_BACKPOINTER
| ACCESS_BACKPOINTER | Accepts a PFN database entry address and returns a virtual address at which you may access the PTE that maps that PFN. This replaces a fetch of a SVAPTE from PFN$L_PTE, which would subsequently be used as an operand for a memory read or write instruction.
| ESTABLISH_BACKPOINTER | Replaces a write of a SVAPTE to PFN$L_PTE.
| TEST_BACKPOINTER | Replaces a test for zero in PFN$L_PTE.
PFN$L_REFCNT | INCREF DECREF | This offset in the PFN database was replaced with a differently sized offset that is packed together with other fields in the PFN database. The supplied macro INCREF should be used to replace any existing increment of the value in PFN$L_REFCNT, while DECREF should be used to replace any existing decrement.
PFN$L_WSLX | PFN$L_WSLX_QW | This offset was renamed to reflect a fundamental change in working set list indexes. Prior to Version 7.0, the working set list index (WSLX) was a longword index. The WSLX has become a quadword index as of Version 7.0, therefore the name of the offset was changed to focus attention on existing code that must be changed to view the value stored at this offset as a quadword index rather than as a longword index.
PHD$C_PHDPAGCTX | None | Supported a feature that was never implemented.
PHD$L_BAK | PHD$L_BAK_ARRAY | PHD$L_BAK contained an offset to an internally maintained array which was used to support swapping of the balance slot contents. As of Version 7.0, the implementation of this array changed to better accommodate the balance slot contents. PHD$L_BAK was replaced by PHD$L_BAK_ARRRAY which is the symbolic offset from the start of the process header to where this array begins.
PHD$L_L2PT_VA | L2PTE_VA | This process header offset formerly contained the system space address of the process's level 2 page table page that was used to map P0 and P1 spaces. As of Version 7.0, the page tables no longer reside in the balance slot, and a process is no longer limited to having only one level 2 page table page. This offset was used to derive addresses of level 2 page table entries. Use the L2PTE_VA macro to derive from a given VA the address of the level 2 PTE that maps that VA.
PHD$L_L3PT_VA PHD$L_L3PT_VA_P1 | PTE_VA | These process header offsets formerly contained the system space addresses of the bases of the P0 and P1 page tables that resided in the process's balance slot. As of Version 7.0, the page tables no longer reside in the balance slot, and the conceptual overlap of the P0 and P1 page tables in virtual memory no longer exists. Use the PTE_VA macro to derive from a given VA the address of the level 3 PTE that maps that VA.
PHD$L_P0LENGTH | None | Different page table layout.
PHD$L_P1LENGTH | None | Different page table layout.
PHD$L_PSTBASMAX | PHD$L_PST_BASE_MAX | Contains new-style section index.
PHD$L_PSTBASOFF | PHD$L_PST_BASE_OFFSET | Name changed.
PHD$L_PSTFREE | PHD$L_PST_FREE | Contains new-style section index.
PHD$L_PSTLAST | PHD$L_PST_LAST | Contains new-style section index.
PHD$L_PTWSLELCK PHD$L_PTWSLEVAL | PFN database | These process header offsets formerly contained internal bookkeeping information for managing page table pages for a process. These have been replaced by a bookkeeping mechanism that resides in the PFN database entries for page table pages. It is highly unlikely that anyone is affected by this change.
PHD$L_QUANT | KTB$L_QUANT |
PHD$L_WSL | CTL$GQ_WSL | You can no longer count on WSL (data cell) following PHD, use pointer to WSL in CTL$GQ_WSL instead.
PHD$L_WSLX | None | WSLX array is no longer in PHD as a result of the new swapper design.
PTE$L_COUNT | PTE$L_FREE_COUNT | Offset to the number of free PTEs in a free PTE structure.
PTE$L_LINK | PTE$Q_INDEX | Contains an index to the next free element in the free PTE list. The contents of the field is a quadword index off the base of page table space. Free system PTEs and free global PTEs are linked together in this manner.
PTE$M_SINGLE_SPTE | PTE$M_SINGLE_PTE | A mask or flag denoting whether a free element describes a single PTE or multiple PTEs.
PTE$V_SINGLE_SPTE | None | The contents of a free PTE element are AND'ed with PTE$M_SINGLE_PTE to determine whether the element describes a single PTE.

Previous | Next | Contents | Index

| privacy and legal statement |
6466PRO_002.HTML