Updated: 11 December 1998

OpenVMS Alpha Guide to Upgrading Privileged-Code Applications

This section describes the I/O-specific additions to cells in Process Header (PHD) structure (see Table A-11).

Table A-11 PHD Structure Changes

Field	Type	Comments
phd$l_iorefc	uint32	Number of reasons to keep the PHD resident due to groups of pages locked for direct I/O. This count is incremented by MMG_STD$IOLOCK_BUF and decremented by MMG_STD$IOUNLOCK_BUF. On the zero-to-one transition of this cell, the slot reference count for the process in the PHV$GL_REFCBAS_LW vector is incremented. On the one-to-zero transition of this cell, the slot reference count for the process in the PHV$GL_REFCBAS_LW vector is decremented.

A.11 SCSI-2 Diagnose Buffer (S2DGB)

For information about S2DGB 64-bit addressing support, see the OpenVMS Alpha Guide to 64-Bit Addressing and VLM Features.

A.12 VMS Communications Request Packet (VCRP)

The VCRP structure is the VMS Communications Request Packet that is used by the OpenVMS LAN driver VMS Communications Interface (VCI). A VCRP is used to transfer data between an upper- and lower-level VCM.

The VCRP is designed so that it can be used as an ACB by an upper-level VCM. Therefore, the VCRP has been enhanced such that it can be used either as an ACB or ACB64 structure by an upper-level VCM. This allows upper-level VCMs the flexibility of providing 64-bit AST support at some time in the future without requiring another VCRP change and the forced recompilation of all VCMs (see Table A-12).

Table A-12 VCRP Structure Changes

Field	Type	Comments
vcrp$v_acb_flags_valid	bit	This is a new bit in the vcrp$b_rmod cell that corresponds to the acb$v_flags_valid bit. This bit is available for the exclusive use of upper-level VCMs.
vcrp$l_acb64x_offset	int	Offset to the ACB64X structure embedded in this VCRP. This cell corresponds to the acb$l_acb64x cell and is overlaid on vcrp$l_ast. This cell is available for the exclusive use of upper-level VCMs.
vcrp$l_acb_flags	unsigned int	This cell corresponds to the acb$l_flags cell and is overlaid on the first longword of the existing fork block filler space in the VCRP. This cell is available for the exclusive use of upper-level VCMs.
vcrp$l_thread_id	int	This cell corresponds to the acb$l_thread_pid cell and is on the second longword of the existing fork block filler space in the VCRP. Reserved for use by the Kernel Threads project.
vcrp$pq_acb64_ast	VOID_FUNC_PQ	This cell corresponds to the acb64$pq_ast cell. This cell is available for the exclusive use of upper-level VCMs.
vcrp$q_acb64_astprm	int64	This cell corresponds to the acb64$q_astprm cell. This cell is available for the exclusive use of upper-level VCMs.
vcrp$q_user_thread_id	uint64	Unique user thread identifier. Corresponds to the acb64$q_user_thread_id cell. This cell is available for the exclusive use of upper-level VCMs.
vcrp$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 vcrp$l_buffer_address cell which continues to be used by lower-level VCMs.
vcrp$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 vcrp$l_svapte cell.
vcrp$t_internal_stack	char[220]	This existing internal stack area of 92 bytes has been increased to 220 bytes to reflect the increased size of a DCBE. SYS$PEDRIVER requires that it can place a DCBE within this stack area. This space is available for the exclusive use of upper-level VCMs.

This appendix contains detailed descriptions of the changes to I/O support routines and the new I/O support routines that are available to enhance device drivers to support 64-bit addresses.

The routines are listed in alphabetical order.

B.1 ACP_STD$READBLK and ACP_STD$WRITEBLK

The routines ACP_STD$READBLK and ACP_STD$WRITEBLK are upper-level FDT routines, so their interfaces remain unchanged:

int acp_std$readblk (IRP *irp, PCB *pcb, UCB *ucb, CCB *ccb) int acp_std$writeblk (IRP *irp, PCB *pcb, UCB *ucb, CCB *ccb)

These routines obtain the address of the caller's buffer from irp->irp$l_qio_p1. These routines have been modified to obtain the full 64-bit buffer address from irp->irp$q_qio_p1 and pass it to EXE_STD$READLOCK or EXE_STD$WRITELOCK. Note, however, that the buffer size remains a longword and is obtained from irp->irp$l_qio_p2 without checking the upper 32-bits.

B.2 EXE_STD$ALLOC_BUFIO_32, EXE_STD$ALLOC_BUFIO_64

Routines EXE_STD$ALLOC_BUFIO_32 and EXE_STD$ALLOC_BUFIO_64 are new routines that device drivers can use to allocate and initialize simple buffered I/O (BUFIO) packets. The appropriate IRP and BUFIO header cells are initialized but it's up the the caller to copy any data into the packet.

The interfaces for these routines are:

int exe_std$alloc_bufio_32 (IRP *irp, PCB *pcb, void *uva, int pktsiz) int exe_std$alloc_bufio_64 (IRP *irp, PCB *pcb, VOID_PQ uva, int pktsiz)

Table B-1 summarizes the use of the arguments.

Table B-1 EXE_STD$ALLOC_BUFIO_32, EXE_STD$ALLOC_BUFIO_64 Arguments

Argument	Type	Access	Description
irp	IRP *	Input	Pointer to the current IRP.
pcb	PCB *	Input	Pointer to the process PCB.
uva	VOID_PQ	Input	User virtual address, EXE_STD$ALLOC_BUFIO_64
	void *	Input	User virtual address, EXE_STD$ALLOC_BUFIO_32
pktsiz	int	Input	Required size of the packet including the packet header.

These routines use the EXE_STD$DEBIT_BYTCNT_ALO routine to allocate the packet and charge the process for the required BYTCNT quota. Any failure status from this routine is returned to the caller.

Table B-2 lists all the implicit outputs that are valid on successful return from these routines.

Table B-2 EXE_STD$ALLOC_BUFIO_32, EXE_STD$ALLOC_BUFIO_64 Implicit Outputs

Field	Value on successful completion
irp$ps_bufio_pkt	Pointer to the allocated BUFIO packet.
irp$l_boff	Number of charged bytes and size of allocated packet.
bufio$ps_pktdata	Pointer to the packet data region in the allocated BUFIO packet.
bufio$ps_uva32	For EXE_STD$ALLOC_BUFIO_32, value of uva. For EXE_STD$ALLOC_BUFIO_64, BUFIO$K_64.
bufio$w_size	Size of allocated packet.
bufio$b_type	DYN$C_BUFIO
bufio$pq_uva64	For EXE_STD$ALLOC_BUFIO_64, value of uva.

B.3 EXE_STD$ALLOC_DIAGBUF

Routine EXE_STD$ALLOC_DIAGBUF is a new routine that allocates either a 32-bit or 64-bit diagnostic buffer packet and initializes the diagnostic buffer packet header. Diagnostic buffer packets use the same layout as BUFIO packets. This routine initializes the appropriate IRP and BUFIO header cells in the diagnostic buffer packet header but it's up the the caller to copy any data into the packet.

The allocation of a 32-bit or 64-bit format diagnostic buffer packet is controlled by a flag bit in the packet size value that is passed to this routine. This allows callers to simply pass in the value of the ddt$w_diagbuf cell directly to this routine.

The interface for this routine is:

int exe_std$alloc_diagbuf (IRP *irp, VOID_PQ *uva, int pktsiz)

Table B-3 summarizes the use of the arguments.

Table B-3 EXE_STD$ALLOC_DIAGBUF Arguments

Argument	Type	Access	Description
irp	IRP *	Input	Pointer to the current IRP.
uva	VOID_PQ	Input	User virtual address
pktsiz	int	Input	The low-order 15-bits of this parameter specify the required size of the packet including the diagnostic packet header. If bit-16 (DDT$M_DIAGBUF64) is set a 64-bit diagnostic buffer packet is allocated. Otherwise a 32-bit diagnostic buffer packet is allocated.

This routine uses the EXE_STD$ALLOCBUF routine to allocate the packet. Any failure status from this routine is returned to the caller of EXE_STD$ALLOC_DIAGBUF. Note that the EXE_STD$ALLOCBUF routine may put the process in a resource wait state and there is no additional process quota charge for a diagnostic buffer packet.

Table B-4 lists all the implicit outputs that are valid on successful return from this routine.

Table B-4 EXE_STD$ALLOC_DIAGBUF Implicit Outputs

Field	Value on successful completion
irp$l_diagbuf	Pointer to the allocated diagnostic buffer packet.
irp$l_sts	Status flag IRP$M_DIAGBUF is set to indicate that the IRP has an associated diagnostic buffer packet.
bufio$ps_pktdata	Pointer to the packet data region in the allocated diagnostic BUFIO packet.
bufio$ps_uva32	If DDT$M_DIAGBUF64 clear, value of uva. If DDT$M_DIAGBUF64 set, BUFIO$K_64.
bufio$w_size	Size of allocated diagnostic buffer packet.
bufio$b_type	DYN$C_BUFIO
bufio$pq_uva64	If DDT$M_DIAGBUF64 set, value of uva.

B.4 EXE_STD$LOCK_ERR_CLEANUP

Routine EXE_STD$LOCK_ERR_CLEANUP is a new routine. This routine unlocks any previously locked down buffers that are associated with the specified IRP or any IRPEs that are attached to it. Additionally, all the attached IRPEs are deallocated.

This routine is designed to be called in a driver-supplied error callback routine that is called if any error is encountered in the EXE_STD$READLOCK, EXE_STD$WRITELOCK, or EXE_STD$MODIFY_LOCK routines.

The interface for this routine is:

void exe_std$lock_err_cleanup (IRP *irp)

Table B-5 summarizes the use of the arguments.

Table B-5 EXE_STD$LOCK_ERR_CLEANUP Arguments

Argument	Type	Access	Description
irp	IRP *	Input	Pointer to the current IRP.

Table B-6 lists all the implicit inputs and outputs that are used by this routine.

Table B-6 EXE_STD$LOCK_ERR_CLEANUP Implicit Inputs and Outputs

Implicit inputs from the IRP
Field	Use
irp$l_svapte	If non-zero, points to the first PTE for a set of pages that will be unlocked.
irp$l_bcnt	Used only if irp$l_svapte is non-zero to calculate number of pages that will be unlocked.
irp$l_boff	Used only if irp$l_svapte is non-zero to calculate number of pages that will be unlocked.
irp$v_extend	If set, the IRPE pointed to by irp$l_extend will be processed.
irp$l_extend	Used only if irp$v_extend is set to find the first IRPE
Implicit inputs from each IRPE
Field	Use
irpe$l_svapte	If non-zero, points to the first PTE for a set of pages that will be unlocked.
irpe$l_bcnt	Used only if irpe$l_svapte is non-zero to calculate number of pages that will be unlocked.
irpe$l_boff	Used only if irpe$l_svapte is non-zero to calculate number of pages that will be unlocked.
irpe$v_extend	If set, the IRPE pointed to by irpe$l_extend will be processed.
irpe$l_extend	Used only if irpe$v_extend is set to find the next IRPE
Implicit outputs in the IRP
Field	Value written
irp$l_svapte	Cleared to indicate no locked pages.
irp$v_extend	Cleared to indicate no attached IPEs.

B.5 EXE_STD$MODIFY, EXE_STD$READ, EXE_STD$WRITE

The routines EXE_STD$MODIFY, EXE_STD$READ, and EXE_STD$WRITE are upper-level FDT routines, so their interfaces remain unchanged:

int exe_std$modify (IRP *irp, PCB *pcb, UCB *ucb, CCB *ccb) int exe_std$read (IRP *irp, PCB *pcb, UCB *ucb, CCB *ccb) int exe_std$write (IRP *irp, PCB *pcb, UCB *ucb, CCB *ccb)

These routines obtain the address of the caller's buffer from irp->irp$l_qio_p1. These routines have been modified to obtain the full 64-bit buffer address from irp->irp$q_qio_p1 and pass it to EXE_STD$READLOCK or EXE_STD$WRITELOCK. Note, however, that the buffer size remains a longword and is obtained from irp->irp$l_qio_p2 without checking the upper 32-bits.

B.6 EXE_STD$MODIFYLOCK, EXE_STD$READLOCK, EXE_STD$WRITELOCK

The routines EXE_STD$MODIFYLOCK, EXE_STD$READLOCK, and EXE_STD$WRITELOCK are FDT support routines that:

• Probe the accessibility of a specified buffer by the mode contained in irp->irp$b_mode
• Lock the buffer into memory if the probe succeeds
• Return the address of the first PTE that maps the buffer in irp->irp$l_svapte

If an error is encountered, an optional error callback routine is invoked and the I/O request is aborted. If the entire buffer is not resident then the I/O request is backed out and a special status is returned to request a pagefault of the needed page.

In releases prior to OpenVMS Alpha Version 7.0, the interfaces for these routines were:

int exe_std$modifylock (IRP *irp, PCB *pcb, UCB *ucb, CCB *ccb, void *buf, int bufsiz, void (*err_rout)(...)) int exe_std$readlock (IRP *irp, PCB *pcb, UCB *ucb, CCB *ccb, void *buf, int bufsiz, void (*err_rout)(...)) int exe_std$writelock (IRP *irp, PCB *pcb, UCB *ucb, CCB *ccb, void *buf, int bufsiz, void (*err_rout)(...))

The new interfaces for these routines are:

int exe_std$modifylock (IRP *irp, PCB *pcb, UCB *ucb, CCB *ccb, VOID_PQ buf, int bufsiz [, void (*err_rout)(...)] ) int exe_std$readlock (IRP *irp, PCB *pcb, UCB *ucb, CCB *ccb, VOID_PQ buf, int bufsiz [, void (*err_rout)(...)] ) int exe_std$writelock (IRP *irp, PCB *pcb, UCB *ucb, CCB *ccb, VOID_PQ buf, int bufsiz [, void (*err_rout)(...)] )

There are two differences in the new OpenVMS Alpha Version 7.0 interfaces:

1. These functions now use the full 64-bits of the buffer address buf that is passed by value.
   Previously, the buffer address was a 32-bit value that was sign-extended into a 64-bit parameter value.
2. It is possible to omit the err_rout parameter. Currently, one can pass in 0 to specify that there is no error routine.
   The new interface supports either method of specifying that there is no error routine. Because many callers do not require an error routine, this allows them to call these routines more efficiently with six parameters.

Both of these interface changes are upwardly compatible.

B.6.1 CALL_xLOCK and CALL_xLOCK_ERR macros

There are six MACRO-32 macros that facilitate the use of the routines described in Section B.6 by code that was originally written to use the JSB-interface counterparts for these routines. These macros have implicit register inputs and outputs that correspond to the register inputs and outputs of the JSB-interface routines.

The CALL_MODIFYLOCK, CALL_READLOCK, and CALL_WRITELOCK macros have been modified to pass the full 64-bits of R0 as the buffer address and to omit the optional error routine parameter instead of passing the value 0.

The CALL_MODIFYLOCK_ERR, CALL_READLOCK_ERR, and CALL_WRITELOCK_ERR macros have been modified to pass the full 64-bits of R0 as the buffer address.

This is an upwardly compatible change to the implementation of these macros. This change is transparent to users prior to OpenVMS Alpha Version 7.0, because R0 currently contains the 32-bit buffer address sign-extended to 64-bits.

B.7 EXE_STD$READCHK and EXE_STD$WRITECHK

The routines EXE_STD$READCHK and EXE_STD$WRITECHK probe the accessibility of a specified buffer by the mode contained in irp->irp$b_mode.

In releases prior to OpenVMS Alpha Version 7.0, the interfaces for these routines were:

int exe_std$readchk (IRP *irp, PCB *pcb, UCB *ucb, void *buf, int bufsiz) int exe_std$writechk (IRP *irp, PCB *pcb, UCB *ucb, void *buf, int bufsiz)

As of OpenVMS Alpha Version 7.0, the new interfaces for these routines are:

int exe_std$readchk (IRP *irp, PCB *pcb, UCB *ucb, VOID_PQ buf, int bufsiz) int exe_std$writechk (IRP *irp, PCB *pcb, UCB *ucb, VOID_PQ buf, int bufsiz)

The only difference in the new interface is that these functions now use the full 64-bits of the buffer address buf that is passed by value. Previously, the buffer address was a 32-bit value sign-extended into a 64-bit parameter value. Thus, this is an upward compatible change to the interface.

B.7.1 CALL_xCHK and CALL_xCHKR macros

The CALL_READCHK, CALL_READCHKR, CALL_WRITECHK, and CALL_WRITECHKR MACRO-32 macros have been modified to pass the full 64-bits of the buffer address in a similar fashion as described in Section B.6.1.

B.8 EXE_STD$SETCHAR and EXE_STD$SETMODE

The routines EXE_STD$SETCHAR and EXE_STD$SETMODE are upper-level FDT routines, thus their interfaces remain unchanged:

int exe_std$setchar (IRP *irp, PCB *pcb, UCB *ucb, CCB *ccb) int exe_std$setmode (IRP *irp, PCB *pcb, UCB *ucb, CCB *ccb)

Both of these routines use the local routine CHECK_SET to obtain and validate a pointer to the caller's buffer from irp->irp$l_qio_p1. The routine CHECK_SET have been modified to obtain the full 64-bit buffer address from irp->irp$q_qio_p1. Routines EXE_STD$SETCHAR and EXE_STD$SETMODE have been modified to use the 64-bit pointer returned by CHECK_SET when loading the UCB characteristics from the caller's buffer.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

6466PRO_008.HTML