Commit | Line | Data |
---|---|---|
0b0f945f JK |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ============== | |
4 | Devlink Region | |
5 | ============== | |
6 | ||
7 | ``devlink`` regions enable access to driver defined address regions using | |
8 | devlink. | |
9 | ||
10 | Each device can create and register its own supported address regions. The | |
11 | region can then be accessed via the devlink region interface. | |
12 | ||
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. | |
9cd3e2c6 | 15 | Regions may optionally support triggering snapshots on demand. |
0b0f945f | 16 | |
aebbd7df JK |
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. | |
20 | ||
0b0f945f | 21 | The major benefit to creating a region is to provide access to internal |
9cd3e2c6 JK |
22 | address regions that are otherwise inaccessible to the user. |
23 | ||
24 | Regions may also be used to provide an additional way to debug complex error | |
8d4a0adc | 25 | states, but see also Documentation/networking/devlink/devlink-health.rst |
0b0f945f | 26 | |
b9a17abf JK |
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 | |
043b3e22 JK |
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. | |
b9a17abf | 33 | |
af6397c9 JK |
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. | |
42 | ||
0b0f945f JK |
43 | example usage |
44 | ------------- | |
45 | ||
46 | .. code:: shell | |
47 | ||
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 ] | |
9c11cc78 | 52 | $ devlink region read DEV/REGION [ snapshot SNAPSHOT_ID ] address ADDRESS length length |
0b0f945f JK |
53 | |
54 | # Show all of the exposed regions with region sizes: | |
55 | $ devlink region show | |
a70e3f02 JK |
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 | |
0b0f945f JK |
58 | |
59 | # Delete a snapshot using: | |
60 | $ devlink region del pci/0000:00:05.0/cr-space snapshot 1 | |
61 | ||
b9a17abf | 62 | # Request an immediate snapshot, if supported by the region |
043b3e22 JK |
63 | $ devlink region new pci/0000:00:05.0/cr-space |
64 | pci/0000:00:05.0/cr-space: snapshot 5 | |
b9a17abf | 65 | |
0b0f945f JK |
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 | |
72 | ||
73 | # Read a specific part of a snapshot: | |
9c11cc78 | 74 | $ devlink region read pci/0000:00:05.0/fw-health snapshot 1 address 0 length 16 |
0b0f945f JK |
75 | 0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30 |
76 | ||
af6397c9 JK |
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 | |
80 | ||
0b0f945f JK |
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. |