Gathered Write Commands

The gathered write commands facilitate communication applications that are required to send header and trailer messages with data buffers. These headers and trailers are typically the same or similar for each transfer. Therefore, there might be a single copy of these messages but multiple data buffers.

The gathered write commands, accessed through the sc_buf.resvd1 field, differ from the spanned commands, accessed through the sc_buf.bp field, in several ways:

• Gathered write commands can transfer data regardless of address alignment, where as spanned commands must be memory page-aligned in address and length, making small transfers difficult.
• Gathered write commands can be implemented either in software (which requires the extra step of copying the data to temporary buffers) or hardware. Spanned commands can be implemented in system hardware due to address-alignment requirements. As a result, spanned commands are potentially faster to run.
• Gathered write commands are not able to handle read requests. Spanned commands can handle both read and write requests.
• Gathered write commands can be initiated only on the process level, but spanned commands can be initiated on either the process or interrupt level.

To execute a gathered write command, the SCSI device driver must:

• Fill in the resvd1 field with a pointer to the uio struct
• Call the SCSI adapter device driver on the same process level with the sc_buf structure in question
• Be attempting a write
• Not have put a non-null value in the sc_buf.bp field

If any of these conditions are not met, the gathered write commands do not succeed and the sc_buf.bufstruct.b_error is set to EINVAL.

This interface allows the SCSI adapter device driver to perform the gathered write commands in both software or and hardware as long as the adapter supports this capability. Because the gathered write commands can be performed in software (by using such kernel services as uiomove), the contents of the resvd1 field and the uio struct can be altered. Therefore, the caller must restore the contents of both the resvd1 field and the uio struct before attempting a retry. Also, the retry must occur from the process level; it must not be performed from the caller's iodone subroutine.

To support SCSI adapter device drivers that perform the gathered write commands in software, additional return values in the sc_buf.bufstruct.b_error field are possible when gathered write commands are unsuccessful.

Note: The gathered write command facility is optional for both the SCSI device driver and the SCSI adapter device driver. Attempting a gathered write command to a SCSI adapter device driver that does not support gathered write can cause a system crash. Therefore, any SCSI device driver must issue a SCIOGTHW ioctl operation to the SCSI adapter device driver before using gathered writes. A SCSI adapter device driver that supports gathered writes must support the SCIOGTHW ioctl as well. The ioctl returns a successful return code if gathered writes are supported. If the ioctl fails, the SCSI device driver must not attempt a gathered write. Typically, a SCSI device driver places the SCIOGTHW call in its open routine for device instances that it will send gathered writes to.