日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.4-RELEASE-K, 13.0-RELEASE-K から 13.3-RELEASE-K, 14.0-RELEASE-K から 14.1-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
PCI(4) FreeBSD カーネルインタフェースマニュアル PCI(4)
名称
pci -- 一般的な PCI/PCIe バスドライバ
書式
PCI バスドライバをカーネルにコンパイルするためには、次の行を利用者のカー
ネル設定ファイルに置きます:
device pci
Single Root I/O Virtualization (SR-IOV) のサポートでコンパイルするために
は:
options PCI_IOV
ネイティブの PCI-express HotPlug のサポートでコンパイルするためには:
options PCI_HP
解説
pci ドライバは、ユーザランドのために PCI デバイスへのカーネルと制限された
アクセスの PCI と PCIe デバイスのサポートを行います。
pci ドライバは、PCI 設定レジスタを読み込み、書き込むためにユーザランドの
プログラムによって使用することができる、/dev/pci キャラクタデバイスを提供
します。また、プログラムは、様々なパターンと一致するすべての PCI デバイス
のリスト、またはすべての PCI デバイスを取得するために、このデバイスを使用
することができます。
pci ドライバは、PCI 設定レジスタのための書き込みインタフェースを提供する
ので、システム管理者は、pci デバイスへのアクセス許可するとき、警告を実効
するべきです。不適切に使用されるなら、このドライバによって、ユーザランド
のアプリケーションは、マシンをクラッシュするか、データ損失を引き起こすこ
とができます。特に、ドライバは、ファイル記述子が書き込みのためにオープン
されているなら、システムの状態を変更するためにオープンされた /dev/pci で
のみ操作を許可します。例えば、PCIOCREAD と PCIOCBARMMAP 操作は、設定レジ
スタの読み込みまたは BAR の読み込みアクセスが関数特有の副作用があるかもし
れないので、書き込み可能な記述子を必要とします。
pci ドライバは、カーネルの PCI バスを実装します。それは、PCI バスのあらゆ
るデバイスを列挙し、それらにアタッチするチャンスを PCI クライアントのドラ
イバに与えます。BIOS が行わないき、それは、リソースを子プロセスに割り当て
ます。それは、必要なときに、割り込みを経路制御することを処理します。PCI
クライアントドライバが実行時に動的にロードされるとき、アタッチされていな
い PCI の子供を再プローブします。また、pci ドライバは、PCI-PCI ブリッジの
ためのサポート、PCI VGA アダプタのための基本的なサポート、とホスト PCI ブ
リッジ特有の様々なプラットフォームのサポートを含みます。
IOCTL
次の ioctl(2) 呼び出しは、pci ドライバによってサポートされます。それら
は、ヘッダファイル <sys/pciio.h> で定義されます。
PCIOCGETCONF この ioctl(2) は、pci_conf_io 構造体を取ります。ユーザ
は、システムのすべての PCI デバイスで、またはユーザに
よって供給されたパターンに一致した PCI デバイスで情報を
検索して取得できます。呼び出しは、copyin(9) か
copyout(9) のいずれかで指定されたどんな値にも errno を設
定するかもしれません。pci_conf_io 構造体は、次の多くの
フィールドから構成されています:
pat_buf_len ユーザによって供給されたパターンで埋めら
れたバッファのバイト単位の長さ。
num_patterns ユーザによって供給されたパターンの数。
patterns ユーザによって供給されたパターンで満たさ
れたバッファへのポインタ。patterns は、
num_patterns pci_match_conf 構造体へのポ
インタです。pci_match_conf 構造体は、次の
要素から構成されています:
pc_sel PCI ドメイン、バス、スロットと
機能。
pd_name PCI デバイスドライバ名。
pd_unit PCI デバイスドライバユニット番
号。
pc_vendor PCI ベンダ ID。
pc_device PCI デバイス ID。
pc_class PCI デバイスクラス。
flags フラグは、カーネルのどのフィー
ルドに一致すべきであるかを記述
します。デバイスは、返されるす
べての指定されたフィールドに一
致しなければなりません。一致フ
ラグは、pci_getconf_flags 構造
体で列挙されます。願わくは、フ
ラグの値は、詳細に説明される必
要がないほど明白です。
match_buf_len PCIOCGETCONF 問い合わせの結果を保持するた
めにユーザによって割り付けたられた
matches バッファの長さ。
num_matches カーネルによって返される一致の数。
matches カーネルによって返される一致デバイスを含
むバッファ。このバッファの中のアイテム
は、次のアイテムから構成されるタイプ
pci_conf です。
pc_sel PCI ドメイン、バス、スロッ
トと機能。
pc_hdr PCI ヘッダタイプ。
pc_subvendor PCI サブベンダ ID。
pc_subdevice PCI サブデバイス ID。
pc_vendor PCI ベンダ ID。
pc_device PCI デバイス ID。
pc_class PCI デバイスクラス。
pc_subclass PCI デバイスサブクラス。
pc_progif PCI デバイスプログラミング
インタフェース。
pc_revid PCI リビジョン ID。
pd_name ドライバ名。
pd_unit ドライバユニット番号。
offset オフセットは、デバイスリストを横断し始め
るべきであるところでカーネルに伝えるため
にユーザによって渡されます。カーネルに
よって渡された値は、最後の 1 つが返された
直後のレコードを指します。ユーザは、
PCIOCGETCONF ioctl へのその後の呼び出しに
おいてカーネルによって返された値を渡すこ
とができます。ユーザがオフセットを使用し
ないつもりであるなら、それは、0 に設定し
なければなりません。
generation PCI 設定世代。この値は、オフセットが設定
される場合にだけ設定される必要がありま
す。カーネルは、ユーザが最後の
PCIOCGETCONF ioctl を呼び出し以来、デバイ
スリストが変化しているかどうか決定するた
めにユーザによって渡された内部のデバイス
リストの現世代の番号を比較します。デバイ
スリストが変化したなら、
PCI_GETCONF_LIST_CHANGED の状態が戻されま
す。
status status は、デバイスリストのための要求の傾
向をユーザに伝えます。指定できる status
の値は、次の通りです:
PCI_GETCONF_LAST_DEVICE
これは、matches バッファに返されたものの
後に、指定された基準と一致している PCI デ
バイスリストにデバイスが何もないことを意
味しています。
PCI_GETCONF_LIST_CHANGED
この状態から、PCIOCGETCONF ioctl への最後
の呼び出し以来 PCI デバイスリストが変化し
ており、そしてリストの始めにやり直すため
に 0 に offset と generation をリセットし
なければならないことが分かります。
PCI_GETCONF_MORE_DEVS
これは、基準に一致するデバイスリストの残
りのデバイスのすべてを保持するためにバッ
ファが十分に大きくなかったことをユーザに
伝えます。
PCI_GETCONF_ERROR
これは、ユーザの要求を行なっている間の一
般的なエラーを示します。pat_buf_len が
sizeof(struct pci_match_conf) の
num_patterns 倍と等しくないなら、errno
は、EINVAL に設定されます。
PCIOCREAD この ioctl(2) は、渡された pci_io 構造体によって指定され
た PCI 設定レジスタを読み込みます。pci_io 構造体は、次の
フィールドから構成されます:
pi_sel ユーザが問い合わせしたいドメイン、バス、スロッ
トと関数を指定する pcisel 構造体。特定のバスが
見つけられないなら、errno は、ENODEV に設定さ
れ、ioctl から -1 が返されます。
pi_reg ユーザがアクセスしたい PCI 設定レジスタ。
pi_width ユーザは、読み込みたいデータのバイト単位の幅。
この値は、1、2 または 4 のいずれかです。3 バイ
トの読み込みと 4 バイトより大きい読み込みはサ
ポートされません。無効の幅が渡されるなら、
errno は、EINVAL に設定されます。
pi_data カーネルによって返されるデータ。
PCIOCWRITE この ioctl(2) によって、ユーザは、渡された pci_io 構造体
で指定される PCI 設定レジスタに書き込むことができます。
pci_io 構造体は、上記に説明されています。読み込みレジス
タのための上記に説明されたデータ幅の制限は、PCI 設定レジ
スタの書き込みも適用されます。
PCIOCATTACHED この ioctl(2) によって、ユーザは、ドライバが、渡される
pci_io 構造体で指定された PCI デバイスにアタッチしている
なら、問い合わせることができます。pci_io 構造体は、上で
説明されますが、しかしながら、pi_reg と pi_width フィー
ルドは、使用されません。デバイスの状態は、pi_data フィー
ルドに格納されます。0 の値は、ドライバがアタッチされない
ことを示しますが、一方、0 より大きな値は、ドライバがア
タッチされていることを示します。
PCIOCBARMMAP この ioctl(2) コマンドによって、ユーザ空間のプロセスは、
そのアドレス空間にメモリマップされた PCI BAR を mmap(2)
することができます。入力パラメータと結果は、次のフィール
ドがある、pci_bar_mmap 構造体に渡されます:
uint64_t pbm_map_base
呼び出し側に確立されたマッピングの
基礎を報告します。
PCIIO_BAR_MMAP_FIXED フラグが指定
されたなら、このフィールドは、マッ
ピングのための要求されたアドレスで
呼び出す前に、満たされなけれなりま
せん。
uint64_t pbm_map_length
バイト単位の BAR のマップされた長
さを報告します。その uint64_t 値
は、常にマシンページの倍数です。
int64_t pbm_bar_length
デバイスによって公開される bar の
長さを報告します。
int pbm_bar_off bar の最初のレジスタの開始にマップ
された基礎からのオフセットを報告し
ます。
struct pcisel pbm_sel
呼び出す前に満たされるべきです。操
作するデバイスを記述します。
int pbm_reg mmap する BAR インデックス。
int pbm_flags 操作を増加するフラグ。以下を参照し
てください。
int pbm_memattr マッピングのためのキャッシュ属性。
通常の値は、制御レジスタ BAR のた
めの VM_MEMATTR_UNCACHEABLE とフ
レームバッファのための
VM_MEMATTR_WRITE_COMBINING です。
通常のメモリのような BAR は、
VM_MEMATTR_DEFAULT 属性でマップさ
れるべきです。
現在定義されたフラグは、次の通りです:
PCIIO_BAR_MMAP_FIXED 結果のマッピングは、
pbm_map_base メンバによって指定
されたアドレスで確立されるべき
で、そうでなければ、失敗しま
す。
PCIIO_BAR_MMAP_EXCL 指定された基礎が、すでに確立さ
れているマッピングを含み、操作
が、暗黙のマップされないそれら
の代わりに失敗するなら、
PCIIO_BAR_MMAP_FIXED とともに使
用されなければなりません。
PCIIO_BAR_MMAP_RW 要求されたマッピングは、読み込
みと書き込みの両方を許可しま
す。フラグなしで、読み込み専用
のマッピングは、確立されます。
それは、読み込みでさえ副作用が
あるデバイスレジスタのために共
通であることに注意してくださ
い。
PCIIO_BAR_MMAP_ACTIVATE (実装されていません) BAR がアク
ティブでないなら、マッピングの
仮定でそれをアクティブにしま
す。現在、エラーを結果のアク
ティブでない BAR を mmap するこ
とを試みます。
PCIOCBARIO この ioctl(2) コマンドによって、ユーザは、BAR からの読み
込みと BAR への書き込みを可能にします。I/O 要求パラメー
タは、次のフィールドがある、struct pci_bar_ioreq 構造体
で渡されます:
struct pcisel pbi_sel
操作するデバイスを説明しています。
int pbi_op
実行する操作。現在サポートされている値は、
PCIBARIO_READ と PCIBARIO_WRITE です。
uint32_t pbi_bar
操作する BAR のインデックス。
uint32_t pbi_offset
操作する BAR へのオフセット。
uint32_t pbi_width
I/O 操作のバイト単位のサイズ。1 バイト、2 バイ
ト、4 バイトと 8 バイトの操作は、サポートされ
ています。
uint32_t pbi_value
読み込みについて、値は、このフィールドに返され
ます。書き込みについて、呼び出し側は、この
フィールドに書き込む値を指定します。
この操作は、対応するリソースのマッピングとアン
マッピングするので、メモリ BAR のために比較的
高価であることに注意してください。代りに、
PCIOCBARMMAP ioctl(2) は、そのような BAR のた
めの永続的なユーザ空間のマッピングを作成するた
めに使用することができます。
ローダ調整変数
カーネルをブートする前に、loader(8) プロンプトで、または loader.conf(5)
に格納され、調整変数を設定することができます。これらの調整変数の現在の値
は、同じ名前の sysctl(8) ノードを通して実行時に調査することができます。そ
うでなければ、指定されないなら、これらの調整変数のそれぞれは、調整変数を
0 以外の値に設定することによって有効にすることができる、ブール値です。
hw.pci.clear_bars (デフォルトは、0)
あらゆるファームウェアで割り当てられたメモリと I/O ポートのリソー
スを無視します。これによって、PCI バスドライバは、最初からメモリ
のためのリソース範囲と I/O ポートのリソースに割り付けることを強制
します。
hw.pci.clear_buses (デフォルトは、0)
PCI-PCI ブリッジのあらゆるファームウェアで割り当てられたバス番号
レジスタを無視します。これによって、PCI バスドライバと PCI-PCI ブ
リッジドライバは、PCI-PCI ブリッジの後ろの 2 番目のバスのためにバ
ス番号を割り付けることを強制します。
hw.pci.clear_pcib (デフォルトは、0)
PCI-PCI ブリッジのあらゆるファームウェアで割り当てられたメモリと
I/O ポートのリソースのウィンドウを無視します。これは、リソースの
ウィンドウのためにメモリと I/O ポートのリソースを最初から割り付け
ることを PCI-PCI ブリッジドライバに強制します。
デフォルトで、PCI-PCI ブリッジドライバは、ブリッジの後ろのファー
ムウェアで割り当てられたリソースのデバイスを含んでいるウィンドウ
を割り付けます。さらに、PCI-PCI ブリッジドライバは、リソース要求
を満たしてすを可能にするとき、既存のウィンドウの領域から部分的に
割り付けます。結果として、hw.pci.clear_bars と hw.pci.clear_pcib
の両方は、ファームウェアで供給されたリソースの割り当てを完全に無
視することが可能でなければなりません。
hw.pci.default_vgapci_unit (デフォルトは、-1)
デフォルトで、システムが遭遇する最初の PCI VGA アダプタは、ブート
表示デバイスであると仮定されます。関連する vgapciX デバイスのユ
ニット番号を指定することによって特有の VGA アダプタを選択するため
に、この調整変数を設定することができます。
hw.pci.do_power_nodriver (デフォルトは、0)
適当なデバイスドライバが見つけられないとき、デバイスを低電力状態
(D3) に置きます。次の値の 1 つに設定することができます:
3 デバイスドライバなしのすべての PCI デバイスの電源を落しま
す。
2 デバイスドライバなしのほとんどのデバイスの電源を落しま
す。ディスプレイ、メモリと基本の周辺デバイスクラスある
PCI デバイスは、電源を落されません。
1 また、記憶域のコントローラが電源を落されないことを除い
て、2 の設定と同様です。
0 すべてのデバイスは、完全に電源が上がったままにされます。
PCI デバイスは、電源が落される電源管理をサポートしなければなりま
せん。デバイスを低電力状態に置くことは、電力の消費量を減少しませ
ん。
hw.pci.do_power_resume (デフォルトは、1)
システムまたは個別のデバイスのいずれかを再開するとき、PCI デバイ
スを完全な電源状態に置きます。これを 0 に設定することは、システム
が、サスベンドの後に、電源が供給されない PCI デバイスに電源を上げ
ることを試みないように、抑制されます。
hw.pci.do_power_suspend (デフォルトは、1)
システムまたは個別のデバイスのいずれかをサスペンドするとき、PCI
デバイスを低電力状態に置きます。通常、D3 状態は、低電力状態として
使用されますが、ファームウェアは、システムのサスペンドの間に、要
求された電源状態を上書きします。
hw.pci.enable_ari (デフォルトは、1)
PCI-express Alternative RID Interpretation のためのサポートを有効
にします。これは、しばしば SR-IOV とともに使用されます。
hw.pci.enable_io_modes (デフォルトは、1)
それがメモリまたは I/O ポートのリソースをファームウェアで割り当て
たなら、PCI デバイスのコマンドレジスタでデコードしているメモリま
たは I/O ポートを有効にします。いくつかのシステムのファームウェア
(BIOS) は、それがリソースをデバイスに割り当てたときでさえ、いくつ
かのデバイスのためにデコードしているメモリまたは I/O ポートを有効
にしません。これは、バスのプローブの間にそのようなリソースのため
にデコードすることを有効にします。
hw.pci.enable_msi (デフォルトは、1)
Message Signalled Interrupts (MSI) のためのサポートを有効にしま
す。この調整変数を 0 に設定することによって MSI 割り込みを無効に
することができます。
hw.pci.enable_msix (デフォルトは、1)
拡張された Message Signalled Interrupt (MSI-X) のためのサポートを
有効にします。この調整変数を 0 に設定することによって MSI-X 割り
込みを無効にすることができます。
hw.pci.enable_pcie_ei (デフォルトは、0)
PCI-express Electromechanical のサポートを有効にします。
hw.pci.enable_pcie_hp (デフォルトは、1)
ネイティブの PCI-express HotPlug のためのサポートを有効にします。
hw.pci.honor_msi_blacklist (デフォルトは、1)
MSI と MSI-X 割り込みは、この調整変数が設定されるとき、MSI と
MSI-X の実装を壊したと知られている特定のチップセットのために無効
にされます。チップセットの照合が偽研修であるなら、MSI と MSI-X 割
り込みの使用を許可するために 0 に設定することができます。
hw.pci.iov_max_config (デフォルトは、1MB)
SR-IOV を通して仮想関数 (Virtual Function) を作成するとき、使用さ
れる設定パラメータのために許可されたメモリの最大の量。また、
sysctl(8) を通して実行時にこの調整変数を変更することができます。
hw.pci.realloc_bars (デフォルトは、0)
別のアクティブなリソースと衝突しているファームウェアで割り当てら
れた範囲であらゆるメモリまたは I/O ポートのリソースのために初期の
デバイスをスキャンする間に、新しいリソース範囲を割り付けることを
試みます。
hw.pci.usb_early_takeover (amd64 と i386 でデフォルトは、1)
初期のデバイスをスキャンする間に、USB デバイスの古いデバイスのエ
ミュレーションを無効にします。USB コントローラドライバなしでカス
タムのカーネルを使用するとき、古いエミュレーションを通して USB デ
バイスを使用するためにこの調整変数を 0 に設定します。
hw.pci<D>.<B>.<S>.INT<P>.irq
古い PCI INTx 割り込みのために経路制御している割り込みを上書きす
るためにこれらの調整変数を使用することができます。このリストの他
の調整変数と違って、これらは、対応した sysctl ノードがありませ
ん。調整変数の名前は、上書きする要求された INTx IRQ のピンと同様
に PCI デバイスのアドレスを含んでいます:
<D> 10 進数の PCI デバイスのドメイン (またはセグメント)。
<B> 10 進数の PCI デバイスのバスアドレス。
<S> 10 進数の PCI デバイスのスロット。
<P> 上書きする PCI スロットの割り込みピン。`A', `B', `C' また
は `D' の 1 つ。
調整変数の値は、調整変数の名前によって識別された INTx 割り込みピ
ンのために使用する生の IRQ 値です。プラットフォームの割り込みソー
スへの IRQ 値のマップは、マシン依存です。
デバイスの配線
利用者は、device.hints とともに与えられた位置でデバイスユニットに配線する
ことができます。形式 hints.<name>.<unit>.at="pci<B>:<S>:<F>" または
hints.<name>.<unit>.at="pci<D>:<B>:<S>:<F>" のエントリは、仕様に一致する
見つけられたあらゆる PCI デバイスのためのユニット unit でプローブしてア
タッチするためにドライバ name を強制します、ここで:
<D> 10 進数の PCI デバイスのドメイン (またはセグメント)。特定されて
いないなら、デフォルトは、0 です。
<B> 10 進数の PCI デバイスのバスアドレス。
<S> 10 進数の PCI デバイスのスロット。
<F> 10 進数の PCI デバイスの関数。
一致するコードは、正確な文字列の照合を必要とします。ヒントファイルで山括
弧 (< >) を指定してはいけません。同じ name と unit への複数デバイスを配線
することは、未定義な結果となります。
使用例
/boot/device.hints に次の行が与えられます: hint.nvme.3.at="pci6:0:0"
hint.igb.8.at="pci14:0:0" PCI バス 14 スロット 0 関数 0 で igb(4) をサ
ポートするデバイスがあるなら、それは、プローブとアタッチのための割り当て
られた igb8 です。同様に、PCI バス 6 スロット 0 関数 0 に nvme(4) カード
があるなら、それは、プローブとアタッチのために割り当てられた nvme3 です。
別のタイプのカードがこれらの位置のいずれかであるなら、そのカードの名前と
ユニットは、デフォルト名であり、これらのヒントによって影響されます。他の
igb または nvme カードが、他の場所に位置付けられるなら、それらは、連続し
て割り当てられます。
関連ファイル
/dev/pci pci ドライバのためのキャラクタデバイス。
関連項目
pciconf(8)
歴史
pci ドライバ (カーネルの PCI サポートコードでない) は、FreeBSD 2.2 ではじ
めて登場し、Stefan Esser と Garrett Wollman によって書かれました。デバイ
スのリストとマッチングのサポートは、Kenneth Merry によって再実装されて、
FreeBSD 3.0 ではじめて登場しました。
作者
Kenneth Merry <ken@FreeBSD.org>
バグ
別の方法で現世代の番号を知る方法が全くないので、ユーザが少なくとも一度
PCIOCGETCONF を呼び出さないでデバイスリスト中に正確なオフセットを指定する
ことはできません。もっとも、ユーザがパターンかカーネルに一致するパターン
を指定することによって容易にそれらの検索を狭くすることができるので、これ
は、たぶん深刻な問題ではありません。
FreeBSD 13.2 October 4, 2022 FreeBSD 13.2