Scsimon driver

Introduction

The purpose of this driver is to log the comings and goings of SCSI devices within the Linux SCSI subsystem. If CONFIG_HOTPLUG has been selected in a recent 2.4 series kernel then it invokes /sbin/hotplug. It is an upper level driver, like sd, sr, st and sg. Scsimon is a relatively small driver and currently does not require any modifications to the rest of the SCSI subsystem. This driver now appears in the Mandrake 8.2 distribution.

Design

The scsimon driver is a character device with a single device name: /dev/scsimon [it appears as /dev/misc/scsimon in a system using devfs]. The driver records all SCSI device attaches and detaches and assigns a unique event_count to each. Three lists are available: The attached device list contains essentially the same information as can be seen in 'cat /proc/scsi/scsi' plus the attach event counts and the time (since boot) of the attachments. The detached device list contains information about the <n> most recently detached devices, together with their detachment times and both their attachment and detachment event counts. The scsimon driver locally stores INQUIRY and host data for detached devices since it may be no longer available from the rest of the SCSI subsystem. The host list provides a way of matching a host number to the host's name and its associated information field. Previously it was not easy to detect a SCSI adapter (i.e. a "host") that did not have any devices attached.

The use of event counts and storing detached device information is an attempt free user space programs of the requirement to be synchronized, especially with device detachment notifications.

Multiple user space programs can access the /dev/scsimon device at the same time. The lists are accessed via ioctls and individual calls can obtain a single element, part or all of a list. The list data provided by a single call is guaranteed to be self consistent and the current event_count is provided with all calls.

Additionally, if CONFIG_HOTPLUG is set, then the /sbin/hotplug program is invoked with the argument "scsi" when SCSI devices are attached or detached. Data about the newly attached or detached device is passed to the user space agent via environment variables:
   ACTION=%s [add or remove]
   SCSI_HOST=%u
   SCSI_BUS=%u
   SCSI_TARGET=%u
   SCSI_LUN=%u
   SCSI_VENDOR=%s
   SCSI_MODEL=%s
   SCSI_REV=%s
   SCSI_TYPE=%d          [0 for direct access device, 1 for ...]
   SCSI_REMOVABLE=%d     [1 for removable, 0 for not removable]
   SCSI_EMULATED=%d      [1 implies native to another stack (emulated)]
   SCSI_ACCESS_COUNT     [number of sd, sr and sg open() active on this device]
   SCSI_WRITEABLE=%d
   SCSI_LOCKABLE=%d
   SCSI_EVENT_ATTACHED=%lu
   [ SCSI_EVENT_DETACHED=%lu when ACTION=remove  ]
 

Details

The driver is accessed via the "misc" char major device (major: 10) and it takes a minor number from the range reserved for local use [247], see the Documentation/devices.txt file. If this driver proves useful, then I will try to obtain an official minor number. These commands may be useful to create an appropriately named device (if devfs is not present):
    $ cd /dev ; mknod scsimon c 10 247
There is a script called MAKEDEV in the tarball that will do this.

Apart from hotplugging techniques, a user space application could monitor for changes with the poll() system call. Provision has also been made for a SIGIO signal bearing POLL_IN for an attach and a POLL_HUP for detach (this hasn't been implemented as yet).

The scsimon driver does not solve all the addressing problems in the SCSI subsystem. Finding out which /dev/sd<x> device corresponds to a recently reported (via scsimon) attachment of a SCSI "direct access device"  may still require some scanning. Using devfs will help in this regard. Also there is no mechanism to lock a given device to the name /dev/sda (for example). This leads to the pathological case in which a newly detected disk is promptly detached and a subsequent attach of another disk is given the same disk name. All this may happen before a user space hotplug agent mounts a file system on the original disk. Since the attach event count represents a unique identifier of a scsi device session, then scsimon could be used to check that value immediately after a mount, and if it has changed, rollback the mount.

Since the scsimon driver maintains state information, the "autoclean" feature that causes its module to be unloaded when there are no open file descriptors can be a nuisance. Hence there is a SCSIMON_LOCK_MOD ioctl that locks the module in memory (by bumping its internal usage count).

This experimental driver was formerly called "scsiinfo" which unfortunately clashed with a Linux utility of the same name. Hence this driver's name has been changed to scsimon [and hopefully no-one is confused by the mid level module name: scsi_mod.o and this module name: scsimon.o].
 

Downloads

Here is a link to a tarball that contains patch for lk 2.4.18 . Also found in that tarball are older patches for lk 2.4.17, 2.4.13, 2.4.10, 2.4.7 and 2.4.3 . Included in that tarball is a small test programs that exercises the available ioctl calls in the driver. Also include is a simple hotplug agent called "scsi.agent" (to put in the /etc/hotplug directory) that loads scsi upper level modules based on the scsi type of the newly added device.

Hopefully this driver will be accepted into the linux kernel 2.5 development series (or, alternatively, some of scsimon functionality will be placed in the scsi mid level). Here is a scsimon tarball for lk 2.5.20 and there are some earlier versions for the lk 2.5 series in the same directory. In the lk 2.5 series devfs (if configured) conveniently "makes" /dev/misc/scsimon and /dev/scsimon (a symlink to the former) when the scsimon driver is loaded.

Information about the Linux hotplugging project can be found at sourceforge.net/projects/linux-hotplug/ .
 

Changelog

Here is the log for the most version (from the scsimon.h file):

    Version: 0.1.96 (20020409)

    Changes since 0.1.95 (20020106)
        - remove loaded_as_module
    Changes since 0.0.95 (20020101)
        - fork for lk 2.5 series
    Changes since 0.0.94 (20011017)
        - add SCSIMON_SET_ONLINE_STATE ioctl() [id is att_event]
        - add device info: writeable, changed, lockable, online
    Changes since 0.0.93 (20010722)
        - add MODULE_LICENSE
    Changes since 0.0.92 (20010313)
        - add SCSIMON_SEND_HOST_IOCTL
        - make access_count available
 
 

Doug Gilbert (dgilbert@interlog.com)
Last updated: 17th June 2002