84 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3==============4Devlink Region5==============6 7``devlink`` regions enable access to driver defined address regions using8devlink.9 10Each device can create and register its own supported address regions. The11region can then be accessed via the devlink region interface.12 13Region snapshots are collected by the driver, and can be accessed via read14or dump commands. This allows future analysis on the created snapshots.15Regions may optionally support triggering snapshots on demand.16 17Snapshot identifiers are scoped to the devlink instance, not a region.18All snapshots with the same snapshot id within a devlink instance19correspond to the same event.20 21The major benefit to creating a region is to provide access to internal22address regions that are otherwise inaccessible to the user.23 24Regions may also be used to provide an additional way to debug complex error25states, but see also Documentation/networking/devlink/devlink-health.rst26 27Regions may optionally support capturing a snapshot on demand via the28``DEVLINK_CMD_REGION_NEW`` netlink message. A driver wishing to allow29requested snapshots must implement the ``.snapshot`` callback for the region30in its ``devlink_region_ops`` structure. If snapshot id is not set in31the ``DEVLINK_CMD_REGION_NEW`` request kernel will allocate one and send32the snapshot information to user space.33 34Regions may optionally allow directly reading from their contents without a35snapshot. Direct read requests are not atomic. In particular a read request36of size 256 bytes or larger will be split into multiple chunks. If atomic37access is required, use a snapshot. A driver wishing to enable this for a38region should implement the ``.read`` callback in the ``devlink_region_ops``39structure. User space can request a direct read by using the40``DEVLINK_ATTR_REGION_DIRECT`` attribute instead of specifying a snapshot41id.42 43example usage44-------------45 46.. code:: shell47 48 $ devlink region help49 $ devlink region show [ DEV/REGION ]50 $ devlink region del DEV/REGION snapshot SNAPSHOT_ID51 $ devlink region dump DEV/REGION [ snapshot SNAPSHOT_ID ]52 $ devlink region read DEV/REGION [ snapshot SNAPSHOT_ID ] address ADDRESS length LENGTH53 54 # Show all of the exposed regions with region sizes:55 $ devlink region show56 pci/0000:00:05.0/cr-space: size 1048576 snapshot [1 2] max 857 pci/0000:00:05.0/fw-health: size 64 snapshot [1 2] max 858 59 # Delete a snapshot using:60 $ devlink region del pci/0000:00:05.0/cr-space snapshot 161 62 # Request an immediate snapshot, if supported by the region63 $ devlink region new pci/0000:00:05.0/cr-space64 pci/0000:00:05.0/cr-space: snapshot 565 66 # Dump a snapshot:67 $ devlink region dump pci/0000:00:05.0/fw-health snapshot 168 0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db3069 0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc870 0000000000000020 0016 0bb8 0016 1720 0000 0000 c00f 3ffc71 0000000000000030 bada cce5 bada cce5 bada cce5 bada cce572 73 # Read a specific part of a snapshot:74 $ devlink region read pci/0000:00:05.0/fw-health snapshot 1 address 0 length 1675 0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db3076 77 # Read from the region without a snapshot78 $ devlink region read pci/0000:00:05.0/fw-health address 16 length 1679 0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc880 81As regions are likely very device or driver specific, no generic regions are82defined. See the driver-specific documentation files for information on the83specific regions a driver supports.84