요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
=============
DRM Internals
=============
This chapter documents DRM internals relevant to driver authors and
developers working to add support for the latest features to existing
drivers.
First, we go over some typical driver initialization requirements, like
setting up command buffers, creating an initial output configuration,
and initializing core services. Subsequent sections cover core internals
in more detail, providing implementation notes and examples.
The DRM layer provides several services to graphics drivers, many of
them driven by the application interfaces it provides through libdrm,
the library that wraps most of the DRM ioctls. These include vblank
event handling, memory management, output management, framebuffer
management, command submission & fencing, suspend/resume support, and
DMA services.
Driver Initialization
=====================
At the core of every DRM driver is a :c:type:`struct drm_driver
<drm_driver>` structure. Drivers typically statically initialize
a drm_driver structure, and then pass it to
drm_dev_alloc() to allocate a device instance. After the
device instance is fully initialized it can be registered (which makes
it accessible from userspace) using drm_dev_register().
The :c:type:`struct drm_driver <drm_driver>` structure
contains static information that describes the driver and features it
supports, and pointers to methods that the DRM core will call to
implement the DRM API. We will first go through the :c:type:`struct
drm_driver <drm_driver>` static information fields, and will
then describe individual operations in details as they get used in later
sections.
Driver Information
------------------
Major, Minor and Patchlevel
~~~~~~~~~~~~~~~~~~~~~~~~~~~
int major; int minor; int patchlevel;
The DRM core identifies driver versions by a major, minor and patch
level triplet. The information is printed to the kernel log at
initialization time and passed to userspace through the
DRM_IOCTL_VERSION ioctl.
The major and minor numbers are also used to verify the requested driver
API version passed to DRM_IOCTL_SET_VERSION. When the driver API
changes between minor versions, applications can call
DRM_IOCTL_SET_VERSION to select a specific version of the API. If the
requested major isn't equal to the driver major, or the requested minor
is larger than the driver minor, the DRM_IOCTL_SET_VERSION call will
return an error. Otherwise the driver's set_version() method will be
called with the requested version.
Name and Description
~~~~~~~~~~~~~~~~~~~~
char \*name; char \*desc; char \*date;
The driver name is printed to the kernel log at initialization time,
used for IRQ registration and passed to userspace through
DRM_IOCTL_VERSION.
The driver description is a purely informative string passed to
userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by
the kernel.
Module Initialization
---------------------
.. kernel-doc:: include/drm/drm_module.h
:doc: overview
Device Instance and Driver Handling
-----------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_drv.c
:doc: driver instance overview
.. kernel-doc:: include/drm/drm_device.h
:internal:
.. kernel-doc:: include/drm/drm_drv.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_drv.c
:export:
Driver Load
-----------
Component Helper Usage
~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: drivers/gpu/drm/drm_drv.c
:doc: component helper usage recommendations
Memory Manager Initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Every DRM driver requires a memory manager which must be initialized at
load time. DRM currently contains two memory managers, the Translation
Table Manager (TTM) and the Graphics Execution Manager (GEM). This
document describes the use of the GEM memory manager only. See ? for
details.
Miscellaneous Device Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Another task that may be necessary for PCI devices during configuration
is mapping the video BIOS. On many devices, the VBIOS describes device
configuration, LCD panel timings (if any), and contains flags indicating
device state. Mapping the BIOS can be done using the pci_map_rom()
call, a convenience function that takes care of mapping the actual ROM,
whether it has been shadowed into memory (typically at address 0xc0000)
or exists on the PCI device in the ROM BAR. Note that after the ROM has
been mapped and any necessary information has been extracted, it should
be unmapped; on many devices, the ROM address decoder is shared with
other BARs, so leaving it mapped could cause undesired behaviour like
hangs or memory corruption.
Managed Resources
-----------------
.. kernel-doc:: drivers/gpu/drm/drm_managed.c
:doc: managed resources
.. kernel-doc:: drivers/gpu/drm/drm_managed.c
:export:
.. kernel-doc:: include/drm/drm_managed.h
:internal:
Open/Close, File Operations and IOCTLs
======================================
.. _drm_driver_fops:
File Operations
---------------
.. kernel-doc:: drivers/gpu/drm/drm_file.c
:doc: file operations
.. kernel-doc:: include/drm/drm_file.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_file.c
:export:
Misc Utilities
==============
Printer
-------
.. kernel-doc:: include/drm/drm_print.h
:doc: print
.. kernel-doc:: include/drm/drm_print.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_print.c
:export:
Utilities
---------
.. kernel-doc:: include/drm/drm_util.h
:doc: drm utils
.. kernel-doc:: include/drm/drm_util.h
:internal:
Unit testing
============
KUnit
-----
KUnit (Kernel unit testing framework) provides a common framework for unit tests
within the Linux kernel.
This section covers the specifics for the DRM subsystem. For general information
about KUnit, please refer to Documentation/dev-tools/kunit/start.rst.
How to run the tests?
~~~~~~~~~~~~~~~~~~~~~
In order to facilitate running the test suite, a configuration file is present
in ``drivers/gpu/drm/tests/.kunitconfig``. It can be used by ``kunit.py`` as
follows:
.. code-block:: bash
$ ./tools/testing/kunit/kunit.py run --kunitconfig=drivers/gpu/drm/tests \
--kconfig_add CONFIG_VIRTIO_UML=y \
--kconfig_add CONFIG_UML_PCI_OVER_VIRTIO=y
.. note::
The configuration included in ``.kunitconfig`` should be as generic as
possible.
``CONFIG_VIRTIO_UML`` and ``CONFIG_UML_PCI_OVER_VIRTIO`` are not
included in it because they are only required for User Mode Linux.
KUnit Coverage Rules
~~~~~~~~~~~~~~~~~~~~
KUnit support is gradually added to the DRM framework and helpers. There's no
general requirement for the framework and helpers to have KUnit tests at the
moment. However, patches that are affecting a function or helper already
covered by KUnit tests must provide tests if the change calls for one.
Legacy Support Code
===================
The section very briefly covers some of the old legacy support code
which is only used by old DRM drivers which have done a so-called
shadow-attach to the underlying device instead of registering as a real
driver. This also includes some of the old generic buffer management and
command submission code. Do not use any of this in new and modern
drivers.
Legacy Suspend/Resume
---------------------
The DRM core provides some suspend/resume code, but drivers wanting full
suspend/resume support should provide save() and restore() functions.
These are called at suspend, hibernate, or resume time, and should
perform any state save or restore required by your device across suspend
or hibernate states.
int (\*suspend) (struct drm_device \*, pm_message_t state); int
(\*resume) (struct drm_device \*);
Those are legacy suspend and resume methods which *only* work with the
legacy shadow-attach driver registration functions. New driver should
use the power management interface provided by their bus type (usually
through the :c:type:`struct device_driver <device_driver>`
dev_pm_ops) and set these methods to NULL.
Legacy DMA Services
-------------------
This should cover how DMA mapping etc. is supported by the core. These
functions are deprecated and should not be used.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
DRM 내부 구조의 범위
1-20이 장은 DRM driver 작성자와 기존 driver에 최신 기능 지원을 추가하는 개발자에게 필요한 DRM 내부 구조를 문서화합니다.
먼저 command buffer 설정, 초기 output configuration 생성, core service 초기화처럼 일반적인 driver 초기화 요구사항을 살펴봅니다. 뒤의 절에서는 구현 참고사항과 예제를 제공하면서 core 내부 구조를 더 자세히 설명합니다.
DRM layer는 graphics driver에 여러 service를 제공합니다. 그중 많은 service는 DRM ioctl 대부분을 감싸는 library인 `libdrm`을 통해 제공되는 application interface에 의해 구동됩니다. 여기에는 vblank event 처리, memory·output·framebuffer 관리, command submission과 fencing, suspend/resume 지원, DMA service가 포함됩니다.
이 장이 초기화 과정과 함께 다루는 graphics driver 공통 기능입니다.
=============
DRM Internals
=============
This chapter documents DRM internals relevant to driver authors and
developers working to add support for the latest features to existing
drivers.
First, we go over some typical driver initialization requirements, like
setting up command buffers, creating an initial output configuration,
and initializing core services. Subsequent sections cover core internals
in more detail, providing implementation notes and examples.
The DRM layer provides several services to graphics drivers, many of
them driven by the application interfaces it provides through libdrm,
the library that wraps most of the DRM ioctls. These include vblank
event handling, memory management, output management, framebuffer
management, command submission & fencing, suspend/resume support, and
DMA services.
DRM driver와 device instance 초기화
21-38모든 DRM driver의 중심에는 `struct drm_driver` 구조체가 있습니다. Driver는 보통 `drm_driver` 구조체를 정적으로 초기화하고 이를 `drm_dev_alloc()`에 전달해 device instance를 할당합니다. Device instance의 초기화가 모두 끝나면 `drm_dev_register()`로 등록하며, 이때부터 userspace에서 접근할 수 있습니다.
`struct drm_driver`에는 driver와 지원 기능을 설명하는 정적 정보, 그리고 DRM core가 DRM API를 구현하기 위해 호출할 method pointer가 들어 있습니다. 이 문서는 먼저 정적 정보 field를 설명하고, 뒤 절에서 실제로 사용되는 시점에 각 operation을 자세히 다룹니다.
Userspace 접근은 모든 instance 초기화가 끝난 뒤에만 허용됩니다.
Driver Initialization
=====================
At the core of every DRM driver is a :c:type:`struct drm_driver
<drm_driver>` structure. Drivers typically statically initialize
a drm_driver structure, and then pass it to
drm_dev_alloc() to allocate a device instance. After the
device instance is fully initialized it can be registered (which makes
it accessible from userspace) using drm_dev_register().
The :c:type:`struct drm_driver <drm_driver>` structure
contains static information that describes the driver and features it
supports, and pointers to methods that the DRM core will call to
implement the DRM API. We will first go through the :c:type:`struct
drm_driver <drm_driver>` static information fields, and will
then describe individual operations in details as they get used in later
sections.
Driver version, name, description
39-71Version field는 `int major; int minor; int patchlevel;`입니다. DRM core는 이 major·minor·patch level 세 값으로 driver version을 식별합니다. 초기화할 때 kernel log에 출력하고 `DRM_IOCTL_VERSION` ioctl을 통해 userspace에도 전달합니다.
Major와 minor는 `DRM_IOCTL_SET_VERSION`으로 요청된 driver API version을 검증하는 데도 사용됩니다. Minor version 사이에서 API가 바뀌면 application은 이 ioctl로 특정 API version을 선택할 수 있습니다. 요청한 major가 driver major와 다르거나 요청 minor가 driver minor보다 크면 오류를 반환합니다. 그 밖의 경우에는 요청 version을 인자로 driver의 `set_version()` method를 호출합니다.
이름과 설명 field는 `char *name; char *desc; char *date;`입니다. Driver name은 초기화 시 kernel log에 출력되고 IRQ 등록에 사용되며 `DRM_IOCTL_VERSION`을 통해 userspace에 전달됩니다. Driver description은 같은 ioctl로 전달되는 순수한 정보 문자열이며 kernel에서는 그 밖의 용도로 사용하지 않습니다.
Version 협상과 userspace 정보 제공에 쓰이는 정적 field입니다.
Driver Information
------------------
Major, Minor and Patchlevel
~~~~~~~~~~~~~~~~~~~~~~~~~~~
int major; int minor; int patchlevel;
The DRM core identifies driver versions by a major, minor and patch
level triplet. The information is printed to the kernel log at
initialization time and passed to userspace through the
DRM_IOCTL_VERSION ioctl.
The major and minor numbers are also used to verify the requested driver
API version passed to DRM_IOCTL_SET_VERSION. When the driver API
changes between minor versions, applications can call
DRM_IOCTL_SET_VERSION to select a specific version of the API. If the
requested major isn't equal to the driver major, or the requested minor
is larger than the driver minor, the DRM_IOCTL_SET_VERSION call will
return an error. Otherwise the driver's set_version() method will be
called with the requested version.
Name and Description
~~~~~~~~~~~~~~~~~~~~
char \*name; char \*desc; char \*date;
The driver name is printed to the kernel log at initialization time,
used for IRQ registration and passed to userspace through
DRM_IOCTL_VERSION.
The driver description is a purely informative string passed to
userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by
the kernel.
Module·device lifecycle와 memory manager
72-110Module 초기화 절은 `include/drm/drm_module.h`의 `overview` 문서 블록을 포함합니다. Device instance와 driver handling 절은 `drivers/gpu/drm/drm_drv.c`의 `driver instance overview`, `include/drm/drm_device.h`와 `include/drm/drm_drv.h`의 내부 문서, 그리고 `drm_drv.c`의 exported API를 결합합니다.
Driver load의 component helper 절은 `drivers/gpu/drm/drm_drv.c`에서 `component helper usage recommendations` 문서 블록을 가져와 component helper를 사용할 때의 권장사항을 제공합니다.
모든 DRM driver에는 load 시 초기화해야 하는 memory manager가 필요합니다. DRM에는 Translation Table Manager(TTM)와 Graphics Execution Manager(GEM) 두 memory manager가 있습니다. 이 문서는 GEM 사용만 설명하며, 상세 참조는 원문에도 해소되지 않은 `?`로 남아 있습니다.
원문이 조합하는 lifecycle 문서와 선택 범위입니다.
Module Initialization
---------------------
.. kernel-doc:: include/drm/drm_module.h
:doc: overview
Device Instance and Driver Handling
-----------------------------------
.. kernel-doc:: drivers/gpu/drm/drm_drv.c
:doc: driver instance overview
.. kernel-doc:: include/drm/drm_device.h
:internal:
.. kernel-doc:: include/drm/drm_drv.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_drv.c
:export:
Driver Load
-----------
Component Helper Usage
~~~~~~~~~~~~~~~~~~~~~~
.. kernel-doc:: drivers/gpu/drm/drm_drv.c
:doc: component helper usage recommendations
Memory Manager Initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Every DRM driver requires a memory manager which must be initialized at
load time. DRM currently contains two memory managers, the Translation
Table Manager (TTM) and the Graphics Execution Manager (GEM). This
document describes the use of the GEM memory manager only. See ? for
details.
VBIOS mapping과 managed resource
111-137PCI device 구성 중에는 video BIOS를 mapping해야 할 수도 있습니다. 많은 device에서 VBIOS는 device configuration과 LCD panel timing을 설명하고 device state를 나타내는 flag를 포함합니다. `pci_map_rom()`은 실제 ROM이 memory에 shadow되어 있든, 보통 `0xc0000` 주소에 있든, PCI device의 ROM BAR에 있든 관계없이 mapping을 처리하는 편의 함수입니다.
ROM에서 필요한 정보를 추출한 뒤에는 반드시 unmap해야 합니다. 많은 device에서 ROM address decoder를 다른 BAR와 공유하므로 mapping을 남겨 두면 hang이나 memory corruption 같은 원치 않는 동작이 발생할 수 있습니다.
Managed resource 절은 `drivers/gpu/drm/drm_managed.c`의 `managed resources` 문서와 exported API, `include/drm/drm_managed.h`의 내부 문서를 결합합니다.
ROM decoder 공유로 인한 장애를 피하기 위한 순서입니다.
구현 설명, exported API, 내부 declaration의 출처입니다.
Miscellaneous Device Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Another task that may be necessary for PCI devices during configuration
is mapping the video BIOS. On many devices, the VBIOS describes device
configuration, LCD panel timings (if any), and contains flags indicating
device state. Mapping the BIOS can be done using the pci_map_rom()
call, a convenience function that takes care of mapping the actual ROM,
whether it has been shadowed into memory (typically at address 0xc0000)
or exists on the PCI device in the ROM BAR. Note that after the ROM has
been mapped and any necessary information has been extracted, it should
be unmapped; on many devices, the ROM address decoder is shared with
other BARs, so leaving it mapped could cause undesired behaviour like
hangs or memory corruption.
Managed Resources
-----------------
.. kernel-doc:: drivers/gpu/drm/drm_managed.c
:doc: managed resources
.. kernel-doc:: drivers/gpu/drm/drm_managed.c
:export:
.. kernel-doc:: include/drm/drm_managed.h
:internal:
File operations, IOCTL, print와 utility API
138-179Open/close, file operation, ioctl 절은 `_drm_driver_fops` anchor 아래에서 DRM file interface를 문서화합니다. `drivers/gpu/drm/drm_file.c`의 `file operations` 설명과 exported API, `include/drm/drm_file.h`의 내부 declaration을 함께 포함합니다.
Printer 절은 `include/drm/drm_print.h`의 `print` 개요와 내부 interface, `drivers/gpu/drm/drm_print.c`의 exported API를 결합합니다. Utilities 절은 `include/drm/drm_util.h`의 `drm utils` 개요와 내부 interface를 포함합니다.
DRM file lifecycle, logging, 공통 helper 문서의 source입니다.
Open/Close, File Operations and IOCTLs
======================================
.. _drm_driver_fops:
File Operations
---------------
.. kernel-doc:: drivers/gpu/drm/drm_file.c
:doc: file operations
.. kernel-doc:: include/drm/drm_file.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_file.c
:export:
Misc Utilities
==============
Printer
-------
.. kernel-doc:: include/drm/drm_print.h
:doc: print
.. kernel-doc:: include/drm/drm_print.h
:internal:
.. kernel-doc:: drivers/gpu/drm/drm_print.c
:export:
Utilities
---------
.. kernel-doc:: include/drm/drm_util.h
:doc: drm utils
.. kernel-doc:: include/drm/drm_util.h
:internal:
DRM KUnit 실행과 coverage 규칙
180-218KUnit(Kernel unit testing framework)은 Linux kernel 내부 unit test에 공통 framework를 제공합니다. 이 절은 DRM subsystem에만 해당하는 세부사항을 다루며, 일반적인 KUnit 정보는 `Documentation/dev-tools/kunit/start.rst`를 참조합니다.
Test suite 실행을 쉽게 하도록 `drivers/gpu/drm/tests/.kunitconfig` configuration file이 제공됩니다. 다음과 같이 `kunit.py`에 전달합니다.
$ ./tools/testing/kunit/kunit.py run --kunitconfig=drivers/gpu/drm/tests \
--kconfig_add CONFIG_VIRTIO_UML=y \
--kconfig_add CONFIG_UML_PCI_OVER_VIRTIO=y`.kunitconfig`에 포함되는 설정은 가능한 한 일반적이어야 합니다. `CONFIG_VIRTIO_UML`과 `CONFIG_UML_PCI_OVER_VIRTIO`는 User Mode Linux에서만 필요하므로 file에 포함하지 않고 command line의 `--kconfig_add`로 추가합니다.
DRM framework와 helper에는 KUnit 지원이 점진적으로 추가되고 있습니다. 현재 모든 framework와 helper가 KUnit test를 가져야 한다는 일반 요구사항은 없습니다. 다만 이미 KUnit test가 다루는 함수나 helper에 영향을 주는 patch는 변경 내용상 test가 필요하다면 반드시 test를 제공해야 합니다.
재사용 가능한 기본 config와 변경별 test 책임을 구분합니다.
Unit testing
============
KUnit
-----
KUnit (Kernel unit testing framework) provides a common framework for unit tests
within the Linux kernel.
This section covers the specifics for the DRM subsystem. For general information
about KUnit, please refer to Documentation/dev-tools/kunit/start.rst.
How to run the tests?
~~~~~~~~~~~~~~~~~~~~~
In order to facilitate running the test suite, a configuration file is present
in ``drivers/gpu/drm/tests/.kunitconfig``. It can be used by ``kunit.py`` as
follows:
.. code-block:: bash
$ ./tools/testing/kunit/kunit.py run --kunitconfig=drivers/gpu/drm/tests \
--kconfig_add CONFIG_VIRTIO_UML=y \
--kconfig_add CONFIG_UML_PCI_OVER_VIRTIO=y
.. note::
The configuration included in ``.kunitconfig`` should be as generic as
possible.
``CONFIG_VIRTIO_UML`` and ``CONFIG_UML_PCI_OVER_VIRTIO`` are not
included in it because they are only required for User Mode Linux.
KUnit Coverage Rules
~~~~~~~~~~~~~~~~~~~~
KUnit support is gradually added to the DRM framework and helpers. There's no
general requirement for the framework and helpers to have KUnit tests at the
moment. However, patches that are affecting a function or helper already
covered by KUnit tests must provide tests if the change calls for one.
Legacy shadow-attach, suspend/resume와 DMA
219-250이 절은 실제 driver로 등록하지 않고 underlying device에 이른바 shadow-attach를 수행했던 오래된 DRM driver만 사용하는 legacy 지원 code를 간단히 설명합니다. 여기에는 오래된 generic buffer management와 command submission code도 포함됩니다. 새롭고 현대적인 driver에서는 어느 것도 사용하면 안 됩니다.
DRM core가 일부 suspend/resume code를 제공하지만 완전한 suspend/resume 지원이 필요한 legacy driver는 `save()`와 `restore()` 함수를 제공해야 합니다. 이 함수들은 suspend, hibernate, resume 시 호출되어 device가 suspend 또는 hibernate state를 거치는 동안 필요한 state를 저장하거나 복원합니다.
int (*suspend)(struct drm_device *, pm_message_t state);
int (*resume)(struct drm_device *);이 `suspend`와 `resume` method는 legacy shadow-attach driver 등록 함수에서만 작동합니다. 새 driver는 bus type이 제공하는 power management interface, 보통 `struct device_driver`의 `dev_pm_ops`를 사용하고 이 legacy method들은 `NULL`로 설정해야 합니다.
Legacy DMA service는 core의 DMA mapping 지원을 다루지만 해당 함수들은 deprecated 상태이므로 사용하면 안 됩니다.
새 driver에서 지켜야 할 전환 원칙입니다.
Legacy Support Code
===================
The section very briefly covers some of the old legacy support code
which is only used by old DRM drivers which have done a so-called
shadow-attach to the underlying device instead of registering as a real
driver. This also includes some of the old generic buffer management and
command submission code. Do not use any of this in new and modern
drivers.
Legacy Suspend/Resume
---------------------
The DRM core provides some suspend/resume code, but drivers wanting full
suspend/resume support should provide save() and restore() functions.
These are called at suspend, hibernate, or resume time, and should
perform any state save or restore required by your device across suspend
or hibernate states.
int (\*suspend) (struct drm_device \*, pm_message_t state); int
(\*resume) (struct drm_device \*);
Those are legacy suspend and resume methods which *only* work with the
legacy shadow-attach driver registration functions. New driver should
use the power management interface provided by their bus type (usually
through the :c:type:`struct device_driver <device_driver>`
dev_pm_ops) and set these methods to NULL.
Legacy DMA Services
-------------------
This should cover how DMA mapping etc. is supported by the core. These
functions are deprecated and should not be used.
요약·해설
drm-internals.rst:1-250DRM driver 작성자가 device를 할당·초기화·등록하는 흐름부터 version 협상, module/device API, GEM memory manager, VBIOS mapping, managed resource, file operation, print/util helper, KUnit, legacy code 전환까지 확인하는 내부 구조 안내서입니다. 원문의 17개 kernel-doc source와 selector, KUnit command, function·ioctl·field 이름을 그대로 보존합니다.
구현 단계별로 이 문서에서 찾아야 할 절입니다.