camcontrol(8)

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 種類の書 式のいずれかを取り得ます:

デバイス名とデバイス番号の組み合わせを、"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
"tagged openings" の数を、表示または設定します。この値は、特 定のデバイスに対して同時にキューイング可能なトランザクション 数です。デフォルトでは、コマンド固有の引数が無いと (一般的な 引数のみを指定すると)、 tags コマンドは、対象のデバイスに キューイング可能なトランザクション数の "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 は、モードページの編集を行う際にどのテ キストエディタを起動するかを決定します。

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 コマンドを送り、設定が効果をあらわすようにします。

cam(3), cam_cdbparse(3), cam(4), pass(4), xpt(4)

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

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

Kenneth Merry ⟨ken@FreeBSD.org⟩

コマンド行引数を解釈するコードは、どのサブコマンドが複数の引数を取るかを 知りません。ですから、たとえば、

      camcontrol cmd -n da -u 1 -c "00 00 00 00 00 v" 0x00 -v

のようなことを試みた場合、test unit ready コマンドで得られるセンス情報は 出力されません。というのは、 −c の 2 番目の引数 (0x00) を見た時点で、 camcontrol の最初の getopt(3) 呼び出しが終ってしまうためです。この動作を 修正するには、ある程度の規模のコードを書き加えるか、 getopt(3) インタ フェースを変更するかのどちらかが必要でしょう。この問題を回避するもっとも 良い方法は、常に camcontrol 共通引数をコマンド固有の引数の前に指定してい ることを確認することです。

FreeBSD 10.0 September 14, 1998 FreeBSD 10.0