1*4882a593Smuzhiyun.. SPDX-License-Identifier: GPL-2.0 2*4882a593Smuzhiyun 3*4882a593Smuzhiyun============== 4*4882a593SmuzhiyunDevlink Region 5*4882a593Smuzhiyun============== 6*4882a593Smuzhiyun 7*4882a593Smuzhiyun``devlink`` regions enable access to driver defined address regions using 8*4882a593Smuzhiyundevlink. 9*4882a593Smuzhiyun 10*4882a593SmuzhiyunEach device can create and register its own supported address regions. The 11*4882a593Smuzhiyunregion can then be accessed via the devlink region interface. 12*4882a593Smuzhiyun 13*4882a593SmuzhiyunRegion snapshots are collected by the driver, and can be accessed via read 14*4882a593Smuzhiyunor dump commands. This allows future analysis on the created snapshots. 15*4882a593SmuzhiyunRegions may optionally support triggering snapshots on demand. 16*4882a593Smuzhiyun 17*4882a593SmuzhiyunSnapshot identifiers are scoped to the devlink instance, not a region. 18*4882a593SmuzhiyunAll snapshots with the same snapshot id within a devlink instance 19*4882a593Smuzhiyuncorrespond to the same event. 20*4882a593Smuzhiyun 21*4882a593SmuzhiyunThe major benefit to creating a region is to provide access to internal 22*4882a593Smuzhiyunaddress regions that are otherwise inaccessible to the user. 23*4882a593Smuzhiyun 24*4882a593SmuzhiyunRegions may also be used to provide an additional way to debug complex error 25*4882a593Smuzhiyunstates, but see also :doc:`devlink-health` 26*4882a593Smuzhiyun 27*4882a593SmuzhiyunRegions may optionally support capturing a snapshot on demand via the 28*4882a593Smuzhiyun``DEVLINK_CMD_REGION_NEW`` netlink message. A driver wishing to allow 29*4882a593Smuzhiyunrequested snapshots must implement the ``.snapshot`` callback for the region 30*4882a593Smuzhiyunin its ``devlink_region_ops`` structure. If snapshot id is not set in 31*4882a593Smuzhiyunthe ``DEVLINK_CMD_REGION_NEW`` request kernel will allocate one and send 32*4882a593Smuzhiyunthe snapshot information to user space. 33*4882a593Smuzhiyun 34*4882a593Smuzhiyunexample usage 35*4882a593Smuzhiyun------------- 36*4882a593Smuzhiyun 37*4882a593Smuzhiyun.. code:: shell 38*4882a593Smuzhiyun 39*4882a593Smuzhiyun $ devlink region help 40*4882a593Smuzhiyun $ devlink region show [ DEV/REGION ] 41*4882a593Smuzhiyun $ devlink region del DEV/REGION snapshot SNAPSHOT_ID 42*4882a593Smuzhiyun $ devlink region dump DEV/REGION [ snapshot SNAPSHOT_ID ] 43*4882a593Smuzhiyun $ devlink region read DEV/REGION [ snapshot SNAPSHOT_ID ] address ADDRESS length length 44*4882a593Smuzhiyun 45*4882a593Smuzhiyun # Show all of the exposed regions with region sizes: 46*4882a593Smuzhiyun $ devlink region show 47*4882a593Smuzhiyun pci/0000:00:05.0/cr-space: size 1048576 snapshot [1 2] 48*4882a593Smuzhiyun pci/0000:00:05.0/fw-health: size 64 snapshot [1 2] 49*4882a593Smuzhiyun 50*4882a593Smuzhiyun # Delete a snapshot using: 51*4882a593Smuzhiyun $ devlink region del pci/0000:00:05.0/cr-space snapshot 1 52*4882a593Smuzhiyun 53*4882a593Smuzhiyun # Request an immediate snapshot, if supported by the region 54*4882a593Smuzhiyun $ devlink region new pci/0000:00:05.0/cr-space 55*4882a593Smuzhiyun pci/0000:00:05.0/cr-space: snapshot 5 56*4882a593Smuzhiyun 57*4882a593Smuzhiyun # Dump a snapshot: 58*4882a593Smuzhiyun $ devlink region dump pci/0000:00:05.0/fw-health snapshot 1 59*4882a593Smuzhiyun 0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30 60*4882a593Smuzhiyun 0000000000000010 0000 0000 ffff ff04 0029 8c00 0028 8cc8 61*4882a593Smuzhiyun 0000000000000020 0016 0bb8 0016 1720 0000 0000 c00f 3ffc 62*4882a593Smuzhiyun 0000000000000030 bada cce5 bada cce5 bada cce5 bada cce5 63*4882a593Smuzhiyun 64*4882a593Smuzhiyun # Read a specific part of a snapshot: 65*4882a593Smuzhiyun $ devlink region read pci/0000:00:05.0/fw-health snapshot 1 address 0 length 16 66*4882a593Smuzhiyun 0000000000000000 0014 95dc 0014 9514 0035 1670 0034 db30 67*4882a593Smuzhiyun 68*4882a593SmuzhiyunAs regions are likely very device or driver specific, no generic regions are 69*4882a593Smuzhiyundefined. See the driver-specific documentation files for information on the 70*4882a593Smuzhiyunspecific regions a driver supports. 71