unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 autochanger(7)						      autochanger(7)




 NAME
      autochanger - SCSI interfaces for medium changer device and magneto-
      optical autochanger surface device

 DESCRIPTION
      An autochanger is a SCSI mass storage device, consisting of a
      mechanical changer device, one or more data transfer devices (such as
      optical disk drives), and media (such as optical disks) for data
      storage.	The mechanical changer moves media between storage and usage
      locations within the autochanger.

      Depending on system architecture, one of two medium changer drivers
      (schgr or autox0) provides access to the medium changer device; a
      module (ssrfc) provides access to the surfaces of the optical disks.

      Two levels of functionality are provided by the medium changer
      drivers.	The mechanical changer device can be accessed directly to
      move media within the autochanger.  Alternatively, media surfaces can
      be accessed as unique devices, causing the changer driver to move the
      media into a drive to perform an I/O request.

      The schgr and autox0 medium changer device drivers follow the SCSI
      specification for medium changer devices to provide a generic medium
      changer interface, making it feasible to construct an application
      level driver for any mechanical changer, jukebox, library, or
      autochanger device (MO, tape, CD-ROM).

      However, the ssrfc module is provided specifically to support
      Hewlett-Packard magneto-optical disk autochanger products.

    Device Naming Convention
      The device naming convention for the autochanger driver enables
      accessing the changer device, as well as individual media surfaces.
      Block devices for autochangers reside in /dev/ac, character devices
      reside in /dev/rac.  Within these directories, names are derived from
      the "c#t#d#" device naming convention (explained in intro(7)), with
      the surface descriptor appended at the end.  Unique device names are
      determined by the card instance, target address of the SCSI changer
      device, LUN of the SCSI changer device, and the surface descriptor.

      The surface descriptor can be zero or non-specified for the changer
      device.  Also, there is no block special file for the changer itself.
      For example,

	   /dev/rac/c1t5d0

      is the character special file for the changer at SCSI target address 5
      and LUN 0, attached to SCSI card instance 1, and is equivalent to
      /dev/rac/c1t5d0_0.





 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 autochanger(7)						      autochanger(7)




      Any given surface is described by the card instance, SCSI target
      address and SCSI LUN of the changer, and then appended with a surface
      descriptor for the slot number and side.	For example,

	   /dev/ac/c1t5d0_1a

      is the block special file for surface 1a of the autochanger just
      mentioned and

	   /dev/rac/c1t5d0_1a

      is the character special file for the same surface 1a.

    Major and Minor Number Descriptions
      The following shows the bit assignments (dev_t format) used by the
      changer drivers to access the changer device and each surface within
      an autochanger:


      +-------+-------+-------+-------+--------+------+--+----------------+
      | 0     |	     7| 8	    15|16    19|20  22|23		31|
      +-------+-------+-------+-------+--------+------+--+----------------+
      |	    MAJOR     |	  INSTANCE    | TARGET | LUN  |	      SURFACE	  |
      +-------+-------+-------+-------+--------+------+--+----------------+

      MAJOR is the major number of the appropriate driver, INSTANCE is the
      card instance of the SCSI interface to which the changer device is
      attached, TARGET is the SCSI target address of the changer device, LUN
      is the SCSI LUN of the changer device, and SURFACE is the unique
      descriptor of each surface in the autochanger, as described in the
      following table. (Note, the surface descriptors refer to bits 23-31.)


	   +----------------+--------------------+
	   |	Surface	    | Surface descriptor |
	   +----------------+--------------------+
	   | changer device |	       00	 |
	   |	   1a	    |	       01	 |
	   |	   1b	    |	       02	 |
	   |	   2a	    |	       03	 |
	   |	   2b	    |	       04	 |
	   |	  ...	    |	      ...	 |
	   |	   31b	    |	       3e	 |
	   |	   32a	    |	       3f	 |
	   |	   32b	    |	       40	 |
	   |	  ....	    |	      ....	 |
	   +----------------+--------------------+

      All fields in the device number are specified in hexadecimal notation.
      Note that there is no support for hard partitions (sections) in this
      minor number.  If desired, partitioning can be achieved via LVM soft-



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 autochanger(7)						      autochanger(7)




      partitioning schemes.

      The major numbers used by the changer drivers are:


		     b_major | c_major |
		   +---------+---------+
	   schgr   |	29   |	 231   |
	   autox0  |	30   |	 230   |
		   +---------+---------+

      Following are long listings showing the major and minor numbers
      associated with the device special file names of the first surface and
      the changer:

      schgr:

      brw-rw-rw- 1 root sys  29 0x015001 Apr 22 10:22 /dev/ac/c1t5d0_1a
      crw-rw-rw- 1 root sys 231 0x015001 Apr 22 10:22 /dev/rac/c1t5d0_1a
      crw-rw-rw- 1 root sys 231 0x015000 Apr 22 10:22 /dev/rac/c1t5d0

      autox0:

      brw-rw-rw- 1 root sys  30 0x015001 Apr 24 11:35 /dev/ac/c1t5d0_1a
      crw-rw-rw- 1 root sys 230 0x015001 Apr 24 11:35 /dev/rac/c1t5d0_1a
      crw-rw-rw- 1 root sys 230 0x015000 Apr 24 11:35 /dev/rac/c1t5d0

 MAGNETO-OPTICAL AUTOCHANGER SURFACE DEVICE ACCESS
      To access disk surfaces within HP magneto-optical libraries, it is
      necessary to include the entry for the surface module, ssrfc, in the
      system configuration file /stand/system, as well as an entry for the
      appropriate SCSI changer driver, schgr or autox0, depending on
      architecture. The ssrfc module enables accessing a magneto-optical
      disk surface much like a disk device.  The disk is moved into an idle
      drive by the changer, then the requested disk I/O operation is
      performed.  Upon completion of the request, the disk is returned to
      its storage location within the autochanger.

      The surface module allows concurrent access to as many disks as there
      are drives in the autochanger product.  Requests for I/O on additional
      disks within the autochanger are blocked awaiting an available drive
      resource.

      By default, some commands (such as mount, newfs, and mediainit) open
      the device with the O_NDELAY flag set. Invocations of these commands
      on an autochanger surface do not wait for a drive resource to become
      available.  Instead, these requests return with EBUSY if no drive is
      available.

      Developers using the surface module functionality to access
      autochanger disks can invoke the open system call with the O_NDELAY



 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 autochanger(7)						      autochanger(7)




      flag to achieve this same "non-blocking" behavior:

	   error = open("/dev/rac/c1t5d0_1a",O_RDWR | O_NDELAY);

      If it is acceptable to block waiting for an available drive resource,
      the O_NDELAY flag is unnecessary.

      Here is a sample script to access multiple disk surfaces in an
      autochanger that has 2 drives, minimizing blocking:

	   dd if=/dev/rdsk/c0t0d0 of=/dev/rac/c1t5d0_1a bs=64k &
	   dd if=/dev/rdsk/c0t1d0 of=/dev/rac/c1t5d0_2a bs=64k &
	   wait
	   dd if=/dev/rdsk/c0t2d0 of=/dev/rac/c1t5d0_1b bs=64k &
	   dd if=/dev/rdsk/c0t3d0 of=/dev/rac/c1t5d0_2b bs=64k &
	   wait
	   ...

      For developers, the ioctl functions available for accessing magneto-
      optical disk surfaces are described in the manual pages for SCSI disk
      drivers.	Several ioctl functions provided specifically for magneto-
      optical disks will be described here briefly.  Included from
      <sys/scsi.h>:

	   #define SIOC_WRITE_WOE	_IOW('S', 17, int)
	   #define SIOC_VERIFY_WRITES	_IOW('S', 18, int)
	   #define SIOC_ERASE		_IOW('S', 19, struct scsi_erase)
	   #define SIOC_VERIFY_BLANK	_IOW('S', 20, struct scsi_verify)
	   #define SIOC_VERIFY		_IOW('S', 21, struct scsi_verify)

      SIOC_ERASE (erase) and SIOC_WRITE_WOE (write without erase) can be
      used together on character special devices.  By performing a pre-erase
      pass of magneto-optical disks, then later setting the SCSI disk driver
      in write-without-erase mode, improved write performance can be
      achieved, eliminating the two-pass erase-then-write which is normally
      necessary on magneto-optical devices.

      SIOC_VERIFY_WRITES (write and verify) performs a verification pass on
      any writes to magneto-optical disks.  This is a good safeguard for
      data integrity.  However, write operations performed with the
      verification pass exhibits a decrease in performance. When used with
      pre-erase and write-without-erase, write and verify provide increased
      reliability of data without decreased performance.  HP recommends
      operating in write-and-verify mode if also performing write-without-
      erase.

      The following are additional ioctl functions that might be desirable
      for some magneto-optical products, included from <sys/scsi.h>:

	   #define SIOC_GET_IR		_IOR('S', 14, int)
	   #define SIOC_SET_IR		_IOW('S', 15, int)



 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 autochanger(7)						      autochanger(7)




	   #define SIOC_SYNC_CACHE	_IOW('S', 70, int)

      SIOC_GET_IR determines the current state of immediate reporting (write
      caching) on the device. SIOC_SET_IR enables or disables immediate
      reporting on the device.	If SIOC_SET_IR is used to enable write
      caching, it may be desirable to flush the write cache using the
      SIOC_SYNC_CACHE  ioctl function.	The command /usr/sbin/scsictl may be
      used to perform the pre-erase of magneto-optical disks, set and check
      the status of immediate reporting.

      With the surface module configured, several ioctl functions to get
      status and information from the changer device are also available.
      These are SIOC_ELEMENT_ADDRESSES, SIOC_ELEMENT_STATUS, and
      SIOC_INQUIRY; they are explained further in the following section on
      the changer driver.  Functions that modify the state of the
      autochanger are not allowed when the surface module is configured into
      the kernel.

 SCSI MEDIUM CHANGER DEVICE DRIVER
      The SCSI medium changer device driver performs moves between different
      media locations within an autochanger.  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.

    Changer Control Requests
      The following ioctl functions are included from <sys/chgrio.h>:




 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000






 autochanger(7)						      autochanger(7)




	   #define CHGR_SSRFC_IS_PRESENT    _IOR('X', 1, int)
	   #define CHGR_CLEAR_RESET	    _IO('X', 2)

      CHGR_SSRFC_IS_PRESENT
	   For developers.  To determine if the surface module functionality
	   (ssrfc) is currently configured in the kernel.

      CHGR_CLEAR_RESET
	   For developers.  autox0 driver only.	 To clear a powerfail
	   recovery condition in the SCSI changer driver.  The
	   CHGR_CLEAR_RESET ioctl function will be necessary for developers
	   using the SCSI changer driver (autox0) to move media within the
	   medium changer, but not using the surface module for transparent
	   access to magneto-optical disks.  In the event of an ECONNRESET
	   error return from any changer ioctl call, a CHGR_CLEAR_RESET call
	   will be necessary prior to any further media moves. This alerts
	   the application of a possible power failure, and allows the
	   developer an opportunity to reset data structures, and re-reserve
	   elements in the medium changer, prior to further operations.

      The following ioctl functions and structure definitions are 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_ELEMENT_ADDRESSES 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 int	resv1:2;
		  unsigned int	import_enable:1; /* allows media insertion (load) */
		  unsigned int	export_enable:1; /* allows media removal (eject) */
		  unsigned int	access:1;	 /* transport element accessible */



 Hewlett-Packard Company	    - 6 -   HP-UX Release 11i: November 2000






 autochanger(7)						      autochanger(7)




		  unsigned int	except:1;	 /* is in an abnormal state */
		  unsigned int	operatr:1;	 /* medium positioned by operator */
		  unsigned int	full:1;		 /* holds a a unit of media */

		  unsigned char resv2;
		  unsigned char sense_code;	 /* info. about abnormal state */
		  unsigned char sense_qualifier; /* info. about abnormal state */

		  unsigned int	not_bus:1;	 /* transfer device SCSI bus differs */
		  unsigned int	resv3:1;
		  unsigned int	id_valid:1;	 /* bus_address is valid */
		  unsigned int	lu_valid:1;	 /* lun is valid */
		  unsigned int	sublu_valid:1;	 /* sub_lun is valid */
		  unsigned int	lun:3;		 /* transfer device SCSI LUN */

		  unsigned char bus_address;	 /* transfer device SCSI address */
		  unsigned char sub_lun;	 /* sub-logical unit number */

		  unsigned int	source_valid:1;	 /* source_element is valid */
		  unsigned int	invert:1;	 /* media in element was inverted */
		  unsigned int	resv4:6;

		  unsigned short source_element;  /* last storage medium location */
		  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;



 Hewlett-Packard Company	    - 7 -   HP-UX Release 11i: November 2000






 autochanger(7)						      autochanger(7)




	   };

      SIOC_INIT_ELEM_STAT
	   Cause 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.  This is a mechanical operation which can take time.	This
	   function only necessary in the event of a severe error of the
	   media changer. If using the surface module (ssrfc) to move disks,
	   this level of error recovery is handled within the surface
	   module.

      SIOC_ELEMENT_ADDRESSES
	   Determine the element addresses supported by a media changer
	   device.  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.

      SIOC_ELEMENT_STATUS
	   Determine 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 about the element address.

      SIOC_RESERVE and SIOC_RELEASE
	   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.

      SIOC_MOVE_MEDIUM and SIOC_EXCHANGE_MEDIUM
	   Reposition unit(s) of media.	 Depending on the source and
	   destination element types, this may result in a media load,
	   eject, or simple repositioning.  Media can be ``flipped'' using



 Hewlett-Packard Company	    - 8 -   HP-UX Release 11i: November 2000






 autochanger(7)						      autochanger(7)




	   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.  In an
	   autochanger with multiple changer mechanisms, or a media staging
	   area, an exchange occurs if the source and second_destination
	   fields are the same.

 DEPENDENCIES
      To obtain access to disk surfaces within HP magneto-optical libraries,
      the ssrfc module must be specified in the system configuration file.
      The ssrfc module depends on either the schgr driver, or the autox0
      driver.  If ssrfc is to be included, then one or both of schgr or
      autox0 must also be included.

 DEFAULT CONFIGURATIONS
      By default, ssrfc, schgr, and autox0 are not included in the system
      configuration (/stand/system) file.

 EXAMPLES
      The following example uses the SIOC_ELEMENT_ADDRESSES and
      SIOC_ELEMENT_STATUS ioctl functions to get bus address information
      about the drives in an HP magneto-optical autochanger:

      int			  last_drive_el;
      struct element_addresses	  el_addrs;
      struct element_status	  el_stat;

      /*
       * Changer attached to card instance 1, with SCSI target id 5, lun 0.
       */
      fd = open("/dev/rac/c1t5d0",O_RDWR);
      if ((error = ioctl(fd, SIOC_ELEMENT_ADDRESSES, &el_addrs)) != 0) {
	 syserr("ioctl: SIOC_ELEMENT_ADDRESSES");
	 return -1;
      } else {
	 last_drive_el = el_addrs.first_data_transfer
		       + el_addrs.num_data_transfers - 1;
	 for (i = el_addrs.first_data_transfer; i <= last_drive_el; i++) {
	    el_stat.element = i;
	    if ((error = ioctl(fd, SIOC_ELEMENT_STATUS, &el_stat)) != 0) {
	       syserr("ioctl: SIOC_ELEMENT_ADDRESSES");
	       return -1;
	    } else {
	       /*
		* You may wish to also check some of the other fields
		* in the el_stat structure to verify that the data is
		* valid.  Fields: el_stat.access (ac accessible),



 Hewlett-Packard Company	    - 9 -   HP-UX Release 11i: November 2000






 autochanger(7)						      autochanger(7)




		* el_stat.except (exception).
		*/
	       if (! el_stat.not_bus && el_stat.id_valid) {
		   drive[i].addr = el_stat.bus_address;
		  if (! el_stat.lu_valid) {
		      drive[i].lun = 0;
		  } else {
		      drive[i].lun = el_stat.lun;
		  }
	       }
	    }
	 }
      }

 WARNINGS
      Do not use LVM to configure multiple autochanger surfaces as one large
      file system. LVM was designed for on-line volumes.  In an autochanger,
      only the disks actualy in the drives are on-line, while the disks
      stored in their slots are off-line. If LVM is not carefully
      configured, thrashing of the autochanger disks result in undesirable
      I/O performance.	Plan carefully for best performance.

      Some non-HP media changer devices do not support the
      SIOC_INIT_ELEM_STAT and SIOC_ELEMENT_STATUS ioctls.

      Some older 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
      insf(1M), mknod(1M), scsictl(1M), ioctl(2), scsi(7), scsi_ctl(7).






















 Hewlett-Packard Company	   - 10 -   HP-UX Release 11i: November 2000