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
  71 Driver-specific documentation
  72 -----------------------------
  73
  74 Each driver that implements ``devlink`` is expected to document what
  75 parameters, info versions, and other features it supports.
  76
  77 .. toctree::
  78    :maxdepth: 1
  79
  80    bnxt
  81    etas_es58x
  82    hns3
  83    i40e
  84    ionic
  85    ice
  86    mlx4
  87    mlx5
  88    mlxsw
  89    mv88e6xxx
  90    netdevsim
  91    nfp
  92    qed
  93    ti-cpsw-switch
  94    am65-nuss-cpsw-switch
  95    prestera
  96    iosm
  97    octeontx2
  98    sfc