index.rst

  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-eswitch-attr
 60   devlink-flash
 61   devlink-health
 62   devlink-info
 63   devlink-linecard
 64   devlink-params
 65   devlink-port
 66   devlink-region
 67   devlink-reload
 68   devlink-resource
 69   devlink-selftests
 70   devlink-trap
 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   am65-nuss-cpsw-switch
 82   bnxt
 83   etas_es58x
 84   hns3
 85   i40e
 86   ice
 87   ionic
 88   iosm
 89   ixgbe
 90   kvaser_pciefd
 91   kvaser_usb
 92   mlx4
 93   mlx5
 94   mlxsw
 95   mv88e6xxx
 96   netdevsim
 97   nfp
 98   octeontx2
 99   prestera
100   qed
101   sfc
102   stmmac
103   ti-cpsw-switch
104   zl3073x