1.. SPDX-License-Identifier: GPL-2.0
2
3==============
4Devlink Region
5==============
6
7``devlink`` regions enable access to driver defined address regions using
8devlink.
9
10Each device can create and register its own supported address regions. The
11region can then be accessed via the devlink region interface.
12
13Region snapshots are collected by the driver, and can be accessed via read
14or dump commands. This allows future analysis on the created snapshots.
15Regions may optionally support triggering snapshots on demand.
16
17The major benefit to creating a region is to provide access to internal
18address regions that are otherwise inaccessible to the user.
19
20Regions may also be used to provide an additional way to debug complex error
21states, but see also :doc:`devlink-health`
22
23example usage
24-------------
25
26.. code:: shell
27
28    $ devlink region help
29    $ devlink region show [ DEV/REGION ]
30    $ devlink region del DEV/REGION snapshot SNAPSHOT_ID
31    $ devlink region dump DEV/REGION [ snapshot SNAPSHOT_ID ]
32    $ devlink region read DEV/REGION [ snapshot SNAPSHOT_ID ]
33            address ADDRESS length length
34
35    # Show all of the exposed regions with region sizes:
36    $ devlink region show
37    pci/0000:00:05.0/cr-space: size 1048576 snapshot [1 2]
38    pci/0000:00:05.0/fw-health: size 64 snapshot [1 2]
39
40    # Delete a snapshot using:
41    $ devlink region del pci/0000:00:05.0/cr-space snapshot 1
42
43    # Trigger (request) a snapshot be taken:
44    $ devlink region trigger pci/0000:00:05.0/cr-space
45
46    # Dump a snapshot:
47    $ devlink region dump pci/0000:00:05.0/fw-health snapshot 1
48    0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30
49    0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc8
50    0000000000000020 0016 0bb8 0016 1720 0000 0000 c00f 3ffc
51    0000000000000030 bada cce5 bada cce5 bada cce5 bada cce5
52
53    # Read a specific part of a snapshot:
54    $ devlink region read pci/0000:00:05.0/fw-health snapshot 1 address 0
55            length 16
56    0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30
57
58As regions are likely very device or driver specific, no generic regions are
59defined. See the driver-specific documentation files for information on the
60specific regions a driver supports.
61