Document revision date: 30 March 2001

## OpenVMS Alpha Guide to Upgrading Privileged-Code Applications

Previous | Contents | Index

## A.6 Direct I/O Buffer Map (DIOBM)

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 is 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 its 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 have 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 move 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.

The size of an IRP has increased by 160 bytes (43%), from 376 to 536 bytes (see Table A-9).

Table A-9 IRP Changes
Field | Type | Comments
--- | --- | ---
irp$b_mode | unsigned char | This is an existing cell in the IRP that contains the caller's mode in the low-order 2 bits. The `irp$l_acb_flags` cell is considered valid by SCH$QAST if and only if ACB$M_FLAGS_VALID mask is set in this cell. The ACB$M_FLAGS_VALID mask is always set in this cell by EXE$QIO when the IRP is allocated.
irp$l_acb64x_offset | int | Offset to the ACB64X structure embedded in this IRP. This cell is considered valid by SCH$QAST if and only if ACB$M_64BITS is set in the `irp$l_acb_flags` cell. This cell is initialized to the offset value of the `irp$pq_acb64_ast` field. This cell corresponds to the `acb64$l_acb64x` cell. Because this cell is at the same offset as the `acb$l_ast` cell, the `irp$l_ast` cell has been removed.
irp$l_acb_flags | unsigned int | This cell has been initialized to the mask value ACB$M_64BITS to indicate that the `irp$l_acb64x_offset` field contains an offset to the ACB64X structure. Corresponds to the `acb$l_flags` cell.
irp$l_thread_pid | int | Corresponds to the `acb$l_thread_pid` cell. Reserved for use by the Kernel Threads project.
irp$pq_acb64_ast | VOID_FUNC_PQ | This cell corresponds to the `acb64$pq_ast` cell and replaces the `irp$l_ast` cell.
irp$l_ast | - | This cell has been removed. It has been replaced by the `irp$pq_acb64_ast` cell.
irp$l_shd_iofl | IRP * | This is an existing cell that contains the link to the cloned shadowing IRPs. This cell was overlaid on `irp$l_ast` and is now overlaid on the low-order longword of the `irp$pq_acb64_ast` cell.
irp$l_iirp_p0 | int | Generic parameter cell that is available in internal IRPs. This cell overlays the low-order longword of the `irp$pq_acb64_ast` cell and is intended for use by components that use the `irp$l_ast` cell for this purpose.
irp$q_acb64_astprm | int64 | This cell corresponds to the `acb64$q_astprm` cell and replaces the `irp$l_astprm` cell.
irp$l_astprm | - | This cell has been removed. It is replaced by the `irp$q_acb64_astprm` cell.
irp$l_shad | SHAD * | This is an existing cell in IRPs cloned by shadowing that points to the SHAD structure. This cell was overlaid on `irp$l_astprm` and is now overlaid on the low-order longword of the `irp$q_acb64_astprm` cell.
irp$l_hrb | HRB * | This is an existing cell in MSCP server IRPs that points to a Host Request Block structure. This cell was overlaid on `irp$l_astprm` and is now overlaid on the low-order longword of the `irp$q_acb64_astprm` cell.
irp$l_mv_tmo | int | This cell is used in internal mount verification IRPs to contain the timeout value. This cell overlays the low-order longword of the `irp$q_acb64_astprm` cell and is intended for use by components that currently use the `irp$l_astprm` cell for this purpose.
irp$l_iirp_p1 | int | Generic parameter cell that is available in internal IRPs. This cell overlays the low-order longword of the `irp$q_acb64_astprm` cell and is intended for use by components that use the `irp$l_astprm` cell for this purpose.
irp$q_user_thread_id | uint64 | Unique user thread identifier. Corresponds to the `acb64$q_user_thread_id` cell. Reserved for use by the Kernel Threads project.
irp$pq_iosb | VOID_PQ | 64-bit pointer to the caller's IOSB. This cell replaces `irp$l_iosb` .
irp$l_iosb | - | This cell has been removed. It is replaced by the `irp$pq_iosb` cell.
irp$l_cln_wle | unsigned int | This is an existing cell that contains the shadowing write log state. This cell was overlaid on `irp$l_iosb` and is now overlaid on the low-order longword of the `irp$pq_iosb` cell.
irp$l_iirp_p2 | int | Generic parameter cell that is available in internal IRPs. This cell overlays the low-order longword of the `irp$pq_iosb` cell and is intended for use by components that use the `irp$l_iosb` cell for this purpose.
irp$pq_va_pte | PTE_PQ | A 64-bit pointer to the actual PTEs that map the user buffer. If the user buffer is not in shared system space, then this PTE virtual address is only valid in the caller's process context.
irp$l_svapte | PTE * | A 32-bit pointer to PTE values that map the user buffer. The PTE values may be copies of the actual PTEs in Page Table Space that map the user buffer. If zero, then no PTEs have been locked for this request. Note that for compatibility with existing drivers, this cell remains overlaid on `irp$ps_bufio_pkt` and this use is valid only if IRP$M_BUFIO is clear in `irp$l_sts` . Note also that this cell contains a pointer into the CPT structure if IRP$M_CACHEIO is set in `irp$l_sts2` .
irp$ps_bufio_pkt | BUFIO * | Pointer for the buffered I/O packet for this request. If zero, then no packet has been allocated for this request. Note that for compatibility with existing drivers, this cell remains overlaid on `irp$l_svapte` and this use is valid only if IRP$M_BUFIO is set in `irp$l_sts` .
irp$r_diobm | DIOBM | Embedded fixed-size primary "direct I/O buffer map" structure. This embedded DIOBM structure is valid if and only if `irp$l_svapte` points to a set of PTEs whose pages have been locked down for direct I/O. Specifically, the DIOBM is in use when both IRP$M_BUFIO and IRP$M_CACHEIO in `irp$l_sts` are clear and the `irp$l_svapte` cell contains a non-zero value. See Section A.6 for a complete description of the DIOBM structure.
irp$q_qio_p1 | int64 | Copy of device dependent $QIO parameter p1. The low order 32-bits of this cell remain accesible via `irp$l_qio_p1` .
irp$q_qio_p2 | int64 | Copy of device dependent $QIO parameter p2. The low order 32-bits of this cell remain accesible via `irp$l_qio_p2` .
irp$q_qio_p3 | int64 | Copy of device dependent $QIO parameter p3. The low order 32-bits of this cell remain accesible via `irp$l_qio_p3` .
irp$q_qio_p4 | int64 | Copy of device dependent $QIO parameter p4. The low order 32-bits of this cell remain accesible via `irp$l_qio_p4` .
irp$q_qio_p5 | int64 | Copy of device dependent $QIO parameter p5. The low order 32-bits of this cell remain accesible via `irp$l_qio_p5` .
irp$q_qio_p6 | int64 | Copy of device dependent $QIO parameter p6. The low order 32-bits of this cell remain accesible via `irp$l_qio_p6` .

Previous | Next | Contents | Index

| privacy and legal statement |
6466PRO_007.HTML