manページ  — CAMCONTROL

camcontrol – CAM コントロールプログラム

書式 解説 環境変数 関連ファイル 使用例 関連項目 歴史 作者 バグ

camcontrol <command> [device id] [generic args] [command args]
camcontrol devlist [-v]
camcontrol periphlist [device id] [-n dev_name] [-u unit_number]
camcontrol tur [device id] [generic args]
camcontrol inquiry [device id] [generic args] [-D] [-S] [-R]
camcontrol start [device id] [generic args]
camcontrol stop [device id] [generic args]
camcontrol load [device id] [generic args]
camcontrol eject [device id] [generic args]
camcontrol rescan <all | bus[:target:lun]>
camcontrol reset <all | bus[:target:lun]>
camcontrol defects [device id] [generic args] <-f format> [-P] [-G]
camcontrol modepage [device id] [generic args] <-m page | -l> [-P pgctl] [-b | -e] [-d]
camcontrol cmd [device id] [generic args] <-c cmd [args]> [-i len fmt] [-o len fmt [args]]
camcontrol debug [-I] [-P] [-T] [-S] [-X] [-c] <all|off|bus[:target[:lun]]>
camcontrol tags [device id] [generic args] [-N tags] [-q] [-v]
camcontrol negotiate [device id] [generic args] [-c] [-D enable|disable] [-O offset] [-q] [-R syncrate] [-T enable|disable] [-U] [-W bus_width] [-v]
camcontrol format [device id] [generic args] [-q] [-r] [-w] [-y]
camcontrol help

camcontrol ユーティリティは、ユーザが FreeBSD CAM サブシステムにアクセスし制御できるようにする方法を提供する ために設計されています。

camcontrol ユーティリティを不適切に使用すると、 データの損失や、システムクラッシュにつながる可能性があります。 経験豊富なユーザであっても、このコマンドを使用する際には 注意を払うことをお勧めします。 素人さんはこのユーティリティに近付いてはいけません。

camcontrol ユーティリティはいくつかの主機能を持っています。 その多くは、省略可能なデバイス識別子をサポートします。 デバイス識別子は、次の 3 種類の書式のいずれかを取り得ます:

deviceUNIT
	デバイス名とデバイス番号の組み合わせを、"da5" や "cd3" のように指定します。 キャラクタデバイスノード名 (例えば /dev/da0) は、ここでは許され ない ことに注意してください。
bus:target
	バス番号とターゲット id を指定します。 バス番号は "camcontrol devlist" の出力により決定可能です。 論理ユニット番号 (lun) はデフォルトの 0 になります。
bus:target:lun
	デバイスのバス (bus) とターゲット (target) と論理ユニット番号 (lun) を、 (例えば 1:2:0 のように) 指定します。

デバイス識別子は、指定された場合には、 機能名の直後にかつ、すべての共通引数または機能固有引数の前に置かれることが 必要 です。 後述する -n と -u の引数は、その前に指定されるデバイス名やユニット番号をオーバライドすることに 注意してください。 しかし、 -n と -u の引数は、bus:target または bus:target:lun の指定はオーバライド しません。

camcontrol の主機能の多くは下に示す共通引数 (generic argument) をサポートします:

-C count
	SCSI コマンドのリトライカウント。 この機能が動作するためには、エラーリカバリ (-E) をオンにしておく必要があります。
-E
	指定したコマンドのための汎用の SCSI エラーリカバリを遂行 するよう、カーネルに指示を出します。 リトライカウント機能 (-C) を有効にするためにはこれが必要です。 コマンドのリトライの他に、コード中にある汎用のエラーリカバリによって、 回っていない HDD を回転させるような試みが通常なされます。 コマンドから返されたセンスコードによっては、他の操作が行われることもあります。
-n dev_name
	操作を行うデバイスのタイプを指定します。 これは例えば "da", "ca" です。
-t timeout
	SCSI コマンドのタイムアウトを秒単位で指定します。 指定したコマンドのすべてにおいて、 これで指定する値はデフォルトのタイムアウトより優先されます。
-u unit_number
	デバイスユニット番号を指定します。 これは例えば "1", "5" です。
-v
	冗舌になります。 SCSI コマンドに失敗するとセンス情報を表示します。

主コマンド機能は次のとおりです。

devlist	CAM サブシステムに接続されたすべての物理デバイス (論理ユニット) の リストを表示します。 このリストには各デバイスに接続された周辺ドライバの一覧も含まれます。 引数 -v を指定すると、SCSI バス番号、アダプタ名、ユニット番号もあわせて 表示されます。
periphlist
	指定した物理デバイス (論理ユニット) に接続されたすべての周辺ドライバの リストを表示します。
tur	指定したデバイスに SCSI test unit ready (0x00) コマンドを送信します。 camcontrol ユーティリティは、そのデバイスがレディ状態であるかどうかを報告します。
inquiry	デバイスに SCSI inquiry (0x12) コマンドを送信します。 デフォルトでは、 camcontrol 標準の inquiry データ、デバイスのシリアル番号、転送レート情報を表示します。 特定のタイプの inquiry データだけを表示するように指定することもできます。

-D
	標準 inquiry データを得ます。
-S
	シリアル番号を表示します。 このフラグだけが指定された場合、 camcontrol は、ドライブが返す値の前に "Serial Number" を表示しません。 これはスクリプトを書く際に役立ちます。
-R
	転送レートの情報を表示します。

start	指定したデバイスに、start ビットをセットした SCSI Start/Stop Unit (0x1B) コマンドを送信します。
stop	指定したデバイスに、start ビットをクリアした SCSI Start/Stop Unit (0x1B) コマンドを送信します。
load	指定したデバイスに、start ビットをセットし load/eject ビットをセットした SCSI Start/Stop Unit (0x1B) コマンドを送信します。
eject	指定したデバイスに、start ビットをクリアし load/eject ビットをセットした SCSI Start/Stop Unit (0x1B) コマンドを送信します。
rescan
	カーネルに、すべてのバス ( all 引数を指定した場合)、指定したバス (XPT_SCAN_BUS)、もしくは bus:target:lun (XPT_SCAN_LUN) をスキャンさせ、新規のデバイスや外されたデバイスを探させます。 ユーザが指定できるのは、バスすべて、バス 1 つ、 もしくは論理ユニット番号 1 つだけです。 あるターゲットのすべての論理ユニット番号をスキャンすることは サポートされていません。
reset	カーネルに、すべてのバス ( all 引数を指定した場合)、指定したバス (XPT_RESET_BUS) もしくは bus:target:lun (XPT_RESET_DEV) をリセットさせます。 前者は、バスに SCSI バスリセットを発行することにより行います。 後者は、典型的には当該デバイスにコネクトした後に、 BUS DEVICE RESET メッセージを発行することにより行います。 本コマンドはシステムに破壊的な影響を与えることがあることに注意してください。
defects
	指定したデバイスに、SCSI READ DEFECT DATA (10) コマンド (0x37) を送信し、 ディフェクト総数、初期ディフェクトリスト (PLIST)、増分ディフェクトリスト (GLIST) を組み合わせて表示します。
-f format
	書式オプションは以下の 3 つです。 block, リストを論理ブロック形式で表示します。 bfi, リストをインデックスからのバイト数の形式で表示します。 phys, リストを物理セクタ形式で表示します。 書式引数は必須です。 ほとんどのドライブは、物理セクタ形式をサポートしています。 一部のドライブは論理ブロック形式をサポートしています。 指定した書式をサポートしていない場合、多くのドライブは、 指定したデータ書式をサポートしていないことを示すセンス情報とともに、 別の書式でデータを返します。 camcontrol ユーティリティは、それを検知して ドライブが返す書式ならどのようなものでも表示しようとします。 ドライブが指定した書式をサポートしていないことを報告する際に、 非標準のセンスコードを用いた場合、 camcontrol は、おそらくそのエラーをリクエスト完了に失敗したためのものと見なすでしょう。
-G
	増分ディフェクトリストを表示します。 これは、工場出荷時以降に再マップされた不良ブロックのリストです。
-P
	初期ディフェクトリストを表示します。

-P も -G もどちらも指定していない場合、 camcontrol は、ドライブから返された READ DEFECT DATA ヘッダから得られるディフェクト数を 表示します。

modepage
	SCSI モードページを表示します。 もしくは、オプション指定により ユーザがモードページを編集できるようにします。 モードページの書式は /usr/share/misc/scsi_modes にあります。 環境変数 SCSI_MODES に別のファイルが指定されている場合はそちらが優先されます。 modepage コマンドは以下のようないくつかの引数を取ります。
-d
	モードセンスのためのブロック記述子を禁止します。
-b
	モードページデータをバイナリフォーマットで表示します。
-e
	このフラグを指定することで、ユーザはモードページ中の値を編集することが できます。 モードページの値を EDITOR 環境変数が示すエディタで編集することも可能ですし、 camcontrol がモードページ値を表示に使用するのと同じ書式にて モードページ値を標準入力から提供することも可能です。 標準入力が端末であると camcontrol が検出するとエディタが起動されます。
-l
	使用可能な全モードページを列挙します。
-m mode_page
	ユーザが表示/編集したいモードページ番号を指定します。 -l が指定されていなければ、この引数は必須です。
-P pgctl
	このフラグを指定することで、ユーザはページ制御フィールドを指定することが できます。 指定可能な値は次の通りです。
0	現在の値
1	変更可能な値
2	デフォルトの値
3	保存された値

cmd	任意のデバイスに任意の SCSI CDB を送信するために用いることができます。 cmd 機能は、CDB を指定するための -c 引数が必要です。 他の引数はオプションで、コマンドの型に依存します。 コマンドとデータを指定する文法は、 cam_cdbparse(3) に記述されています。 注: 指定した CDB によって、対象の SCSI デバイスとのデータ送受信が 発生する場合、 -i または -o を指定する必要があります。
-c cmd [args]
	これは SCSI CDB を指定します。 CDB は 6, 10, 12, 16 バイトのいずれかが可能です。
-i len fmt
	これは、読み込むデータの量と、どのように表示するかとを指定します。 書式が '-' である場合、 len バイトのデータがデバイスから読み込まれ、標準出力に書き出されます。
-o len fmt [args]
	これは、デバイスに書き出すデータの量と、書き出されるデータとを指定します。 書式が '-' である場合、 len バイトのデータが標準入力から読み込まれデバイスに書き出されます。

debug	カーネルの CAM デバッグ用 printf をオンにします。 カーネルの設定ファイル中に CAMDEBUG オプションが指定されている必要があります。 注意: 現在のところ、デバッグ用 printf を使えるようにすると、 極めて多数のカーネル printf が生じることになります。 一度デバッグ用 printf をスタートさせてしまうと、停止させるのは難しいでしょう。 というのは、カーネルはメッセージを表示するのに忙しくなるので、 他のリクエストをすぐにサービスすることができなくなるからです。 debug 機能はいくつかの引数を取ります。
-I
	CAM_DEBUG_INFO printf を有効にします。
-P
	CAM_DEBUG_PERIPH printf を有効にします。
-T
	CAM_DEBUG_TRACE printf を有効にします。
-S
	CAM_DEBUG_SUBTRACE printf を有効にします。
-X
	CAM_DEBUG_XPT printf を有効にします。
-c
	CAM_DEBUG_CDB printf を有効にします。 これにより、カーネルが、指定したデバイスに送信した SCSI CDB を 表示することになります。
all	すべてのデバイスについてデバッグ出力を有効にします。
off	すべてのデバイスについてデバッグ出力を無効にします。
bus[:target[:lun]]
	指定したバス、ターゲット、論理ユニット番号 (lun) についてデバッグ出力を 有効にします。 論理ユニット番号、もしくはターゲットと論理ユニット番号が指定されない場合は、 ワイルドカード指定されたものとして扱います (すなわち、バスだけを指定すると、そのバスのすべてのデバイスについて デバッグ用 printf が有効になります)。

tags	amp;"tagged openings" の数を、表示または設定します。 この値は、特定のデバイスに対して同時にキューイング可能な トランザクション数です。 デフォルトでは、コマンド固有の引数が無いと (一般的な引数のみを指定すると)、 tags コマンドは、 対象のデバイスにキューイング可能なトランザクション数の amp;"soft" 最大値を表示します。 さらに詳細な情報を得るには、次に説明する -v 引数を指定してください。
-N tags
	指定したデバイスのタグ数を設定します。 この値は、 カーネル中の癖の表 (quirk table) にある最小値と最大値の間にある必要があります。 タグ付きキューイングをサポートするほとんどのデバイスのデフォルトは、 最小値が 2 で最大値が 255 です。 指定したデバイスの最大値と最小値を調べるには、 -v スイッチを使用します。 この camcontrol サブコマンドに対する -v スイッチの意味は後述します。
-q
	静かになり、タグ数を報告しません。 一般的には、タグ数を設定するときに使用します。
-v
	冗長フラグは、 tags 引数に対しては特殊な機能があります。 このフラグを指定すると camcontrol は、XPT_GDEV_TYPE CCB のタグ付きキューイング関連フィールドを表示します:
dev_openings
	指定されたデバイスに対してキューイング可能なトランザクションの総数です。
dev_active
	指定されたデバイスに対して現在キューイングされているトランザクション数です。
devq_openings
	トランザクション用のカーネルキュー空間です。 通常この数は dev_openings を反映します。 エラーリカバリ時は例外であり、対象デバイスのキューは凍結されるか (デバイスはコマンド受信を許されません)、 dev_openings の数が減じられるか、トランザクションの再実行が行われます。
devq_queued
	カーネルキュー内でデバイスが空くのを待っているトランザクション数です。 エラーリカバリ中でなければ、通常この数は 0 です。
held	held 数は、周辺装置ドライバが保持する CCB 数です。 このような CCB は、丁度完了したものであるか、 デバイスによってサービスを受けるために転送層に渡されようとしているものです。 保持されている CCB は、対象のデバイスに空きを予約します。
mintags
	同時にデバイスにキューイング可能なトランザクション数の、 現在の "hard" 最小値です。 既出の dev_openings 値はこの数より小さくはなり得ません。 mintags のデフォルト値は 2 ですが、 デバイスによってはより大きくまたはより小さく設定され得ます。
maxtags
	同時にデバイスにキューイング可能なトランザクション数の、 現在の "hard" 最大値です。 既出の dev_openings はこの値より大きくはなり得ません。 maxtags のデフォルト値は 255 ですが、 デバイスによってはより大きくまたはより小さく設定され得ます。

negotiate
	様々な通信パラメータを、表示またはネゴシエートします。 コントローラによっては、特定の値の設定や変更をサポートしません。 例えば Adaptec 174x コントローラは、 デバイスの同期レートやオフセットの変更をサポートしません。 あるパラメータの設定をサポートしないとコントローラが示す場合、 camcontrol ユーティリティはそのパラメータの設定を試みません。 コントローラがサポートするものを調べるには、 -v フラグを使用します。 negotiate コマンドでの -v フラグの意味は後述します。 また、コントローラドライバによっては、 下位のコントローラがあるネゴシエーションパラメータの変更を サポートしているにもかかわらず、 そのネゴシエーションパラメータの設定をサポートしません。 Advansys ワイドコントローラのように、 コントローラの同期ネゴシエーションの有効と無効をサポートしているにも かかわらず、 同期ネゴシエーションレートの設定をサポートしないコントローラがあります。
-a
	ネゴシエーション設定がすぐに効果を持つようにするため、 対象デバイスに Test Unit Ready コマンドを送ります。
-c
	現在のネゴシエーション設定を、表示または設定します。 これがデフォルトです。
-D enable|disable
	切断 (disconnection) を、有効または無効にします。
-O offset
	コマンド遅延オフセットを設定します。
-q
	静かになり、なにも表示しません。 一般的には、パラメータを設定したいが状態情報は不要であるときに有用です。
-R syncrate
	デバイスの同期レートを変更します。 同期レートは、MHz で指定される浮動小数点値です。 例えば '20' としては、 '20.000' が正しい値です。
-T enable|disable
	デバイスのタグ付きキューイングを、有効または無効にします。
-U
	ユーザのネゴシエーション設定を、表示または設定します。 デフォルトでは、現在のネゴシエーション設定を表示または設定します。
-v
	冗長フラグは、 negotiate サブコマンドに対しては特殊な意味があります。 このフラグを指定すると camcontrol は、コントローラデバイスに送った Path Inquiry (XPT_PATH_INQ) CCB の内容を 表示します。
-W bus_width
	デバイスとネゴシエートするバス幅を指定します。 バス幅はビット数で指定します。 指定可能な値は、8, 16, 32 のいずれかのビット数です。 設定が効果を持つためには、 そのバス幅をコントローラがサポートする必要があります。

一般的には、あるデバイスの同期レートとオフセット設定が効果をあらわすのは、 そのデバイスに対してコマンドが送られてからです。 前述の -a スイッチは、ネゴシエーションパラメータが効果をあらわすようにするため、 自動的に Test Unit Ready をデバイスに送ります。

format
	SCSI FORMAT UNIT コマンドを指定したデバイスに送ります。 警告! 警告! 警告! ディスクをローレベルフォーマットすると、 ディスク上の「すべて」のデータを破壊します。 このコマンドを発行するときには、非常に注意してください。 本当はローレベルフォーマットが不要なディスクに対し、 多くのユーザがローレベルフォーマットを行っています。 ローレベルフォーマットが必要となる状況は、比較的少ないです。 ローレベルフォーマットが必要となる理由のひとつは、 ディスクの物理セクタの大きさを変えた後でディスクを初期化するためです。 ローレベルフォーマットが必要となる別の理由は、 ディスクへの読み込みまたは書き込みの要求に対して "medium format corrupted" (メディアフォーマットが壊れている) エラーとなる場合に、そのディスクを復活させるためです。 ディスクによっては、 他のディスクよりもフォーマットに時間がかかります。 フォーマットが完了するために十分なタイムアウト値を、 ユーザが指定する必要があります。 デフォルトのフォーマットタイムアウトは 3 時間です。 ハードディスクによっては、非常に短い期間 (5 分以下の単位) でフォーマット操作が完了します。 このような場合のほとんどは、 FORMAT UNIT コマンドをドライブが実際にはサポートをしていないため、 すなわちコマンドを受け付けて数分待ってから戻るだけであるためです。 'format' サブコマンドはいくつかの引数を取り、デフォルトの動作を変えます。 -q および -y の引数は、スクリプトにおいて有用です。
-q
	静かになり、状態メッセージを表示しません。 しかしながら、本オプションは、質問は無効化しません。 質問を無効化するには、後述の -y 引数を使用してください。
-r
	"報告のみ" モードで動作します。 これはドライブに対して進行中のフォーマットの状態を報告します。
-w
	非即時のフォーマットコマンドを発行します。 デフォルトでは、 camcontrol は FORMAT UNIT コマンドを即時ビット (immediate bit) をセットして発行します。 これは、フォーマットが実際に完了する前に、 即時にフォーマットコマンドを返すよう、デバイスに指示します。 そして camcontrol が SCSI センス情報を毎秒デバイスから収集し、フォーマット処理の進捗を判断します。 -w 引数が指定されると、 camcontrol は非即時のフォーマットコマンドを発行します。 この場合、ディスクの何パーセントがフォーマットされたのかを ユーザへ知らせるための表示は行われません。
-y
	質問をしません。 デフォルトでは、 camcontrol はユーザに対し、対象のディスクを本当にフォーマットしたいのか、 そしてフォーマットコマンドのデフォルトタイムアウトで良いかを質問します。 タイムアウトをコマンドラインで指定した場合、タイムアウトは質問されません。

help	冗長な、使用方法に関する情報を表示します。

変数 SCSI_MODES によって、別のモードページの書式ファイルを指定することができます。

変数 EDITOR によって、 camcontrol は、モードページの編集を行う際に どのテキストエディタを起動するかを決定します。

/usr/share/misc/scsi_modes
	SCSI モード書式データベース。
/dev/xpt0	トランスポート層デバイス。
/dev/pass*	CAM アプリケーションパススルーデバイス。

    camcontrol eject -n cd -u 1 -v

cd1 から CD をイジェクトし、コマンド実行に失敗した場合は SCSI センス情報を 出力します。

    camcontrol tur da0

SCSI test unit ready コマンドを da0 に送信します。 camcontrol ユーティリティはそのディスクがレディ状態であるかどうかを報告しますが、 -v スイッチが指定されていないため、コマンド実行に失敗してもセンス情報を 表示しません。

camcontrol tur da1 -E -C 4 -t 50 -v

SCSI test unit ready コマンドを da1 に送信します。 カーネルエラーリカバリを有効にします。 リトライカウントを 4 に、タイムアウトを 50 秒に設定します。 コマンド実行に失敗した場合 ( -v フラグがあるので) センス情報が出力されます。 エラーリカバリが設定されているので、 ディスクが回転していない場合は回転させられます。 camcontrol ユーティリティはディスクがレディ状態かどうかを報告します。

camcontrol cmd -n cd -u 1 -v -c "3C 00 00 00 00 00 00 00 0e 00" \
        -i 0xe "s1 i3 i1 i1 i1 i1 i1 i1 i1 i1 i1 i1"

READ BUFFER コマンド (0x3C) を cd1 に対して発行します。 cd1 のバッファサイズと cd1 のキャッシュの最初の 10 バイトを表示します。 コマンド実行に失敗した場合 SCSI センス情報を表示します。

camcontrol cmd -n cd -u 1 -v -c "3B 00 00 00 00 00 00 00 0e 00" \
        -o 14 "00 00 00 00 1 2 3 4 5 6 v v v v" 7 8 9 8

WRITE BUFFER コマンド (0x3B) を cd1 に対して発行します。 (予約済の) 4 バイトヘッダを含まないデータ 10 バイトを書き出します。 コマンド実行に失敗した場合センス情報を表示します。 このコマンドには細心の注意を払って下さい。 不適切に使用した場合、データが破壊されるかもしれません。

camcontrol modepage da3 -m 1 -e -P 3

da3 のモードページ 1 (Read-Write Error Recover ページ) を編集し、 編集結果をそのドライブにセーブします。 モードページ 1 には、ディスクドライブの読み出し、 書き込みの自動再配置の設定などが含まれます。

    camcontrol rescan all

システム中のすべての SCSI バスに対し、 追加/削除/変更されたデバイスを再スキャンします。

    camcontrol rescan 0

SCSI バス 0 を再スキャンし、追加、削除、変更されたデバイスを探します。

    camcontrol rescan 0:1:0

SCSI バス 0, ターゲット 1, 論理ユニット番号 0 を再スキャンし、そのデバイスが 追加、削除、変更されたかどうかを調べます。

    camcontrol tags da5 -N 24

da5 の同時トランザクション数を 24 に設定します。

camcontrol negotiate -n da -u 4 -T disable

da4 のタグ付きキューイングを無効にします。

camcontrol negotiate -n da -u 3 -R 20.000 -O 15 -a

同期レート 20MHz とオフセット 15 を、da3 とネゴシエートします。 その後 Test Unit Ready コマンドを送り、設定が効果をあらわすようにします。

camcontrol ユーティリティは、 FreeBSD 3.0 ではじめて登場しました。

モードページ編集のコードと任意の SCSI コマンドのコードは、 Julian Elischer と Peter Dufault が書いた、かつての scsi(8) ユーティリティと scsi(3) ライブラリのものに基づいています。 scsi(8) プログラムは BSD 386 0.1.2.4 ではじめて登場し、 FreeBSD では、 FreeBSD 2.0.5 ではじめて登場しました。

Kenneth Merry <ken@FreeBSD.org>