forked from Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
70 lines
2.8 KiB
70 lines
2.8 KiB
.. 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 :doc:`devlink-health` |
|
|
|
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. |
|
|
|
example 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] |
|
pci/0000:00:05.0/fw-health: size 64 snapshot [1 2] |
|
|
|
# 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 |
|
|
|
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.
|
|
|