Documentation/networking/devlink/index.rst

   1 Linux Devlink Documentation
   2 ===========================
   3
   4 devlink is an API to expose device information and resources not directly
   5 related to any device class, such as chip-wide/switch-ASIC-wide configuration.
   6
   7 Locking
   8 -------
   9
  10 Driver facing APIs are currently transitioning to allow more explicit
  11 locking. Drivers can use the existing ``devlink_*`` set of APIs, or
  12 new APIs prefixed by ``devl_*``. The older APIs handle all the locking
  13 in devlink core, but don't allow registration of most sub-objects once
  14 the main devlink object is itself registered. The newer ``devl_*`` APIs assume
  15 the devlink instance lock is already held. Drivers can take the instance
  16 lock by calling ``devl_lock()``. It is also held all callbacks of devlink
  17 netlink commands.
  18
  19 Drivers are encouraged to use the devlink instance lock for their own needs.
  20
  21 Drivers need to be cautious when taking devlink instance lock and
  22 taking RTNL lock at the same time. Devlink instance lock needs to be taken
  23 first, only after that RTNL lock could be taken.
  24
  25 Nested instances
  26 ----------------
  27
  28 Some objects, like linecards or port functions, could have another
  29 devlink instances created underneath. In that case, drivers should make
  30 sure 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
  46 The nested devlink info is exposed to the userspace over object-specific
  47 attributes of devlink netlink.
  48
  49 Interface documentation
  50 -----------------------
  51
  52 The following pages describe various interfaces available through devlink in
  53 general.
  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
  72 Driver-specific documentation
  73 -----------------------------
  74
  75 Each driver that implements ``devlink`` is expected to document what
  76 parameters, 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    mlx4
  88    mlx5
  89    mlxsw
  90    mv88e6xxx
  91    netdevsim
  92    nfp
  93    qed
  94    ti-cpsw-switch
  95    am65-nuss-cpsw-switch
  96    prestera
  97    iosm
  98    octeontx2
  99    sfc