Orange Pi5 kernel

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