요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. _vkms:
==========================================
drm/vkms Virtual Kernel Modesetting
==========================================
.. kernel-doc:: drivers/gpu/drm/vkms/vkms_drv.c
:doc: vkms (Virtual Kernel Modesetting)
Setup
=====
The VKMS driver can be setup with the following steps:
To check if VKMS is loaded, run::
lsmod | grep vkms
This should list the VKMS driver. If no output is obtained, then
you need to enable and/or load the VKMS driver.
Ensure that the VKMS driver has been set as a loadable module in your
kernel config file. Do::
make nconfig
Go to `Device Drivers> Graphics support`
Enable `Virtual KMS (EXPERIMENTAL)`
Compile and build the kernel for the changes to get reflected.
Now, to load the driver, use::
sudo modprobe vkms
On running the lsmod command now, the VKMS driver will appear listed.
You can also observe the driver being loaded in the dmesg logs.
The VKMS driver has optional features to simulate different kinds of hardware,
which are exposed as module options. You can use the `modinfo` command
to see the module options for vkms::
modinfo vkms
Module options are helpful when testing, and enabling modules
can be done while loading vkms. For example, to load vkms with cursor enabled,
use::
sudo modprobe vkms enable_cursor=1
To disable the driver, use ::
sudo modprobe -r vkms
Testing With IGT
================
The IGT GPU Tools is a test suite used specifically for debugging and
development of the DRM drivers.
The IGT Tools can be installed from
`here <https://gitlab.freedesktop.org/drm/igt-gpu-tools>`_ .
The tests need to be run without a compositor, so you need to switch to text
only mode. You can do this by::
sudo systemctl isolate multi-user.target
To return to graphical mode, do::
sudo systemctl isolate graphical.target
Once you are in text only mode, you can run tests using the --device switch
or IGT_DEVICE variable to specify the device filter for the driver we want
to test. IGT_DEVICE can also be used with the run-test.sh script to run the
tests for a specific driver::
sudo ./build/tests/<name of test> --device "sys:/sys/devices/platform/vkms"
sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/<name of test>
sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./scripts/run-tests.sh -t <name of test>
For example, to test the functionality of the writeback library,
we can run the kms_writeback test::
sudo ./build/tests/kms_writeback --device "sys:/sys/devices/platform/vkms"
sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/kms_writeback
sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./scripts/run-tests.sh -t kms_writeback
You can also run subtests if you do not want to run the entire test::
sudo ./build/tests/kms_flip --run-subtest basic-plain-flip --device "sys:/sys/devices/platform/vkms"
sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/kms_flip --run-subtest basic-plain-flip
Testing With KUnit
==================
KUnit (Kernel unit testing framework) provides a common framework for unit tests
within the Linux kernel.
More information in ../dev-tools/kunit/index.rst .
To run the VKMS KUnit tests::
tools/testing/kunit/kunit.py run --kunitconfig=drivers/gpu/drm/vkms/tests
TODO
====
If you want to do any of the items listed below, please share your interest
with VKMS maintainers.
IGT better support
------------------
Debugging:
- kms_plane: some test cases are failing due to timeout on capturing CRC;
Virtual hardware (vblank-less) mode:
- VKMS already has support for vblanks simulated via hrtimers, which can be
tested with kms_flip test; in some way, we can say that VKMS already mimics
the real hardware vblank. However, we also have virtual hardware that does
not support vblank interrupt and completes page_flip events right away; in
this case, compositor developers may end up creating a busy loop on virtual
hardware. It would be useful to support Virtual Hardware behavior in VKMS
because this can help compositor developers to test their features in
multiple scenarios.
Add Plane Features
------------------
There's lots of plane features we could add support for:
- Add background color KMS property[Good to get started].
- Scaling.
- Additional buffer formats. Low/high bpp RGB formats would be interesting
[Good to get started].
- Async updates (currently only possible on cursor plane using the legacy
cursor api).
For all of these, we also want to review the igt test coverage and make sure
all relevant igt testcases work on vkms. They are good options for internship
project.
Runtime Configuration
---------------------
We want to be able to reconfigure vkms instance without having to reload the
module. Use/Test-cases:
- Hotplug/hotremove connectors on the fly (to be able to test DP MST handling
of compositors).
- Configure planes/crtcs/connectors (we'd need some code to have more than 1 of
them first).
- Change output configuration: Plug/unplug screens, change EDID, allow changing
the refresh rate.
The currently proposed solution is to expose vkms configuration through
configfs. All existing module options should be supported through configfs
too.
Writeback support
-----------------
- The writeback and CRC capture operations share the use of composer_enabled
boolean to ensure vblanks. Probably, when these operations work together,
composer_enabled needs to refcounting the composer state to proper work.
[Good to get started]
- Add support for cloned writeback outputs and related test cases using a
cloned output in the IGT kms_writeback.
- As a v4l device. This is useful for debugging compositors on special vkms
configurations, so that developers see what's really going on.
Output Features
---------------
- Variable refresh rate/freesync support. This probably needs prime buffer
sharing support, so that we can use vgem fences to simulate rendering in
testing. Also needs support to specify the EDID.
- Add support for link status, so that compositors can validate their runtime
fallbacks when e.g. a Display Port link goes bad.
CRC API Improvements
--------------------
- Optimize CRC computation ``compute_crc()`` and plane blending ``blend()``
Atomic Check using eBPF
-----------------------
Atomic drivers have lots of restrictions which are not exposed to userspace in
any explicit form through e.g. possible property values. Userspace can only
inquiry about these limits through the atomic IOCTL, possibly using the
TEST_ONLY flag. Trying to add configurable code for all these limits, to allow
compositors to be tested against them, would be rather futile exercise. Instead
we could add support for eBPF to validate any kind of atomic state, and
implement a library of different restrictions.
This needs a bunch of features (plane compositing, multiple outputs, ...)
enabled already to make sense.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
VKMS 설정·module option과 load/unload
1-53`drm/vkms`는 Virtual Kernel Modesetting driver입니다. 전체 개요는 `drivers/gpu/drm/vkms/vkms_drv.c`의 `vkms (Virtual Kernel Modesetting)` kernel-doc에서 가져옵니다.
먼저 `lsmod | grep vkms`로 VKMS가 load됐는지 확인합니다. 결과가 없으면 kernel config에서 VKMS를 enable하거나 module을 load해야 합니다. `make nconfig`를 실행하고 `Device Drivers > Graphics support`로 이동해 `Virtual KMS (EXPERIMENTAL)`을 활성화한 뒤 kernel을 compile·build합니다.
Driver는 `sudo modprobe vkms`로 load합니다. 이후 `lsmod` 목록과 dmesg log에서 확인할 수 있습니다. VKMS는 여러 hardware 유형을 흉내 내는 optional feature를 module option으로 노출합니다. `modinfo vkms`로 option을 확인합니다.
시험 시 module을 load하면서 option을 활성화할 수 있습니다. Cursor를 켜려면 `sudo modprobe vkms enable_cursor=1`을 사용합니다. Driver를 disable하려면 `sudo modprobe -r vkms`를 실행합니다.
Build 설정과 module 생명주기입니다.
Kernel config에서 module 확인까지의 순서입니다.
.. _vkms:
==========================================
drm/vkms Virtual Kernel Modesetting
==========================================
.. kernel-doc:: drivers/gpu/drm/vkms/vkms_drv.c
:doc: vkms (Virtual Kernel Modesetting)
Setup
=====
The VKMS driver can be setup with the following steps:
To check if VKMS is loaded, run::
lsmod | grep vkms
This should list the VKMS driver. If no output is obtained, then
you need to enable and/or load the VKMS driver.
Ensure that the VKMS driver has been set as a loadable module in your
kernel config file. Do::
make nconfig
Go to `Device Drivers> Graphics support`
Enable `Virtual KMS (EXPERIMENTAL)`
Compile and build the kernel for the changes to get reflected.
Now, to load the driver, use::
sudo modprobe vkms
On running the lsmod command now, the VKMS driver will appear listed.
You can also observe the driver being loaded in the dmesg logs.
The VKMS driver has optional features to simulate different kinds of hardware,
which are exposed as module options. You can use the `modinfo` command
to see the module options for vkms::
modinfo vkms
Module options are helpful when testing, and enabling modules
can be done while loading vkms. For example, to load vkms with cursor enabled,
use::
sudo modprobe vkms enable_cursor=1
To disable the driver, use ::
sudo modprobe -r vkms
IGT로 VKMS 시험
54-91IGT GPU Tools는 DRM driver debugging과 development를 위한 test suite이며 `https://gitlab.freedesktop.org/drm/igt-gpu-tools`에서 설치할 수 있습니다.
Test는 compositor 없이 실행해야 하므로 `sudo systemctl isolate multi-user.target`으로 text-only mode로 전환합니다. Graphical mode로 돌아가려면 `sudo systemctl isolate graphical.target`을 실행합니다.
Text-only mode에서는 `--device` switch 또는 `IGT_DEVICE` variable로 시험할 driver의 device filter를 지정합니다. 직접 test binary를 실행하거나 `run-tests.sh`에 환경 변수를 전달할 수 있습니다.
일반 형식은 `sudo ./build/tests/<name of test> --device "sys:/sys/devices/platform/vkms"`, `sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/<name of test>`, `sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./scripts/run-tests.sh -t <name of test>`입니다.
Writeback library를 시험하려면 위 세 방식으로 `kms_writeback`을 실행합니다. Test 전체가 필요 없으면 `kms_flip --run-subtest basic-plain-flip`처럼 `--run-subtest`를 사용하며 `--device` 또는 `IGT_DEVICE`를 함께 지정합니다.
같은 VKMS device filter를 여러 runner에 적용합니다.
Compositor를 멈추고 virtual device만 대상으로 실행합니다.
Testing With IGT
================
The IGT GPU Tools is a test suite used specifically for debugging and
development of the DRM drivers.
The IGT Tools can be installed from
`here <https://gitlab.freedesktop.org/drm/igt-gpu-tools>`_ .
The tests need to be run without a compositor, so you need to switch to text
only mode. You can do this by::
sudo systemctl isolate multi-user.target
To return to graphical mode, do::
sudo systemctl isolate graphical.target
Once you are in text only mode, you can run tests using the --device switch
or IGT_DEVICE variable to specify the device filter for the driver we want
to test. IGT_DEVICE can also be used with the run-test.sh script to run the
tests for a specific driver::
sudo ./build/tests/<name of test> --device "sys:/sys/devices/platform/vkms"
sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/<name of test>
sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./scripts/run-tests.sh -t <name of test>
For example, to test the functionality of the writeback library,
we can run the kms_writeback test::
sudo ./build/tests/kms_writeback --device "sys:/sys/devices/platform/vkms"
sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/kms_writeback
sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./scripts/run-tests.sh -t kms_writeback
You can also run subtests if you do not want to run the entire test::
sudo ./build/tests/kms_flip --run-subtest basic-plain-flip --device "sys:/sys/devices/platform/vkms"
sudo IGT_DEVICE="sys:/sys/devices/platform/vkms" ./build/tests/kms_flip --run-subtest basic-plain-flip
KUnit 실행과 TODO 참여
92-108KUnit은 Linux kernel 내부 unit test를 위한 공통 framework이며 자세한 내용은 `../dev-tools/kunit/index.rst`에 있습니다.
VKMS KUnit test는 `tools/testing/kunit/kunit.py run --kunitconfig=drivers/gpu/drm/vkms/tests`로 실행합니다.
아래 TODO 항목 중 하나를 수행하려면 먼저 VKMS maintainer에게 관심과 작업 의사를 공유해야 합니다.
Integration test와 unit test의 도구를 구분합니다.
VKMS 전용 config로 kernel unit test를 구동합니다.
Testing With KUnit
==================
KUnit (Kernel unit testing framework) provides a common framework for unit tests
within the Linux kernel.
More information in ../dev-tools/kunit/index.rst .
To run the VKMS KUnit tests::
tools/testing/kunit/kunit.py run --kunitconfig=drivers/gpu/drm/vkms/tests
TODO
====
If you want to do any of the items listed below, please share your interest
with VKMS maintainers.
IGT 지원·vblank-less mode·plane 기능
109-145IGT 지원 개선 중 debugging 과제로 `kms_plane`의 일부 testcase가 CRC capture timeout 때문에 실패하는 문제가 있습니다.
VKMS는 hrtimer로 vblank를 simulation하며 `kms_flip` test로 시험할 수 있습니다. 이 점에서는 실제 hardware vblank를 흉내 냅니다. 그러나 vblank interrupt를 지원하지 않고 page-flip event를 즉시 완료하는 virtual hardware도 있습니다.
이런 hardware에서 compositor가 busy loop를 만들 수 있으므로 VKMS가 vblank-less virtual hardware 동작도 지원하면 compositor developer가 여러 scenario에서 기능을 시험할 수 있습니다.
추가할 plane 기능은 많습니다. 입문 과제로 적합한 background color KMS property, scaling, 역시 입문에 좋은 low/high bpp RGB 같은 additional buffer format, 현재 legacy cursor API의 cursor plane에서만 가능한 async update가 후보입니다.
모든 기능은 IGT coverage를 함께 검토하고 관련 testcase가 VKMS에서 동작하도록 해야 합니다. Internship project로도 적합합니다.
Virtual hardware가 흉내 낼 동작과 시험 항목입니다.
기능 구현과 IGT coverage를 함께 확장합니다.
IGT better support
------------------
Debugging:
- kms_plane: some test cases are failing due to timeout on capturing CRC;
Virtual hardware (vblank-less) mode:
- VKMS already has support for vblanks simulated via hrtimers, which can be
tested with kms_flip test; in some way, we can say that VKMS already mimics
the real hardware vblank. However, we also have virtual hardware that does
not support vblank interrupt and completes page_flip events right away; in
this case, compositor developers may end up creating a busy loop on virtual
hardware. It would be useful to support Virtual Hardware behavior in VKMS
because this can help compositor developers to test their features in
multiple scenarios.
Add Plane Features
------------------
There's lots of plane features we could add support for:
- Add background color KMS property[Good to get started].
- Scaling.
- Additional buffer formats. Low/high bpp RGB formats would be interesting
[Good to get started].
- Async updates (currently only possible on cursor plane using the legacy
cursor api).
For all of these, we also want to review the igt test coverage and make sure
all relevant igt testcases work on vkms. They are good options for internship
project.
Runtime configfs와 writeback 확장
146-178목표는 module을 reload하지 않고 VKMS instance를 재구성하는 것입니다. Runtime use/test case에는 connector를 동적으로 hotplug·hotremove하여 compositor의 DP MST handling을 시험하는 기능이 있습니다.
Plane, CRTC, connector를 구성할 수 있어야 하며 이를 위해 먼저 각 object를 둘 이상 만드는 code가 필요합니다. Screen plug/unplug, EDID 변경, refresh rate 변경 같은 output configuration도 지원해야 합니다.
현재 제안은 configfs를 통해 VKMS configuration을 노출하는 것입니다. 기존 module option도 모두 configfs에서 설정할 수 있어야 합니다.
Writeback과 CRC capture는 vblank를 보장하려고 `composer_enabled` boolean을 함께 사용합니다. 두 operation이 동시에 동작할 때 올바른 composer state를 유지하려면 이 boolean을 refcount 방식으로 바꿔야 할 가능성이 큽니다. 입문 과제로 적합합니다.
Cloned output을 사용하는 IGT `kms_writeback` testcase와 cloned writeback output 지원을 추가해야 합니다. 또한 V4L device로 노출하면 특별한 VKMS configuration에서 compositor를 debugging할 때 developer가 실제 합성 결과를 볼 수 있습니다.
Reload 없는 구성과 output 관찰 기능입니다.
실행 중인 VKMS instance의 topology를 바꿉니다.
Runtime Configuration
---------------------
We want to be able to reconfigure vkms instance without having to reload the
module. Use/Test-cases:
- Hotplug/hotremove connectors on the fly (to be able to test DP MST handling
of compositors).
- Configure planes/crtcs/connectors (we'd need some code to have more than 1 of
them first).
- Change output configuration: Plug/unplug screens, change EDID, allow changing
the refresh rate.
The currently proposed solution is to expose vkms configuration through
configfs. All existing module options should be supported through configfs
too.
Writeback support
-----------------
- The writeback and CRC capture operations share the use of composer_enabled
boolean to ensure vblanks. Probably, when these operations work together,
composer_enabled needs to refcounting the composer state to proper work.
[Good to get started]
- Add support for cloned writeback outputs and related test cases using a
cloned output in the IGT kms_writeback.
- As a v4l device. This is useful for debugging compositors on special vkms
configurations, so that developers see what's really going on.
Output 기능·CRC 최적화·eBPF atomic check
179-206Output 기능으로 variable refresh rate와 FreeSync를 지원할 수 있습니다. 시험에서 VGEM fence로 rendering을 simulation하려면 PRIME buffer sharing 지원이 필요할 가능성이 크고, EDID 지정 기능도 필요합니다.
Link status도 지원하면 DisplayPort link가 나빠지는 상황 등에서 compositor가 runtime fallback을 올바르게 수행하는지 검증할 수 있습니다.
CRC API 개선 과제는 CRC 계산 함수 `compute_crc()`와 plane blending 함수 `blend()`를 최적화하는 것입니다.
Atomic driver에는 가능한 property value처럼 userspace에 명시적으로 노출되지 않는 제약이 많습니다. Userspace는 `TEST_ONLY` flag를 사용할 수 있는 atomic IOCTL로만 이런 제한을 질의할 수 있습니다.
Compositor 시험을 위해 모든 제한을 configurable code로 하나씩 추가하는 것은 효과가 낮습니다. 대신 어떤 atomic state든 검증할 수 있게 eBPF를 지원하고 여러 제약의 library를 구현할 수 있습니다.
이 기능이 의미 있으려면 plane compositing과 multiple output 같은 여러 기능이 먼저 VKMS에 활성화돼야 합니다.
Timing·link·CRC와 configurable restriction을 다룹니다.
Virtual KMS에 다양한 hardware 제약을 주입합니다.
Output Features
---------------
- Variable refresh rate/freesync support. This probably needs prime buffer
sharing support, so that we can use vgem fences to simulate rendering in
testing. Also needs support to specify the EDID.
- Add support for link status, so that compositors can validate their runtime
fallbacks when e.g. a Display Port link goes bad.
CRC API Improvements
--------------------
- Optimize CRC computation ``compute_crc()`` and plane blending ``blend()``
Atomic Check using eBPF
-----------------------
Atomic drivers have lots of restrictions which are not exposed to userspace in
any explicit form through e.g. possible property values. Userspace can only
inquiry about these limits through the atomic IOCTL, possibly using the
TEST_ONLY flag. Trying to add configurable code for all these limits, to allow
compositors to be tested against them, would be rather futile exercise. Instead
we could add support for eBPF to validate any kind of atomic state, and
implement a library of different restrictions.
This needs a bunch of features (plane compositing, multiple outputs, ...)
enabled already to make sense.
요약·해설
vkms.rst:1-206VKMS 설정, IGT·KUnit 시험과 virtual display 확장 TODO를 설명합니다.
Source와 관련 구현입니다.