An Introduction to SCSI Drivers This month, I’m going to talk about writing a driver for a simple SCSI controller under Linux. The Linux kernel SCSI layer does most of the work for SCSI device handling, so a simple SCSI driver is relatively painless to write. For more advanced devices, however, the kernel’s SCSI code is actually too clever — there are plans afoot to streamline it and solve these problems. Alan Cox Sunday, August 15th, 1999 Community Tools Recommend This [?] (No Ratings Yet)  Loading ... Users That Liked This [?] No one yet. Be the first. Tags:  No Comments This month, I’m going to talk about writing a driver for a simple SCSI controller under Linux. The Linux kernel SCSI layer does most of the work for SCSI device handling, so a simple SCSI driver is relatively painless to write. For more advanced devices, however, the kernel’s SCSI code is actually too clever — there are plans afoot to streamline it and solve these problems. The job of a SCSI driver is different than that of a block device driver. The upper layers of the SCSI code handle CD-ROMs, disks and other devices. Requests from these upper layers are turned into SCSI command blocks before they are fed to your driver. This means your SCSI driver need only worry about low-level SCSI requests and not about other aspects of the kernel device structure. In order to illustrate SCSI drivers I’m going to invent a SCSI controller that has a simple command interface. Sadly, this is rarely the case for real devices. However, our imaginary SCSI controller will make the examples much easier to follow. This should be enough to get you started — dealing with the complexities of a particular piece of hardware would take up more space than this column allows. Overall Driver Structure A Linux SCSI driver contains seven main functions: * The detect function is called by the SCSI layer when the driver is initialized. It is responsible for scanning for the controller and registering whatever it finds with the SCSI layer. Oncecontrollers are registered, the SCSI layer will issue commands to the controller to probe the SCSI devices on the chain. * The queuecommand function issues a SCSI command and does not wait for it to finish. This is used by almost all operations. When the command completes, the driver calls back up to the SCSI layer to inform it of the completion, passing back any error information it may find. * The command function issues a SCSI command synchronously and then waits for it to complete. Most drivers do this by calling their own queuecommand function. * The abort and reset functions are used to handle error situations orcases where the SCSI layer thinks a command has gone missing. The SCSI layer will first attempt to abort a command which has gone astray; if this isn’t effective, then the SCSI layer may need to reset the entire controller. Hopefully, this will never happen. * The info function returns a description of the actual controller itself. This descriptor tends to be a very short piece of code. * Finally, the bios_param function is called by the SCSI layer to ask the controller to query its BIOS for a faked disk geometry, or to have the driver compute a geometry itself. This is necessary as the mapping of SCSI blocks to the PC disk geometry has never been properly standardized; different controllers implement this in different ways. The detect function [ see Figure 1 ] is called at boot time or when a SCSI module is loaded. For our example we are going to assume that there can be only one card and that it behaves sanely. Figure 1: The myscsi_detect Function int myscsi_detect(Scsi_Host_Template *tpnt) { struct Scsi_Host *shpnt; int io = 0×320, irq = 11; /* Assume fixed for example */ if(myscsi_probe(io, irq) == 0) { /* Found - create an instance of this controller */ shpnt = scsi_register(tpnt, 0); if(shpnt == NULL) return 0; shpnt->unique_id = io; shpnt->io_port = io; shpnt->n_io_port = MY_PORT_RANGE; shpnt->irq = irq; shpnt->this_id = MY_SCSI_ID; my_hardware_init(shpnt); if(request_irq(irq, my_irq_handler, 0, “myscsi”, shpnt)) { scsi_unregister(shpnt); printk(”my_scsi: IRQ %d is busy.n”, irq); return 0; } } return 1; } In our example we will use a fixed IO and IRQ. A real controller would either read PCI space or would probe a list of common addresses. The logic to probe for a particular device is hidden here in the function myscsi_probe . After probing for the controller, we create a device structure using scsi_register . tpnt is the template passed into the detect function, described later in the article. The returned structure, shpnt , represents the particular controller which we have registered. We pass 0 for the second argument of scsi_register , as no driver-private memory area is needed. Passing a size arranges for a private block to be allocated as shpnt->hostdata , for convenience. Now we start to fill in the shpnt structure. unique_id is for distinguishing multiple cards. In our case, the I/O portis a convenient choice for this. this_id holds the ID of the controller itself. Each SCSI device has an identity, including the controller ID, which the kernel SCSI layer needs to know about. We assume for this example that it is fixed. We then call the my_hardware_init routine, which initializes the actual hardware. You get to write this routine to do whatever initialization the hardware requires. Linux Magazine / August 1998 / Gearheads / Page 1 2 3 feedback mail to a friend printer-friendly version        page 1 2 3   next >>   Linux Magazine / August 1999 / GEARHEADS ONLY An Introduction to SCSI Drivers

The next step is to register an interrupt handler in the usual way. If we can’t register an interrupt handler, we are stuck. In this case we unregister the SCSI controller and report no controllers found. We also let the user know, so as to avoid confusion.

If everything worked correctly, we report that one controller was found. (A real driver would count all detected controllers and return that value.) The SCSI layer will now go off and scan for devices hanging off of this controller. We will take care of this by using the queuecommand and command functions.

The queuecommand routine in Figure 2 takes two arguments: a pointer to the command structure, and the function pointer ( done ), which this driver should call when the command completes.

Figure 2: The myscsi_queuecommand Function

 int myscsi_queuecommand(Scsi_Cmnd *SCpnt, void (*done)(Scsi_Cmnd *))
 {
     int io, i;
     unsigned long flags;
     io = SCpnt->host->io_port;    /* Dig out our I/O port */
     current_command = SCpnt;
     current_command->scsi_done = done;
     current_command->SCp.Status = 0;
     save_flags(flags);
     cli();
     outb(SCpnt->target, io + TARGET_PORT);
     for(i = 0;i < SCpnt->cmd_len;i++)
         outb(SCpnt->cmnd[i], io + BUF + i);
     outb(COMMAND_BEGIN, io + COMMAND);
     restore_flags(flags);
     return 0;
}

For this example, we will assume that the controller handles only one command at a time. This is typical for a cheap ISA controller, but not for decent hardware. If we supported many concurrent SCSI commands we couldn’t use a global current_command value, but would need to keep some kind of list and match replies from the card to the list entries. This is basic programming and not important to our understanding of the driver structure.

Using the outb kernel routine to perform I/O, we load the target device into the card, then we load the command. SCSI commands are blocks of up to 16 bytes, including length information. After pushing the command to the card, we kick it to begin operation and allow interrupts as we are ready to handle the result of the command.

After queuing the command, we return back to the SCSI layer. If there is no response to the command, the SCSI layer will bother us after a timeout.

When the SCSI layer does want to bother us about commands that have gone astray, it will call our abort function; if that fails, it will call our reset function. Many simpler controllers cannot abort a queued command. If so, the abort function is quite simple, as can be seen in Figure 3.

Figure 3: The myscsi_abort Function

 int myscsi_abort(Scsi_Cmnd *SCpnt)
 {
     return SCSI_ABORT_SNOOZE;
}

In returning SCSI_ABORT_ SNOOZE , the driver is asking the kernel to wait a bit longer and hope that the command completes. If this doesn’t happen, the kernel will get bored of waiting and call our reset function. Alternately, abort can return SCSI_ABORT_ PENDING to indicate that the command is in the process of being aborted, but hasn’t yet — for example, in case an interrupt must first confirm the abort. The other two options are to return SCSI_ ABORT_SUCCESS , if we aborted the command successfully, and SCSI_ABORT_ BUSY if the driver is busy (or if there is some other reason we would like to abort, but cannot do so right now).

After trying to abort and reissue failing commands, the SCSI layer will try to reset things. It first tries to reset the device, then the SCSI bus, and finally the SCSI controller itself.

How you handle a reset depends on the ability of the controller hardware. A simple example of this function can be seen in Figure 4.

Figure 4: The myscsi_reset Function

 int myscsi_reset(Scsi_Cmnd *SCpnt, unsigned int flags)
 {
     myhardware_reset(SCpnt->host);
     return SCSI_RESET_PENDING;
}

For our example, we assume that the controller is fairly dumb and simply reset the SCSI controller itself, using the myhardware_reset function (which you should write). Returning SCSI_ RESET_PENDING indicates that the card has been reset but that commands will be returned with a failure status later. If the controller reset caused commands to be returned immediately, we could return SCSI_RESET_SUCCESS and allow commands to be reissued. If we do not think this type of reset is appropriate, we can return SCSI_ RESET_PUNT .

The flags argument is a set of four flags designed to provide hints as to what to reset and how. The important flags are SCSI_RESET_SUGGEST_ BUS_RESET , used when the SCSI layer thinks the entire bus should be reset, and SCSI_RESET_ SUGGEST_HOST_RESET , which is the last resort hint to the driver that it might be appropriate to completely restart the board itself.

The next step is to describe the controller interrupt handler [ see Figure 5 ]. The details of an interrupt handler can vary substantially between cards. For our example driver, I’m going to assume that the controller will interrupt us on two conditions: when it is ready for data to be read and/or written as the result of a command, and when a command completes.

Figure 5: The my_irq_handler Function

 int my_irq_handler(int irq, void *dev_id, struct pt_regs *regs)
 {
     struct Scsi_Host *shpnt = dev_id;
     int io = shpnt->io_port;
     u16 data;
     data = inw(io + READ_STATUS);
     if(data & RESET_DONE)
     {
         current_command->result = DID_RESET << 16;
         current_command->scsi_done(current_command);
         return;
     }
     if(data & PARITY_ERROR)
     {
         current_command->result = DID_PARITY << 16;
         current_command->scsi_done(current_command);
         return;
     }
     if(data & GENERAL_ERROR)
     {
         current_command->result = DID_ERROR << 16;
         current_command->scsi_done(current_command);
         return;
     }
     if(data & DATA_OUT)
     {
         outsw(port + DATA_FIFO,
             current_command->request_buffer,
             current_command->request_bufflen);
     }
     if(data & DATA_IN)
     {
         int len = inw(port + DATA_LEN);
         if(len > current_command->request_bufflen)
             len = current_command->request_bufflen;
 insw(port + DATA_FIFO, current_command->request_buffer,
                 current_command->request_bufflen);
     }
     if(data & COMMAND_DONE)
     {
         current_command->status = inb(port + CMD_STATUS);
         current_command->scsi_done(current_command);
     }
}

When we requested the interrupt, we used the host pointer as dev_id — a device-specific field that is passed to the handler by the kernel. This makes it very easy for us to find which card we are handling in a driver that is supporting multiple interface cards. We then dig out our I/O port as we will probably need to utilize this often in the interrupt handler.

First the handler checks if the bus has been reset (either by the driver or by other devices). If so, we report that the command was reset. This will also inform the SCSI layer that the reset we reported as pending in our reset function has now completed.

Next we check for errors. A real driver should check for as many errors as can be identified. Here, we show handling of parity errors and “general” errors (those without any particular meaning). The SCSI layer will handle recovery from an error situation.

Then we look to see if this interrupt is due to a SCSI phase change. SCSI commands pass through a set of phases during their lifetime. A smart controller handles all of these phases automatically, whereas a dumb controller usually needs some help from the driver. In our case, we will assume that the only phase changes that will need driver assistance are ‘data in’ and ‘data out,’ in which we will copy bytes to or from the SCSI device as the result of a previously-issued command.

To send data to the board, we copy the buffer found in current_command->request_buffer to the board, using the outsw I/O routine. A real SCSI controller may use DMA for this operation instead.

To read data from the board, we first check how many bytes were received and copy them to the command request buffer, using the insw I/O routine.

If a SCSI command has completed, we read its status from the board and set it in the current_command structure, calling the scsi_done routine of the command to inform the SCSI layer that it’s done.

SCSI commands can also be issued synchronously, through the command function, although this is rarely used. Supporting synchronous commands is best done in terms of the queuecommand function, shown by the code in Figure 6.

Figure 6: The myscsi_command Function

 static void it_finished(Scsi_Cmnd *SCpnt)
 {
     SCpnt->SCp.Status++;
 }
 int myscsi_command(Scsi_Cmnd *SCpnt)
 {
     myscsi_queuecommand(SCpnt, it_finished);
     /* Wait for the command to complete */
     while(!SCpnt->SCp.Status)
         barrier();
     return SCpnt->result;
}

We queue a command and tell the queue function that the completion handler ( scsi_done ) is it_finished , which simply increments the command status value. Having issued the command, we spin in a loop until the command finishes. The barrier() statement is important here. gcc might otherwise optimize:

while(variable)

to:

if(variable)
    while(1);

barrier tells the compiler that it cannot cache values from variables across the barrier() function call. This ensures that the status, which is changed by an interrupt, will be seen by the looping code.

 const char *myscsi_info(struct Scsi_Host *SChost)
 {
     return(”My SCSI device”);
 }

 int sym53c416_bios_param(Disk *disk, kdev_t dev, int *ip)
 {
     int size;
     size = disk->capacity;
     ip[0] = 64; /* heads */
     ip[1] = 32; /* sectors */
     if((ip[2] = size >> 11) > 1024)
                      /* cylinders, test for
                             big disk */
     {
         ip[0] = 255; /* heads */
         ip[1] = 63; /* sectors */
         ip[2] = size / (255 * 63); /* cylinders */
     }
     return 0;
}

 int myscsi_release(struct Scsi_Host *SChost)
 {
     free_irq(SChost->irq, SChost);
     return 0;
 }

 extern int myscsi_detect(Scsi_Host_Template *);
 extern const char *myscsi_info(struct Scsi_Host *)
 /* … other function definitions … */
 #define MYSCSI { 
 name:        “My SCSI Demo”, 
     detect:    myscsi_detect, 
     info:        myscsi_info, 
     command:    myscsi_command, 
     queuecommand:    myscsi_queuecommand, 
     abort:        myscsi_abort, 
     reset:        myscsi_reset, 
     bios_param:    myscsi_bios_param, 
     can_queue:    1, 
     this_id:    MY_SCSI_ID, 
     sg_tablesize:    SG_NONE,    
     cmd_per_lun:    1,        
     unchecked_isa_dma: 1,        
     use_clustering: ENABLE_CLUSTERING, 
     proc_dir:    &myscsi_proc 
    }

 struct proc_dir myscsi_proc =
 {
     PROC_SCSI_MYSCSI,
     “myscsi”,
     6,        /* Length of name */
     S _ IFDIR|S _ IRUGO|S _ IXUGO,
     2
};