Document revision date: 19 July 1999

This section describes how to manage Fast Path.

10.2.2.1 Fast Path Sysgen Parameters

There are two FAST_PATH SYSGEN parameters:

• FAST_PATH
• IO_PREFER_CPUS

These parameters can be used to control Fast Path as follows:

FAST_PATH

FAST_PATH is a static SYSGEN parameter that enables (1) or disables (0) the Fast Path performance features for all Fast Path-capable ports. Starting in OpenVMS Version 7.2, Fast Path is enabled by default. In Versions 7.0 and 7.1, Fast Path was disabled by default.

IO_PREFER_CPUS

IO_PREFER_CPUS is a dynamic SYSGEN parameter that controls the set of CPUs available for use as Fast Path preferred CPUs.

IO_PREFER_CPUS is a CPU bit mask specifying the CPUs that are allowed to serve as preferred CPUs and thus can be assigned a Fast Path port. CPUs whose bit is set in the IO_PREFER_CPUS bit mask are enabled for Fast Path port assignment. IO_PREFER_CPUS defaults to -1, which specifies that all CPUs are allowed to be assigned Fast Path ports.

You may want to disable the primary CPU from serving as a preferred CPU by clearing it's bit in IO_PREFER_CPUS. This will reserve the primary for use by non-Fast Path IO operations.

Changing the value of IO_PREFER_CPUS causes the FASTPATH_SERVER process to execute the automatic assignment algorithm that spreads Fast Path ports evenly among the new set of usable CPUs.

Following are the full set of commands used to identify and set a preferred CPU for a port.

DCL SHOW DEVICE/FULL or $GETDVI DVI$_PREFERRED_CPU

To identify the preferred CPU for any Fast Path-capable device when Fast Path is enabled, use the DCL command SHOW DEVICE/FULL to display - whether or not the device supports Fast Path - the current preferred CPU ID and, if set, the User Preferred CPU ID for a port or disk device.

Alternatively, the $GETDVI system service or the DCL F$GETDVI lexical function will return the preferred CPU for a given device or file. The $GETDVI system service item code is DVI$_PREFERRED_CPU, and the F$GETDVI item code string argument is PREFERRED_CPU. The return argument is a 32-bit CPU bit mask with a bit set indicating the preferred CPU. A return argument containing a bit mask of zero indicates that no preferred CPU exists, either because Fast Path is disabled or the device is not a Fast Path capable device. The return argument is designed to serve as a CPU bit mask input argument to the $PROCESS_AFFINITY system service that can be used to assign an application process to the optimal preferred CPU.

For an application seeking optimal Fast Path benefits, you can code each application process to identify and run on the preferred CPU where the majority of the process's I/O activity occurs.

A high-availability feature of OpenVMS Cluster Systems is that dual-pathed devices automatically fail over to a secondary path, if the primary path becomes inoperable. Because a Fast Path device could fail over to another path or port, and thereby, to another preferred CPU, an application should occasionally reissue the $GETDVI in a timer thread to check that process assignment is optimal.

DCL SHOW CPU /FULL

You can use this DCL command to identify whether a CPU is enabled for use as a preferred CPU, and the current set of ports assigned to that CPU.

DCL SET /PREFERRED_CPU and /NOPREFERRED_CPU

These commands allow you to specify a CPU or a set of candidate CPUs from which the operating system will choose the CPU to assign to the Fast Path port. The chosen CPU is called the preferred CPU for this Fast Path port. The Fast Path port's interrupt I/O completion processing and I/O initiation processing will be performed on this preferred CPU.

In addition to selecting the preferred CPU, the User Preferred CPU will be set for this port. Setting the User Preferred CPU prevents the port from being reassigned to another CPU unless the User Preferred CPU is being stopped. The qualifier can be negated. When the /NOPREFERRED_CPUS qualifier is specified, the User Preferred CPU will be cleared for the port, but it still remains a Fast Path port, and the current preferred CPU will not be changed.

If both /PREFERRED_CPUS and /NOPREFERRED_CPUS are specified on the same command line, /NOPREFERRED_CPUS is ignored.

$QIO IO$_SETPRFPATH ! IO$M_PREFERRED_CPU [!IO$M_SYS_ASSIGNABLE]

You can change the assignment of a Fast Path port to a CPU by issuing a $QIO IO$_SETPRFPATH (Set Preferred Path) to the port device, for example, PNA0. The IO$M_PREFERRED_CPU modifier must be set, and the $QIO argument P1 must be set to either zero or the address of a 32-bit CPU bit mask with a bit set indicating the new preferred CPU. On return from the I/O, the port and its associated devices are all assigned to a new preferred CPU. Note that explicitly setting the preferred CPU overrides any default assignment of Fast Path ports to CPUs. This interface allows you the flexibility to load balance I/O activity over multiple CPUs in an SMP system. This is important because I/O activity can change over the course of a day or week.

The $QIO passes in either a set containing one or more candidate CPUs, or zero as a wildcard value indicating the set of usable CPUs. If the candidate set contains only one CPU, you are explicitly designating the new preferred CPU. If the candidate set contains multiple CPUs, you are requesting use of the automatic preferred CPU assignment algorithm to select a suitable CPU from the candidate set.

Including the IO$M_SYS_ASSIGNABLE modifier inhibits setting the selected CPU as the device's User Preferred CPU.

The $QIO or the SET DEVICE/PREFERRED_CPU command will make a best effort to assign the port to a CPU. However, it is possible for this request to return failure for the following reasons:

• There is no intersection between the candidate set and the node's set of usable CPUs.
• There is resource contention. If after a reasonable effort the request is unable to acquire a key system resource, the request will fail. Some key resources include Fast Path spinlock, the CPU mutex, and a CPU transition lock.

If the $QIO or SET DEVICE/PREFERRED_CPU returns failure, you should consider retrying either immediately or after a short delay. It is possible that a large number of ports were being reassigned, and the request failed due to resource contention.

$IO_FASTPATH

The $IO_FASTPATH system service performs operations on the set of Fast Path devices and CPUs enabled for Fast Path use. The $IO_FASTPATHW system service completes synchronously. That is, it returns after the operation is complete.

The FP$K_BALANCE_PORTS function code specifies that the system service is to distribute the set of system assignable Fast Path ports across the intersection of a caller-supplied set of candidate CPUs.

Fast Path restrictions include the following:

• Only high-volume I/Os are optimized.
  Fast Path streamlines the operation of high-volume I/O. I/O that does not meet the definition of high-volume is not optimized. A high-volume Fast Path I/O is characterized as follows:
  1. A virtual, logical, or physical read or write I/O without special I/O modifiers.
  2. An I/O request that is less than 64K bytes in size.
  3. An I/O issued when all I/O resources exist that needed to perform the I/O.
• Send credits resource must be managed.
  Applications seeking maximum performance must ensure the availability of sufficient I/O resources.
  The only I/O resource that a Fast Path user needs to be concerned about is send credits. Send credits are extended by DSA controllers to host systems and represent the maximum number of I/Os that can be outstanding at any given point in time. If an application sends an unlimited number of simultaneous I/Os to a controller, it is likely that some I/O will back up waiting for send credits. You can tell whether the send-credit limit is being exceeded by using the DCL command SHOW CLUSTER/CONTINUOUS, followed by an ADD CONNECTIONS, CR_WAIT command. Rapidly increasing credit-wait counts for the disk-class driver connections (a LOC_PROC_NAME name of VMS$DISK_CL_DRVR) is a sign that an application may be incurring send-credit waits.
  To ensure sufficient send credits, some controllers, like the HSC and HSJ, allow the number of send credits to vary. However, not all controllers have this flexibility, and different controllers have different send-credit limits. The best workaround is to know your application access patterns and look for send credit waits. If the number of send credits is being exhausted on one node, then add another controller to spread the load over multiple controllers. An alternative is to rework the application to load balance controller activity throughout the cluster, spreading a given controller's disk load over multiple nodes and allowing an application to exceed the send credits allotted to one node.

This chapter includes updated information for OpenVMS Version 7.2.

This appendix lists the function codes and function modifiers defined in the $IODEF macro. The arguments for these functions are also listed.

A.1 ACP-QIO Interface Driver

This section lists the function codes and function modifiers for the ACP-QIO interface driver.

Functions	Arguments	Modifiers
IO$_CREATE IO$_ACCESS IO$_DEACCESS IO$_MODIFY IO$_DELETE IO$_ACPCONTROL	P1---FIB descriptor ####address P2---file name string ####address P3---result string length ####address P4---result string ####descriptor address P5---attribute list ####address	IO$M_CREATE 1 IO$M_ACCESS 1 IO$M_DELETE 2 IO$M_DMOUNT 3
IO$_MOUNT	None	None

This section lists the function codes and function modifiers for the disk drivers.

Functions	Arguments	Modifiers
IO$_READVBLK IO$_READLBLK IO$_READPBLK 4 IO$_WRITEVBLK IO$_WRITELBLK IO$_WRITEPBLK 4	P1---buffer address P2---byte count P3---disk address	IO$M_INHSEEK 1 IO$M_DATACHECK 2 IO$M_DELDATA 3 IO$M_INHRETRY IO$M_ERASE 5
IO$_WRITECHECK 2	P1---buffer address P2---byte count P3---disk address	None
IO$_SENSECHAR IO$_SENSEMODE IO$_PACKACK IO$_AVAILABLE IO$_UNLOAD	None	None
IO$_SEARCH	P1---read/write ####head position	None
IO$_SEEK 4	P1---seek to ####specified ####cylinder	None
IO$_FORMAT	P1---RX02 density	None
IO$_SETPRFPATH	P1---node or HSx name	IO$_FORCEPATH
IO$_CREATE IO$_ACCESS IO$_DEACCESS IO$_MODIFY IO$_DELETE IO$_ACPCONTROL	P1---FIB descriptor ####address P2---file name string ####address P3---result string ####length address P4---result string ####descriptor ####address P5---attribute list ####address	IO$M_CREATE 6 IO$M_ACCESS 6 IO$M_DELETE 7 IO$M_DMOUNT 8

This section lists the function codes and function modifiers for the magnetic tape drivers.

Functions	Arguments	Modifiers
IO$_READVBLK IO$_READLBLK IO$_READPBLK	P1---buffer address P2---byte count	IO$M_DATACHECK 1 IO$M_INHRETRY IO$M_REVERSE 3
IO$_WRITEVBLK IO$_WRITELBLK IO$_WRITEPBLK	P1---buffer address P2---byte count	IO$M_DATACHECK 1 IO$M_INHRETRY IO$M_INHEXTGAP 2 IO$M_NOWAIT 8 IO$M_ERASE 7
IO$_SETMODE IO$_SETCHAR	P1---characteristics buffer ####address P2---characteristics buffer ####length 9
IO$_CREATE IO$_ACCESS IO$_DEACCESS IO$_MODIFY IO$_ACPCONTROL	P1---FIB descriptor ####address P2---file name string ####address P3---result string length ####address P4---result string ####descriptor address P5---attribute list address	IO$M_CREATE 4 IO$M_ACCESS 4 IO$M_DMOUNT 5
IO$_SKIPFILE	P1---skip n tape marks	IO$M_ALLOWFAST 10 IO$M_INHRETRY IO$M_NOWAIT 8
IO$_SKIPRECORD	P1---skip n blocks	IO$M_INHRETRY IO$M_NOWAIT 8
IO$_REWIND IO$_REWINDOFF IO$_UNLOAD	None	IO$M_INHRETRY IO$M_NOWAIT IO$M_RETENSION
IO$_WRITEOF	None	IO$M_INHEXTGAP 2 IO$M_INHRETRY IO$M_NOWAIT 8
IO$_SENSEMODE IO$_SENSECHAR	P1---characteristics ####buffer address 9 P2---characteristics ####buffer length 9	IO$M_INHRETRY
IO$_DSE 6 IO$_PACKACK IO$_AVAILABLE	None	None

	privacy and legal statement
6136PRO_036.HTML