| 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. |
| 15 |
Regions may optionally support triggering snapshots on demand. |
| 16 |
|
| 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 |
|
| 21 |
The major benefit to creating a region is to provide access to internal |
| 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 |
| 25 |
states, but see also Documentation/networking/devlink/devlink-health.rst |
| 26 |
|
| 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. |
| 33 |
|
| 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 |
|
| 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 ] |
| 52 |
$ devlink region read DEV/REGION [ snapshot SNAPSHOT_ID ] address ADDRESS length LENGTH |
| 53 |
|
| 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 |
| 58 |
|
| 59 |
# Delete a snapshot using: |
| 60 |
$ devlink region del pci/0000:00:05.0/cr-space snapshot 1 |
| 61 |
|
| 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 |
| 65 |
|
| 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: |
| 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 |
| 76 |
|
| 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 |
|
| 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. |