Documentation/networking/devlink/devlink-region.rst

   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.