요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: GPL-2.0
3
==============
4
Devlink Region
5
==============
7
``devlink`` regions enable access to driver defined address regions using
8
devlink.
10
Each device can create and register its own supported address regions. The
11
region can then be accessed via the devlink region interface.
13
Region snapshots are collected by the driver, and can be accessed via read
14
or dump commands. This allows future analysis on the created snapshots.
15
Regions may optionally support triggering snapshots on demand.
17
Snapshot identifiers are scoped to the devlink instance, not a region.
18
All snapshots with the same snapshot id within a devlink instance
19
correspond to the same event.
21
The major benefit to creating a region is to provide access to internal
22
address regions that are otherwise inaccessible to the user.
24
Regions may also be used to provide an additional way to debug complex error
25
states, but see also Documentation/networking/devlink/devlink-health.rst
27
Regions may optionally support capturing a snapshot on demand via the
28
``DEVLINK_CMD_REGION_NEW`` netlink message. A driver wishing to allow
29
requested snapshots must implement the ``.snapshot`` callback for the region
30
in its ``devlink_region_ops`` structure. If snapshot id is not set in
31
the ``DEVLINK_CMD_REGION_NEW`` request kernel will allocate one and send
32
the snapshot information to user space.
34
Regions may optionally allow directly reading from their contents without a
35
snapshot. Direct read requests are not atomic. In particular a read request
36
of size 256 bytes or larger will be split into multiple chunks. If atomic
37
access is required, use a snapshot. A driver wishing to enable this for a
38
region should implement the ``.read`` callback in the ``devlink_region_ops``
39
structure. User space can request a direct read by using the
40
``DEVLINK_ATTR_REGION_DIRECT`` attribute instead of specifying a snapshot
41
id.
43
example usage
44
-------------
46
.. code:: shell
48
$ devlink region help
49
$ devlink region show [ DEV/REGION ]
50
$ devlink region del DEV/REGION snapshot SNAPSHOT_ID
51
$ devlink region dump DEV/REGION [ snapshot SNAPSHOT_ID ]
52
$ devlink region read DEV/REGION [ snapshot SNAPSHOT_ID ] address ADDRESS length LENGTH
54
# Show all of the exposed regions with region sizes:
55
$ devlink region show
56
pci/0000:00:05.0/cr-space: size 1048576 snapshot [1 2] max 8
57
pci/0000:00:05.0/fw-health: size 64 snapshot [1 2] max 8
59
# Delete a snapshot using:
60
$ devlink region del pci/0000:00:05.0/cr-space snapshot 1
62
# Request an immediate snapshot, if supported by the region
63
$ devlink region new pci/0000:00:05.0/cr-space
64
pci/0000:00:05.0/cr-space: snapshot 5
66
# Dump a snapshot:
67
$ devlink region dump pci/0000:00:05.0/fw-health snapshot 1
68
0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30
69
0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc8
70
0000000000000020 0016 0bb8 0016 1720 0000 0000 c00f 3ffc
71
0000000000000030 bada cce5 bada cce5 bada cce5 bada cce5
73
# Read a specific part of a snapshot:
74
$ devlink region read pci/0000:00:05.0/fw-health snapshot 1 address 0 length 16
75
0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30
77
# Read from the region without a snapshot
78
$ devlink region read pci/0000:00:05.0/fw-health address 16 length 16
79
0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc8
81
As regions are likely very device or driver specific, no generic regions are
82
defined. See the driver-specific documentation files for information on the
83
specific regions a driver supports.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Devlink Region 소개
1-26이 문서는 `GPL-2.0` 라이선스를 따릅니다.
Devlink Region
`devlink` region을 사용하면 devlink를 통해 driver가 정의한 address region에 접근할 수 있습니다.
각 장치는 자신이 지원하는 address region을 만들고 등록할 수 있습니다. 등록한 region에는 devlink region interface로 접근합니다.
Region snapshot은 driver가 수집하며 `read` 또는 `dump` 명령으로 접근할 수 있습니다. 따라서 만들어 둔 snapshot을 나중에 분석할 수 있습니다. Region은 필요할 때 즉시 snapshot을 생성하는 기능도 선택적으로 지원할 수 있습니다.
Snapshot identifier의 범위는 개별 region이 아니라 devlink instance입니다. 한 devlink instance 안에서 snapshot ID가 같은 모든 snapshot은 동일한 event에 대응합니다.
Region을 만드는 가장 큰 이점은 사용자가 다른 방법으로는 접근할 수 없는 내부 address region을 열람할 수 있다는 점입니다.
Region은 복잡한 error state를 debug하는 보조 수단으로도 사용할 수 있습니다. 함께 볼 문서는 `Documentation/networking/devlink/devlink-health.rst`입니다.
.. SPDX-License-Identifier: GPL-2.0
==============
Devlink Region
==============
``devlink`` regions enable access to driver defined address regions using
devlink.
Each device can create and register its own supported address regions. The
region can then be accessed via the devlink region interface.
Region snapshots are collected by the driver, and can be accessed via read
or dump commands. This allows future analysis on the created snapshots.
Regions may optionally support triggering snapshots on demand.
Snapshot identifiers are scoped to the devlink instance, not a region.
All snapshots with the same snapshot id within a devlink instance
correspond to the same event.
The major benefit to creating a region is to provide access to internal
address regions that are otherwise inaccessible to the user.
Regions may also be used to provide an additional way to debug complex error
states, but see also Documentation/networking/devlink/devlink-health.rst
요청형 snapshot과 direct read
27-42Region은 `DEVLINK_CMD_REGION_NEW` netlink message를 통해 요청 시 snapshot을 capture하는 기능을 선택적으로 제공할 수 있습니다. 요청형 snapshot을 허용하려는 driver는 해당 region의 `devlink_region_ops` 구조체에 `.snapshot` callback을 구현해야 합니다.
`DEVLINK_CMD_REGION_NEW` 요청에 snapshot ID가 지정되지 않으면 kernel이 ID를 할당하고 snapshot 정보를 user space로 보냅니다.
Region은 snapshot을 만들지 않고 내용을 직접 읽는 기능도 선택적으로 제공할 수 있습니다. Direct read 요청은 atomic하지 않습니다. 특히 256 byte 이상의 read 요청은 여러 chunk로 나뉩니다. Atomic access가 필요하면 snapshot을 사용해야 합니다.
Region에서 direct read를 활성화하려는 driver는 `devlink_region_ops` 구조체에 `.read` callback을 구현해야 합니다. User space는 snapshot ID를 지정하는 대신 `DEVLINK_ATTR_REGION_DIRECT` attribute를 사용해 direct read를 요청할 수 있습니다.
방식driver callback특성
요청형 snapshot`.snapshot`동일 event의 고정된 내용을 보존하며 kernel이 ID를 할당할 수 있음
direct read`.read`snapshot 없이 읽지만 atomic하지 않고 256 byte 이상은 여러 chunk로 분할
일관성이 필요한 분석에는 snapshot을, 최신 내용을 바로 읽을 때는 direct read를 사용합니다.
Regions may optionally support capturing a snapshot on demand via the
``DEVLINK_CMD_REGION_NEW`` netlink message. A driver wishing to allow
requested snapshots must implement the ``.snapshot`` callback for the region
in its ``devlink_region_ops`` structure. If snapshot id is not set in
the ``DEVLINK_CMD_REGION_NEW`` request kernel will allocate one and send
the snapshot information to user space.
Regions may optionally allow directly reading from their contents without a
snapshot. Direct read requests are not atomic. In particular a read request
of size 256 bytes or larger will be split into multiple chunks. If atomic
access is required, use a snapshot. A driver wishing to enable this for a
region should implement the ``.read`` callback in the ``devlink_region_ops``
structure. User space can request a direct read by using the
``DEVLINK_ATTR_REGION_DIRECT`` attribute instead of specifying a snapshot
id.
사용 예
43-80사용 예
다음 명령은 region 조회, snapshot 삭제·생성·dump, snapshot 일부 읽기, snapshot 없는 direct read를 보여 줍니다. 명령, 장치 경로, address, length, 출력 byte는 원문 그대로 보존했습니다.
$ devlink region help
$ devlink region show [ DEV/REGION ]
$ devlink region del DEV/REGION snapshot SNAPSHOT_ID
$ devlink region dump DEV/REGION [ snapshot SNAPSHOT_ID ]
$ devlink region read DEV/REGION [ snapshot SNAPSHOT_ID ] address ADDRESS length LENGTH
# 공개된 모든 region과 크기 표시
$ devlink region show
pci/0000:00:05.0/cr-space: size 1048576 snapshot [1 2] max 8
pci/0000:00:05.0/fw-health: size 64 snapshot [1 2] max 8
# snapshot 삭제
$ devlink region del pci/0000:00:05.0/cr-space snapshot 1
# region이 지원할 경우 즉시 snapshot 요청
$ devlink region new pci/0000:00:05.0/cr-space
pci/0000:00:05.0/cr-space: snapshot 5
# snapshot dump
$ devlink region dump pci/0000:00:05.0/fw-health snapshot 1
0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30
0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc8
0000000000000020 0016 0bb8 0016 1720 0000 0000 c00f 3ffc
0000000000000030 bada cce5 bada cce5 bada cce5 bada cce5
# snapshot의 특정 부분 읽기
$ devlink region read pci/0000:00:05.0/fw-health snapshot 1 address 0 length 16
0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30
# snapshot 없이 region에서 읽기
$ devlink region read pci/0000:00:05.0/fw-health address 16 length 16
0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc8example usage
-------------
.. code:: shell
$ devlink region help
$ devlink region show [ DEV/REGION ]
$ devlink region del DEV/REGION snapshot SNAPSHOT_ID
$ devlink region dump DEV/REGION [ snapshot SNAPSHOT_ID ]
$ devlink region read DEV/REGION [ snapshot SNAPSHOT_ID ] address ADDRESS length LENGTH
# Show all of the exposed regions with region sizes:
$ devlink region show
pci/0000:00:05.0/cr-space: size 1048576 snapshot [1 2] max 8
pci/0000:00:05.0/fw-health: size 64 snapshot [1 2] max 8
# Delete a snapshot using:
$ devlink region del pci/0000:00:05.0/cr-space snapshot 1
# Request an immediate snapshot, if supported by the region
$ devlink region new pci/0000:00:05.0/cr-space
pci/0000:00:05.0/cr-space: snapshot 5
# Dump a snapshot:
$ devlink region dump pci/0000:00:05.0/fw-health snapshot 1
0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30
0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc8
0000000000000020 0016 0bb8 0016 1720 0000 0000 c00f 3ffc
0000000000000030 bada cce5 bada cce5 bada cce5 bada cce5
# Read a specific part of a snapshot:
$ devlink region read pci/0000:00:05.0/fw-health snapshot 1 address 0 length 16
0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30
# Read from the region without a snapshot
$ devlink region read pci/0000:00:05.0/fw-health address 16 length 16
0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc8
Driver별 region
81-83Region은 장치나 driver에 매우 종속적일 가능성이 크므로 generic region은 정의하지 않습니다. 특정 driver가 지원하는 구체적인 region은 해당 driver 문서를 참조하십시오.
As regions are likely very device or driver specific, no generic regions are
defined. See the driver-specific documentation files for information on the
specific regions a driver supports.
요약·해설
devlink-region.rst:1-83Devlink region은 평소 user space에서 볼 수 없는 장치 내부 memory나 상태 영역을 진단 목적으로 노출합니다. 일관된 시점의 분석에는 snapshot을 사용하고, 최신 내용을 즉시 확인할 때만 atomic하지 않은 direct read의 제약을 감수해야 합니다.
목적에 맞는 접근 방식을 선택해 장치 상태를 수집합니다.