Writing Device Drivers

Command Transport

As part of command transport, the HBA driver accepts a command from the target driver, issues the command to the device hardware, services any interrupts that occur, and manages timeouts.


The tran_start(9E) entry point for a SCSI HBA driver is called to transport a SCSI command to the addressed target. The SCSI command is described entirely within the scsi_pkt(9S) structure, which the target driver allocated through the HBA driver's tran_init_pkt(9E) entry point. If the command involves a data transfer, DMA resources must also have been allocated for the scsi_pkt(9S) structure.

The tran_start(9E) entry point is called when a target driver calls scsi_transport(9F).

tran_start(9E) should perform basic error checking along with whatever initialization the command requires, queue the command for execution on the HBA hardware, and return without blocking. If the hardware is idle, the command may be started immediately.

For commands with the FLAG_NOINTR bit set in the pkt_flags field of the scsi_packet(9S) structure, tran_start(9E) should not return until the command has been completed, and the HBA driver should not call the pkt completion routine.

Example 14-10 demonstrates how to handle the tran_start(9E) entry point. The ISP hardware provides a queue per-target device. For devices that can manage only one active outstanding command, the driver itself is typically required to manage a per-target queue and starts up a new command upon completion of the current command in a round-robin fashion.

Example 14-10 HBA Driver tran_start(9E) Entry Point

static int
	struct scsi_address						*ap,
	struct scsi_pkt						*pkt)
	struct isp_cmd						*sp;
	struct isp						*isp;
	struct isp_request						*req;
	u_long						cur_lbolt;
	int						xfercount;
	int						rval	= TRAN_ACCEPT;
	int						i;

	sp = (struct isp_cmd *)pkt->pkt_ha_private;
	isp = (struct isp *)ap->a_hba_tran->tran_hba_private;

	sp->cmd_flags = (sp->cmd_flags & ~CFLAG_TRANFLAG) |
	pkt->pkt_reason = CMD_CMPLT;

	 * set up request in cmd_isp_request area so it is ready to
	 * go once we have the request mutex
	req = &sp->cmd_isp_request;

	req->req_header.cq_entry_type = CQ_TYPE_REQUEST;
	req->req_header.cq_entry_count = 1;
	req->req_header.cq_flags			= 0;
	req->req_header.cq_seqno = 0;
	req->req_reserved = 0;
	req->req_token = (opaque_t)sp;
	req->req_target = TGT(sp);
	req->req_lun_trn = LUN(sp);
	req->req_time = pkt->pkt_time;
	ISP_SET_PKT_FLAGS(pkt->pkt_flags, req->req_flags);

	 * Set up dma transfers data segments.
	if (sp->cmd_flags & CFLAG_DMAVALID) {

		if (sp->cmd_flags & CFLAG_CMDIOPB) {
			(void) ddi_dma_sync(sp->cmd_dmahandle,
			    sp->cmd_dma_offset, sp->cmd_dma_len,

		ASSERT(sp->cmd_cookiecnt > 0 &&
		    sp->cmd_cookiecnt <= ISP_NDATASEGS);

		xfercount = 0;
		req->req_seg_count = sp->cmd_cookiecnt;
		for (i = 0; i < sp->cmd_cookiecnt; i++) {
			req->req_dataseg[i].d_count =
			req->req_dataseg[i].d_base =
			xfercount +=

		for (; i < ISP_NDATASEGS; i++) {
			req->req_dataseg[i].d_count = 0;
			req->req_dataseg[i].d_base = 0;

		pkt->pkt_resid = xfercount;

		if (sp->cmd_flags & CFLAG_DMASEND) {
			req->req_flags |= ISP_REQ_FLAG_DATA_WRITE;
		} else {
			req->req_flags |= ISP_REQ_FLAG_DATA_READ;
	} else {
		req->req_seg_count = 0;
		req->req_dataseg[0].d_count = 0;

	 * Set up cdb in the request
	req->req_cdblen = sp->cmd_cdblen;
	bcopy((caddr_t)pkt->pkt_cdbp, (caddr_t)req->req_cdb,

	 * Start the cmd.  If NO_INTR, must poll for cmd completion.
	if ((pkt->pkt_flags & FLAG_NOINTR) == 0) {
		rval = isp_i_start_cmd(isp, sp);
	} else {
		rval = isp_i_polled_cmd_start(isp, sp);

	return (rval);

Interrupt Handler and Command Completion

The interrupt handler must check the status of the device to be sure the device is generating the interrupt in question. It must also check for any errors that may have occurred and service any interrupts generated by the device.

If data was transferred, the hardware should be checked to determine how much data was actually transferred, and the pkt_resid field in the scsi_pkt(9S) structure should be set to the residual of the transfer.

For commands marked with the PKT_CONSISTENT flag when DMA resources were allocated through tran_init_pkt(9E), the HBA driver must ensure that the data transfer for the command is correctly synchronized before the target driver's command completion callback is performed.

Once a command has completed, there are two requirements:

It is important to start a new command on the hardware, if possible, before calling the PKT_COMP command completion callback. The command completion handling may take considerable time, as the target driver will typically call functions such as biodone(9F) and possibly scsi_transport(9F) to begin a new command.

The interrupt handler must return DDI_INTR_CLAIMED if this interrupt is claimed by this driver; otherwise, the handler returns DDI_INTR_UNCLAIMED.

Example 14-11 shows an interrupt handler for the SCSI HBA isp driver. The caddr_t argument is the parameter set up when the interrupt handler was added in attach(9E) and is typically a pointer to the state structure allocated per instance.

Example 14-11 HBA Driver Interrupt Handler

static u_int
isp_intr(caddr_t arg)
	struct isp_cmd						*sp;
	struct isp_cmd						*head, 	*tail;
	u_short						response_in;
	struct isp_response						*resp;
	struct isp						*isp 	= (struct isp *)arg;
	struct isp_slot						*isp_slot;
	int						n;

	if (ISP_INT_PENDING(isp) == 0) {

	do {
		 * head list collects completed packets for callback later
		head = tail = NULL;

		 * Assume no mailbox events (e.g. mailbox cmds, asynch
		 * events, and isp dma errors) as common case.
		if (ISP_CHECK_SEMAPHORE_LOCK(isp) == 0) {

			 * Loop through completion response queue and post
			 * completed pkts.  Check response queue again
			 * afterwards in case there are more
			isp->isp_response_in =
			    response_in = ISP_GET_RESPONSE_IN(isp);

			 * Calculate the number of requests in the queue
			n = response_in - isp->isp_response_out;
			if (n < 0) {
				    isp->isp_response_out + response_in;

			while (n-- > 0) {
				sp = (struct isp_cmd *)resp->resp_token;

				 * copy over response packet in sp
				isp_i_get_response(isp, resp, sp);

				if (head) {
					tail->cmd_forw = sp;
					tail = sp;
					tail->cmd_forw = NULL;
				} else {
					tail = head = sp;
					sp->cmd_forw = NULL;


			if (head) {
				isp_i_call_pkt_comp(isp, head);
		} else {
			if (isp_i_handle_mbox_cmd(isp) != ISP_AEN_SUCCESS) {
				return (DDI_INTR_CLAIMED);
			 * if there was a reset then check the response
			 * queue again
			goto again;	

	} while (ISP_INT_PENDING(isp));


static void
	struct isp					*isp,
	struct isp_cmd					*head)
	struct isp					*isp;
	struct isp_cmd					*sp;
	struct scsi_pkt					*pkt;
	struct isp_response	*resp;
	u_char					status;

	while (head) {
		sp = head;
		pkt = sp->cmd_pkt;
		head = sp->cmd_forw;

		ASSERT(sp->cmd_flags & CFLAG_FINISHED);

		resp = &sp->cmd_isp_response;

		pkt->pkt_scbp[0] = (u_char)resp->resp_scb;
		pkt->pkt_state = ISP_GET_PKT_STATE(resp->resp_state);
		pkt->pkt_statistics = (u_long)
		pkt->pkt_resid = (long)resp->resp_resid;

		 * if data was xferred and this is a consistent pkt,
		 * we need to do a dma sync
		if ((sp->cmd_flags & CFLAG_CMDIOPB) &&
		    (pkt->pkt_state & STATE_XFERRED_DATA)) {

			(void) ddi_dma_sync(sp->cmd_dmahandle,
			    sp->cmd_dma_offset, sp->cmd_dma_len,

		sp->cmd_flags = (sp->cmd_flags & ~CFLAG_IN_TRANSPORT) |

		 * Call packet completion routine if FLAG_NOINTR is not set.
		if (((pkt->pkt_flags & FLAG_NOINTR) == 0) &&
		    pkt->pkt_comp) {

Timeout Handler

The HBA driver should be prepared to time out the command if it is not complete within a specified time unless a zero timeout was specified in the scsi_pkt(9S) structure.

When a command times out, the HBA driver should mark the scsi_pkt(9S) with pkt_reason set to CMD_TIMEOUT and pkt_statistics OR'd with STAT_TIMEOUT. The HBA driver should also attempt to recover the target and/or bus and, if this recovery can be performed successfully, mark the scsi_pkt(9S) with pkt_statistics OR'd with either STAT_BUS_RESET or STAT_DEV_RESET.

Once the command has timed out and the target and bus recovery attempt has completed, the HBA driver should call the command completion callback.

Note -

If recovery was unsuccessful or not attempted, the target driver may attempt to recover from the timeout by calling scsi_reset(9F).

The ISP hardware manages command timeout directly and returns timed-out commands with the necessary status, so the isp sample driver timeout handler checks active commands for timeout state only once every 60 seconds.

The isp sample driver uses the timeout(9F) facility to arrange for the kernel to call the timeout handler every 60 seconds. The caddr_t argument is the parameter set up when the timeout is initialized at attach(9E) time. In this case, the caddr_t argument is a pointer to the state structure allocated per driver instance.

If the driver discovers timed-out commands that have not been returned as timed-out by the ISP hardware, the hardware is not functioning correctly and needs to be reset.