As its name suggests, a HwStartIo routine is the entry point for incoming requests to peripheral devices on the HBA-driven bus(es). HwStartIo is called with pointers to an SRB and to the miniport's device extension for per-HBA state.
If the miniport's DriverEntry routine also requested that memory be allocated for logical unit extensions (see DriverEntry Routine), the HwStartIo routine calls ScsiPortGetLogicalUnit with the input device extension pointer and the PathId, TargetId, and Lun values from the input SRB.
If the DriverEntry routine requested that memory be allocated for SRB extensions, the SrbExtension field in each SRB contains a pointer to the miniport's per-request storage area. Note that a miniport driver must request that memory be allocated for SrbExtensions if it maintains per-request state information. It cannot use an SRB for this purpose. In particular, a miniport driver can write values into SRBs only for the following purposes and only in the following fields:
After the higher-level SCSI class drivers have loaded, most of the SRBs sent to the HwStartIo routine have the Function field set to SRB_FUNCTION_EXECUTE_SCSI. On receipt of such a request, the StartIo routine does the following:
For example, a miniport driver might set up a logical unit extension with pointers to the SRB itself and the SRB DataBuffer pointer, the SRB DataTransferLength value, and a driver-defined value (or CDB SCSIOP_xxx value) indicating the operation to be carried out on the HBA.
For a device I/O operation, such an internal routine generally selects the target device and sends the CDB over the bus to the target logical unit.
If the miniport driver uses system DMA, it must call ScsiPortIoMapTransfer before programming the HBA to transfer data. ScsiPortIoMapTransfer sets up the system DMA controller and calls the miniport's HwDmaStarted routine, described in HwDmaStarted Routine, next.
A HwStartIo routine is also responsible for handling incoming SRBs with the Function field set to SRB_FUNCTION_ABORT_COMMAND. For an abort request, the miniport driver might need to verify that the given SRB has not been aborted already by calling ScsiPortGetSrb for the target logical unit and comparing the returned pointer to the current SRB's NextSrb value. If they are unequal, the current SRB has already been aborted, and the miniport driver should do the following:
Otherwise, the HwStartIo routine does the following:
The port driver always sends its own reset-bus requests directly to the miniport's HwResetBus routine, described in HwResetBus Routine. However, it is possible for the HwStartIo routine to be called with an SRB in which the Function field is set to SRB_FUNCTION_RESET_BUS if a SCSI class driver requests this operation. The StartIo routine can simply call the HwResetBus routine to satisfy an incoming reset request.
If the HBA caches data internally, as indicated when the HwFindAdapter routine (see HwFindAdapter Routines) set up the PORT_CONFIGURATION_INFORMATION, the HwStartIo routine must support the SRB_FUNCTION_FLUSH and SRB_FUNCTION_SHUTDOWN requests. An SRB with its Function field set to SRB_FUNCTION_FLUSH tells the miniport driver to transfer data cached in the HBA, usually to a disk. The miniport should hold on to the flush request until all cached data has been transferred and, then, complete the flush request. (Such a flush request might originate when an application closes a file or the application itself is terminated.)
An SRB with its Function field set to SRB_FUNCTION_SHUTDOWN tells the miniport driver to complete transferring data, including flushing all cached data, out to the target device. The miniport driver should hold on to the shutdown request until no data remains in the HBA's internal cache for the target logical unit and, then, complete the shutdown request. Note that the miniport can be called with more than one shutdown request, possibly for the same LU or with several shutdown requests for different LUs, before the system itself is actually shut down.
Whether a miniport driver handles SRB_FUNCTION_IO_CONTROL requests depends on whether the HBA is to provide dedicated support for an application. Supporting this request allows a set of privately defined device I/O control requests to be sent directly to the miniport driver. For SRBs with the Function field set to SRB_FUNCTION_IO_CONTROL, the DataBuffer field contains a pointer to a system-defined SRB_IO_CONTROL structure containing the driver-defined and application-specified ControlCode. Note that system-defined device I/O control requests sent to SCSI class drivers are mapped to SRBs with the Function field set to SRB_FUNCTION_EXECUTE_SCSI.
Every HwStartIo routine must handle the receipt of an unsupported SRB_FUNCTION_xxx, as follows:
1 Set the input SRB's SrbStatus to SRB_STATUS_INVALID_REQUEST.
2 Call ScsiPortNotification with the NotificationType RequestComplete and with the input SRB.
3 Call ScsiPortNotification again with the NotificationType NextRequest, or with NextLuRequest if the HBA supports tagged queueing or multiple requests per logical unit.
Every HwStartIo routine must return a Boolean value, indicating whether the input request was processed or should be resubmitted later (FALSE). However, the miniport eventually must call ScsiPortNotification twice for each SRB input to its StartIo routine: first, to complete the request (NotificationType RequestComplete) and, second, to tell the port driver to call the StartIo routine again with the next SRB (NotificationType NextRequest or NextLuRequest).
The HwStartIo routine of a miniport driver that manages its HBA exclusively by polling calls ScsiPortNotification with the NotificationType RequestTimerCall and a pointer to its HwTimer routine. For more information about the HwTimer routine, see HwTimer Routine.
The following SRB Function values are defined for use in future versions:
The port driver processes requests with the following SRB Function values without calling the miniport driver:
Miniport driver designers can assume that their miniports will never be sent an SRB with any of the immediately preceding Function values. The port driver handles these requests from SCSI class and filter drivers to protect these higher-level SCSI drivers from having to access any HBA-specific (or miniport-specific) state information in order to find their devices or cancel queued requests. This ensures that SCSI class and filter drivers have no dependencies on any particular model of HBA.
For more information about SRBs and the set of system-defined SRB_FUNCTION_xxx values, see the Introduction to SCSI Port Driver Services Reference.