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 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> [-P pgctl] [-e] [-d] camcontrol cmd [device id] [generic args] <-c cmd [args]> [-i len fmt] [-o len fmt [args]] camcontrol debug [-I] [-T] [-S] [-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] [-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
    デバイスユニット番号を指定します。デフォルトは 0 です。

-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) コマンドを送信します。

eject
    指定したデバイスに、start ビットをクリアし eject ビットをセットした SCSI Start/Stop Unit (0x1B) コマンドを送信します。

rescan
    カーネルに、すべてのバス ( all 引数を指定した場合)、指定したバス (XPT_SCAN_BUS)、もしくは bus:target:lun (XPT_SCAN_LUN) をスキャンさせ、新規のデバイスや外されたデバイスを 探させます。ユーザが指定できるのは、スキャンするバスもしくは 論理ユニット番号だけです。あるターゲットのすべての論理ユニット番号を スキャンすることはサポートされていません。

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 モードページを表示します。もしくは、オプション指定により ユーザがモードページを編集できるようにします。 modepage の書式は /usr/share/misc/scsi_modes にあります。 環境変数 SCSI_MODES に別のファイルが指定されている場合はそちらが優先されます。 modepage コマンドは以下のようないくつかの引数を取ります。

    -d  モードセンスのためのブロック記述子を禁止します。

    -e  このフラグを指定することで、ユーザはモードページ中の値を編集することが できます。

    -m mode_page
        ユーザが表示/編集したいモードページ番号を指定します。この引数は必須です。

    -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 を有効にします。

    -T  CAM_DEBUG_TRACE printf を有効にします。

    -S  CAM_DEBUG_SUBTRACE 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 引数を使用してください。

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

関連項目
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 共通引数をコマンド固有の引数の前に指定していることを確認することです。