I am sponsoring the following fasttrack for Grant Zhang, requesting patch
binding and a timeout of 08/29/2007.
This proposal is being driven by the Sun Media Management System (SMMS)
product needing to know error details for the last failed tape
operation.
-Chris
Template Version: @(#)sac_nextcase 1.64 07/13/07 SMI
This information is Copyright 2007 Sun Microsystems
1. Introduction
1.1. Project/Component Working Name:
MTIOCGETERROR
1.2. Name of Document Author/Supplier:
Author: Grant Zhang
1.3 Date of This Document:
20 August, 2007
4. Technical Description
Background
----------
PSARC 1999/085 introduces a partner-private ioctl
USCSIGETRQS which provides a mechanism for returning the
sense data from the last SCSI I/O process to a user-level
application. USCSIGETRQS was later removed in PSARC 2003/629
under the consideration that request sense data can be
retrieved via uscsi(7I) interface. uscsi interface allows
user-level applications to send individual SCSI commands and
if the command returns a Check Condition status, the driver
will automatically issue a Request Sense command and return
the sense data along with the original status.
Problem
-------
User-level applications are interested in getting the sense
data for better handling errors in st(7D) driver. Currently
user-level applications only get error registers(sense key
error) from st in the MTIOCGET ioctl and this is not enough.
Sun Media Management System (SMMS) needs to know the details
of an error so that SMMS may take the proper action to deal
with it. The uscsi interface may return sense data, but only
for the individual SCSI command sent from the uscsi
interface. Under certain situations st driver sends out
SCSI commands on the behalf of the users who may not know
the individual SCSI commands. For example, the MTOFFL ioctl
sends a REWIND and a UNLOAD command to the tape drive;
neither commands are done via uscsi. If MTOFFL fails, there
is no way for the user to know which commands fail and why.
The lack of sense data reporting mechanism also promotes
the user-level applications to use the uscsi interface,
which is deemed detrimental to a driver like st: e.g. st's
uscsi implementation having to snoop in order to maintain
state information, like position.
In summary ST needs to provide a mechanism to provide sense
data for a specified tape drive that returned CHECK
CONDITION. Such a mechanism will help steer the user-level
applications away from mixing st and uscsi.
Proposed Solution
-----------------
The proposal is to introduce a new mtio ioctl MTIOCGETERROR
+ ioctl(fd, MTIOCGETERROR, caddr_t arg)
The argument is a pointer to a mterror_entry structure.
struct mterror_entry {
size_t mtee_cdb_len; /* CDB length */
uchar_t *mtee_cdb_buf; /* CDB sent to device */
size_t mtee_arq_status_len; /* scsi_arq_status length */
struct scsi_arq_status *mtee_arq_status;
/* scsi_arq_status */
}
This new ioctl allows user-level applications to retrieve
error records from the st driver. An error record consists
of the SCSI command cdb which causes the error, and an auto
request sense scsi_arq_status(9S) structure if available.
The scsi_arq_status(9S) structure supplies the SCSI status
of the original command, the transport information
pertaining to the request sense command and the request
sense data.
st driver maintains an error record stack which stores each
generated error record. The error record stack operates as
follows:
o Each error pushes a new error record on the stack.
o Each MTIOCGETERROR pops one error record off the stack,
and returns the information to the user application. An
MTIOCGETERROR to an empty stack returns an error(ENXIO). An
application that wants to consume all the error records
accumulated for the last 'command' will issue MTIOCGETERROR
until it returns the empty stack error.
o Each new call to driver entry function (read/write/ioctl
/open/close) will clear the error record stack (pop
everything off). The MTIOCGETERROR ioctl itself is special,
and does not empty the stack.
The user-level application is responsible for allocating and
releasing the memory for mtee_cdb_buf and mtee_arq_status
of each mterror_entry. The mtee_cdb_len field might be updated
to the actual length of CDB, if the actual length of CDB is
less than the specified mtee_cdb_len.
Before issuing the ioctl, the mtee_arq_status_len value
should be at least equal to "sizeof(struct scsi_arq_status)".
If more sense data than the size of scsi_extended_sense(9S)
is desired then the mtee_arq_status_len may be larger
than "sizeof(struct scsi_arq_status)" by the amount
of additional extended sense data desired. The es_add_len
field of scsi_extended_sense(9S) can be used to determine
the amount of valid sense data returned by the device.
The following pseudo code snippet shows how a user-level
application may use the MTIOCGETERROR ioctl to get error
records.
fd = open(/dev/rmt/2, O_RDWR|O_NDELAY);
if (ioctl(fd, MTOFFL) < 0) {
struct mterror_entry *err_entry;
err_entry->mtee_cdb_buf = malloc(cdblen);
err_entry->mtee_cdb_len = cdblen;
err_entry->mtee_arq_status = malloc(statuslen);
err_entry->mtee_arq_status_len = statuslen;
while (ioctl(fd,MTIOCGETERROR,err_entry)==0) {
parse_error_record(err_entry);
}
}
Proposed manpage changes to mtio (7I) are attached.
Interface Table
---------------
------------------------------------------------------------------
Interface Level Comments
------------------------------------------------------------------
New:
MTIOCGETERROR(7I) Committed ioctl to retrieve
error record from st
Release Binding
---------------
Micro release/patch binding is requested
References
----------
USCSIGETRQS ioctl
http://sac.sfbay/PSARC/1999/085/
Common Solaris Target Disk Driver update
http://sac.sfbay/PSARC/2003/629/
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name: ON
6.5. ARC review type: FastTrack
Manpage changes(output of diff -C10) to mtio (7I):
***************
*** 638,658 ****
--- 638,669 ----
uchar_t speeds[MT_NSPEEDS]; /* speed codes, low->hi */
ushort_t non_motion_timeout; /* Seconds for non-motion */
ushort_t io_timeout; /* Seconds for data to from tape */
ushort_t rewind_timeout; /* Seconds to rewind */
ushort_t space_timeout; /* Seconds to space anywhere */
ushort_t load_timeout; /* Seconds to load tape and ready */
ushort_t unload_timeout; /* Seconds to unload */
ushort_t erase_timeout; /* Seconds to do long erase */
};
+ /* structure for MTIOCGETERROR- get recent sense
+ * data command */
+ struct mterror_entry {
+ size_t mtee_cdb_len; /* CDB length */
+ uchar_t *mtee_cdb_buf; /* CDB sent to device */
+ size_t mtee_arq_status_len; /* scsi_arq_status length */
+ struct scsi_arq_status *mtee_arq_status;
+ /* scsi_arq_status buffer */
}
The MTWEOF ioctl is used for writing file marks to tape. Not
only does this signify the end of a file, but also usually
SunOS 5.11 Last change: 31 July 2006 10
***************
*** 832,851 ****
--- 843,867 ----
The MTIOCGETDRIVETYPE get drivetype ioctl call returns the
name of the tape drive as defined in st.conf (name), Vendor
ID and model (product), ID (vid), type of tape device
(type), block size (bsize), drive options (options), max-
imum read retry count (max_rretries), maximum write retry
count (max_wretries), densities supported by the drive (den-
sities), and default density of the tape drive
(default_density).
+ The MTIOCGETERROR ioctl call returns the most recent
+ SCSI commands which caused CHECK CONDITION. The status
+ of the commands and the generated sense data are
+ returned as well.
Persistent Error Handling IOCTLs and Asynchronous
MTIOCPERSISTENT enables/disables persistent error
handling
6. Resources and Schedule
6.4. Steering Committee requested information
6.4.1. Consolidation C-team Name:
ON
6.5. ARC review type: FastTrack
6.6. ARC Exposure: open
