| 1 | |
| 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.
|