xref: /linux/Documentation/networking/devlink/devlink-resource.rst (revision 3d2c3d2eea9acdbee5b5742d15d021069b49d3f9) 
1.. SPDX-License-Identifier: GPL-2.0
2
3================
4Devlink Resource
5================
6
7``devlink`` provides the ability for drivers to register resources, which
8can allow administrators to see the device restrictions for a given
9resource, as well as how much of the given resource is currently
10in use. Additionally, these resources can optionally have configurable size.
11This could enable the administrator to limit the number of resources that
12are used.
13
14For example, the ``netdevsim`` driver enables ``/IPv4/fib`` and
15``/IPv4/fib-rules`` as resources to limit the number of IPv4 FIB entries and
16rules for a given device.
17
18Resource Ids
19============
20
21Each resource is represented by an id, and contains information about its
22current size and related sub resources. To access a sub resource, you
23specify the path of the resource. For example ``/IPv4/fib`` is the id for
24the ``fib`` sub-resource under the ``IPv4`` resource.
25
26Generic Resources
27=================
28
29Generic resources are used to describe resources that can be shared by multiple
30device drivers and their description must be added to the following table:
31
32.. list-table:: List of Generic Resources
33   :widths: 10 90
34
35   * - Name
36     - Description
37   * - ``physical_ports``
38     - A limited capacity of physical ports that the switch ASIC can support
39
40example usage
41-------------
42
43The resources exposed by the driver can be observed, for example:
44
45.. code:: shell
46
47    $devlink resource show pci/0000:03:00.0
48    pci/0000:03:00.0:
49      name kvd size 245760 unit entry
50        resources:
51          name linear size 98304 occ 0 unit entry size_min 0 size_max 147456 size_gran 128
52          name hash_double size 60416 unit entry size_min 32768 size_max 180224 size_gran 128
53          name hash_single size 87040 unit entry size_min 65536 size_max 212992 size_gran 128
54
55Some resource's size can be changed. Examples:
56
57.. code:: shell
58
59    $devlink resource set pci/0000:03:00.0 path /kvd/hash_single size 73088
60    $devlink resource set pci/0000:03:00.0 path /kvd/hash_double size 74368
61
62The changes do not apply immediately, this can be validated by the 'size_new'
63attribute, which represents the pending change in size. For example:
64
65.. code:: shell
66
67    $devlink resource show pci/0000:03:00.0
68    pci/0000:03:00.0:
69      name kvd size 245760 unit entry size_valid false
70      resources:
71        name linear size 98304 size_new 147456 occ 0 unit entry size_min 0 size_max 147456 size_gran 128
72        name hash_double size 60416 unit entry size_min 32768 size_max 180224 size_gran 128
73        name hash_single size 87040 unit entry size_min 65536 size_max 212992 size_gran 128
74
75Note that changes in resource size may require a device reload to properly
76take effect.
77
78Port-level Resources and Full Dump
79==================================
80
81In addition to device-level resources, ``devlink`` also supports port-level
82resources. These resources are associated with a specific devlink port rather
83than the device as a whole.
84
85To list resources for all devlink devices and ports:
86
87.. code:: shell
88
89    $ devlink resource show
90    pci/0000:03:00.0:
91      name max_local_SFs size 128 unit entry dpipe_tables none
92      name max_external_SFs size 128 unit entry dpipe_tables none
93    pci/0000:03:00.0/196608:
94      name max_SFs size 128 unit entry dpipe_tables none
95    pci/0000:03:00.0/196609:
96      name max_SFs size 128 unit entry dpipe_tables none
97    pci/0000:03:00.1:
98      name max_local_SFs size 128 unit entry dpipe_tables none
99      name max_external_SFs size 128 unit entry dpipe_tables none
100    pci/0000:03:00.1/196708:
101      name max_SFs size 128 unit entry dpipe_tables none
102    pci/0000:03:00.1/196709:
103      name max_SFs size 128 unit entry dpipe_tables none
104
105To show resources for a specific port:
106
107.. code:: shell
108
109    $ devlink resource show pci/0000:03:00.0/196608
110    pci/0000:03:00.0/196608:
111      name max_SFs size 128 unit entry dpipe_tables none
112
113Resource Scope Filtering
114========================
115
116When dumping resources for all devices, ``devlink resource show`` accepts
117an optional ``scope`` parameter to restrict the response to device-level
118resources, port-level resources, or both (the default).
119
120To dump only device-level resources across all devices:
121
122.. code:: shell
123
124    $ devlink resource show scope dev
125    pci/0000:03:00.0:
126      name max_local_SFs size 128 unit entry dpipe_tables none
127      name max_external_SFs size 128 unit entry dpipe_tables none
128    pci/0000:03:00.1:
129      name max_local_SFs size 128 unit entry dpipe_tables none
130      name max_external_SFs size 128 unit entry dpipe_tables none
131
132To dump only port-level resources across all devices:
133
134.. code:: shell
135
136    $ devlink resource show scope port
137    pci/0000:03:00.0/196608:
138      name max_SFs size 128 unit entry dpipe_tables none
139    pci/0000:03:00.0/196609:
140      name max_SFs size 128 unit entry dpipe_tables none
141    pci/0000:03:00.1/196708:
142      name max_SFs size 128 unit entry dpipe_tables none
143    pci/0000:03:00.1/196709:
144      name max_SFs size 128 unit entry dpipe_tables none
145
146Note that port-level resources are read-only.
147