1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ============== 3 ==============
4 Devlink Region 4 Devlink Region
5 ============== 5 ==============
6 6
7 ``devlink`` regions enable access to driver de 7 ``devlink`` regions enable access to driver defined address regions using
8 devlink. 8 devlink.
9 9
10 Each device can create and register its own su 10 Each device can create and register its own supported address regions. The
11 region can then be accessed via the devlink re 11 region can then be accessed via the devlink region interface.
12 12
13 Region snapshots are collected by the driver, 13 Region snapshots are collected by the driver, and can be accessed via read
14 or dump commands. This allows future analysis 14 or dump commands. This allows future analysis on the created snapshots.
15 Regions may optionally support triggering snap 15 Regions may optionally support triggering snapshots on demand.
16 16
17 Snapshot identifiers are scoped to the devlink 17 Snapshot identifiers are scoped to the devlink instance, not a region.
18 All snapshots with the same snapshot id within 18 All snapshots with the same snapshot id within a devlink instance
19 correspond to the same event. 19 correspond to the same event.
20 20
21 The major benefit to creating a region is to p 21 The major benefit to creating a region is to provide access to internal
22 address regions that are otherwise inaccessibl 22 address regions that are otherwise inaccessible to the user.
23 23
24 Regions may also be used to provide an additio 24 Regions may also be used to provide an additional way to debug complex error
25 states, but see also Documentation/networking/ 25 states, but see also Documentation/networking/devlink/devlink-health.rst
26 26
27 Regions may optionally support capturing a sna 27 Regions may optionally support capturing a snapshot on demand via the
28 ``DEVLINK_CMD_REGION_NEW`` netlink message. A 28 ``DEVLINK_CMD_REGION_NEW`` netlink message. A driver wishing to allow
29 requested snapshots must implement the ``.snap 29 requested snapshots must implement the ``.snapshot`` callback for the region
30 in its ``devlink_region_ops`` structure. If sn 30 in its ``devlink_region_ops`` structure. If snapshot id is not set in
31 the ``DEVLINK_CMD_REGION_NEW`` request kernel 31 the ``DEVLINK_CMD_REGION_NEW`` request kernel will allocate one and send
32 the snapshot information to user space. 32 the snapshot information to user space.
33 33
34 Regions may optionally allow directly reading 34 Regions may optionally allow directly reading from their contents without a
35 snapshot. Direct read requests are not atomic. 35 snapshot. Direct read requests are not atomic. In particular a read request
36 of size 256 bytes or larger will be split into 36 of size 256 bytes or larger will be split into multiple chunks. If atomic
37 access is required, use a snapshot. A driver w 37 access is required, use a snapshot. A driver wishing to enable this for a
38 region should implement the ``.read`` callback 38 region should implement the ``.read`` callback in the ``devlink_region_ops``
39 structure. User space can request a direct rea 39 structure. User space can request a direct read by using the
40 ``DEVLINK_ATTR_REGION_DIRECT`` attribute inste 40 ``DEVLINK_ATTR_REGION_DIRECT`` attribute instead of specifying a snapshot
41 id. 41 id.
42 42
43 example usage 43 example usage
44 ------------- 44 -------------
45 45
46 .. code:: shell 46 .. code:: shell
47 47
48 $ devlink region help 48 $ devlink region help
49 $ devlink region show [ DEV/REGION ] 49 $ devlink region show [ DEV/REGION ]
50 $ devlink region del DEV/REGION snapshot S 50 $ devlink region del DEV/REGION snapshot SNAPSHOT_ID
51 $ devlink region dump DEV/REGION [ snapsho 51 $ devlink region dump DEV/REGION [ snapshot SNAPSHOT_ID ]
52 $ devlink region read DEV/REGION [ snapsho 52 $ devlink region read DEV/REGION [ snapshot SNAPSHOT_ID ] address ADDRESS length LENGTH
53 53
54 # Show all of the exposed regions with reg 54 # Show all of the exposed regions with region sizes:
55 $ devlink region show 55 $ devlink region show
56 pci/0000:00:05.0/cr-space: size 1048576 sn 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 snapsh 57 pci/0000:00:05.0/fw-health: size 64 snapshot [1 2] max 8
58 58
59 # Delete a snapshot using: 59 # Delete a snapshot using:
60 $ devlink region del pci/0000:00:05.0/cr-s 60 $ devlink region del pci/0000:00:05.0/cr-space snapshot 1
61 61
62 # Request an immediate snapshot, if suppor 62 # Request an immediate snapshot, if supported by the region
63 $ devlink region new pci/0000:00:05.0/cr-s 63 $ devlink region new pci/0000:00:05.0/cr-space
64 pci/0000:00:05.0/cr-space: snapshot 5 64 pci/0000:00:05.0/cr-space: snapshot 5
65 65
66 # Dump a snapshot: 66 # Dump a snapshot:
67 $ devlink region dump pci/0000:00:05.0/fw- 67 $ devlink region dump pci/0000:00:05.0/fw-health snapshot 1
68 0000000000000000 0014 95dc 0014 9514 0035 68 0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30
69 0000000000000010 0000 0000 ffff ff04 0029 69 0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc8
70 0000000000000020 0016 0bb8 0016 1720 0000 70 0000000000000020 0016 0bb8 0016 1720 0000 0000 c00f 3ffc
71 0000000000000030 bada cce5 bada cce5 bada 71 0000000000000030 bada cce5 bada cce5 bada cce5 bada cce5
72 72
73 # Read a specific part of a snapshot: 73 # Read a specific part of a snapshot:
74 $ devlink region read pci/0000:00:05.0/fw- 74 $ devlink region read pci/0000:00:05.0/fw-health snapshot 1 address 0 length 16
75 0000000000000000 0014 95dc 0014 9514 0035 75 0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30
76 76
77 # Read from the region without a snapshot 77 # Read from the region without a snapshot
78 $ devlink region read pci/0000:00:05.0/fw- 78 $ devlink region read pci/0000:00:05.0/fw-health address 16 length 16
79 0000000000000010 0000 0000 ffff ff04 0029 79 0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc8
80 80
81 As regions are likely very device or driver sp 81 As regions are likely very device or driver specific, no generic regions are
82 defined. See the driver-specific documentation 82 defined. See the driver-specific documentation files for information on the
83 specific regions a driver supports. 83 specific regions a driver supports.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.