NAME

scsi_changer − SCSI media changer device driver

DESCRIPTION

SCSI media changer devices mechanically move media between storage and usage locations.  Each potential media location has a specific element address and is one of the following element types:

storage A location to hold a unit of media not currently in use.  Typically most media will be located in this type of element. 

import/export A location for inserting and removing media from the device.  Movement of a unit of media to this type of location is in effect an eject operation.  Movement of a unit of media from this type of location is a load operation. 

data transfer A location for accessing media data.  This is generally the location of a device that reads and/or writes data on the media being handled by the media changer device.  Movement to this type of location is a physical-media-mount operation.  Movement from this type of location is a physical-media-unmount operation. 

media transport A location for media movement.  Media is generally temporarily located in this type of element only during actual media movement. 

The SIOC_INIT_ELEM_STAT ioctl causes the media changer device to take inventory.  As a result, the media changer device determines the status of each and every element address, including the presence or absence of a unit of media. 

The element addresses supported by a media changer device can be determined by use of the SIOC_ELEMENT_ADDRESSES ioctl.  The first valid element address and the number of elements is indicated for each element type.  These element addresses may be used as source and destination location arguments. 

The SIOC_ELEMENT_STATUS ioctl indicates the status of an element.  The element address for which status information is requested is specified via the element field.  The resulting status data indicates the presence or absence of a unit of media in that element address as well as other information. 

The SIOC_RESERVE and SIOC_RELEASE ioctls control access to element addresses.  Depending on the device, reservations may limit operator control of those element addresses in the media changer device.  Specific element addresses can be reserved to handle interlocking between multiple requesters if each requester has a unique reservation identification.  The value zero in the all_elements field specifies that a single element address should be reserved or released.  An element address reserved in this manner can not be reserved by another single element address reservation using a different reservation identification.  The reservation field specifies the reservation identification.  The element field specifies the element address to be reserved. 

The value “1” in the all_elements field indicates that all element addresses should be reserved.  The reservation and element fields should contain the value zero since these fields are not meaningful when reserving all element addresses.  Reserving all element addresses is primarily useful for limiting operator control. 

The SIOC_MOVE_MEDIUM and SIOC_EXCHANGE_MEDIUM ioctls reposition unit(s) of media.  Depending of the source and destination element types, this may result in a media load, eject, mount, unmount, or simple repositioning.  Media can be “flipped” using values of “1” in the invert, invert_first, or invert_second fields.  The SIOC_EXCHANGE_MEDIUM ioctl repositions two different units of media.  One unit of media is moved from the element specified by the source field to the element specified by the first_destination field.  A second unit of media is moved from the element specified by the first_destination field to the element specified by the second_destination field.  An exchange occurs if the source and second_destination fields are the same. 

The following is included from <sys/scsi.h>:

#define SIOC_INIT_ELEM_STAT      _IO(’S’, 51)
#define SIOC_ELEMENT_ADDRESSES   _IOW(’S’, 52, struct element_addresses)
#define SIOC_ELEMENT_STATUS      _IOWR(’S’, 53, struct element_status)
#define SIOC_RESERVE             _IOW(’S’, 54, struct reservation_parms)
#define SIOC_RELEASE             _IOW(’S’, 55, struct reservation_parms)
#define SIOC_MOVE_MEDIUM         _IOW(’S’, 56, struct move_medium_parms)
#define SIOC_EXCHANGE_MEDIUM     _IOW(’S’, 57, struct exchange_medium_parms)
/* structure for SIOC_INIT_ELEM_STAT ioctl */
struct element_addresses {
        unsigned short  first_transport;
        unsigned short  num_transports;
        unsigned short  first_storage;
        unsigned short  num_storages;
        unsigned short  first_import_export;
        unsigned short  num_import_exports;
        unsigned short  first_data_transfer;
        unsigned short  num_data_transfers;
};
/* structure for SIOC_ELEMENT_STATUS ioctl */
struct element_status {
        unsigned short  element;          /* element address */
        unsigned char   full:1;           /* holds a a unit of media */
        unsigned char   reserved:1;       /* is currently reserved */
        unsigned char   except:1;         /* is in an abnormal state */
        unsigned char   access:1;         /* transport element accessible */
        unsigned char   export_enable:1;  /* allows media removal (eject) */
        unsigned char   import_enable:1;  /* allows media insertion (load) */
        unsigned char   resv1:2;
        unsigned char   resv2;
        unsigned char   sense_code;       /* info. about abnormal state */
        unsigned char   sense_qualifier;  /* info. about abnormal state */
        unsigned char   not_bus:1;        /* transfer device SCSI bus differs */
        unsigned char   resv3:1;
        unsigned char   id_valid:1;       /* bus_address is valid */
        unsigned char   lu_valid:1;       /* lun is valid */
        unsigned char   resv4:1;
        unsigned char   lun:3;            /* transfer device SCSI LUN */
        unsigned char   bus_address;      /* transfer device SCSI address */
        unsigned char   resv4;
        unsigned char   resv5:6;
        unsigned char   invert:1;         /* media in element was inverted */
        unsigned char   source_valid:1;   /* source_element is valid */
        unsigned short  source_element;   /* last storage location of medium */
        char            pri_vol_tag[36];  /* volume tag (device optional) */
        char            alt_vol_tag[36];  /* volume tag (device optional) */
        unsigned char   misc_bytes[168];  /* device specific */
};
/* structure for SIOC_RESERVE and SIOC_RELEASE ioctls */
struct reservation_parms {
        unsigned short  element;
        unsigned char   identification;
        unsigned char   all_elements;
};
/* structure for SIOC_MOVE_MEDIUM ioctl */
struct move_medium_parms {
        unsigned short  transport;
        unsigned short  source;
        unsigned short  destination;
        unsigned char   invert;
};
/* structure for SIOC_EXCHANGE_MEDIUM ioctl */
struct exchange_medium_parms {
        unsigned short  transport;
        unsigned short  source;
        unsigned short  first_destination;
        unsigned short  second_destination;
        unsigned char   invert_first;
        unsigned char   invert_second;
};

WARNING

Some media changer devices do not support the SIOC_INIT_ELEM_STAT and SIOC_ELEMENT_STATUS ioctls.  For some of these devices, it may be possible to determine the full or empty status of an element address by attempting media movement using that element address as both the source and destination arguments of a media movement operation. 

Many media changer devices do not support the SIOC_EXCHANGE_MEDIUM ioctl.  For these devices, multiple SIOC_MOVE_MEDIUM ioctl operations may be used to accomplish the same results, provided a suitable temporary element address may be found. 

SEE ALSO

scsi(7), autochanger(7), mknod(1M). 

Hewlett-Packard Company  —  HP-UX Release 9.0: August 1992