1Linux Devlink Documentation
2===========================
3
4devlink is an API to expose device information and resources not directly
5related to any device class, such as chip-wide/switch-ASIC-wide configuration.
6
7Locking
8-------
9
10Driver facing APIs are currently transitioning to allow more explicit
11locking. Drivers can use the existing ``devlink_*`` set of APIs, or
12new APIs prefixed by ``devl_*``. The older APIs handle all the locking
13in devlink core, but don't allow registration of most sub-objects once
14the main devlink object is itself registered. The newer ``devl_*`` APIs assume
15the devlink instance lock is already held. Drivers can take the instance
16lock by calling ``devl_lock()``. It is also held all callbacks of devlink
17netlink commands.
18
19Drivers are encouraged to use the devlink instance lock for their own needs.
20
21Drivers need to be cautious when taking devlink instance lock and
22taking RTNL lock at the same time. Devlink instance lock needs to be taken
23first, only after that RTNL lock could be taken.
24
25Nested instances
26----------------
27
28Some objects, like linecards or port functions, could have another
29devlink instances created underneath. In that case, drivers should make
30sure to respect following rules:
31
32 - Lock ordering should be maintained. If driver needs to take instance
33   lock of both nested and parent instances at the same time, devlink
34   instance lock of the parent instance should be taken first, only then
35   instance lock of the nested instance could be taken.
36 - Driver should use object-specific helpers to setup the
37   nested relationship:
38
39   - ``devl_nested_devlink_set()`` - called to setup devlink -> nested
40     devlink relationship (could be user for multiple nested instances.
41   - ``devl_port_fn_devlink_set()`` - called to setup port function ->
42     nested devlink relationship.
43   - ``devlink_linecard_nested_dl_set()`` - called to setup linecard ->
44     nested devlink relationship.
45
46The nested devlink info is exposed to the userspace over object-specific
47attributes of devlink netlink.
48
49Interface documentation
50-----------------------
51
52The following pages describe various interfaces available through devlink in
53general.
54
55.. toctree::
56   :maxdepth: 1
57
58   devlink-dpipe
59   devlink-health
60   devlink-info
61   devlink-flash
62   devlink-params
63   devlink-port
64   devlink-region
65   devlink-resource
66   devlink-reload
67   devlink-selftests
68   devlink-trap
69   devlink-linecard
70   devlink-eswitch-attr
71
72Driver-specific documentation
73-----------------------------
74
75Each driver that implements ``devlink`` is expected to document what
76parameters, info versions, and other features it supports.
77
78.. toctree::
79   :maxdepth: 1
80
81   bnxt
82   etas_es58x
83   hns3
84   i40e
85   ionic
86   ice
87   ixgbe
88   kvaser_pciefd
89   kvaser_usb
90   mlx4
91   mlx5
92   mlxsw
93   mv88e6xxx
94   netdevsim
95   nfp
96   qed
97   ti-cpsw-switch
98   am65-nuss-cpsw-switch
99   prestera
100   iosm
101   octeontx2
102   sfc
103   zl3073x
104