doc/ja_JP.eucJP/man/man4/ch.4

.\"	%Id: ch.4,v 1.12 1998/09/15 10:26:24 gibbs Exp %
.\" jpman %Id: ch.4,v 1.3 2000/01/06 12:54:41 horikawa Stab %
.\" Copyright (c) 1996
.\"	Julian Elischer <julian@freebsd.org>.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd May 14, 1998
.Dt CH 4
.Os FreeBSD
.Sh 名称
.Nm ch
.Nd SCSI メディアチェンジャ (ジュークボックス) ドライバ
.Sh 書式
.Cd device ch
.Cd device ch1 target 4 lun 0
.Sh 解説
.Xr ch
ドライバは、
.Em SCSI
メディアチェンジャをサポートします。このドライバは、多くのスロットに
存在するメディアを複数のドライブの間で多重化して利用できるようにします。
チェンジャデバイスには、オプションとしてバーコードリーダを備え付けること
もできます。このリーダを使い、メディアに付随する情報を読み込みます。
.Pp
SCSI チェンジャをシステムに組み込む前に、SCSI アダプタを別途組み込んで
おく必要があります。
.Pp
ブート時に SCSI アダプタをプローブしているときに、
.Em SCSI
バスを走査しデバイスを探します。`Changer' タイプであると応答するデバイスが
見つかると、それらは
.Nm
ドライバに「アタッチ」されます。
2.1 より前のリリースの FreeBSD では、最初に見つかったデバイスが
.Em ch0
にアタッチされ、以後見つかったデバイスは順次、
.Em ch1
などにアタッチされます。
2.1 から、あるデバイスがどの ch ユニットとして接続すべきかを指定
できるようになりました。このためのカーネル設定については、
.Xr scsi 4
を参照して下さい。
.Pp
.Sh カーネル設定
設定の際に、オプションとして
.Ar count
を指定した場合、その数だけの SCSI メディアチェンジャが設定されます。
ドライバの記憶領域のほとんどは、デバイスが見つかった時にのみ
割り当てられるので、たくさんのデバイスを設定しても
高くはつきません (ひとたび最初のデバイスがドライバを組み込んだ場合)。
.Pp
.Sh IOCTL
ユーザモードプログラムは、次に示す ioctl を使ってチェンジャドライバと
データのやりとりを行ないます。カーネルとチェンジャデバイスとの間の
データのやりとりで使用される、チェンジャエレメントのアドレスは、
0 から始まる論理アドレスに割り当てられます。エレメントのタイプは
次のように指定します。
.Bl -tag -width CHET_MT
.It Dv CHET_MT
メディア移動エレメント (ピッカ)
.It Dv CHET_ST
ストレージエレメント (スロット)
.It Dv CHET_IE
持ち込み/持ち出しエレメント (ポータル)
.It Dv CHET_DT
データ転送エレメント (ドライブ)
.El
.Pp
次に示す
.Xr ioctl 2
呼び出しがチェンジャに適用されます。これらはヘッダファイル
.Aq Pa sys/chio.h
で定義されます。
.Pp
.Bl -tag -width CHIOEXCHANGE
.It Dv CHIOMOVE
.Pq Li "struct changer_move"
これは、現在のピッカを用いて、メディアをあるエレメントから別の
エレメントに移動させます (\fBMOVE MEDIUM\fR)。移動元と移動先の
エレメントは、changer_move 構造体の中で指定します。この構造体は、
少なくとも次に示すフィールドを持ちます。
.Bd -literal -offset indent
u_int cm_fromtype; /* 移動元エレメントのタイプ */
u_int cm_fromunit; /* 移動元エレメントの論理ユニット */
u_int cm_totype;   /* 移動先エレメントのタイプ */
u_int cm_tounit;   /* 移動先エレメントの論理ユニット */
u_int cm_flags;	   /* その他フラグ */

.Ed
\fBcm_flags\fR フィールドの \fBCM_INVERT\fR が設定されている場合、
メディアチェンジャは移動中にメディアを反転させるように指示されます。
.It Dv CHIOEXCHANGE
.Pq Li "struct changer_exchange"
これは、移動元エレメントにあるメディアを最初の移動先エレメントに移動させ、
最初の移動先エレメントにあったメディアを 2 番目の移動先エレメントに
移動させます。単純な交換の場合、移動元と 2 番目の移動先とは同じである
必要があります。この操作の遂行に際し現在のピッカが用いられます。影響を
受けるエレメントのアドレスは、changer_exchange 構造体に含めて
ioctl に対して指定します。この構造体は少なくとも次の要素を持ちます。
.Bd -literal -offset indent
u_int ce_srctype;	 /* 移動元エレメントのタイプ */
u_int ce_srcunit;	 /* 移動元の論理ユニット */
u_int ce_fdsttype; /* 最初の移動先エレメントのタイプ */
u_int ce_fdstunit; /* 最初の移動先の論理ユニット */
u_int ce_sdsttype; /* 2番目の移動先エレメントのタイプ */
u_int ce_sdstunit; /* 2番目の移動先の論理ユニット */
u_int ce_flags;	 /* その他フラグ */

.Ed
\fBce_flags\fR の中で、\fBCM_INVERT1\fR と \fBCM_INVERT2\fR を設定
でき、これらはそれぞれ、最初のメディアと 2 番目のメディアを移動中に
反転させます。
.Pp
\fIこの機能はテストしていません。\fR
.It Dv CHIOPOSITION
.Pq Li "struct changer_position"
これは、現在のピッカを移動させ指定したエレメントの前に置きます。
エレメントは changer_position 構造体で指定します。これは少なくとも
次の要素を持ちます。
.Bd -literal -offset indent
u_int cp_type;  /* エレメントのタイプ */
u_int cp_unit;  /* エレメントの論理ユニット */
u_int cp_flags; /* その他フラグ */

.Ed
\fBcp_flags\fR フィールドで \fBCP_INVERT\fR を設定でき、これは
移動中にピッカを反転させます。
.It Dv CHIOGPICKER
.Pq Li "int"
これは、現在のピッカの論理アドレスを返します。
.It Dv CHIOSPICKER
.Pq Li "int"
これは、与えた論理アドレスが指すピッカを選択します。
.It Dv CHIOGPARAMS
.Pq Li "struct changer_params"
これは、メディアチェンジャの設定パラメータを返します。この ioctl は、
ユーザが渡した changer_params 構造体の、
少なくとも以下のフィールドを埋めます。
.Bd -literal -offset indent
u_int cp_npickers; /* ピッカの数 */
u_int cp_nslots;   /* スロットの数 */
u_int cp_nportals; /* 持ち込み/持ち出しポータルの数 */
u_int cp_ndrives;  /* ドライブの数 */

.Ed
アプリケーションが \fBCHIGSTATUS\fR ioctl を用いてジュークボックスの
状態を調べるに先だって、ジュークボックスの諸元を問い合わせる際に、この
呼び出しを使用できます。
.It Dv CHIOIELEM
これは、メディアチェンジャデバイスに対し、\fBINITIALIZE ELEMENT STATUS\fR
呼び出しを行ないます。これにより、メディアチェンジャは、ロードしている
メディアに関する内部状態情報を更新させられます。チェンジャがラベルリーダを
持つ場合、バーコードラベルの走査もあわせて行ないます。この呼び出しでは、
.Nm
ドライバの状態は影響を受けません。
.It Dv CHIOGSTATUS
.Pq Li "struct changer_element_status_request"
これは、メディアチェンジャデバイスに対し、\fBREAD ELEMENT STATUS\fR
呼び出しを行ないます。この呼び出しはメディアチェンジャの
エレメント状態情報を読み込み、それを \fBchanger_element_status\fR
構造体の配列に変換します。
.Pp
.Dv CHIOGSTATUS
の呼び出しごとに、あるタイプの 1 つ以上のエレメントの状態が
問い合わされます。
.Pp
アプリケーションは changer_element_status_request 構造体を
.Nm
ドライバに渡します。この構造体は次に示すフィールドを持ちます。
.Bd -literal -offset indent
u_int                          cesr_element_type;
u_int                          cesr_element_base; 
u_int                          cesr_element_count;
u_int                          cesr_flags;
struct changer_element_status *cesr_element_status;

.Ed
ドライバはこの構造体を読み込み、タイプ、論理ベースアドレス、エレメント数
を決定し、cesr_element_status フィールドが指す changer_element_status
構造体の配列にどの情報を返すかを知ります。アプリケーションは、
cesr_element_count 個の状態構造体 (次を見て下さい) を保持するのに
十分な大きさのメモリを割り当てる必要があります。cesr_flags にオプションで
.Dv CESR_VOLTAGS
を設定し、ボリュームタグ (バーコード) 情報をジュークボックスから
読み込んで返す必要があることを通知できます。
.Pp
cesr_element_base フィールドと cesr_element_count フィールドは、
チェンジャの物理的構成に照らして正当な値でなければなりません。もし
正当な値でない場合、
.Dv CHIOGSTATUS
ioctl は
.Er EINVAL
エラーコードを返します。
.Pp
エレメントについての情報は、changer_element_status 構造体の配列の中に
返されます。この構造体は少なくとも次に示すフィールドを持ちます。
.Bd -literal -offset indent
u_int            ces_addr;      /* メディアチェンジャのエレメントアドレス */
u_char           ces_flags;     /* 以下の CESTATUS の定義を参照 */
u_char           ces_sensecode; /* エレメントの追加センスコード */
u_char           ces_sensequal; /* 追加センスコード修飾子 */
u_char           ces_invert;    /* 反転ビット */
u_char           ces_svalid;    /* 移動元アドレス (ces_source) が有効 */
u_short          ces_source;    /* メディアの移動元アドレス */
changer_voltag_t ces_pvoltag;   /* プライマリボリュームタグ */
changer_voltag_t ces_avoltag;   /* 代替ボリュームタグ */
u_char           ces_idvalid;   /* ces_scsi_id が有効 */
u_char           ces_scsi_id;   /* エレメントの SCSI id (ces_idvalid が非 0 の場合) */
u_char           ces_lunvalid;  /* ces_scsi_lun が有効 */
u_char           ces_scsi_lun;  /* エレメントの SCSI lun (ces_lunvalid が非 0 の場合) */

.Ed
ces_addr フィールドは、メディアチェンジャの座標系で表した
エレメントのアドレスを保持します。ドライバはこれを使用しません。
診断目的のみで使用して下さい。
.Pp
\fBces_flags\fR フィールドに対し、次に示すフラグが定義されます。
.Bl -tag -width CESTATUS_IMPEXP
.It Dv CESTATUS_FULL
メディアが存在します。
.It Dv CESTATUS_IMPEXP
メディアを置いたのはオペレータです (ピッカが置いたものではありません)。
.It Dv CESTATUS_EXCEPT
そのエレメントは例外的状態 (例えば、バーコードラベルが不当な値、
バーコードがまだ走査されていない) にあります。
.It Dv CESTATUS_ACCESS
そのエレメントはピッカによってアクセス可能な状態です。
.It Dv CESTATUS_EXENAB
そのエレメントはメディア持ち出しをサポートしています。
.It Dv CESTATUS_INENAB
そのエレメントはメディア持ち込みをサポートしています。
.El
.Pp
すべてのエレメントタイプに対しすべてのフラグが有効とは限らないことに
注意して下さい。
.El
.Sh 注
このバージョンの
.Nm
ドライバは、DEC TZ875 (5 スロット、1 DLT ドライブ) と Breece Hill Q47
(60 スロット、4 DLT ドライブ、バーコードリーダ付き) を用いてテストして
あります。
.Pp
テストに利用できたデバイスが必要なコマンドをサポートしていないという
事実により、
.Nm
ドライバがサポートする機能の多くは、完全にテストできていません。これは、
代替ボリュームタグ、メディア反転、エレメントの持ち込み/持ち出し操作、
複数ピッカ操作、その他の機能があります。
.Sh 作者
.Nm
は、
And Communications, http://www.and.com/ の
.An Jason R. Thorpe Aq thorpej@and.com
が記述しました。これを、その手のデバイスを持っていた
.An Stefan Grefen Aq grefen@goofy.zdv.uni-mainz.de
がシステムに付け加えました。
これを CAM に移植したのは、
.An Kenneth Merry Aq ken@FreeBSD.ORG
です。
これを更新してボリュームタグをサポートするようにしたのは、
.An Hans Huebner Aq hans@artcom.de
です。
.Sh 関連ファイル
.Bl -tag -width /dev/ch[0-9] -compact
.It Pa /dev/ch[0-9]
デバイスエントリ
.El
.Sh 診断
メディアチェンジャが
.Nm
ドライバが要求する機能をサポートしていない場合、ここで記述した ioctl に
対し、コンソールエラーメッセージとエラーリターンコードを生成します。
.Sh 関連項目
.Xr chio 1 ,
.Xr cd 4 ,
.Xr sd 4 ,
.Xr st 4
.Sh 歴史
.Nm
は、386BSD 0.1 で現れました。