Writing Custom SCSI Routines

Transcription

1 Chapter 7 Writing Custom SCSI Routines Tornado Device Driver Workshop Copyright 7-1 Overview of SCSI. Using SCSI devices in a VxWorks Environment. Configuring VxWorks for your SCSI device. Putting Device Specific Commands on the SCSI Bus. Note: This chapter does not include writing a SCSI controller driver.

2 Writing Custom SCSI Routines 7.1 Defining SCSI Configuration Communicating with a SCSI Target Tornado Device Driver Workshop Copyright 7-2 What is SCSI. SCSI Terminology.

3 What is SCSI SCSI VxWorks Application VxWorks SCSI Driver Device 0.. SCSI Device 6 Peripheral 0.. Peripheral 7 Tornado Device Driver Workshop Copyright 7-3 Acronym for Small Computer System Interface. ANSI standard intended to provide device independence. Advantage of SCSI: One controller can talk with multiple devices. SCSI Driver does not need to know how to talk with individual devices, only with SCSI. SCSI device 6 is an example of a controller talking with multiple peripherals. SCSI device 0 is an example of a newer peripheral with a built-in controller.

4 SCSI Bus Bus Id = 6 LUN = 3 Controller Bus Id = 6 Bus Id = 6 VxWorks SCSI Bus Bus Id = 5 LUN = 0 LUN = 5 Tape Initiator Drive Bus Id = 7 Tornado Device Driver Workshop Copyright 7-4 Initiator Target Bus Id LUN Device that invokes or initiates the action. VxWorks currently can be the only initiator on the bus, multiple targets are supported. Device to which request is made, not to be confused with a VxWorks target (which is the initiator in the SCSI world). Also known as the bus address, each device on the bus must have a unique address, addresses range from 0-7. Logical Unit Number - Each bus Id can have up to 8 logical units associated with it (0-7). SCSI Version SCSI-1 and SCSI-2 supported by VxWorks

5 Writing Custom SCSI Routines Defining SCSI 7.2 Configuration Communicating with a SCSI Target Tornado Device Driver Workshop Copyright 7-5 SCSI Data Structures. User Callable Routines. Remainder of chapter deals with on-board SCSI chip and supported controller drivers.

6 VxWorks and SCSI direct access device scsilib SCSI Controller Driver nonaccess direct onboard SCSI Chip Bus SCSI SCSI Target CPU Board Tornado Device Driver Workshop Copyright 7-6 Configure VxWorks to include SCSI or SCSI-2. Initialize data structures describing the physical device (target). For direct access devices, partition device, configure file system, and access device via the file system. For sequential devices with SCSI-2 support, partition device, configure tape file system, and access device via the file system. For non-direct access devices without SCSI-2 support, some further development is required. Direct access devices are the same as block devices.

7 SCSI Configuration Overview Generic SCSI Configuration and Initialization Direct Access Devices Non-Direct Access Devices Tornado Device Driver Workshop Copyright 7-7 The point here is that there is a generic SCSI configuration and initialization issues (generic in the sense that it is regardless of target type) and then two different paths depending on whether the target is a direct access (block) or non-direct access (character or non-block) device.

8 Configuring VxWorks Include SCSI-2 by defining INCLUDE_SCSI2 in wind/ target/config/target/config.h. Include SCSI by defining INCLUDE_SCSI in wind/target/ config/target/config.h. If the BSP includes DMA support, define INCLUDE_SCSI_DMA in wind/target/config/target/ config.h. To automatically locate and configure all the targets on the SCSI bus define SCSI_AUTO_CONFIG in wind/target/ config/target/config.h. Tornado Device Driver Workshop Copyright 7-8 If SCSI_AUTO_CONFIG is defined, scsiautoconfig is called which steps through all possible Bus Id s and LUN s trying to configure them. The most common use of auto configuring is to find out what s out on the bus. It can also be useful from boot code. A table of all the physical devices on the bus is stored in the SCSI_CTRL structure. If auto configuring this table will be initialized with all the physical devices on the SCSI bus (otherwise only the devices explicitly created with scsiphysdevcreate are listed). From boot code, we can then access this table to find out information about the device. If we know the make and model we can search the table for these strings and then access information about the device e.g. bus id or LUN without explicitly having to know the configuration.

9 Initializing SCSI Data Structures SCSI controller specific information Stored in SCSI_CTRL structure. Structure initialized when INCLUDE_SCSI2 or INCLUDE_SCSI defined. Addressed by global pointer psysscsictrl. SCSI target specific information Stored in SCSI_PHYS_DEV structure. Initialized by scsiphysdevcreate( ). Tornado Device Driver Workshop Copyright 7-9 Structures are defined in scsilib.h. psysscsictrl initialized in sysscsiinit() by calling driver specific controller create routine (e.g. wd33c93ctrlcreate()).

10 scsiphysdevcreate(...) Initializes structure for device described by args. Returns a pointer to a SCSI_PHYS_DEV structure or NULL on error. Should be called for each device on the SCSI bus. If not auto configuring, modify default target configuration in usrscsiconfig( ) in wind/target/src/ config/usrscsi.c. Tornado Device Driver Workshop Copyright 7-10

11 scsiphysdevcreate(...) SCSI_PHYS_DEV * scsiphysdevcreate (pscsictrl, devbusid, devlun, reqsenselength, devtype, removable, numblocks, blocksize) pscsictrl devbusid devlun reqsenselength devtype removable numblocks blocksize pointer to SCSI controller info device s SCSI bus Id device s logical unit number length of REQUEST SENSE data device returns type of SCSI device whether medium is removable number of blocks on device size of a block in bytes Tornado Device Driver Workshop Copyright 7-11 Note: The reqsenselength arg was, in older versions/patches, seltimeout which is now a global variable (scsiselecttimeout). ReqSenseLength is the maximum number of bytes the device supplies in response to a REQUEST SENSE command. This command is issued after a SCSI command fails to determine the cause. If set to NULL, VxWorks attempt to determine the value.

12 Direct Access Devices Once logical partition created, use file system initialization routines to set up a particular file system. Access to the SCSI device should be like accessing a file system on any other device. Tornado Device Driver Workshop Copyright 7-12 Calling scsiblkdevcreate( ) to create a logical partition for each random-access device returns a pointer to a control structure used to manage the logical device. Calling, e.g., dosfsdevinit ) initializes a DOS file system for each logical partition. At this point, no further development is necessary.

13 SCSI-2 Sequential Devices Once sequential partition created, use tape file system initialization routines to set up a sequential file system. Access to the SCSI device should be like accessing a file system on any other device. Tornado Device Driver Workshop Copyright 7-13 Calling scsiseqdevcreate( ) to create a logical partition for each sequential block device returns a pointer to a control structure used to manage the device. Calling tapefsdevinit ) initializes a file system for a sequential partition. At this point, no further development is necessary.

14 Modifying usrscsi.c If not auto configuring, modify default target configuration in usrscsiconfig( ) in wind/target/src/ config/usrscsi.c Example modification using usrscsiconfig( ): Configuration Current New busid 2 4 LUN 0 1 File systems 3 2 FS Types DOS DOS (blk size 0x20000) RT-11 Raw (use remainder RT-11 of disk) Tornado Device Driver Workshop Copyright 7-14

15 Code Segment from usrscsiconfig() 1 /* configure Winchester at busid = 2, LUN = 0 */ 2 if ((pspd20 = scsiphysdevcreate (psysscsictrl, 2, 0, 0, NONE, 0, 3 0, 0)) == (SCSI_PHYS_DEV *) NULL) 4 SCSI_DEBUG_MSG ( usrscsiconfig: scsiphysdevcreate 5 failed.\n ); 6 else 7 { 8 /* create block devices */ 9 if (((psbd0 = scsiblkdevcreate (pspd20, 0x10000, 0)) == 10 NULL) 11 ((psbd1 = scsiblkdevcreate (pspd20, 0x10000, 12 0x10000)) == NULL) 13 ((psbd2 = scsiblkdevcreate (pspd20, 0, 0x20000)) == 14 NULL)) 15 { 16 return (ERROR); 17 } Tornado Device Driver Workshop Copyright 7-15 The above code sample is from usrconfig.c for a MV147

16 Code Segment (cont d) 18 if ((dosfsdevinit ( /sd0/, psbd0, NULL) == NULL) 19 (rt11fsdevinit ( /sd1/, psbd1, 0, 256) == NULL) 20 (rt11fsdevinit ( /sd2/, psbd2, 0, 256) == NULL)) 21 { 22 return (ERROR); 23 } 24 } Tornado Device Driver Workshop Copyright 7-16

17 Modifications 1 /* configure Winchester at busid = 4, LUN = 1 */ 2 if ((pspd41 = scsiphysdevcreate (psysscsictrl, 4, 1, 0, NONE, 3 0, 0, 0)) == (SCSI_PHYS_DEV *) NULL) 4 SCSI_DEBUG_MSG ( usrscsiconfig: scsiphysdevcreate 5 failed.\n ); 6 else 7 { 8 /* create block devices */ 9 if (((psbd0 = scsiblkdevcreate (pspd41, 0x20000, 0)) 10 == NULL) 11 ((psbd1 = scsiblkdevcreate (pspd41, 0, 0x20000)) 12 == NULL)) 13 { 14 return (ERROR); 15 } 16 if ((dosfsdevinit ( /sd0/, psbd0, NULL) == NULL) 17 (rawfsdevinit ( /sd1/, psbd1) == NULL)) 18 { 19 return (ERROR); 20 } 21 } Tornado Device Driver Workshop Copyright 7-17

18 Debugging Tools From the VxWorks shell, use scsishow( ) to display the targets configured on the SCSI bus. In usrscsiconfig( ) define scsidebug = TRUE to display SCSI debug information. Use the macro SCSI_DEBUG_MSG to log SCSI debugging messages. SCSI_DEBUG_MSG ( mycmd: Error on Device ); Tornado Device Driver Workshop Copyright 7-18 Example: -> scsishow ID LUN VendorId ProductID Rev. Type Blocks BlkSize pscsiphysdev ARCHIVE VIPER R 0 0 0x003cf654 value = 0 = 0x0 scsishow( ) can be used to verify initiator is communicating with target. If target does not appear for scsishow( ), check physical connections, power and cabling. scsishow( ) can also be used to determine the bus id and LUN of targets as well as vender specific information (e.g. Model name and number.) Type is the device type in above ex. 1R indicates removable device

19 Writing Custom SCSI Routines Defining SCSI Configuration 7.3 Communicating with a SCSI Target Tornado Device Driver Workshop Copyright 7-19 Transaction Data Structure. Putting commands on the SCSI Bus.

20 Devices Without File Systems After calling scsiphysdevcreate( ) some additional development may be required. Use scsiioctl( ) to put target unique commands on the SCSI bus. Two types of user interface: Write functions to send command to target that the user can call directly, i.e. a non-standard driver interface. Write an I/O system interface. Tornado Device Driver Workshop Copyright 7-20

21 Putting Commands on the SCSI Bus For commands supported by scsilib, no additional development is required. To transfer commands to a target that are not supported by scsilib: Define command to put on SCSI bus. Build a SCSI transaction data structure describing SCSI transaction. Use scsiioctl( ) to put transaction request on the bus. Tornado Device Driver Workshop Copyright 7-21 See man page on scsilib for which SCSI commands are supported.

22 Defining a Custom Transaction Fields in SCSI_TRANSACTION data structure: cmdaddress cmdlength dataaddress datadirection address of SCSI command length of SCSI command in bytes address of data buffer direction of data transfer datalength length of data buffer in bytes (0= no data) addlengthbyte statusbyte if not equal to NONE, byte number of additional length (see next page) status byte returned from target Tornado Device Driver Workshop Copyright 7-22 cmdaddress is the address of a SCSI_COMMAND data structure typedef UINT8 SCSI_COMMAND [MAX_SCSI_CMD_LENGTH]; First element in array is the command opcode remaining fields are opcode specific. Refer to device s hardware manual for specific commands. Depending on command, data fields in the SCSI_TRANSACTION structure may be used to indicate that there is no data transfer for this command (e.g. a tape rewind). Both the SCSI_TRANSACTION and SCSI_COMMAND structures are defined in scsilib.h addlengthbyte is only used with commands where the target passes data to the initiator and the amount of data passed is device specific. addlengthbyte contains the byte number where the length of data is specified by the device. Low level SCSI routines use this value to determine how much data was passed back. For example the INQUIRY command s length of data is stored in the fifth byte (byte 4).

23 addlengthbyte SCSI_COMMAND. device scsilib SCSI_TRANSACTION addlengthbyte 4.. VxWorks n+4 n vendor unique data n bytes Tornado Device Driver Workshop Copyright 7-23 Some SCSI commands return vendor specific data. When this occurs the amount of data is going to vary from device to device. addlengthbyte indicates which byte position in the data, will give the amount of vendor unique data to follow.

24 Example Read transaction for a viper 150 tape drive: 1 SCSI_TRANSACTION viper150transact; 2 SCSI_COMMAND viper150cmd;... 3 viper150cmd[0]= viper150_opcode_read; 4 viper150cmd[1]= 0x1 /* defined by hardware manual */ 5 viper150cmd[2]= (UINT8)((blksToRead >> 16) & MASK); /* MSB */ 6 viper150cmd[3]= (UINT8)((blksToRead >> 8) & MASK); 7 viper150cmd[4]= (UINT8)(blksToRead & MASK); /* LSB */ 8 viper150cmd[5]= 0; 9 viper150transact.cmdaddress = viper150cmd; 10 viper150transact.cmdlength = 6; 11 viper150transact.dataaddress = (UINT8 *)buffer; 12 viper150transact.direction = READ; 13 viper150transact.datalength = sizeof (buffer); 14 viper150transact.addlengthbyte = NONE; Tornado Device Driver Workshop Copyright 7-24 Opcode stored in viper150cmd[0] determines value of remaining bytes in viper150cmd. This is defined by ANSI standard and described in target s hardware documentation. SCSI_COMMAND is typedef ed as an array of UINT8. The size of the command block depends on the command itself. In scsilib.h the typedef used the maximum size a command block can be.

25 Device Unique Commands To place a command that is not supported by scsilib on the SCSI bus, use: STATUS scsiioctl (pscsiphysdev, command, arg) pscsiphysdev command arg ptr to SCSI device information (note this is not a fd, we are not going through the I/O system) to place SCSI command on bus use FIOSCSICOMMAND for FIOSCSICOMMAND, arg is address of scsitransaction Tornado Device Driver Workshop Copyright 7-25 Example using transaction structure from previous page: if (scsiioctl (ptapephysdev, FIOSCSICOMMAND, &viper150transact) == ERROR) { SCSI_DEBUG_MSG( myinterface: scsiioctl error\n ); return(error): }

26 Custom Interface Build a set of library routines to access device using scsiioctl() Commands for a custom interface are device specific, but may include Rewinding the media Marking an end of file Reading/writing the device Seeking to a particular location on device Tornado Device Driver Workshop Copyright 7-26 Example of a custom interface for a SEEK command 1 STATUS viper150seek (int position) 2 { 3 SCSI_TRANSACTION viper150transact; 4 SCSI_COMMAND viper150cmd; 5 viper150cmd[0]=(uint8)viper150_opcode_seek; 6 viper150cmd[1]=(uint8)0x1; 7 viper150cmd[2]=(uint8)0x0; 8 viper150cmd[3]=(uint8)((position >>8) & MASK ); 9 viper150cmd[4]=(uint8)(position & MASK); 10 viper150cmd[5]=(uint8)0x0; 11 viper150transact.cmdaddress=viper150cmd; 12 viper150transact.cmdlength=6; 13 viper150transact.dataaddress=null; 14 viper150transact.datadirection=none; 15 viper150transact.datalength=0; 16 viper150transact.addlengthbyte=none; 17 if (scsiioctl(ptapephysdev, FIOSCSICOMMAND, &viper150transact) == ERROR) 18 { 19 SCSI_DEBUG_MSG( viper150seek: Seek Error\n ); 20 return(error); 21 } 22 return(ok);

27 SCSI I/O System Interface Conventions xxdevcreate xxopen xxread xxwrite xxioctl Call scsiphysdevcreate() Test if unit is ready, (loop until ready) then issue command to set density of target, if appropriate Build transaction structure for read command and put on SCSI bus Build transaction structure for write command and put on bus Build transaction structures appropriate for device specific commands Tornado Device Driver Workshop Copyright 7-27 For character drivers for which device only writes and reads fixed-size chunks: xxread( ) and xxwrite( ) must buffer any extra data beyond the fixed size blocks. Initialize buffer information on open and write out any remaining data as well as an end of file marker on close. See Appendix A: SCSI Example on page 11.

28 Summary scsiphysdevcreate( ) Direct Access Devices Non-Direct Access Devices scsiblkdevcreate( ) use file system initialization routines to put FS on SCSI block device scsiioctl( ) Tornado Device Driver Workshop Copyright 7-28