SCSI media changer 드라이버

실제 jukebox용 media changer

이 드라이버는 `/proc/scsi/scsi`에 `Type: Medium Changer`로 표시되는 SCSI Medium Changer 장치를 위한 것이다. 실제 jukebox를 대상으로 하며, slot마다 LUN 하나를 쓰는 소형 SCSI CD-ROM changer나 IDE drive 같은 일반 소형 changer는 지원하지 않는다.

User space 도구는 `http://linux.bytesex.org/misc/changer.html`에서 구할 수 있다.

.. SPDX-License-Identifier: GPL-2.0

=========================
SCSI media changer driver
=========================

This is a driver for SCSI Medium Changer devices, which are listed
with "Type: Medium Changer" in /proc/scsi/scsi.

This is for *real* Jukeboxes.  It is *not* supported to work with
common small CD-ROM changers, neither one-lun-per-slot SCSI changers
nor IDE drives.

Userland tools available from here:
        http://linux.bytesex.org/misc/changer.html

Changer의 SCSI ID와 네 가지 element

Changer에는 보통 SCSI ID가 둘 이상 있다. 하나는 robot을 제어하는 changer 장치용이고 다른 하나는 실제 데이터를 읽고 쓰는 drive용이다. 후자는 MOD, CD-ROM, tape 등 무엇이든 될 수 있다. Changer 장치는 media를 옮기기만 하며 그 내용을 읽거나 쓰지 않는다.

SCSI changer model은 IDE-CD changer보다 복잡하지만 거의 모든 구성을 표현할 수 있다. 각 element 종류의 개수는 하나로 제한되지 않는다. 예를 들어 CD-ROM slot 123개, reader 5개, transport arm 2개인 jukebox는 changer와 reader를 합쳐 SCSI ID 6개를 사용해도 처리할 수 있다.

General Information
-------------------

First some words about how changers work: A changer has 2 (possibly
more) SCSI ID's. One for the changer device which controls the robot,
and one for the device which actually reads and writes the data. The
later may be anything, a MOD, a CD-ROM, a tape or whatever. For the
changer device this is a "don't care", he *only* shuffles around the
media, nothing else.


The SCSI changer model is complex, compared to - for example - IDE-CD
changers. But it allows to handle nearly all possible cases. It knows
4 different types of changer elements:

  ===============   ==================================================
  media transport   this one shuffles around the media, i.e. the
                    transport arm.  Also known as "picker".
  storage           a slot which can hold a media.
  import/export     the same as above, but is accessible from outside,
                    i.e. there the operator (you !) can use this to
                    fill in and remove media from the changer.
                    Sometimes named "mailslot".
  data transfer     this is the device which reads/writes, i.e. the
                    CD-ROM / Tape / whatever drive.
  ===============   ==================================================

None of these is limited to one: A huge Jukebox could have slots for
123 CD-ROM's, 5 CD-ROM readers (and therefore 6 SCSI ID's: the changer
and each CD-ROM) and 2 transport arms. No problem to handle.

Character device와 NetBSD 호환 ioctl

드라이버는 NetBSD와 비슷한 ioctl interface를 가진 character device driver로 구현됐다. NetBSD header와 다른 Linux SCSI device driver를 출발점으로 삼았으며 source code 수준에서 NetBSD와 호환되는 것을 목표로 한다. BSD 계열 changer driver를 지원하는 software라면 이 드라이버에서도 동작해야 한다.

시간이 지나며 NetBSD ioctl API에 없던 volume tag 지원 등 몇 가지 ioctl이 추가됐다.

How it is implemented
---------------------

I implemented the driver as character device driver with a NetBSD-like
ioctl interface. Just grabbed NetBSD's header file and one of the
other linux SCSI device drivers as starting point. The interface
should be source code compatible with NetBSD. So if there is any
software (anybody knows ???) which supports a BSDish changer driver,
it should work with this driver too.

Over time a few more ioctls where added, volume tag support for example
wasn't covered by the NetBSD ioctl API.

지원 상태와 장치 호환성

Transport arm을 둘 이상 사용하는 기능은 아직 구현되지 않았다. 작성자는 Grundig 35-slot CD-ROM jukebox로 직접 시험했고 Exabyte, HP, DEC tape autoloader, Amanda backup software, 11-slot 소형 장치와 MO drive 4개·slot 88개인 대형 magneto-optical jukebox에서도 동작한다는 보고를 받았다.

Black list나 white list 형태의 장치 목록은 없다. 원칙적으로 SCSI-2 media changer command set을 지원하는 모든 changer가 별도 설정 없이 동작해야 한다. 동작하지 않는다면 driver 또는 changer firmware의 bug다.

Current State
-------------

Support for more than one transport arm is not implemented yet (and
nobody asked for it so far...).

I test and use the driver myself with a 35 slot cdrom jukebox from
Grundig.  I got some reports telling it works ok with tape autoloaders
(Exabyte, HP and DEC).  Some People use this driver with amanda.  It
works fine with small (11 slots) and a huge (4 MOs, 88 slots)
magneto-optical Jukebox.  Probably with lots of other changers too, most
(but not all :-) people mail me only if it does *not* work...

I don't have any device lists, neither black-list nor white-list.  Thus
it is quite useless to ask me whenever a specific device is supported or
not.  In theory every changer device which supports the SCSI-2 media
changer command set should work out-of-the-box with this driver.  If it
doesn't, it is a bug.  Either within the driver or within the firmware
of the changer device.

Device node 생성과 LUN 1 검색

이 character device의 major number는 86이다. `mknod /dev/sch0 c 86 0`으로 특수 파일을 만든다. Module이 changer를 발견하면 장치 정보를 kernel log에 남기고 `/proc/devices`에도 나타나야 하므로 보이지 않으면 `dmesg`를 확인한다.

일부 changer는 drive를 LUN 0, robot mechanism을 LUN 1에 둔다. Linux는 고장 난 장치가 많다는 이유로 기본적으로 0 이외 LUN을 찾지 않는다. 이때 `echo "scsi add-single-device 0 0 ID 1" > /proc/scsi/scsi`로 LUN 1을 추가하거나 kernel command line에 `max_scsi_luns=1`을 지정한다. `lilo.conf`에서는 `append="max_scsi_luns=1"`을 사용할 수 있다.

Using it
--------

This is a character device with major number is 86, so use
"mknod /dev/sch0 c 86 0" to create the special file for the driver.

If the module finds the changer, it prints some messages about the
device [ try "dmesg" if you don't see anything ] and should show up in
/proc/devices. If not....  some changers use ID ? / LUN 0 for the
device and ID ? / LUN 1 for the robot mechanism. But Linux does *not*
look for LUNs other than 0 as default, because there are too many
broken devices. So you can try:

  1) echo "scsi add-single-device 0 0 ID 1" > /proc/scsi/scsi
     (replace ID with the SCSI-ID of the device)
  2) boot the kernel with "max_scsi_luns=1" on the command line
     (append="max_scsi_luns=1" in lilo.conf should do the trick)

Debug log와 오류 문자열

`insmod debug=1`로 driver를 넣으면 자세한 정보를 syslog에 기록한다. Kernel을 `CONFIG_SCSI_CONSTANTS=y`로 build하면 error code를 사람이 읽을 수 있는 문자열로 변환하므로 오류 메시지 품질이 크게 좋아진다.

메시지는 `dmesg`나 log file에서 확인한다. Driver 문제를 문의할 때는 이 메시지를 반드시 함께 보낸다.

Trouble?
--------

If you insmod the driver with "insmod debug=1", it will be verbose and
prints a lot of stuff to the syslog.  Compiling the kernel with
CONFIG_SCSI_CONSTANTS=y improves the quality of the error messages a lot
because the kernel will translate the error codes into human-readable
strings then.

You can display these messages with the dmesg command (or check the
logfiles).  If you email me some question because of a problem with the
driver, please include these messages.

Module option과 vendor element

`debug=0/1`은 debug message를 켜며 기본값은 0이다. `verbose=0/1`은 자세한 출력을 제어하며 기본값은 1이다. `init=0/1`은 module 삽입 때 changer에 `INITIALIZE ELEMENT STATUS` 명령을 보낼지 정하고 기본값은 1이다.

`timeout_init=<seconds>`는 `INITIALIZE ELEMENT STATUS` timeout으로 기본 3600초다. `timeout_move=<seconds>`는 나머지 모든 명령의 timeout이며 기본 120초다. `dt_id`와 `dt_lun`은 data transfer element의 SCSI ID와 LUN을 직접 지정한다. Jukebox가 보통 이 정보를 제공하지만 일부 장치는 제공하지 않는다.

`vendor_firsts`, `vendor_counts`, `vendor_labels`는 vendor 고유 element 유형을 알려 준다. 예를 들어 Grundig jukebox의 새 CD label printer가 type 5, element `0xc000`이면 `vendor_firsts=0xc000 vendor_counts=1 vendor_labels=printer`로 지정한다. 세 option은 쉼표로 나눈 값을 각각 최대 네 개 받아 element type 5~8을 설정한다. 이 값은 SCSI-2 표준 범위 밖이므로 해당 장치의 SCSI 명세가 필요할 수 있다.

Insmod options
--------------

debug=0/1
        Enable debug messages (see above, default: 0).

verbose=0/1
        Be verbose (default: 1).

init=0/1
        Send INITIALIZE ELEMENT STATUS command to the changer
        at insmod time (default: 1).

timeout_init=<seconds>
        timeout for the INITIALIZE ELEMENT STATUS command
        (default: 3600).

timeout_move=<seconds>
        timeout for all other commands (default: 120).

dt_id=<id1>,<id2>,... / dt_lun=<lun1>,<lun2>,...
        These two allow to specify the SCSI ID and LUN for the data
        transfer elements.  You likely don't need this as the jukebox
        should provide this information.  But some devices don't ...

vendor_firsts=, vendor_counts=, vendor_labels=
        These insmod options can be used to tell the driver that there
        are some vendor-specific element types.  Grundig for example
        does this.  Some jukeboxes have a printer to label fresh burned
        CDs, which is addressed as element 0xc000 (type 5).  To tell the
        driver about this vendor-specific element, use this::

                $ insmod ch                        \
                        vendor_firsts=0xc000        \
                        vendor_counts=1                \
                        vendor_labels=printer

        All three insmod options accept up to four comma-separated
        values, this way you can configure the element types 5-8.
        You likely need the SCSI specs for the device in question to
        find the correct values as they are not covered by the SCSI-2
        standard.

개발과 시험에 기여한 사람들

Gerd Knorr는 여러 지역에서 patch를 우편처럼 주고받는 방식으로 이 driver를 작성했다. Daniel Moehwald, Dane Jasper, R. Scott Bailey, Jonathan Corbet이 도움을 주었다.

Martin Kuehne는 오래된 중고지만 완전히 동작하는 CD-ROM jukebox를 제공했고, 작성자는 이를 driver와 tool 개발·시험에 사용했다.

Credits
-------

I wrote this driver using the famous mailing-patches-around-the-world
method.  With (more or less) help from:

        - Daniel Moehwald <moehwald@hdg.de>
        - Dane Jasper <dane@sonic.net>
        - R. Scott Bailey <sbailey@dsddi.eds.com>
        - Jonathan Corbet <corbet@lwn.net>

Special thanks go to

        - Martin Kuehne <martin.kuehne@bnbt.de>

for a old, second-hand (but full functional) cdrom jukebox which I use
to develop/test driver and tools now.

Have fun,

   Gerd

Gerd Knorr <kraxel@bytesex.org>