OpenVMS Alpha Guide to Upgrading Privileged-Code Applications

The PID in this form is typically know as the internal PID (IPID). It consists of two pieces of information, both one word in length. Figure 6-3 shows the layout.

Figure 6-3 Process ID (PID)

The low word is the process index (PIX). The PIX is used as an index into the PCB vector. This is a vector of PCB addresses. Therefore the PIX gives a quick method of determining the PCB address given a PID.

Another array, also indexed by PIX, contains a sequence number entry for each PIX. The sequence number increments every time a PIX is reused. The high word of the IPID is a copy of the value in the array for a particular PIX. This feature validates a PID to ensure that the ID is not for a process which has been deleted. The sequence number in the IPID must match the one in the sequence number array for that PIX.

The EPID is the cluster-visible PID. It consists of five parts, as Figure 6-4 shows.

Figure 6-4 Extended Process ID (EPID)

The EPID takes its low 21 bits from the two word IPID fields seen in Figure 6-3. The value of MAXPROCESSCNT determines the number of bits within the 21 bits used for the PIX (5 to 13 bits). The sequence number uses the remaining bits (8 to 16 bits). The PIX cannot be larger than 8192; the sequence number no larger than 32767. If the system is an OpenVMS cluster member, the next 10 bits of the EPID uniquely identify the PID within the cluster. They contain 8 bits of the cluster system ID (CSID) for the system, and a 2 bit sequence number. The system service SYS$GETJPI uses the high bit (31). If set, the bit specifies that the PID is a wildcard context value. This allows collecting information for all processes in the system.

6.3.1 Multithread Effects on the PID

With kernel threads implementation, the PID's definition undergoes two changes:

• MAXPROCESSCNT's maximum value is increased to 16,384.
  To do this, the maximum PIX field width for the EPID is increased by one bit. This results in shrinking the sequence number field by one bit.
• A redefinition of the sequence number.
  The redefinition of the usage of the sequence number results in it taking on a dual meaning. It continues to be used to validate a PID; it also becomes the means for determining the kernel thread ID. Instead of a single sequence number being assigned to a PIX, a range of sequence numbers are used, one for each kernel thread. Therefore, the format of a kernel thread PID is identical to that of the PID in either its IPID, or EPID representation. The PIX and sequence number fields are in the same location, and they are the same size. In the EPID, the 10 bits used to uniquely identify the PID within the cluster remain the same; this enables kernel threads to be visible clusterwide.

Every process has at least one kernel thread, the initial thread, which is always thread ID zero; therefore, given a particular PID, the PIX continues to be used as an index into the PCB and sequence vectors. A range check validates the sequence numbers.

Before kernel threads implementation, the sequence number vector (SCH$GL_SEQVEC) was a vector of words. After kernel threads implementation, it is a vector of longwords that enables range checking for sequence number validation. The low word in each longword is the base sequence number for a particular PIX, and the upper word is the next sequence number for that PIX. The sequence number for a single-threaded process must be equal to the base value. Kernel threads PID sequence numbers must fall within the base and next values.

Figure 6-5 shows the flow of range checking of sequence numbers.

Figure 6-5 Range Checking and Sequence Vectors

Similar to the fields in the PCB that migrate to the KTB, there are several status bits that need to be per thread. The interface for the SYS$GETJPI and SYS$PROCESS_SCAN system services indicates that the entire longword fields that contain the status bits can be returned. Therefore, all the status bits must remain defined as they are. The PCB specific bits are "reserved" in the KTB structure definition. Likewise, the KTB specific bits are "reserved" in the PCB. Because the PCB is really an overlaid structure with the initial thread's KTB, just the PCB status bits need to be returned for the initial thread. The status longword returned for other threads is built by first masking out the initial thread's bits, and then OR'ing the remainder with the status longword in the appropriate KTB.

If a thread in a multithreaded process requests information about itself using SYS$GETJPI (passes PID=0), then the status bits for the kernel thread it's running on are returned. Since each kernel thread has its own PID, SYS$GETJPI can be called for each of the kernel threads in a process. The return status bits are the combination of the PCB status bits and those in the KTB associated with the input PID.

This appendix contains descriptions of the OpenVMS Alpha Version 7.0 I/O data structure changes made to support 64-bit addressing.

The data structures are listed in alphabetical order. However, the individual structure members are listed in the order in which they are defined within each data structure. Note, however, that the following sections only describe new or changed structure members. Existing unchanged members are not described. In addition, unused or "fill" structure members that might be added to obtain natural alignment are not listed. Thus, you can not use the following descriptions to calculate the precise memory layout of the structures. However, you can assume that any new or changed structure members will be naturally aligned within the structure.

A.1 Pointer Size Conventions

Any unqualified use of the term pointer implies a 32-bit pointer. All 64-bit pointers will be explicitly identified as either a 64-bit or quadword pointer.

As of OpenVMS Alpha Version 7.0, a new C compiler pragma controls the pointer size. To facilitate the use of 64-bit pointers, a new header file, far_pointers.h in SYS$STARLET_C.TLB, defines types for 64-bit pointers to the intrinsic C data types.

Table A-1 summarizes the 64-bit pointer data types.

Table A-1 64-Bit Pointer Data Types

Type Name	32-Bit Analog	Description	Defined by
CHAR_PQ	char *	64-bit pointer to a char	far_pointers.h
CHAR_PPQ	char **	64-bit pointer to a CHAR_PQ	far_pointers.h
INT_PQ	int *	64-bit pointer to a 32-bit int	far_pointers.h
INT64_PQ	int64 *	64-bit pointer to a 64-bit int	far_pointers.h
UINT64_PQ	uint64 *	64-bit pointer to a 64-bit int	far_pointers.h
VOID_PQ	void *	64-bit pointer to arbitrary data	far_pointers.h
VOID_PPQ	void **	64-bit pointer to a VOID_PQ	far_pointers.h
IOSB_PQ	IOSB *	64-bit pointer to an IOSB structure	iosbdef.h
IOSB_PPQ	IOSB **	64-bit pointer to an IOSB_PQ	iosbdef.h
PTE_PQ	PTE *	64-bit pointer to a PTE	ptedef.h
PTE_PPQ	PTE **	64-bit pointer to a PTE_PQ	ptedef.h

A.2 Buffer Object Descriptor (BOD)

This section describes the additions and changes to cells in the buffer object descriptor (BOD) structure (see Table A-2).

Table A-2 BOD Structure Changes

Field	Type	Comments
bod$v_s2_window	Bit	A bit equal to BOD$M_S2_WINDOW in the bod$l_flags cell. When this bit is clear, the buffer object is mapped into the S0/S1 portion of system space and the bod$ps_svapte and bod$l_basesva cells are valid. When this bit is set, the buffer object is mapped into the S2 portion of system space and the bod$pq_va_pte and bod$pq_basesva cells are valid.
bod$pq_basepva	VOID_PQ	Process virtual address for the start of the buffer object. This cell replaces the bod$l_basepva cell.
bod$l_basepva	-	This cell will be removed. It will be replaced by the bod$pq_basepva cell.
bod$pq_basesva	VOID_PQ	System virtual address for the start of the buffer object. This cell is overlaid on the bod$l_basesva cell and this use is valid only if BOD$M_S2_WINDOW is set in bod$l_flags.
bod$pq_va_pte	PTE_PQ	Virtual address for the first system PTE that maps the buffer object. This cell is overlaid on the bod$ps_svapte cell and this use is valid only if BOD$M_S2_WINDOW is set in bod$l_flags.

A.3 Buffered I/O (BUFIO)

The existing 32-bit Buffered I/O (BUFIO) packet format will continue to be supported. In addition, a new 64-bit BUFIO packet format will be supported. These BUFIO packets are self identifying. That is, it is possible to distinguish a 32-bit from a 64-bit format BUFIO packet from information in the packet.

Although the structure type code DYN$C_BUFIO is defined and there is an expected layout for the header of buffered I/O packet there currently is no formal definition of a structure. Existing code in drivers and IOCIOPOST.MAR uses numeric constants as offsets.

The existing 32-bit BUFIO packet will be formally defined along with a new 64-bit BUFIO packet format. The 64-bit BUFIO structure format will also be used for 64-bit diagnostic buffer packets (see Table A-3).

Table A-3 BUFIO Packet

Field	Type	Comments
bufio$ps_pktdata	void *	Pointer to the buffered data within the packet.
bufio$ps_uva32	void *	32-bit pointer to user's address space. On a read function data is transfered from that user virtual address to the buffer packet during FDT processing. On a write function data is transfered to that user virtual address from the buffer packet during I/O Postprocessing. If this cell contains the value BUFIO$K_64 (-1) then the pointer to the user buffer is in bufio$pq_uva64.
bufio$w_size	unsigned short	Size of the BUFIO packet in bytes.
bufio$b_type	unsigned char	Nonpaged pool packet type code, DYN$C_BUFIO
BUFIO$K_HDRLEN32	constant	Size in bytes of the minimal buffered I/O packet header with a 32-bit user virtual address (12).
bufio$pq_uva64	VOID_PQ	64-bit pointer to user's address space. On a read function data is transfered from that user virtual address to the buffer packet during FDT processing. On a write function data is transfered to that user virtual address from the buffer packet during I/O Postprocessing. This cell contains a valid address only if the bufio$ps_uva32 cell contains the value BUFIO$K_64 (-1).
BUFIO$K_HDRLEN64	constant	Size in bytes of the minimal buffered I/O packet header with a 64-bit user virtual address (24).

A.4 CXB

The CXB structure defines the format of entries that are linked together to build a complex chained buffered I/O packet.

The CXB structure will be enhanced such that it can be used by existing code with no source changes to support a 32-bit caller's buffer address. However, the same enhanced CXB structure can be used to support a 64-bit caller's buffer address as well (see Table A-4).

Table A-4 CXB Structure Changes

Field	Type	Comments
cxb$ps_pktdata	void *	Pointer to the buffered data within the packet. This cell will be overlaid on the existing cxb$l_fl cell to reflect its current alternate use.
cxb$ps_uva32	void *	32-bit pointer to user's address space. If this cell contains the value BUFIO$K_64 (-1) then the pointer to the user buffer is in cxb$pq_uva64. This cell will be overlaid on the existing cxb$l_bl cell to reflect its current alternate use.
cxb$pq_uva64	VOID_PQ	64-bit pointer to user's address space. This cell contains a valid address only if the cxb$ps_uva32 cell contains the value BUFIO$K_64 (-1). This cell will be inserted as the last aligned quadword just before the end of the standard CXB header which is CXB$K_LENGTH bytes long.

A.5 DCBE

The DCBE structure is the Data Chain Block that is used by the OpenVMS LAN driver VMS Communications Interface (VCI). A DCBE is used to connect to a VCRP all or part of the data to be transmitted. A chain of DCBEs is used when the data is contained in more than one discontiguous buffer in virtual memory.¹

There are two mutually exclusive methods that a DCBE can use to identify the start of the buffer:

1. When the dcbe$l_buffer_address cell contains a zero, the buffer address is specified by the dcbe$l_svapte and dcbe$l_boff cells. A fixed-size primary DIOBM structure will be added to the DCBE. This embedded DIOBM structure is available for use by an upper-level VCM if it needs to derive a 32-bit SVAPTE from a 64-bit VA_PTE for the PTEs that map the buffer. The lower-level VCM will not alter this embedded DIOBM or make any assumptions about it.
2. When the dcbe$l_buffer_address cell contains the a non-zero value, this value is the system virtual address of the buffer. This method remains unchanged.

Because a VCRP can also be used as a DCBE, the named DCBE cells must be at the same offsets as their VCRP counterparts. Therefore, DCBE changes are reflected in the VCRP and changes to the common portion of the VCRP are reflected in the DCBE.

In addition, SYS$PEDRIVER overlays a DCBE with the vcrp$t_internal_stack area within the VCRP. Therefore, an increase in the size of the DCBE must be reflected by a corresponding increase in the size of the internal stack area within the VCRP (see Table A-5).

Table A-5 DCBE Structure Changes

Field	Type	Comments
dcbe$l_reserved	int32[13]	This existing vector of 6 filler longwords has been increased to 13 fill longwords to reflect the increased size of the common portion of the VCRP. The common portion of the VCRP has been increased to accommodate either an ACB64 or ACB structure.
dcbe$pq_buffer_addr64	VOID_PQ	64-bit buffer address. This cell is available for use by upper-level VCMs only. Note that this cell does not replace the dcbe$l_buffer_address cell which continues to be used by lower-level VCMs. The dcbe$pq_buffer_addr64 cell has been added after the dcbe$l_bcnt cell.
dcbe$r_diobm	DIOBM	Embedded fixed-size primary "direct I/O buffer map" structure. This DIOBM structure is available for use by upper-level VCMs that need to lock down a buffer and provide a value for the dcbe$l_svapte cell. This structure has been added just before the end of the DCBE header.

Note

¹ The DCBE should not be confused with the similarly named DCB structure. The DCB is used internally by the DECnet Phase IV NETDRIVER. As described in Section 2.2.3, the dcb$l_svapte cell value will be derived from the irp$l_svapte cell in the associated IRP and will rely on the DIOBM that's embedded in the IRP. For this reason there is no need for an embedded DIOBM in the DCB structure.

The Direct I/O Buffer Map (DIOBM) is a new structure that is used to solve the cross-process PTE problem for buffers that have been locked into memory for direct I/O.

There are two variants of the DIOBM structure. The first is the primary DIOBM structure. The primary DIOBM structure can be used in the following mutually exclusive ways:

1. To contain copies of the actual PTEs that map the buffer.
2. To point to a larger secondary DIOBM structure if the primary DIOBM structure has insufficient room for all the PTEs that map the user buffer.
3. To manage a PTE window in S0/S1 space onto the actual PTEs that map the buffer if the required PTE count exceeds the capacity of the largest allowable DIOBM structure.

Each of these methods yields a 32-bit system virtual address for the PTEs that map the buffer. This address is valid regardless of process or system context.

The fixed-size DIOBM structure contains room for exactly DIOBM$K_PTECNT_FIX (9) PTEs and is 88 bytes long. Most primary DIOBM structures are fixed-sized and embedded in other structures. For example, the IRP, IRPE, VCRP, and DCBE structures all contain an embedded fixed-sized primary DIOBM structure.

A secondary DIOBM structure can have room for up to ioc$gl_diobm_ptecnt_max PTEs and is used only for PTE copies.

Although the offsets and types for both the primary and secondary DIOBM structures are identical, for clarity, they are described in separate tables (see Table A-6 and Table A-7).

Table A-6 Primary DIOBM structure

Field	Type	Comments
diobm$ps_aux_diobm	DIOBM *	This a pointer to a secondary DIOBM structure that is valid if and only if DIOBM$M_AUX_INUSE in diobm$l_flags is set. The secondary DIOBM structure contains copies of the PTE that map the buffer. When a secondary DIOBM is used, the only use for the primary DIOBM is to locate the secondary.
diobm$l_pte_count	unsigned int	If DIOBM$M_PTE_WINDOW is clear in diobm$l_flags, this cell contains the count of PTEs that have been copied to the PTE vector diobm$q_pte_vector in this DIOBM structure. If DIOBM$M_PTE_WINDOW is set in diobm$l_flags, this cell contains the count of SPTEs that have been allocated for a PTE window in S0/S1 space to the actual PTEs that map the buffer.
diobm$w_size	unsigned short	Size of the DIOBM packet in bytes.
diobm$b_type	unsigned char	Nonpaged pool packet type code, DYN$C_MISC
diobm$b_subtype	unsigned char	Nonpaged pool packet subtype code, new DYN$C_MISC subtype code DYN$C_DIOBM
diobm$l_flags	unsigned int	Flag bits.
diobm$v_rel_dealloc	bit	A bit equal to DIOBM$M_REL_DEALLOC in the diobm$l_flags cell. If set, routine IOC_STD$RELEASE_DIOBM deallocates this DIOBM structure. The routine IOC_STD$FILL_DIOBM sets this bit on any secondary DIOBM structure that it may allocate. The routine IOC_STD$CREATE_DIOBM sets this bit on the primary DIOBM structure that it allocates.
diobm$v_pte_window	bit	A bit equal to DIOBM$M_PTE_WINDOW in the diobm$l_flags cell. This bit is set if the direct I/O buffer is too large for a DIOBM packet (the buffer requires more than ioc$gl_diobm_ptecnt_max PTEs) and a window in S0 to its PTEs has been allocated. When this bit is set diobm$l_pte_count contains the count of SPTEs that have been allocated and the diobm$l_ptew_sva cell contains the system virtual address that is mapped by the first SPTE allocated for the PTE window. This bit must be clear if diobm$v_aux_inuse is set.
diobm$v_aux_inuse	bit	A bit equal to DIOBM$M_AUX_INUSE in the diobm$l_flags cell. The diobm$ps_aux_diobm cell contains a pointer to a secondary DIOBM structure if and only if the diobm$v_aux_inuse bit is set. This bit must be clear if diobm$v_pte_window is set.
diobm$v_inuse	bit	A bit equal to DIOBM$M_INUSE in the diobm$l_flags cell. This flag is an aid to detecting inproper use of DIOBM structures and is used only by the full-checking versions of the routines in the IO_ROUTINES_MON.EXE execlet. This flag is set by the IOC_STD$FILL_DIOBM and IOC_STD$CREATE_DIOBM routines and is cleared by the IOC_STD$RELEASE_DIOBM routine. Prior to setting the flag, the IOC_STD$FILL_DIOBM routine checks this flag if the diobm$b_type cell contains the DYN$C_MISC value and diobm$b_subtype contains DYN$C_DIOBM. If the diobm$v_inuse flag is set under these conditions, the IOC_STD$FILL_DIOBM routine declares a INCONSTATE bugcheck.
diobm$v_s0pte_window	bit	A bit equal to DIOBM$M_S0PTE_WINDOW in the diobm$l_flags cell. This bit is set if the S0/S1 PTE window was used to derive a 32-bit PTE address for this buffer. When this bit is set the diobm$v_pte_window and diobm$v_aux_inuse flags must be clear and the diobm$l_pte_count cell must contain 0.
DIOBM$K_HDRLEN	constant	Size in bytes of the minimal DIOBM packet header excluding the PTE vector. This is equal to the byte offset of the diobm$q_pte_vector[0] cell (16).
diobm$q_pte_vector	PTE[diobm$l_pte_count]	Vector of diobm$l_pte_count quadword PTEs that are copies of the PTEs that map the buffer that has been locked for direct I/O. This vector is valid only if both DIOBM$M_AUX_INUSE and DIOBM$M_PTE_WINDOW in diobm$l_flags are clear.
DIOBM$K_PTECNT_FIX	constant	This constant specifies the number of PTE entries (9) that fit into the PTE vector in a fix-sized DIOBM structure.
DIOBM$K_PTECNT_MAX_UNI	constant	This constant specifies the number of PTE entries (94) that fit into the PTE vector in the largest allowable DIOBM structure on an uniprocessor system.
DIOBM$K_PTECNT_MAX_SMP	constant	This constant specifies the number of PTE entries (430) that fit into the PTE vector in the largest allowable DIOBM structure on an SMP system.
diobm$ps_ptew_sva	void *	The lowest S0/S1 space virtual address that is mapped by the PTEs that have been allocated for the window onto the direct I/O buffer PTEs. This cell is used to deallocate the PTE window. This cell is overlaid on a portion of diobm$q_pte_vector since their use is mutually exclusive. This cell is valid if and only if DIOBM$M_PTE_WINDOW in diobm$l_flags is set.
DIOBM$M_NORESWAIT	constant	This is an option bit mask for the flags parameter to the IOC_STD$FILL_DIOBM and IOC_STD$CREATE_DIOBM routines. When this option bit is set and there are insufficient resources for the needs of these routines an error status is returned to their callers instead of putting the process into a resource wait state.

Table A-7 Secondary DIOBM structure

Field	Type	Comments
diobm$ps_aux_diobm	DIOBM *	This cell must be zero in a secondary DIOBM structure.
diobm$l_pte_count	unsigned int	Contains the number of PTEs that can fit into the diobm$q_pte_vector in this DIOBM structure.
diobm$w_size	unsigned short	Size of the DIOBM packet in bytes.
diobm$b_type	unsigned char	Nonpaged pool packet type code, DYN$C_MISC
diobm$b_subtype	unsigned char	Nonpaged pool packet subtype code, new DYN$C_MISC subtype code DYN$C_DIOBM
diobm$l_flags	unsigned int	Flag bits.
diobm$v_rel_dealloc	bit	A bit equal to DIOBM$M_REL_DEALLOC in the diobm$l_flags cell. If set, routine IOC_STD$RELEASE_DIOBM deallocates this DIOBM structure.
diobm$v_pte_window	bit	A bit equal to DIOBM$M_PTE_WINDOW in the diobm$l_flags cell. This bit must be clear in a secondary DIOBM structure.
diobm$v_aux_inuse	bit	A bit equal to DIOBM$M_AUX_INUSE in the diobm$l_flags cell. This bit must be clear in a secondary DIOBM structure.
diobm$v_s0pte_window	bit	A bit equal to DIOBM$M_S0PTE_WINDOW in the diobm$l_flags cell. This bit must be clear in a secondary DIOBM structure.
diobm$q_pte_vector	PTE[diobm$l_pte_count]	Vector of diobm$l_pte_count quadword PTEs that are copies of the PTEs that map the buffer that has been locked for direct I/O.

A.7 Function Decision Table (FDT)

This section describes the additions to the driver Function Decision Table (FDT) structure (see Table A-8).

Table A-8 FDT Structure Changes

Field	Type	Comments
fdt$q_ok64bit	unsigned int64	A 64-bit mask corresponding to the 64 possible I/O function codes. The corresponding bit is set if the function supports a 64-bit $QIO p1 parameter value. This cell is initialized to zero by the MACRO-32 macro FDT_INI, the BLISS macro FDTAB, and in the prototype FDT, DRIVER$FDT, which is used by drivers written in C. This cell has been added to the end of the existing FDT structure.

A.8 I/O Request Packet (IRP)

This section describes the additions and changes to cells in the I/O Request Packet (IRP) structure. The significant IRP changes are:

1. The IRP resembles a 64-bit capable ACB64 structure instead of the existing ACB structure.
2. A fixed-size primary DIOBM is embedded in the IRP for use in deriving a 32-bit system virtual address for the PTEs that map a buffer locked into memory for direct I/O.
3. The IRP cells that contain copies of the 64-bit $QIO parameter values and the caller's IOSB address has been expanded from 32-bits to 64-bits.
4. Any cells overlaid on the irp$l_ast, irp$l_astprm, or irp$l_iosb cells moves to the low-order longword of their quadword replacements.
5. Alternative cell names have been defined for the ast, astprm, and iosb cells that can be used for arbitrary parameters in internal IRPs.

  6466P005.HTM
  OSSG Documentation
  22-NOV-1996 13:11:36.84

Copyright © Digital Equipment Corporation 1996. All Rights Reserved.

Legal