HP OpenVMS systems documentation

The use of the DIOBM structure by this routine is described in detail in Appendix A.

This routine is coded in C and is contained in the new DIOBM.C module.

B.10 IOC_STD$FILL_DIOBM

Routine IOC_STD$FILL_DIOBM is a new routine that is used to derive a 32-bit system virtual address for a specific number of PTEs that are pointed to by a 64-bit process virtual address. This routine employs a previously allocated or embedded "primary" DIOBM structure that must be supplied as one of its inputs. When the derived 32-bit system virtual address is no longer required, the DIOBM must be released by calling the IOC_STD$RELEASE_DIOBM routine.

This routine derives a 32-bit system virtual address for the PTEs using one of the following methods:

1. If the PTEs are in the region of the page table space that maps S0/S1 space, a 32-bit PTE address using the SPT window is returned.
2. If less than or equal to DIOBM$K_PTECNT_FIX PTEs are required, the PTEs are copied into the PTE vector in the DIOBM and the 32-bit system virtual address of the PTE vector in the DIOBM is returned.
3. If more than DIOBM$K_PTECNT_FIX and less than or equal to ioc$gl_diobm_ptecnt_max PTEs are required, a secondary DIOBM is allocated, the PTEs are copied into the PTE vector in the secondary DIOBM, and the 32-bit system virtual address of the PTE vector in the secondary DIOBM is returned.
4. If more than ioc$gl_diobm_ptecnt_max PTEs are required, a temporary PTE window in S0/S1 space is created that maps the neccessary process level-3 page table pages. These level-3 page table pages are locked into memory and the 32-bit S0/S1 address of the PTEs through the PTE window is returned.

The interface for IOC_STD$FILL_DIOBM is:

int ioc_std$fill_diobm (DIOBM *const diobm, const PTE_PQ va_pte, const uint32 pte_count, const uint32 flags, PTE **svapte_p)

Table B-8 summarizes the use of the arguments.

Table B-8 IOC_STD$FILL_DIOBM Arguments

Argument	Type	Access	Description
diobm	DIOBM *	Input	Pointer to a previously allocated but unused or uninitialized DIOBM structure.
va_pte	PTE_PQ	Input	A 64-bit pointer to the first PTE that maps the user buffer.
pte_count	uint32	Input	Number of PTEs that are required to map the entire buffer.
flags	uint32	Input	Option flags. The following bit mask values can be set: DIOBM$M_NORESWAIT - Disable resource wait. All other option bits must be zero.
svapte_p	PTE **	Output	Pointer to a 32-bit PTE address that is returned. The returned address is always a 32-bit system virtual address.

This routine may require system resources, either nonpaged pool or SPTEs, depending on the number of PTEs that are required to map the buffer. If there are insufficient resources this routine will, by default, place the process (kernel thread) in a kernel mode wait state for nonpaged pool and try again until it succeeds. In this case, the return value of this routine is always SS$_NORMAL because it will not return until it can do so successfully.

However, the caller can inhibit this resource wait by setting the DIOBM$M_NORESWAIT option in the flags parameter. When this is done, an error status is returned to the caller if there are insufficient system resources. This capability is intended to be used in contexts where either a resource wait in kernel mode is not acceptable or the caller can readily put the process into a wait state in the requestor's mode.

This routine must be called in process context and assumes that it was called at IPL 2, or minimally that it can lower IPL to 2.

The use of the DIOBM structure by this routine is described in detail in Appendix A. The normal version of the IOC_STD$FILL_DIOBM routine makes no assumptions about the contents of the input DIOBM structure. In contrast, the full checking version of this routine in the IO_ROUTINES_MON.EXE execlet performs some initial validation and declares an INCONSTATE bugcheck should this check fail.

B.11 IOC_STD$PTETOPFN

The routine IOC_STD$PTETOPFN allows drivers or other components to obtain the PFN for a page that has been previously locked into memory but the valid bit in its PTE is currently clear. This routine handles transition PTEs and PTEs that have reverted into GPTX format.

In releases prior to OpenVMS Alpha Version 7.0, the interface for this routine was:

int ioc_std$ptetopfn (PTE *pte);

The new interface for this routine is:

int ioc_std$ptetopfn (PTE_PQ pte);

The first interface difference is that IOC_STD$PTETOPFN uses the full 64-bits of the caller's PTE address that is passed by value. The second interface difference is not apparent from the above function prototype. The IOC_STD$PTETOPFN routine has been enhanced to handle the case where the pte$v_valid bit is set in the PTE. Therefore, drivers can use this routine without first checking the valid bit.

Both of these are upwardly compatible changes to the interface.

B.12 IOC_STD$RELEASE_DIOBM

Routine IOC_STD$RELEASE_DIOBM is a new routine that is used to release the PTE mapping resources that were set up by a prior call to either the IOC_STD$CREATE_DIOBM or IOC_STD$FILL_DIOBM routines.

The interface for IOC_STD$RELEASE_DIOBM is:

int ioc_std$release_diobm (DIOBM *const diobm)

Table B-9 summarizes the use of the arguments.

Table B-9 IOC_STD$RELEASE_DIOBM Arguments

Argument	Type	Access	Description
diobm	DIOBM *	Input	Pointer to an active primary DIOBM.

This routine deallocates any secondary DIOBM that is connected to the primary DIOBM. If this primary DIOBM has a PTE window, the resources used for the window are deallocated. If the primary DIOBM was allocated by IOC_STD$CREATE_DIOBM, the primary DIOBM is deallocated as well. The use of the DIOBM structure by this routine is described in detail in Appendix A.

The returned value of this routine is always SS$_NORMAL.

This routine does not depend on process context. However, the IPL and spinlocks of the caller must allow this routine to acquire and restore the MMG spinlock.

This routine is coded in C and is contained in the new DIOBM.C module.

B.13 IOC_STD$SIMREQCOM, IOC$SIMREQCOM

The routine IOC_STD$SIMREQCOM allows drivers or other components to complete an I/O that does not have a normal IRP associated with it. Because this routine does not have an IRP, the necessary information to signal an I/O completion is passed directly in separate parameters. For example, the user's IOSB address, the event flag value, a pointer to an ACB, and the caller's access mode are among the parameters.

In releases prior to OpenVMS Alpha Version 7.0, the interface for this routine was:

int ioc_std$simreqcom (int32 iosb[2], int pri, int efn, int32 iost[2], ACB *acb, int acmode);

The new interface for this routine is:

int ioc_std$simreqcom (VOID_PQ iosb_p, int pri, int efn, int32 iost[2], ACB *acb, int acmode);

The first interface difference is that IOC_STD$SIMREQCOM uses the full 64-bits of the caller's IOSB address iosb_p that is passed by value. The second interface difference is not apparent from the above function prototype. The IOC_STD$SIMREQCOM routine has been enhanced to accept either a pointer to an ACB64 or an ACB structure.

Both of these are upwardly compatible changes to the interface.