scsi-changer.rst 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184
  1. .. SPDX-License-Identifier: GPL-2.0
  2. ========================================
  3. README for the SCSI media changer driver
  4. ========================================
  5. This is a driver for SCSI Medium Changer devices, which are listed
  6. with "Type: Medium Changer" in /proc/scsi/scsi.
  7. This is for *real* Jukeboxes. It is *not* supported to work with
  8. common small CD-ROM changers, neither one-lun-per-slot SCSI changers
  9. nor IDE drives.
  10. Userland tools available from here:
  11. http://linux.bytesex.org/misc/changer.html
  12. General Information
  13. -------------------
  14. First some words about how changers work: A changer has 2 (possibly
  15. more) SCSI ID's. One for the changer device which controls the robot,
  16. and one for the device which actually reads and writes the data. The
  17. later may be anything, a MOD, a CD-ROM, a tape or whatever. For the
  18. changer device this is a "don't care", he *only* shuffles around the
  19. media, nothing else.
  20. The SCSI changer model is complex, compared to - for example - IDE-CD
  21. changers. But it allows to handle nearly all possible cases. It knows
  22. 4 different types of changer elements:
  23. =============== ==================================================
  24. media transport this one shuffles around the media, i.e. the
  25. transport arm. Also known as "picker".
  26. storage a slot which can hold a media.
  27. import/export the same as above, but is accessible from outside,
  28. i.e. there the operator (you !) can use this to
  29. fill in and remove media from the changer.
  30. Sometimes named "mailslot".
  31. data transfer this is the device which reads/writes, i.e. the
  32. CD-ROM / Tape / whatever drive.
  33. =============== ==================================================
  34. None of these is limited to one: A huge Jukebox could have slots for
  35. 123 CD-ROM's, 5 CD-ROM readers (and therefore 6 SCSI ID's: the changer
  36. and each CD-ROM) and 2 transport arms. No problem to handle.
  37. How it is implemented
  38. ---------------------
  39. I implemented the driver as character device driver with a NetBSD-like
  40. ioctl interface. Just grabbed NetBSD's header file and one of the
  41. other linux SCSI device drivers as starting point. The interface
  42. should be source code compatible with NetBSD. So if there is any
  43. software (anybody knows ???) which supports a BSDish changer driver,
  44. it should work with this driver too.
  45. Over time a few more ioctls where added, volume tag support for example
  46. wasn't covered by the NetBSD ioctl API.
  47. Current State
  48. -------------
  49. Support for more than one transport arm is not implemented yet (and
  50. nobody asked for it so far...).
  51. I test and use the driver myself with a 35 slot cdrom jukebox from
  52. Grundig. I got some reports telling it works ok with tape autoloaders
  53. (Exabyte, HP and DEC). Some People use this driver with amanda. It
  54. works fine with small (11 slots) and a huge (4 MOs, 88 slots)
  55. magneto-optical Jukebox. Probably with lots of other changers too, most
  56. (but not all :-) people mail me only if it does *not* work...
  57. I don't have any device lists, neither black-list nor white-list. Thus
  58. it is quite useless to ask me whenever a specific device is supported or
  59. not. In theory every changer device which supports the SCSI-2 media
  60. changer command set should work out-of-the-box with this driver. If it
  61. doesn't, it is a bug. Either within the driver or within the firmware
  62. of the changer device.
  63. Using it
  64. --------
  65. This is a character device with major number is 86, so use
  66. "mknod /dev/sch0 c 86 0" to create the special file for the driver.
  67. If the module finds the changer, it prints some messages about the
  68. device [ try "dmesg" if you don't see anything ] and should show up in
  69. /proc/devices. If not.... some changers use ID ? / LUN 0 for the
  70. device and ID ? / LUN 1 for the robot mechanism. But Linux does *not*
  71. look for LUNs other than 0 as default, because there are too many
  72. broken devices. So you can try:
  73. 1) echo "scsi add-single-device 0 0 ID 1" > /proc/scsi/scsi
  74. (replace ID with the SCSI-ID of the device)
  75. 2) boot the kernel with "max_scsi_luns=1" on the command line
  76. (append="max_scsi_luns=1" in lilo.conf should do the trick)
  77. Trouble?
  78. --------
  79. If you insmod the driver with "insmod debug=1", it will be verbose and
  80. prints a lot of stuff to the syslog. Compiling the kernel with
  81. CONFIG_SCSI_CONSTANTS=y improves the quality of the error messages a lot
  82. because the kernel will translate the error codes into human-readable
  83. strings then.
  84. You can display these messages with the dmesg command (or check the
  85. logfiles). If you email me some question because of a problem with the
  86. driver, please include these messages.
  87. Insmod options
  88. --------------
  89. debug=0/1
  90. Enable debug messages (see above, default: 0).
  91. verbose=0/1
  92. Be verbose (default: 1).
  93. init=0/1
  94. Send INITIALIZE ELEMENT STATUS command to the changer
  95. at insmod time (default: 1).
  96. timeout_init=<seconds>
  97. timeout for the INITIALIZE ELEMENT STATUS command
  98. (default: 3600).
  99. timeout_move=<seconds>
  100. timeout for all other commands (default: 120).
  101. dt_id=<id1>,<id2>,... / dt_lun=<lun1>,<lun2>,...
  102. These two allow to specify the SCSI ID and LUN for the data
  103. transfer elements. You likely don't need this as the jukebox
  104. should provide this information. But some devices don't ...
  105. vendor_firsts=, vendor_counts=, vendor_labels=
  106. These insmod options can be used to tell the driver that there
  107. are some vendor-specific element types. Grundig for example
  108. does this. Some jukeboxes have a printer to label fresh burned
  109. CDs, which is addressed as element 0xc000 (type 5). To tell the
  110. driver about this vendor-specific element, use this::
  111. $ insmod ch \
  112. vendor_firsts=0xc000 \
  113. vendor_counts=1 \
  114. vendor_labels=printer
  115. All three insmod options accept up to four comma-separated
  116. values, this way you can configure the element types 5-8.
  117. You likely need the SCSI specs for the device in question to
  118. find the correct values as they are not covered by the SCSI-2
  119. standard.
  120. Credits
  121. -------
  122. I wrote this driver using the famous mailing-patches-around-the-world
  123. method. With (more or less) help from:
  124. - Daniel Moehwald <moehwald@hdg.de>
  125. - Dane Jasper <dane@sonic.net>
  126. - R. Scott Bailey <sbailey@dsddi.eds.com>
  127. - Jonathan Corbet <corbet@lwn.net>
  128. Special thanks go to
  129. - Martin Kuehne <martin.kuehne@bnbt.de>
  130. for a old, second-hand (but full functional) cdrom jukebox which I use
  131. to develop/test driver and tools now.
  132. Have fun,
  133. Gerd
  134. Gerd Knorr <kraxel@bytesex.org>