요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
===============
GPU Debugging
===============
General Debugging Options
=========================
The DebugFS section provides documentation on a number files to aid in debugging
issues on the GPU.
GPUVM Debugging
===============
To aid in debugging GPU virtual memory related problems, the driver supports a
number of options module parameters:
`vm_fault_stop` - If non-0, halt the GPU memory controller on a GPU page fault.
`vm_update_mode` - If non-0, use the CPU to update GPU page tables rather than
the GPU.
Decoding a GPUVM Page Fault
===========================
If you see a GPU page fault in the kernel log, you can decode it to figure
out what is going wrong in your application. A page fault in your kernel
log may look something like this:
::
[gfxhub0] no-retry page fault (src_id:0 ring:24 vmid:3 pasid:32777, for process glxinfo pid 2424 thread glxinfo:cs0 pid 2425)
in page starting at address 0x0000800102800000 from IH client 0x1b (UTCL2)
VM_L2_PROTECTION_FAULT_STATUS:0x00301030
Faulty UTCL2 client ID: TCP (0x8)
MORE_FAULTS: 0x0
WALKER_ERROR: 0x0
PERMISSION_FAULTS: 0x3
MAPPING_ERROR: 0x0
RW: 0x0
First you have the memory hub, gfxhub and mmhub. gfxhub is the memory
hub used for graphics, compute, and sdma on some chips. mmhub is the
memory hub used for multi-media and sdma on some chips.
Next you have the vmid and pasid. If the vmid is 0, this fault was likely
caused by the kernel driver or firmware. If the vmid is non-0, it is generally
a fault in a user application. The pasid is used to link a vmid to a system
process id. If the process is active when the fault happens, the process
information will be printed.
The GPU virtual address that caused the fault comes next.
The client ID indicates the GPU block that caused the fault.
Some common client IDs:
- CB/DB: The color/depth backend of the graphics pipe
- CPF: Command Processor Frontend
- CPC: Command Processor Compute
- CPG: Command Processor Graphics
- TCP/SQC/SQG: Shaders
- SDMA: SDMA engines
- VCN: Video encode/decode engines
- JPEG: JPEG engines
PERMISSION_FAULTS describe what faults were encountered:
- bit 0: the PTE was not valid
- bit 1: the PTE read bit was not set
- bit 2: the PTE write bit was not set
- bit 3: the PTE execute bit was not set
Finally, RW, indicates whether the access was a read (0) or a write (1).
In the example above, a shader (cliend id = TCP) generated a read (RW = 0x0) to
an invalid page (PERMISSION_FAULTS = 0x3) at GPU virtual address
0x0000800102800000. The user can then inspect their shader code and resource
descriptor state to determine what caused the GPU page fault.
UMR
===
`umr <https://gitlab.freedesktop.org/tomstdenis/umr>`_ is a general purpose
GPU debugging and diagnostics tool. Please see the umr
`documentation <https://umr.readthedocs.io/en/main/>`_ for more information
about its capabilities.
Debugging backlight brightness
==============================
Default backlight brightness is intended to be set via the policy advertised
by the firmware. Firmware will often provide different defaults for AC or DC.
Furthermore, some userspace software will save backlight brightness during
the previous boot and attempt to restore it.
Some firmware also has support for a feature called "Custom Backlight Curves"
where an input value for brightness is mapped along a linearly interpolated
curve of brightness values that better match display characteristics.
In the event of problems happening with backlight, there is a trace event
that can be enabled at bootup to log every brightness change request.
This can help isolate where the problem is. To enable the trace event add
the following to the kernel command line:
tp_printk trace_event=amdgpu_dm:amdgpu_dm_brightness:mod:amdgpu trace_buf_size=1M
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
일반 GPU debugging 진입점
1-10GPU 문제를 조사할 때 먼저 AMDGPU DebugFS 문서의 interface를 확인합니다. Debugfs file은 ring, MQD, fence, power, memory, register와 firmware 상태를 관찰하거나 test·reset 같은 동작을 실행하는 진단 수단입니다.
Debugfs는 보통 `/sys/kernel/debug/dri/<num>` 아래에 있으며 안정된 userspace ABI가 아닙니다. 대상 DRM device와 file의 side effect를 확인한 뒤 사용해야 합니다.
이 문서와 AMDGPU DebugFS 문서의 역할을 구분합니다.
===============
GPU Debugging
===============
General Debugging Options
=========================
The DebugFS section provides documentation on a number files to aid in debugging
issues on the GPU.
GPUVM debugging module parameter
11-22Driver는 GPU virtual memory 문제를 조사하기 위한 module parameter를 제공합니다. 두 option 모두 값이 0이 아닐 때 동작이 바뀌며, 재현 조건과 성능·진행 상태에 영향을 줄 수 있으므로 debugging 목적으로 사용합니다.
두 module parameter의 non-zero 동작을 원문 그대로 정리했습니다.
GPUVM Debugging
===============
To aid in debugging GPU virtual memory related problems, the driver supports a
number of options module parameters:
`vm_fault_stop` - If non-0, halt the GPU memory controller on a GPU page fault.
`vm_update_mode` - If non-0, use the CPU to update GPU page tables rather than
the GPU.
GPUVM page fault log의 구조
23-42Kernel log에 GPU page fault가 나타나면 memory hub, `vmid`, `pasid`, process, fault address, IH client, `VM_L2_PROTECTION_FAULT_STATUS`의 하위 필드를 순서대로 읽어 application에서 무엇이 잘못됐는지 좁힐 수 있습니다.
아래 log는 원문의 예시를 그대로 보존합니다. `gfxhub0`, ring 24, `vmid:3`, `pasid:32777`, process와 thread 정보, GPU virtual address, UTCL2 client, permission과 read/write 상태가 함께 기록됩니다.
[gfxhub0] no-retry page fault (src_id:0 ring:24 vmid:3 pasid:32777, for process glxinfo pid 2424 thread glxinfo:cs0 pid 2425)
in page starting at address 0x0000800102800000 from IH client 0x1b (UTCL2)
VM_L2_PROTECTION_FAULT_STATUS:0x00301030
Faulty UTCL2 client ID: TCP (0x8)
MORE_FAULTS: 0x0
WALKER_ERROR: 0x0
PERMISSION_FAULTS: 0x3
MAPPING_ERROR: 0x0
RW: 0x0Log field를 해석하는 권장 순서입니다.
Decoding a GPUVM Page Fault
===========================
If you see a GPU page fault in the kernel log, you can decode it to figure
out what is going wrong in your application. A page fault in your kernel
log may look something like this:
::
[gfxhub0] no-retry page fault (src_id:0 ring:24 vmid:3 pasid:32777, for process glxinfo pid 2424 thread glxinfo:cs0 pid 2425)
in page starting at address 0x0000800102800000 from IH client 0x1b (UTCL2)
VM_L2_PROTECTION_FAULT_STATUS:0x00301030
Faulty UTCL2 client ID: TCP (0x8)
MORE_FAULTS: 0x0
WALKER_ERROR: 0x0
PERMISSION_FAULTS: 0x3
MAPPING_ERROR: 0x0
RW: 0x0
Memory hub, VMID/PASID와 client ID
43-65`gfxhub`는 일부 chip에서 graphics, compute, SDMA가 사용하는 memory hub이고, `mmhub`는 일부 chip에서 multimedia와 SDMA가 사용하는 memory hub입니다. 어느 hub에서 fault가 났는지는 원인 engine 범위를 정하는 첫 단서입니다.
`vmid`가 0이면 kernel driver 또는 firmware가 원인일 가능성이 높고, 0이 아니면 일반적으로 user application fault입니다. `pasid`는 `vmid`를 system process ID와 연결하며 fault 시 process가 살아 있으면 process 정보도 log에 출력됩니다.
그 다음 fault를 일으킨 GPU virtual address와 client ID를 확인합니다. Client ID는 실제 접근을 발생시킨 graphics, command processor, shader, SDMA, video 또는 JPEG block을 가리킵니다.
원문이 설명하는 hub별 대표 사용 영역입니다.
자주 나타나는 client ID와 원인 block입니다.
First you have the memory hub, gfxhub and mmhub. gfxhub is the memory
hub used for graphics, compute, and sdma on some chips. mmhub is the
memory hub used for multi-media and sdma on some chips.
Next you have the vmid and pasid. If the vmid is 0, this fault was likely
caused by the kernel driver or firmware. If the vmid is non-0, it is generally
a fault in a user application. The pasid is used to link a vmid to a system
process id. If the process is active when the fault happens, the process
information will be printed.
The GPU virtual address that caused the fault comes next.
The client ID indicates the GPU block that caused the fault.
Some common client IDs:
- CB/DB: The color/depth backend of the graphics pipe
- CPF: Command Processor Frontend
- CPC: Command Processor Compute
- CPG: Command Processor Graphics
- TCP/SQC/SQG: Shaders
- SDMA: SDMA engines
- VCN: Video encode/decode engines
- JPEG: JPEG enginesPERMISSION_FAULTS와 RW 판독
66-79`PERMISSION_FAULTS`는 page-table entry에서 어떤 조건을 위반했는지 bitmask로 나타냅니다. 여러 bit가 동시에 set될 수 있으므로 값을 하나의 오류 이름으로만 읽지 말고 각 bit를 분해해야 합니다.
마지막 `RW` field는 접근 방향을 나타냅니다. 0은 read, 1은 write입니다. 원문 예시는 TCP shader가 `RW = 0x0` read를 수행했고 `PERMISSION_FAULTS = 0x3`이므로 bit 0과 bit 1, 즉 invalid PTE와 read bit 부재가 함께 나타난 경우입니다.
PTE validity와 read/write/execute permission bit입니다.
예시 log의 핵심 field를 원인 조사 항목으로 연결합니다.
PERMISSION_FAULTS describe what faults were encountered:
- bit 0: the PTE was not valid
- bit 1: the PTE read bit was not set
- bit 2: the PTE write bit was not set
- bit 3: the PTE execute bit was not set
Finally, RW, indicates whether the access was a read (0) or a write (1).
In the example above, a shader (cliend id = TCP) generated a read (RW = 0x0) to
an invalid page (PERMISSION_FAULTS = 0x3) at GPU virtual address
0x0000800102800000. The user can then inspect their shader code and resource
descriptor state to determine what caused the GPU page fault.UMR 진단 도구
80-87`umr`은 범용 GPU debugging·diagnostics tool입니다. AMDGPU debugfs의 raw ring, MQD, VRAM/GTT, register, wave와 GPR interface를 사람이 조사할 수 있는 형태로 다루는 데 사용됩니다.
Project와 사용법은 원문 링크를 유지합니다. Source repository는 `https://gitlab.freedesktop.org/tomstdenis/umr`, 기능 문서는 `https://umr.readthedocs.io/en/main/`입니다.
원문이 제공하는 project와 documentation 링크입니다.
UMR
===
`umr <https://gitlab.freedesktop.org/tomstdenis/umr>`_ is a general purpose
GPU debugging and diagnostics tool. Please see the umr
`documentation <https://umr.readthedocs.io/en/main/>`_ for more information
about its capabilities.Backlight brightness 변화 추적
88-105기본 backlight brightness는 firmware가 알리는 policy를 통해 설정하도록 설계되며, firmware는 AC와 DC 전원 상태에 서로 다른 default를 제공할 수 있습니다. 또한 일부 userspace software는 이전 boot의 brightness를 저장했다가 복원합니다.
일부 firmware의 `Custom Backlight Curves`는 입력 brightness 값을 display 특성에 더 맞는 brightness 값 곡선에 선형 보간하여 mapping합니다. 따라서 표시 값과 실제 panel 밝기의 관계가 단순 선형이 아닐 수 있습니다.
Backlight 문제가 있으면 boot 시 trace event를 enable해 모든 brightness change request를 기록할 수 있습니다. 어느 component가 값을 바꿨는지 분리하기 위해 다음 문자열을 kernel command line에 추가합니다.
tp_printk trace_event=amdgpu_dm:amdgpu_dm_brightness:mod:amdgpu trace_buf_size=1MBrightness 값의 가능한 출처와 trace 지점을 구조화했습니다.
Boot부터 brightness request를 기록하기 위한 세 부분입니다.
Debugging backlight brightness
==============================
Default backlight brightness is intended to be set via the policy advertised
by the firmware. Firmware will often provide different defaults for AC or DC.
Furthermore, some userspace software will save backlight brightness during
the previous boot and attempt to restore it.
Some firmware also has support for a feature called "Custom Backlight Curves"
where an input value for brightness is mapped along a linearly interpolated
curve of brightness values that better match display characteristics.
In the event of problems happening with backlight, there is a trace event
that can be enabled at bootup to log every brightness change request.
This can help isolate where the problem is. To enable the trace event add
the following to the kernel command line:
tp_printk trace_event=amdgpu_dm:amdgpu_dm_brightness:mod:amdgpu trace_buf_size=1M
요약·해설
debugging.rst:1-105AMDGPU GPUVM page fault와 backlight brightness 문제를 조사하는 문서입니다. GPUVM module parameter, kernel log field, memory hub와 VMID/PASID, client ID, permission bit, RW 방향, UMR 자료와 boot-time brightness trace option을 전문 번역했습니다.
Page fault 조사의 핵심은 log를 순서대로 해석하는 것입니다. `vmid == 0` 여부로 kernel/firmware 가능성을 먼저 분류하고, client block과 fault address를 찾은 뒤 `PERMISSION_FAULTS` bitmask와 `RW`를 결합해 잘못된 page-table permission과 접근 방향을 확인합니다.
증상별 첫 진입점과 핵심 증거입니다.