专题一-简介

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），非常适合3D的图形加速。在内核的图形驱动程序可以使用DRM函数，使如内存管理、中断处理、DMA等任务变得更加容易，并且提供一个统一的应用程序接口。

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”的地方表示该接口可以被清理。