.\"
.\" Copyright (c) 1998 Kenneth D. Merry.
.\" 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.
.\" 3. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" 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.
.\"
.\"	%Id: camcontrol.8,v 1.9 1998/12/20 18:51:56 mjacob Exp %
.\" jpman %Id: camcontrol.8,v 1.4 1998/12/22 02:35:45 oku Stab %
.\"
.\" WORD: defect list		ディフェクトリスト[camcontrol.8]
.\"
.Dd September 14, 1998
.Dt CAMCONTROL 8
.Os FreeBSD 3.0
.Sh 名称
.Nm camcontrol
.Nd CAM コントロールプログラム
.Sh 書式
.Nm camcontrol
.Aq command
.Op generic args
.Op command args
.Nm camcontrol
devlist
.Op Fl v
.Nm camcontrol
periphlist
.Op Fl n Ar dev_name
.Op Fl u Ar unit_number
.Nm camcontrol
tur
.Op generic args
.Nm camcontrol
inquiry 
.Op generic args
.Op Fl D
.Op Fl S
.Op Fl R
.Nm camcontrol
start
.Op generic args
.Nm camcontrol
stop
.Op generic args
.Nm camcontrol
eject
.Op generic args
.Nm camcontrol
rescan
.Aq bus Ns Op :target:lun
.Nm camcontrol
reset
.Aq bus Ns Op :target:lun
.Nm camcontrol
defects
.Op generic args
.Aq Fl f Ar format
.Op Fl P
.Op Fl G
.Nm camcontrol
modepage
.Op generic args
.Aq Fl m Ar page
.Op Fl P Ar pgctl
.Op Fl e
.Op Fl d
.Nm camcontrol
cmd
.Op generic args
.Aq Fl c Ar cmd Op args
.Op Fl i Ar len Ar fmt
.Bk -words
.Op Fl o Ar len Ar fmt Op args
.Ek
.Nm camcontrol
debug
.Op Fl I
.Op Fl T
.Op Fl S
.Op Fl c
.Aq all|off|bus Ns Op :target Ns Op :lun
.Sh 解説
.Nm camcontrol
は、ユーザが
.Tn FreeBSD
CAM サブシステムにアクセスし制御できるようにする方法を提供する
ために設計されたユーティリティです。
.Pp
.Nm camcontrol
を不適切に使用すると、
データの損失や、システムクラッシュにつながる可能性があります。経験
豊富なユーザであっても、このコマンドを使用する際には注意を払うことを
お勧めします。素人さんはこのユーティリティに近付いてはいけません。
.Pp
.Nm camcontrol
はいくつかの主機能を持っています。その多くは下に示す
共通の引数(generic argument)のいくつかを取ります。
.Bl -tag -width 01234567890123
.It Fl C Ar count
SCSI コマンドのリトライカウント。この機能が動作するためには、エラーリカバリ
.Po
.Fl E
.Pc
をオンにしておく必要があります。
.It Fl E
指定したコマンドのための汎用の SCSI エラーリカバリを遂行
するよう、カーネルに指示を出します。リトライカウント機能
.Po
.Fl C
.Pc
を有効にするためにはこれが必要です。
コマンドのリトライの他に、コード中にある汎用のエラーリカバリによって、
回っていない HDD を回転させるような試みが通常なされます。コマンドから
返されたセンスコードによっては、他の操作が行なわれることもあります。
.It Fl n Ar dev_name
操作を行なうデバイスのタイプを指定します。デフォルトは
.Em da
です。
.It Fl t Ar timeout
SCSI コマンドのタイムアウトを秒単位で指定します。指定したコマンドのすべてに
おいて、これで指定する値はデフォルトのタイムアウトより優先されます。
.It Fl u Ar unit_number
デバイスユニット番号を指定します。デフォルトは 0 です。
.It Fl v
冗舌になります。SCSI コマンドに失敗するとセンス情報を表示します。
.El
.Pp
主コマンド機能は次のとおりです。
.Bl -tag -width periphlist
.It devlist
CAM サブシステムに接続されたすべての物理デバイス (論理ユニット) の
リストを表示します。このリストには各デバイスに接続された周辺ドライバの
一覧も含まれます。
引数
.Fl v
を指定すると、SCSI バス番号、アダプタ名、ユニット番号もあわせて
表示されます。
.It periphlist
指定した物理デバイス (論理ユニット) に接続されたすべての周辺ドライバの
リストを表示します。
.It tur
指定したデバイスに SCSI test unit ready (0x00) コマンドを送信します。
.Nm camcontrol
は、そのデバイスがレディ状態であるかどうかを報告します。
.It inquiry
デバイスに SCSI inquiry (0x12) コマンドを送信します。デフォルトでは、
.Nm camcontrol
標準の inquiry データ、デバイスのシリアル番号、転送レート情報を表示します。
特定のタイプの inquiry データだけを表示するように指定することもできます。
.Bl -tag -width 1234
.It Fl D
標準 inquiry データを得ます。
.It Fl S
シリアル番号を表示します。このフラグだけが指定された場合、
.Nm camcontrol
は、ドライブが返す値の前に "Serial Number" を表示しません。これは
スクリプトを書く際に役立ちます。
.It Fl R
転送レートの情報を表示します。
.El
.It start
指定したデバイスに、start ビットをセットした SCSI Start/Stop Unit
(0x1B) コマンドを送信します。
.It stop
指定したデバイスに、start ビットをクリアした SCSI Start/Stop Unit
(0x1B) コマンドを送信します。
.It eject
指定したデバイスに、start ビットをクリアし eject ビットをセットした
SCSI Start/Stop Unit (0x1B) コマンドを送信します。
.It rescan
カーネルに指定したバス (XPT_SCAN_BUS)、もしくは bus:target:lun
(XPT_SCAN_LUN) をスキャンさせ、新規のデバイスや外されたデバイスを
探させます。ユーザが指定できるのは、スキャンするバスもしくは
論理ユニット番号だけです。あるターゲットのすべての論理ユニット番号を
スキャンすることはサポートされていません。
.It reset
指定したバス (XPT_RESET_BUS) または指定した bus:target:lun (XPT_RESET_DEV) を、
カーネルにリセットさせます。
前者は、バスに SCSI バスリセットを発行することにより行います。
後者は、典型的には当該デバイスにコネクトした後に、
BUS DEVICE RESET メッセージを発行することにより行います。
本コマンドはシステムに破壊的な影響を与えることがあることに注意してください。
.It defects
指定したデバイスに、SCSI READ DEFECT DATA (10) コマンド (0x37) を送信し、
ディフェクト総数、初期ディフェクトリスト (PLIST)、増分ディフェクトリスト
(GLIST) を組み合わせて表示します。
.Bl -tag -width 01234567890
.It Fl f Ar format
書式オプションは以下の 3 つです。
.Em block ,
リストを論理ブロック形式で表示します。
.Em bfi ,
リストをインデックスからのバイト数の形式で表示します。
.Em phys ,
リストを物理セクタ形式で表示します。書式引数は必須です。ほとんどのドライブ
は、物理セクタ形式をサポートしています。一部のドライブは論理ブロック形式を
サポートしています。指定した書式をサポートしていない場合、多くのドライブは、
指定したデータ書式をサポートしていないことを示すセンス情報とともに、
別の書式でデータを返します。
.Nm camcontrol
は、それを検知して
ドライブが返す書式ならどのようなものでも表示しようとします。ドライブが
指定した書式をサポートしていないことを報告する際に、非標準のセンスコードを
用いた場合、
.Nm camcontrol
は、おそらくそのエラーをリクエスト完了に失敗したためのものと見なすでしょう。
.It Fl G
増分ディフェクトリストを表示します。これは、工場出荷時以降に再マップ
された不良ブロックのリストです。
.It Fl P
初期ディフェクトリストを表示します。
.El
.Pp
.Fl P
も
.Fl G
もどちらも指定していない場合、
.Nm camcontrol
は、ドライブから返された READ DEFECT DATA ヘッダから得られるディフェクト数を
表示します。
.It modepage
SCSI モードページを表示します。もしくは、オプション指定により
ユーザがモードページを編集できるようにします。モードページの書式は
.Pa /usr/share/misc/scsi_modes
にあります。
環境変数
.Ev SCSI_MODES
に別のファイルが指定されている場合はそちらが優先されます。
modepage コマンドは以下のようないくつかの引数を取ります。
.Bl -tag -width 012345678901
.It Fl B
モードセンスのためのブロック記述子を禁止します。
.It Fl e
このフラグを指定することで、ユーザはモードページ中の値を編集することが
できます。
.It Fl m Ar mode_page
ユーザが表示/編集したいモードページ番号を指定します。この引数は必須です。
.It Fl P Ar pgctl
このフラグを指定することで、ユーザはページ制御フィールドを指定することが
できます。指定可能な値は次の通りです。
.Bl -tag -width xxx -compact
.It 0
現在の値
.It 1
変更可能な値
.It 2
デフォルトの値
.It 3
保存された値
.El
.El
.It cmd
任意のデバイスに任意の SCSI CDB を送信するために用いることができます。
cmd 機能は、CDB を指定するための
.Fl c
引数が必要です。他の引数はオプションで、コマンドの型に依存します。コマンドと
データを指定する文法は、
.Xr cam 3
に記述されています。
注釈: 指定した CDB によって、対象の SCSI デバイスとのデータ送受信が
発生する場合、
.Fl i
または
.Fl o
を指定する必要があります。
.Bl -tag -width 01234567890123456
.It Fl c Ar cmd Op args
これは SCSI CDB を指定します。CDB は 6, 10, 12, 16 バイトのいずれか
が可能です。
.It Fl i Ar len Ar fmt
これは、読み込むデータの量と、どのように表示するかとを指定します。書式が
.Sq -
である場合、
.Ar len
バイトのデータがデバイスから読み込まれ、標準出力に書き出されます。
.It Fl o Ar len Ar fmt Op args
これは、デバイスに書き出すデータの量と、書き出されるデータとを指定します。
書式が
.Sq -
である場合、
.Ar len
バイトのデータが標準入力から読み込まれデバイスに書き出されます。
.El
.It debug
カーネルの CAM デバッグ用 printf をオンにします。カーネルの設定
ファイル中に CAMDEBUG オプションが指定されている必要があります。
注意: 現在のところ、デバッグ
用 printf を使えるようにすると、極めて多数のカーネル printf が生じる
ことになります。
一度デバッグ用 printf をスタートさせてしまうと、停止させるのは難しい
でしょう。というのは、カーネルはメッセージを表示するのに忙しくなるので、
他のリクエストをすぐにサービスすることができなくなるからです。
デバッグ機能はいくつかの引数を取ります。
.Bl -tag -width 012345678901234567
.It Fl I
CAM_DEBUG_INFO printf を有効にします。
.It Fl T
CAM_DEBUG_TRACE printf を有効にします。
.It Fl S
CAM_DEBUG_SUBTRACE printf を有効にします。
.It Fl c
CAM_DEBUG_CDB printf を有効にします。これにより、カーネルが、指定した
デバイスに送信した SCSI CDB を表示することになります。
.It all
すべてのデバイスについてデバッグ出力を有効にします。
.It off
すべてのデバイスについてデバッグ出力を無効にします。
.It bus Ns Op :target Ns Op :lun
指定したバス、ターゲット、論理ユニット番号(lun)についてデバッグ出力を
有効にします。論理ユニット番号、もしくはターゲットと論理ユニット番号が
指定されない場合は、ワイルドカード指定されたものとして扱います。(すなわち、
バスだけを指定すると、そのバスのすべてのデバイスについてデバッグ用
printf が有効になります。)
.El
.El
.Sh 環境変数
変数
.Ev SCSI_MODES
によって、別のモードページの書式ファイルを指定することができます。
.Pp
変数
.Ev EDITOR
によって、
.Nm camcontrol
は、モードページの編集を行なう際に
どのテキストエディタを起動するかを決定します。
.Sh 関連ファイル
.Bl -tag -width /usr/share/misc/scsi_modes -compact
.It Pa /usr/share/misc/scsi_modes
SCSI モード書式データベース。
.It Pa /dev/xpt0 
トランスポート層デバイス。
.It Pa /dev/pass*
CAM アプリケーションパススルーデバイス。
.El
.Sh 使用例
.Dl camcontrol eject -n cd -u 1 -v
.Pp
cd1 から CD をイジェクトし、コマンド実行に失敗した場合は SCSI センス情報を
出力します。
.Pp
.Dl camcontrol tur
.Pp
SCSI test unit ready コマンドを da0 に送信します。
.Nm camcontrol
はそのディスクがレディ状態であるかどうかを報告しますが、
.Fl v
スイッチが指定されていないため、コマンド実行に失敗してもセンス情報を
表示しません。
.Pp
.Bd -literal -offset foobar
camcontrol tur -n da -u 1 -E -C 4 -t 50 -v
.Ed
.Pp
SCSI test unit ready コマンドを da1 に送信します。カーネルエラーリカバリ
を有効にします。リトライカウントを 4 に、タイムアウトを 50 秒に
設定します。コマンド実行に失敗した場合(
.Fl v
フラグがあるので)センス情報が出力されます。エラーリカバリが設定されて
いるので、ディスクが回転していない場合は回転させられます。
.Nm camcontrol
はディスクがレディ状態かどうかを報告します。
.Bd -literal -offset foobar
camcontrol cmd -n cd -u 1 -v -c "3C 00 00 00 00 00 00 00 0e 00" \e
	-i 0xe "s1 i3 i1 i1 i1 i1 i1 i1 i1 i1 i1 i1"
.Ed
.Pp
READ BUFFER コマンド (0x3C) を cd1 に対して発行します。cd1 のバッファサイズと
cd1 のキャッシュの最初の 10 バイトを表示します。コマンド実行に失敗した場合
SCSI センス情報を表示します。
.Pp
.Bd -literal -offset foobar
camcontrol cmd -n cd -u u -v -c "3B 00 00 00 00 00 00 00 0e 00" \e
	-o 14 "00 00 00 00 1 2 3 4 5 6 v v v v" 7 8 9 8
.Ed
.Pp
WRITE BUFFER コマンド (0x3B) を cd1 に対して発行します。(予約済の) 4 バイト
ヘッダを含まないデータ 10 バイトを書き出します。コマンド実行に失敗した場合
センス情報を表示します。このコマンドには細心の注意を払って下さい。不適切に
使用した場合、データが破壊されるかもしれません。
.Pp
.Bd -literal -offset foobar
camcontrol modepage -n da -u 3 -m 1 -e -P 3
.Ed
.Pp
da3 のモードページ 1 (Read-Write Error Recover ページ)を編集し、編集結果を
そのドライブにセーブします。モードページ 1 には、
ディスクドライブの読み出し、書き込みの自動再配置の設定などが含まれます。
.Pp
.Dl camcontrol rescan 0
.Pp
SCSI バス 0 を再スキャンし、追加、削除、変更されたデバイスを探します。
.Pp
.Dl camcontrol rescan 0:1:0
.Pp
SCSI バス 0, ターゲット 1, 論理ユニット番号 0 を再スキャンし、そのデバイスが
追加、削除、変更されたかどうかを調べます。
.Sh 関連項目
.Xr cam 3 ,
.Xr pass 4 ,
.Xr cam 9 ,
.Xr xpt 9
.Sh 歴史
.Nm camcontrol
コマンドは、
.Fx 3.0
で最初に現れました。
.Pp
モードページ編集のコードと任意の SCSI コマンドのコードは、
Julian Ellischer と Peter Dufault が書いた、かつての
.Xr scsi 8
ユーティリティと
.Xr scsi 3
ライブラリのものに基づいています。
.Xr scsi 8
プログラムが最初に出現したのは 386BSD 0.1.2.4 で、
.Tn FreeBSD
で最初に出現したのは、
.Fx 2.0.5
です。
.Sh 作者
.An Kenneth Merry Aq ken@FreeBSD.ORG
.Sh バグ
マニュアルページのクロスリファレンスのほとんどはまだ存在していません。
これは近いうちに修正されます。
.Pp
コマンド行引数を解釈するコードは、どのサブコマンドが複数の引数を取るかを
知りません。ですから、たとえば、
.Bd -literal -offset foobar
camcontrol -n da -u 1 -c "00 00 00 00 00 v" 0x00 -v
.Ed
.Pp
のようなことを試みた場合、test unit ready コマンドで得られるセンス情報は
出力されません。というのは、
.Fl c
の 2 番目の引数
.Po
0x00
.Pc
を見た時点で、
.Nm camcontrol
の最初の
.Xr getopt 3
呼び出しが
終ってしまうためです。
この動作を修正するには、ある程度の規模のコードを書き加えるか、
.Xr getopt 3
インタフェースを変更するかのどちらかが必要でしょう。
この問題を回避するもっとも良い方法は、常に
.Nm camcontrol
共通の引数をコマンド固有の引数の前に指定していることを確認することです。
.Pp
bus/target/lun か、デバイス名 (たとえば "da1" などの)でデバイスを
指定できるようにするほうがよいかもしれません。