日本語 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
DTC(1) FreeBSD 一般コマンドマニュアル DTC(1)
名称
dtc -- デバイスツリーコンパイラ
書式
dtc [-@fhsv] [-b boot_cpu_id] [-d dependency_file] [-i include_path]
[-E [no-]checker_name] [-H phandle_format] [-I input_format]
[-O output_format] [-o output_file] [-R entries] [-S bytes]
[-p bytes] [-V blob_version] [-W [no-]checker_name]
[-P predefined_properties] input_file
解説
dtc ユーティリティは、フラットにされたデバイスツリー (flattened device
tree; FDT) 表現の間を変換します。それは、デバイスツリーブロブ (blob)
(device tree blobs; DTB)、FDT のバイナリの表現、デバイスツリーソース
(device tree sources; DTS) から ASCII テキストソース表現を生成するために
最も共通に使用されます。
バイナリは、2 つの形式、バイナリとアセンブリで書き込むことができます。バ
イナリは、メモリ間の表現と同一で、ファームウェア、ローダなどによって直接
使用することができます。ASM FORMAT で文書化された、アセンブリ形式は、アセ
ンブルされるとき、同じバイナリ形式を生成しますが、テーブルの一部を参照す
るいくつかのグローバル変数も含みます。この形式は、コンパイルされたデバイ
スツリーのブロブ (blob) でデバイスに特有なカーネルを生成するために最も共
通に使用されます。
オプションは、次の通りです:
-d dependency_file
make によって理解できる依存状態ファイルを指定されたファイルに書き
込みます。このファイルは、Makefile に含めることができ、出力ファイ
ルが入力ファイルとそれが含むあらゆるファイルに依存することを保証
します。この引数は、ソース形式にだけ含められた概念だけあるよう
に、入力が DTS であるときだけ役に立ちます。
-i include_path
インクルードファイルのための検索するパスを追加します。
-E [no-]checker_name
指定されたチェッカを有効にするか、または無効にします。引数は、
チェッカの名前です。チェッカの完全なリストは、「チェッカ」で与え
られます。
-@ プラグインがロードできる __symbols__ ノードを出力します。
-f たとえ入力にエラーがあっても、ツールが出力を生成することを試みる
ことを強制します。
-h ヘルプテキストを表示し、終了します。
-H phandle_format
出力で生成する phandle ノードのタイプを指定します。有効な値は、次
の通りです:
linux 古いシステムによって予期される、古い linux、phandle ノー
ドを生成します。
epapr ePAPR 仕様で説明されるように phandle ノードを生成します。
これは、FreeBSD で使用されているデバイスツリーのための最
も賢明なオプションです。
both 最大の互換性のために両方とも生成します。
-I input_format
入力形式を指定します。有効な値は、次の通りです:
dtb デバイスツリーのブロブ (blob)。FDT のバイナリの表現。
dts デバイスツリーのソース。FDT の ASCII 表現。入力形式が明示
的に規定されていないなら、これは、デフォルトです。
-O output_format
出力形式を指定します。有効な値は、次の通りです:
asm ASM FORMAT で説明されるようにデバイスツリーのブロブ
(blob) を生成するためのアセンブラソース。
dtb デバイスツリーのブロブ (blob)。FDT のバイナリの表現。出力
形式が明示的に規定されていないなら、これは、デフォルトで
す。
dts デバイスツリーのソース。FDT の ASCII 表現。
-o output_file
出力を書き込むファイル。
-P predefined_macro
条件付きの構成要素を含んでいるデバイスツリーのソースファイルのた
めに使用される、形式 name=value または name でマクロを定義しま
す。このツールは、デバイスツリーの条件付きコンパイルをサポートす
るために標準への 2 つの拡張をサポートしています。最初は、指定され
たプロパティがこのフラグで渡されるなら、指定されたファイルだけを
含むファイルの開始で許可される /include/if [property]/ file.dts
ディレクティブです。2 番目は、プロパティ値のための $NAME 形式で
す。これらによってプロパティ値を、コマンド行で指定することができ
ます。
-R entries
テーブルをパディングする空の予約テーブルエントリの数。利用者が
ブートローダ、またはオペレーティングシステムに制御を渡す前に、い
くらかのメモリを予約する必要がある、同様のもののためにデバイスツ
リーのブロブ (blob) を生成しているなら、これは、役に立ちます。
-S bytes
ブロブ (blob) のバイト単位の最小のサイズ。ブロブ (blob) は、それ
が正確なサイズであることを保証するために文字列テーブルの後にパ
ディングされます。これは、デバイスツリーのブロブ (blob) が、適切
な位置で修正されなければならない環境のために役に立ちます。
-p bytes
ブロブ (blob) に追加するためにパディングするバイト数。ブロブ
(blob) は、それが正確なサイズであることを保証するために文字列テー
ブルの後でパディングされます。これは、デバイスツリーのブロブ
(blob) が、適切な位置で修正されなければならない環境のために役に立
ちます。
-W [no-]checker_name
指定されたチェッカを有効にするか、または無効にします。これは、-E
のためのエイリアス (別名) です。
-s ツリーのプロパティとノードをソートします。これは、2 つのデバイス
ツリーのソースを比較するために diff(1) のようなツールを使用すると
き、主に役に立ちます。
-V output_version
出力への形式のバージョン。これは、バイナリの出力のためだけに関連
し、17 の値だけが、現在サポートされています。
-v ツールのバージョンを表示し、終了します。
input_file
ソースファイル。
ASM FORMAT
アセンブリ形式は、ソースで指定されたあらゆるラベルに加えて、他のコンパイ
ルユニットから参照することができるいくつかのグローバルを定義します。これ
らは、次の通りです:
dt_blob_start デバイスツリーのブロブ (blob) の開始。
dt_header ヘッダの開始、通常ブロブ (blob) の開始と同一で
す。
dt_reserve_map 予約マップの開始。
dt_struct_start 構造テーブルの開始。
dt_struct_end 構造テーブルの終わり。
dt_strings_start 文字列テーブルの開始。
dt_strings_end 文字列テーブルの終わり。
dt_blob_end デバイスツリーのブロブ (blob) の終わり。
チェッカ
ユーティリティは、ツリーの正確さの多くの意味的なチェックを提供します。こ
れらは、-W フラグで無効にすることができます。例えば、-W no-type-phandle
は、phandle タイプチェックを無効にします。サポートされたチェックは、次の
通りです:
type-compatible compatible (互換性) のプロパティのタイプをチェック
します。
type-model model プロパティのタイプをチェックします。
type-compatible compatible (互換性) のプロパティのタイプをチェック
します。
cells-attributes
子供があるすべてのノードが、#address-cells と
#size-cells プロパティの両方があることをチェックし
ます。
deleted-nodes すべての /delete-node/ 文がマージされるノードを参
照するかをチェックします。
オーバレイ
ユーティリティは、プラグインとしても知られているオーバレイを生成するため
のサポートを行います。オーバレイは、-@ フラグでコンパイルされなかったデバ
イスツリーにパッチするためのいくらかの制限されたサポートがある、-@ フラグ
でコンパイルされた基本のデバイスツリーにパッチしている方法です。
DTS が、オーバレイとして使用されることを意図していることを示すために、あ
らゆる適用可能な /dts-v1/; タグに続いて、/plugin/; は、ヘッダに含められる
べきです。
慣習的なオーバレイは、ルートの fragment ノードを作成することによって丹念
に作られます。各フラグメントノードは、ラベル参照に設定された target プロ
パティ、またはパスに設定された target-path 文字列プロパティのいずれかがな
ければなりません。次に、それは、オーバレイが適用されるとき、プロパティと
子供ノードが、基本のデバイスツリーにマージされる、__overlay__ 子ノードが
なければなりません。
より簡単な構文的なシュガーは、生成しているオーバレイを簡素化するために、
後で考案されました。手動で作成しているターゲットとなるフラグメントの代わ
りに、慣習的な DTS でサポートされる &label 構文を使用して基本の FDT のラ
ベルをターゲットとするルートノードを代わりに作成することができます。これ
は、与えられた label が、ターゲットとなるように、フラグメントがノードのた
めに生成されるべきであることを示し、プロパティと子供ノードは、__overlay__
として使用されます。
さらに、この構文上のシュガーのパスベースのバージョンが、サポートされてい
ます。ルートノードは、形式 &{/path} の名前を使用して基本の FDT のパスを
ターゲットとします。フラグメントは、target-path プロパティが /path に設定
され、target が、設定されないことを除いて、&label の場合であるように、
ノードのために生成されます。
伝統的なオーバレイ、とより遅く追加された構文的なシュガー (sugar) の両方
が、サポートされます。
loader.conf(5) の fdt_overlays を設定することによって、ブート時に、オーバ
レイのブロブ (blob) を適用することができます。複数のオーバレイは、指定さ
れ、それらは、与えられた順序で適用されます。
ノードの省略
このユーティリティは、それらが、デバイスツリーの他の場所で最終的に参照さ
れないなら、省略のためのノードをマークするために、/omit-if-no-ref/ 文をサ
ポートしています。これは、ツリーがコンパイルされている特有のデバイスに適
用可能ではない、ノードを削除するために、より多くの空白の強制された環境で
使用されます。
-@ フラグがシンボルを書き込むために使用されるとき、ラベルがあるノードは、
参照が考慮され、ツリーから削除されません。
使用例
コマンド:
dtc -o blob.S -O asm device.dts
は、デバイスツリーのソース device.dts から blob.S ファイルを生成し、パー
ジングまたはプロパティのチェックの間に、何らかのエラーが起こるなら、エ
ラーを印刷 (表示) します。結果のファイルは、アセンブルすることができ、バ
イナリにリンクすることができます。
コマンド:
dtc -o - -O dts -I dtb device.dtb
は、デバイスツリーブロブ (blob) device.dtb のためのデバイスツリーソースを
標準出力に書き込みます。これは、デバイスツリーのデバッグのとき、役に立ち
ます。
コマンド:
dtc -@ -O dtb -I dts -o device.dtb device.dts
は、オーバレイがそれに適用できるように、含まれる __symbols__ ノードでデバ
イスツリーソース device.dts から device.dtb ファイルを生成します。
コマンド:
dtc -@ -O dtb -I dts -o device_overlay.dtbo device_overlay.dts
は、デバイスツリーのソース device_overlay.dts からデバイスツリーのオーバ
レイのための標準の拡張を使用して、device_overlay.dtbo ファイルを生成しま
す。オーバレイがそれに適用できるように __symbols__ ノードが含まれます。
device_overlay.dts の /plugin/; ディレクティブの存在は、それがオーバレイ
で必要な基本的なメタデータも生成するべきであるユーティリティを示します。
互換性
このユーティリティは、elinux.org によって提供されたデバイスツリーコンパイ
ラとの互換であることを目的にしています。現在、それは、FreeBSD と FreeBSD
の開発者によって要求された他のものを構築するために必要な機能のサブセット
を実装しています。
fs 入力形式は、サポートされません。これは、Linux /proc/device-tree、
sysctl によって直接 DTB を公開する代わりに、FreeBSD で見つけられないファ
イルのシステム階層構造からツリーを構築します。
elinux.org ツールによってサポートされた警告とエラーは、文書化されていませ
ん。このツールは、「チェッカ」セクションで説明された警告をサポートしま
す。
関連項目
fdt(4)
規格
このツールによって理解されているデバイスツリー形式は、「バグ」セクション
で注記されることを除いて、elinux.org ツールがある互換性のための次の例外
で、Power.org Standard for Embedded Power Architecture Platform Require
ments (組み込まれた Power アーキテクチャのプラットフォームの要件) (ePAPR)
に適合しています:
• 相互参照のターゲットは、仕様でノード名であると定義されるますが、実際
は、ラベルです。
/include/ ディレクティブは、標準の一部ではありませんが、それが elinux.org
ツールと互換性のセマンティックスで実装されます。それは、ファイルの先頭の
レベルに現れなければならず、新しいルート定義をインポートします。その含有
物のうちのすべてを加えて、ファイルが複数のルートを含んでいるなら、それら
は、マージされます。2 番目に存在するが、最初にインポートされない、すべて
のノード。両方で現れるものは、何でも、最初からそれらを置き換え、2 番目の
プロパティと再帰的にマージされているプロパティの子供ノードで再帰的にマー
ジされます。
歴史
dtc ツールは、FreeBSD 9.0 ではじめて登場しました。ツールのこのバージョン
は、FreeBSD 10.0 ではじめて登場しました。
作者
dtc は、David T. Chisnall によって書かれました。いくつかの機能は、後で
Kyle Evans によって追加されました。
注: ツールと作者が、同じイニシャルを共有するという事実は、完全に偶然で
す。
バグ
デバイスツリーコンパイラは、まだ次の機能をサポートしていません:
• プロパティ値の中央のラベル。これは、アセンブリ出力でのみ役に立ちま
す、そこで漠然と役に立つだけであるので、すぐ追加されることは、ありそ
うにありません。
• phandles のためのターゲットとしてラベルではなく、完全なパス。これは、
追加することがあまり難しくありませんが、たぶん、実際、何かにそれが必
要とされるまで、追加されません。
現在のバージョンは、ツリーのセマンティックなチェックの非常に制限された
セットを実行します。これは、将来のバージョンで改善されるでしょう。
FreeBSD 13.2 March 27, 2019 FreeBSD 13.2