特集1-概要
3873 ワード
Introduction
紹介する
The Linux DRM layer contains code intended to support the needs of complex graphics devices, usually containing programmable pipelines well suited to 3D graphics acceleration. Graphics drivers in the kernel may make use of DRM functions to make tasks like memory management, interrupt handling and DMA easier, and provide a uniform interface to applications.
LinuxのDRM層に含まれるコードは、複雑なグラフィックデバイスのニーズをサポートするために使用され、通常は複数のプログラマブルパイプ(pipeline)を含み、3 Dのグラフィック加速に非常に適している.カーネルのグラフィックドライバでは、メモリ管理、割り込み処理、DMAなどのタスクをより容易にし、統一されたアプリケーションインタフェースを提供するDRM関数を使用できます.
A note on versions: this guide covers features found in the DRM tree, including the TTM memory manager, output configuration and mode setting, and the new vblank internals, in addition to all the regular features found in current kernels.
バージョンノート:このガイドではDRM treeの機能について説明します.現在のカーネルの一般的な機能に加えて、TTMのメモリマネージャ、出力構成、モード設定、新しいVBLANK internalsも含まれています.
[Insert diagram of typical DRM stack here]
Style Guidelines
スタイルルール
For consistency this documentation uses American English. Abbreviations are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so on. To aid in reading, documentations make full use of the markup characters kerneldoc provides: @parameter for function parameters, @member for structure members, &structure to reference structures and function() for functions. These all get automatically hyperlinked if kerneldoc for the referenced objects exists. When referencing entries in function vtables please use ->vfunc(). Note that kerneldoc does not support referencing struct members directly, so please add a reference to the vtable struct somewhere in the same paragraph or at least section.
このドキュメントはアメリカ英語を使用しています.略語は大文字で、例えばDRM、KMS、IOCTL、CRTCなどです.読みやすいように、本文で使用するkerneldocが提供するタグ文字:@parameterを関数パラメータとし、@memberを構造メンバーとし、&structureは構造を参照し、function()は関数を表す.参照するオブジェクトkerneldocが存在する場合、これらのタグは自動的にリンクされます.関数vtablesのエントリを参照する場合は、->vfunc()を使用します.kerneldocでは、構造体を直接参照するメンバーはサポートされていません.vtable構造への参照を同じ段落または少なくとも同じセクションに追加してください.
Except in special situations (to separate locked from unlocked variants) locking requirements for functions aren’t documented in the kerneldoc. Instead locking should be check at runtime using e.g.
特殊な場合(locked変数とunlocked変数を区別する)を除く関数のlockingはkerneldocに記録されていないことを要求する.ただし、lockingは実行時にチェックする必要があります(例えばwarn_on!mutex_is_locked(...)).ファイルを無視することは、実行時のノイズよりも多くの価値を提供しやすいためです.lockingルールが変更されるとruntimeチェックは更新され、正しい確率が増加します.ドキュメントでは、lockingルールは、関連構造で説明する必要があります.または、lockが何を保護するか、データフィールドがどのロックを保護する必要があるか、または両方を保護する必要があるかをコメントで説明します.
Functions which have a non-
void以外の戻り値を持つ関数には、異なる場合に望ましい戻り値とその意味を説明する「Returns」という段落があるはずです.このセクションの名前をすべて大文字にするか、コロンで終わるかはまだ要求されていません.ファイルのローカルスタイルと一致します.他の一般的な部分は「Notes」と命名され、dangerousとtrickyのケース情報を記述し、「FIXME」の場所はインタフェースがクリーンアップできることを示しています.
紹介する
The Linux DRM layer contains code intended to support the needs of complex graphics devices, usually containing programmable pipelines well suited to 3D graphics acceleration. Graphics drivers in the kernel may make use of DRM functions to make tasks like memory management, interrupt handling and DMA easier, and provide a uniform interface to applications.
LinuxのDRM層に含まれるコードは、複雑なグラフィックデバイスのニーズをサポートするために使用され、通常は複数のプログラマブルパイプ(pipeline)を含み、3 Dのグラフィック加速に非常に適している.カーネルのグラフィックドライバでは、メモリ管理、割り込み処理、DMAなどのタスクをより容易にし、統一されたアプリケーションインタフェースを提供するDRM関数を使用できます.
A note on versions: this guide covers features found in the DRM tree, including the TTM memory manager, output configuration and mode setting, and the new vblank internals, in addition to all the regular features found in current kernels.
バージョンノート:このガイドではDRM treeの機能について説明します.現在のカーネルの一般的な機能に加えて、TTMのメモリマネージャ、出力構成、モード設定、新しいVBLANK internalsも含まれています.
[Insert diagram of typical DRM stack here]
Style Guidelines
スタイルルール
For consistency this documentation uses American English. Abbreviations are written as all-uppercase, for example: DRM, KMS, IOCTL, CRTC, and so on. To aid in reading, documentations make full use of the markup characters kerneldoc provides: @parameter for function parameters, @member for structure members, &structure to reference structures and function() for functions. These all get automatically hyperlinked if kerneldoc for the referenced objects exists. When referencing entries in function vtables please use ->vfunc(). Note that kerneldoc does not support referencing struct members directly, so please add a reference to the vtable struct somewhere in the same paragraph or at least section.
このドキュメントはアメリカ英語を使用しています.略語は大文字で、例えばDRM、KMS、IOCTL、CRTCなどです.読みやすいように、本文で使用するkerneldocが提供するタグ文字:@parameterを関数パラメータとし、@memberを構造メンバーとし、&structureは構造を参照し、function()は関数を表す.参照するオブジェクトkerneldocが存在する場合、これらのタグは自動的にリンクされます.関数vtablesのエントリを参照する場合は、->vfunc()を使用します.kerneldocでは、構造体を直接参照するメンバーはサポートされていません.vtable構造への参照を同じ段落または少なくとも同じセクションに追加してください.
Except in special situations (to separate locked from unlocked variants) locking requirements for functions aren’t documented in the kerneldoc. Instead locking should be check at runtime using e.g.
WARN_ON(!mutex_is_locked(...));
. Since it’s much easier to ignore documentation than runtime noise this provides more value. And on top of that runtime checks do need to be updated when the locking rules change, increasing the chances that they’re correct. Within the documentation the locking rules should be explained in the relevant structures: Either in the comment for the lock explaining what it protects, or data fields need a note about which lock protects them, or both. 特殊な場合(locked変数とunlocked変数を区別する)を除く関数のlockingはkerneldocに記録されていないことを要求する.ただし、lockingは実行時にチェックする必要があります(例えばwarn_on!mutex_is_locked(...)).ファイルを無視することは、実行時のノイズよりも多くの価値を提供しやすいためです.lockingルールが変更されるとruntimeチェックは更新され、正しい確率が増加します.ドキュメントでは、lockingルールは、関連構造で説明する必要があります.または、lockが何を保護するか、データフィールドがどのロックを保護する必要があるか、または両方を保護する必要があるかをコメントで説明します.
Functions which have a non-
void
return value should have a section called “Returns” explaining the expected return values in different cases and their meanings. Currently there’s no consensus whether that section name should be all upper-case or not, and whether it should end in a colon or not. Go with the file-local style. Other common section names are “Notes” with information for dangerous or tricky corner cases, and “FIXME” where the interface could be cleaned up. void以外の戻り値を持つ関数には、異なる場合に望ましい戻り値とその意味を説明する「Returns」という段落があるはずです.このセクションの名前をすべて大文字にするか、コロンで終わるかはまだ要求されていません.ファイルのローカルスタイルと一致します.他の一般的な部分は「Notes」と命名され、dangerousとtrickyのケース情報を記述し、「FIXME」の場所はインタフェースがクリーンアップできることを示しています.