send(D2sdi)

send -- queue a request for Host Bus Adapter

Synopsis

   long prefixsend(struct hbadata *hbap, int flag);

Description

The send( ) entry point routine queues requests for HBAs, and generally is used for every request. After the target driver has entered the pointer to the SCSI command block in the device-specific request block (previously allocated by the getblk(D2sdi) routine), it calls sdi_send(D3sdi) or sdi_xsend(D3sdi), which invokes the appropriate HBA-specific send( ) routine. The target driver has no awareness of the HBA request block.

Arguments

hbap: a pointer to the device-specific request block defining the request to be queued
flag: indicates whether the request may sleep or not, and is set to either KM_SLEEP or KM_NOSLEEP

Return values

On success, send( ) returns SDI_RET_OK. On failure, it returns SDI_RET_ERR. For a request retry, it returns SDI_RET_RETRY.

Usage

Each HBA send( ) routine should be capable of handling an unlimited number of send requests and can choose either to send or queue the request, depending on the current state of the hardware. Rather than requiring target drives to know how many requests an HBA can handle under the best of conditions, the target drivers typically provide no queuing and send down all possible requests. The HBA driver should have a simple and fast queue mechanism, while maintaining the optimum number of active jobs at the controller. With this scheme, the HBA driver can achieve the maximum throughput from the HBA hardware.

The argument passed to this routine is a hbadata(D4sdi) structure. If the HBA hardware supports scatter-gather or programmed I/O, merging requests should be attempted while queuing the request. As would be expected, if no requests are currently pending, or if the optimum number of active requests has not been reached, the request being sent to the HBA driver should be started immediately.

Sequential access devices, such as tape drivers, must process jobs on a first-come/first-served basis. To do otherwise risks data corruption. Direct access devices can process jobs in any order they see fit.

Context and synchronization

If flag is KM_SLEEP, blockable context. If flag is KM_NOSLEEP, non-blockable context.

Applicable hardware

All

Version applicability

sdi: 1, 2, 3, 4 HBA drivers.

References

getblk(D2sdi), sdi_send(D3sdi), sdi_xsend(D3sdi)