Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1.. SPDX-License-Identifier: GPL-2.0+
2
3============================
4DRM RAS over Generic Netlink
5============================
6
7The DRM RAS (Reliability, Availability, Serviceability) interface provides a
8standardized way for GPU/accelerator drivers to expose error counters and
9other reliability nodes to user space via Generic Netlink. This allows
10diagnostic tools, monitoring daemons, or test infrastructure to query hardware
11health in a uniform way across different DRM drivers.
12
13Key Goals:
14
15* Provide a standardized RAS solution for GPU and accelerator drivers, enabling
16 data center monitoring and reliability operations.
17* Implement a single drm-ras Generic Netlink family to meet modern Netlink YAML
18 specifications and centralize all RAS-related communication in one namespace.
19* Support a basic error counter interface, addressing the immediate, essential
20 monitoring needs.
21* Offer a flexible, future-proof interface that can be extended to support
22 additional types of RAS data in the future.
23* Allow multiple nodes per driver, enabling drivers to register separate
24 nodes for different IP blocks, sub-blocks, or other logical subdivisions
25 as applicable.
26
27Nodes
28=====
29
30Nodes are logical abstractions representing an error type or error source within
31the device. Currently, only error counter nodes is supported.
32
33Drivers are responsible for registering and unregistering nodes via the
34`drm_ras_node_register()` and `drm_ras_node_unregister()` APIs.
35
36Node Management
37-------------------
38
39.. kernel-doc:: drivers/gpu/drm/drm_ras.c
40 :doc: DRM RAS Node Management
41.. kernel-doc:: drivers/gpu/drm/drm_ras.c
42 :internal:
43
44Generic Netlink Usage
45=====================
46
47The interface is implemented as a Generic Netlink family named ``drm-ras``.
48User space tools can:
49
50* List registered nodes with the ``list-nodes`` command.
51* List all error counters in an node with the ``get-error-counter`` command with ``node-id``
52 as a parameter.
53* Query specific error counter values with the ``get-error-counter`` command, using both
54 ``node-id`` and ``error-id`` as parameters.
55
56YAML-based Interface
57--------------------
58
59The interface is described in a YAML specification ``Documentation/netlink/specs/drm_ras.yaml``
60
61This YAML is used to auto-generate user space bindings via
62``tools/net/ynl/pyynl/ynl_gen_c.py``, and drives the structure of netlink
63attributes and operations.
64
65Usage Notes
66-----------
67
68* User space must first enumerate nodes to obtain their IDs.
69* Node IDs or Node names can be used for all further queries, such as error counters.
70* Error counters can be queried by either the Error ID or Error name.
71* Query Parameters should be defined as part of the uAPI to ensure user interface stability.
72* The interface supports future extension by adding new node types and
73 additional attributes.
74
75Example: List nodes using ynl
76
77.. code-block:: bash
78
79 sudo ynl --family drm_ras --dump list-nodes
80 [{'device-name': '0000:03:00.0',
81 'node-id': 0,
82 'node-name': 'correctable-errors',
83 'node-type': 'error-counter'},
84 {'device-name': '0000:03:00.0',
85 'node-id': 1,
86 'node-name': 'uncorrectable-errors',
87 'node-type': 'error-counter'}]
88
89Example: List all error counters using ynl
90
91.. code-block:: bash
92
93 sudo ynl --family drm_ras --dump get-error-counter --json '{"node-id":0}'
94 [{'error-id': 1, 'error-name': 'error_name1', 'error-value': 0},
95 {'error-id': 2, 'error-name': 'error_name2', 'error-value': 0}]
96
97Example: Query an error counter for a given node
98
99.. code-block:: bash
100
101 sudo ynl --family drm_ras --do get-error-counter --json '{"node-id":0, "error-id":1}'
102 {'error-id': 1, 'error-name': 'error_name1', 'error-value': 0}
103