Template Version: @(#)onepager.txt 1.30 06/09/28 SMI 1. Introduction 1.1. Project/Component Working Name: St: Scsi Tape logical block Interface 1.2. Name of Document Author/Supplier: Author: Randy Ralphs 1.3. Date of This Document: 04/16/07 1.4. Name of Major Document Customer(s)/Consumer(s) 1.4.1. The PAC or CPT you expect to review your project: Solaris PAC 1.4.2. The ARC(s) you expect to review your project: PSARC 1.4.3. The Director/VP who is "Sponsoring" this project: Scott.Tracy@Sun.COM 1.4.4. The name of your business unit: N2SD 1.5. Email Aliases: 1.5.1. Responsible Manager: Dan.Maslowski@sun.com 1.5.2. Responsible Engineer: randall.ralphs@sun.com 1.5.3. Marketing Manager: 1.5.4. Interest List: 2. Project Summary 2.1. Project Description: This project is to make st(7D), the Solaris Scsi Tape driver Logical Block count aware and support Logical Block query and positioning ioctl(2)'s equivalent to those used on Linux and other operating systems. 2.2. Risks and Assumptions: The intent is to maintain current functionality while adding logical block awareness and positioning. The risk is that this has been so long in coming that almost all backup and restore applications have implemented there own logical block code using uscsi(7I) pass thru. To do so they had to spoof st into believing the legacy position was valid while also send all positioning commands with the USCSI_SILENT flag set. Knowing that this was being done, this project attempts to anticipate how the current driver is being used and not break such applications. However some application my use sgen(7D) or their own pass thru drivers which makes it hard or even impossible to guess what side effects might occur. 3. Business Summary 3.1. Problem Area: Ideas and projects from STK and MPXIO for tape can not be done as the currently implemented positioning doesn't allow for recovery of lost positioning. 3.2. Market/Requester: Requests from Sun StorageTek to have multipath for tape would require the ability to resume down another data path after establishing position. 3.3. Business Justification: Having logical block positioning is an enabler to recover individual command failures. 3.4. Competitive Analysis: Linux has had this for many years. IBM currently provides a tape target driver that supports this on Solaris and other operating systems for there tape products. The IBM driver proves that customers will look elsewhere for improved functionality for their tape drives on the Solaris platform. Where we can win is that they only support a subset of tape drives that we do and that they have to deal with issues of forcing binding to their driver. 3.5. Opportunity Window/Exposure: We have missed this window but not doing this could cause us to miss market windows for command recovery and multipath tape. 3.6. How will you know when you are done?: After passing all existing tape tests and tests of new interfaces work as expected. 4. Technical Description: 4.1. Details: This project is to implement Logical Block positioning within st. Currently st only supports the block/file (legacy) positioning schema. In this method the position is counted in files from the beginning of tape and blocks from the beginning of the correct file. If position is lost or unsure. The only means of reestablishing position is to rewind, space to the desired file, then read or space to the desired block within that file. There is no way to query the drive for its block/file position. Logical Block positioning is an absolute position from the beginning of the tape partition. In this method each recorded entity is counted without regard to its type. For example writing one data block or writing one filemark would advance the logical block count by one. If the position is lost or unsure the host can query the drive for the position using the SCSI READ POSITION command. If the position is not what is expected, a SCSI LOCATE command can be used to return to the expected position. This project does not propose to replace the block/file mode with Logical Block mode. It would in many cases keep track of both. The exceptions are when the user does commands that do not allow the counting of block/file position. Commands such as random locates (seek) or space commands that are not relative to the current position (space EOD for example) would put st into a pure "Logical" positioning mode. Issuing a rewind would return it to "Legacy" mode where both the file/block and Logical positions are valid. In the case where the user or application does a relative positioning command such as a SCSI SPACE via the USCSI command or via an MTFSF ioctl for example. St will do a READ POSITION immediately so that the logical position remains valid. When an error or reset occurs, The position mode gets set to "Invalid". While the position mode is Invalid all reads and writes will fail to prevent reading the wrong block or potentially over writing customer data. If a user or application does a SCSI READ POSITION via USCSICMD, a MTTELL via MTIOCTOP (or MTIOCLTOP) or an mt(1) tell command the position mode will be promoted to Logical. Because the current st(7D) has no means of positioning outside the file/block mode. Commands that were not relative to the current position could not be supported. Logical Block mode will allows st to use more of the SCSI command set. Other then the already mentioned Locate command. The Space Sequential Filemarks and Space to End-Of-Data can now be supported. The MTFSFM and MTBSFM were added to space forward and backward to the location where there are N filemarks in a row. St already supports the MTEOM (space to End Of recorded Medium) ioctl by spacing forward a large number of files till EOD (End Of Data) is detected. However if a device is already in Logical mode, it will use the Space to EOD SCSI command as there is no need to count files for positioning. Because the SCSI-3 standard dropped support for space commands to setmarks they were not added. 4.2. Bug/RFE Number(s): 1243433 st: need to implement SCSI fast search support 4.3. In Scope: Obvious. 4.4. Out of Scope: This project does not implement the recovery of position on failed commands, resets, and transport failures. The positioning in the tapepos_t structure includes a partition field but this project does not add an interface to create partitions. The few drives that support partitioning I've seen had different means of creating partitions. However if a tape has more then one partition, the MTIOCRESTPOS ioctl should allow changing partitions of those drives that do so by the SCSI standard LOCATE with change partition set method. 4.5. Interfaces: mt(1) CLI: Adds commands tell, seek, fssf, bssf and load. mtio(7I): MTIOCGET ioctl. Add MTF_LOGICAL_BLOCK to mt_flag of the mtget structure returned by this ioctl. This will allow application that run on different Solaris releases to tell if the new interfaces are available. MTIOCTOP ioctl add mt_op's. (operations) MTTELL Add to read logical position. Returned mt_count contains position value. MTSEEK Add to locate to a logical position. Passed mt_count contains requested position. MTFSSF Add to forward space over sequential file marks. MTBSSF Add to backward space over sequential file marks. MTLOCK Add to lock media. MTUNLOCK Add to unlock media. MTIOCLTOP New ioctl that uses a new structure mtlop. Since logical block numbers can be 64 bit in length and the old mtop structure mt_count would truncate values on some platforms. The new structure will work all previous operations (mt_op) but will use the new mtlop structure to pass 64 bit mt_count values. The old MTIOCTOP will be maintained for compatibility and will return ERANGE when a value is to large for its mt_count field. tapepos_t structure typedef enum { invalid, legacy, logical } posmode; typedef struct tapepos { uint64_t lgclblkno; int32_t fileno; int32_t blkno; int32_t partition; pstatus eof; posmode pmode; char pad[4]; }tapepos_t; Since tape position really contains more state then just a block number. Depending on the position mode (pmode) st can use this to store a current position or get back to a previous position. The fileno and blockno are valid while in legacy mode. The lgclblkno is the logical block position and should be valid when the pmode is not invalid (lost). The eof keeps track of state that includes information about where the location is with in a file and if it is near or after the End Of Tape (EOT). MTIOCGETPOS Get current position tapepos_t. Gets the current position state. This interface is not implemented in mt. This more focused toward position aware backup and restore utilities and white box testing. MTIOCRESTPOS Restore tape position tapepos_t. Also not implemented in mt for same reasons. 4.6. Doc Impact: man pages for: mt(1) Add descriptions for user commands tell, seek and load. mtio(7I) Add flag Add MTF_LOGICAL_BLOCK to mt_flag field of the mtget structure. Add descriptions for the following ioctl()'s MTFSSF Forward space over sequential file marks. MTBSSF Backward space over sequential file marks. MTTELL Read Logical Position. MTSEEK Locate to a Logical Position. MTLOCK Lock Media. MTUNLOCK Unlock Media. MTIOCPOS Get current position tapepos_t. MTIOCRESTPOS Restore tape position tapepos_t. 4.7. Admin/Config Impact: Adds to available commands for mt(1). 4.8. HA Impact: none. 4.9. I18N/L10N Impact: none. 4.10. Packaging & Delivery: none. 4.11. Security Impact: none. 4.12. Dependencies: none. 5. Reference Documents: http://t10.org/ftp/t10/drafts/spc3/spc3r23.pdf http://t10.org/ftp/t10/drafts/ssc/ssc-r22.pdf http://sac.sfbay.sun.com/PSARC/1997/114/ 6. Resources and Schedule: 6.1. Projected Availability: Nevada Q4 2007 S10 Q1 2008 6.2. Cost of Effort: One developer for 2 months. 6.3. Cost of Capital Resources: Uses existing resources. 6.4. Product Approval Committee requested information: 6.4.1. Consolidation or Component Name: Solaris ON 6.4.3. Type of CPT Review and Approval expected: Standard 6.4.4. Project Boundary Conditions: none 6.4.5. Is this a necessary project for OEM agreements: No 6.4.6. Notes: none 6.4.7. Target RTI Date/Release: snv_64 6.4.8. Target Code Design Review Date: 6.4.9. Update approval addition: none 6.5. ARC review type: Standard 7. Prototype Availability: 7.1. Prototype Availability: Nightly builds at: /net/bsvr-1001.central/export/local9/rralphs/nv_logical_block/archives 7.2. Prototype Cost: One developer 2 weeks.