8    CAM SIM Modules

This chapter describes how the SCSI Interface Module (SIM) layers handle asynchronous callbacks. It also describes the following SIM routines:

• sim_action

• sim_init

Appendix C lists the routines alphabetically and includes descriptions and syntax information in Digital UNIX reference-page format.

8.1    SIM Asynchronous Callback Handling

This section describes how the SIM layers handle asynchronous callbacks from the XPT to SCSI/CAM peripheral device drivers when an event such as a SCSI bus device reset (BDR) or an asynchronous event notification (AEN) occurs.

Each SCSI/CAM peripheral device driver registers an asynchronous callback function for each active SCSI device during driver initialization. The SCSI/CAM peripheral device drivers use the ccmn_sasy_ccb_bld routine to create a SET ASYNCHRONOUS CALLBACK CCB and send it to the XPT.

The async_flags field of the CCB is set to 1 for those events for which the SCSI/CAM peripheral device driver wants to be notified, using the asynchronous callback function. The possible async_flags settings are:

Flag Name	Description
AC_FOUND_DEVICES	A new device was found during a rescan.
AC_SIM_DEREGISTER	A previously loaded SIM driver has deregistered.
AC_SIM_REGISTER	A loaded SIM driver has registered.
AC_SENT_BDR	A bus device reset (BDR) message was sent to the target.
AC_SCSI_AEN	A SCSI asynchronous event notification has been received.
AC_UNSOL_RESEL	An unsolicited reselection of the system by a device on the bus has occurred.
AC_BUS_RESET	A SCSI bus RESET occurred.

These define statements are in /usr/sys/include/io/cam/cam.h.

8.2    SIM Routines That Device Driver Writers Use

This section describes the SIM routines device driver writers need to understand.

8.2.1    The sim_action Routine

The sim_action routine initiates an I/O request from a SCSI/CAM peripheral device driver. The XPT uses the routine for immediate as well as for queued operations. For the SCSI I/O CCB, when the operation has completed, the SIM uses the CCB callback address to call back directly to the peripheral driver, if callbacks are enabled and the operation is not to be carried out immediately.

The SIM determines whether an operation is to be carried out immediately or to be queued according to the function code of the CCB structure. All queued operations, such as ``Execute SCSI I/O'' (reads or writes), are placed by the SIM on a nexus-specific queue and return with a CAM status of CAM_INPROG.

Some immediate operations, as described in the American National Standard for Information Systems, SCSI-2 Common Access Method: Transport and SCSI Interface Module, working draft, X3T9.2/90-186, may not be executed immediately. However, all CCBs to be carried out immediately return to the XPT layer at once. For example, the ABORT CCB command does not always complete synchronously with its call; however, the CCB_ABORT returns to the XPT immediately. An XPT_RESET_BUS CCB returns to the XPT following the reset of the bus.

8.2.2    The sim_init Routine

The sim_init routine initializes the SIM. The SIM clears all its queues and releases all allocated resources in response to this call. This routine is called using the function address contained in the CAM_SIM_ENTRY structure. This routine can be called at any time; the SIM layer must ensure that data integrity is maintained.

8.3    Digital-Specific Features of the SIM Layers

This section describes Digital-specific features of the SIM layers of the CAM subsystem.

8.3.1    SCSI I/O CCB Priorities

In the Digital implementation of the SCSI/CAM Architecture, the SIM layer of the CAM subsystem can give priority to certain SCSI I/O CCBs based on the value of the cam_vu_flags member of the CCB_SCSIIO. The following priorities are defined in the /usr/sys/include/io/cam/dec_cam.h file and can be set by a SCSI/CAM peripheral device driver in the cam_vu_flags member of the CCB_SCSIIO:

Flag Name	Description
DEC_CAM_HIGH_PRIOR	This CCB is assigned high priority by the SIM.
DEC_CAM_MED_PRIOR	This CCB is assigned medium priority by the SIM.
DEC_CAM_LOW_PRIOR	This CCB is assigned low priority by the SIM.
DEC_CAM_ZERO_PRIOR	This CCB is not assigned a priority by the SIM.

The Digital SCSI/CAM peripheral disk device driver uses this feature in its cdisk_strategy function for reads and writes that do not have the B_ASYNC bit set in the b_flags member of the buf structure associated with the read or write request.

This feature can be used in conjunction with the Digital SCSI/CAM SCSI I/O CCB reordering feature.

You can disable this feature by setting the sim_allow_io_priority_sorting variable in the /usr/sys/data/cam_data.c file to 0 (zero).

The following example shows how the SIM performs priority sorting:

1. The SIM queue for the bus, target, and LUN of 0, 0, 0 contains the following SCSI I/O CCB:

   CCB_SCSIIO #1 - Priority of DEC_CAM_LOW_PRIOR

2. The SIM receives a second SCSI I/O CCB, CCB_SCSIIO #2, with a priority level of DEC_CAM_HIGH_PRIOR, which is given priority over CCB_SCSIIO #1. The SIM queue now appears as follows:

   CCB_SCSIIO #2 - Priority of DEC_CAM_HIGH_PRIOR CCB_SCSIIO #1 - Priority of DEC_CAM_LOW_PRIOR

3. The SIM receives a third SCSI I/O CCB, CCB_SCSIIO #3, with a priority level of DEC_CAM_HIGH_PRIOR. CCB_SCSIIO #3 is given priority over CCB_SCSIIO #1, but is placed after CCB_SCSIIO #2:

   CCB_SCSIIO #2 - Priority of DEC_CAM_HIGH_PRIOR CCB_SCSIIO #3 - Priority of DEC_CAM_HIGH_PRIOR CCB_SCSIIO #1 - Priority of DEC_CAM_LOW_PRIOR

8.3.2    SCSI I/O CCB Reordering

In the Digital implementation of the SCSI/CAM architecture, the SIM layer of the CAM subsystem can reorder SCSI I/O CCBs, based on a value provided by the SCSI/CAM peripheral device driver. SCSI I/O CCB reordering obtains maximum performance from the device by minimizing the head movement of the device.

The SCSI disk device driver uses SCSI I/O CCB reordering for devices that have the SZ_REORDER flag set in the dd_flags member of the device descriptor entry in the cam_devdesc_tab device array. This array is contained in /usr/sys/data/cam_data.c. file. The following SCSI I/O CCBs can be reordered:

• Character and block device reads

• Block device writes

SCSI I/O CCB reordering performed in the SIM layer does not affect any SCSI/CAM peripheral device drivers that do not use it.

The cam_sort member has been added to the CCB_SCSIIO structure. This member replaces the cam_osd_rsvd0 member specified in American National Standard for Information Systems, SCSI-2 Common Access Method: Transport and SCSI Interface Module, working draft, X3T9.2/90-186.

The SCSI disk driver specifies that a SCSI I/O CCB can be reordered by assigning a value to the cam_sort member. Typically, this value is the logical block number (LBN) specified by the command descriptor block (CDB) for the SCSI I/O CCB. If the cam_sort member has a value of 0 (zero), the SCSI I/O CCB is not reordered and no SCSI I/O CCBs are placed before it in the SIM queue for that device. The CAM flag, CAM_SIM_QHEAD, takes priority over the cam_sort member. A CCB with the CAM_SIM_QHEAD flag set is always placed at the head of the SIM queue for that device.

You can disable this feature by setting the sim_allow_io_sorting variable in the /usr/sys/data/cam_data.c file to 0 (zero).

In a busy system, some SCSI I/O CCBs may have to wait if reordering is allowing many other SCSI I/O CCBs to be handled first. The SIM has been configured so that it does not allow a SCSI I/O CCB to wait for more than 2 seconds. If a SCSI I/O CCB has reached this maximum wait limit, no other SCSI I/O CCBs can be inserted before it. You can change the 2-second limit by assigning the desired value to the sim_sort_age_time variable in the /usr/sys/data/cam_data.c file.

The following example shows how the SIM performs SCSI I/O CCB reordering:

1. Assume that the last cam_sort value processed by the SIM was LBN 20.

2. The SIM receives SCSI I/O CCBs with the following cam_sort values in the following order:

   50 23 1 7 28 15 19 60

3. Sorting produces the following result:

   23 28 50 60 1 4 7 15 19