[PATCH v1 1/2] doc: add devargs documentation

[PATCH v1 1/2] doc: add devargs documentation

[Anatoly Burakov]

Currently, the devargs syntax documentation is missing from the
programmer's guide, and is only documented implicitly through the devargs
API headers. Add a detailed description of the two supported devargs
syntaxes.

Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
---
 doc/guides/prog_guide/dev_args.rst | 243 +++++++++++++++++++++++++++++
 doc/guides/prog_guide/index.rst    |   1 +
 2 files changed, 244 insertions(+)
 create mode 100644 doc/guides/prog_guide/dev_args.rst

diff --git a/doc/guides/prog_guide/dev_args.rst b/doc/guides/prog_guide/dev_args.rst
new file mode 100644
index 0000000000..2997bcdbd3
--- /dev/null
+++ b/doc/guides/prog_guide/dev_args.rst
@@ -0,0 +1,243 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2025 Intel Corporation.
+
+.. _device_arguments:
+
+Device Arguments
+================
+
+Introduction
+------------
+
+Device arguments (devargs) provide a standardized way to specify and configure devices in DPDK applications.
+Devargs are used both at EAL initialization time (via command-line options) and at runtime (via hotplug APIs) to identify devices and pass configuration parameters to them.
+
+A devargs string can specify identifiers and arguments at multiple levels:
+
+* **Bus identifier and arguments**: Which bus handles the device (e.g., ``pci``, ``vdev``) and bus-level parameters
+* **Class identifier and arguments**: Device class (e.g., ``eth``, ``crypto``) and class-level parameters
+* **Driver identifier and arguments**: The specific driver and its driver-specific parameters
+
+DPDK supports two devargs syntaxes:
+
+1. **Simplified syntax** - For common case targeting a specific device.
+2. **Multi-layer syntax** - For device filtering by bus, class, or driver.
+
+
+Devargs Syntax
+--------------
+
+Device-centric syntax
+~~~~~~~~~~~~~~~~~~~~~
+
+In most cases, devargs can be used with simplified format that targets specific devices:
+
+.. code-block:: none
+
+   [bus:]device_identifier[,arg1=val1,arg2=val2,...]
+
+Where:
+
+* ``bus:`` is an optional prefix specifying the bus name (pci, vdev, auxiliary, etc.)
+* ``device_identifier`` uniquely identifies the device on its bus
+* ``arg1=val1,arg2=val2,...`` are optional driver-specific configuration parameters
+
+The arguments are provided to the driver, but the driver name itself is inferred from the device and does not need to be specified.
+
+**Examples**:
+
+.. code-block:: none
+
+   0000:02:00.0                          # PCI device, no arguments
+   0000:02:00.0,txq_inline=128           # PCI device with driver arguments
+   pci:0000:02:00.0                      # Explicit bus prefix
+   net_ring0                             # Virtual device
+   vdev:net_pcap0,rx_pcap=input.pcap     # Virtual device with arguments and bus prefix
+
+If the bus prefix is omitted, DPDK tries each registered bus in turn to see if it can recognize the device identifier.
+
+
+Driver-centric Syntax
+~~~~~~~~~~~~~~~~~~~~~
+
+For advanced use cases that need to pass arguments to bus and/or class layers, or when matching multiple devices is required, DPDK supports a multi-layer syntax with three slash-separated segments:
+
+.. code-block:: none
+
+   bus=<busname>,<bus_args>/class=<classname>,<class_args>/driver=<drvname>,<driver_args>
+
+This allows the user to specify:
+
+* ``bus`` layer: bus identifier, as well as bus-level arguments
+* ``class`` layer: class identifier, as well as class-level arguments
+* ``driver`` layer: driver identifier, as well as driver-specific parameters
+
+.. note::
+   By default, multi-layer syntax is driver-centric and will apply to all devices using a particular bus, class, and driver combination.
+   To target a specific device, a device-identifying argument should be provided to the bus layer. The specific key depends on the bus:
+   for PCI use ``addr=`` (e.g. ``bus=pci,addr=0000:02:00.0``), for most other buses use ``name=`` (e.g. ``bus=vdev,name=net_ring0``).
+
+**Example**:
+
+.. code-block:: none
+
+   bus=pci/class=eth/driver=ice,representor=[0-3]
+
+The above example will pass "representor=[0-3]" devarg to each device matching the provided criteria (PCI bus, Ethernet class, in use by ``ice`` driver).
+
+
+Virtual Device Arguments
+------------------------
+Virtual devices (vdevs) are software-based devices that don't correspond to physical hardware.
+Unlike PCI or other hardware buses where devices are discovered by scanning, virtual devices must be explicitly created by specifying their driver name.
+
+Understanding Virtual Device Naming
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A virtual device name consists of:
+
+1. **Driver name**: The vdev driver to use (e.g., ``net_ring``, ``net_pcap``, ``crypto_null``)
+2. **Instance identifier**: A numeric suffix to create multiple instances of the same driver
+
+**Format**:
+
+.. code-block:: none
+
+   [vdev:]<driver_name><instance_number>[,arg=val,...]
+
+**Examples**:
+
+Create a ring-based virtual port:
+
+.. code-block:: none
+
+   net_ring0
+
+Create a PCAP virtual device with input file:
+
+.. code-block:: none
+
+   net_pcap0,rx_pcap=input.pcap
+
+
+Using Devargs in Applications
+------------------------------
+
+At EAL Initialization
+~~~~~~~~~~~~~~~~~~~~~
+
+Devargs can be specified on the command line when starting a DPDK application:
+
+**Allow-list (permit specific devices)**:
+
+.. code-block:: console
+
+   ./myapp -a 0000:02:00.0 -a 0000:03:00.0,txq_inline=128
+
+**Block-list (exclude specific devices)**:
+
+.. code-block:: console
+
+   ./myapp -b 0000:04:00.0
+
+**Virtual devices**:
+
+.. code-block:: console
+
+   ./myapp --vdev net_ring0 --vdev 'net_pcap0,rx_pcap=input.pcap'
+
+See :doc:`../linux_gsg/linux_eal_parameters` for complete EAL parameter documentation.
+
+At Runtime (Hotplug)
+~~~~~~~~~~~~~~~~~~~~
+
+Devargs are used with hotplug APIs to attach devices dynamically:
+
+.. code-block:: c
+
+   #include <rte_dev.h>
+
+   /* Attach a PCI device */
+   ret = rte_dev_probe("0000:05:00.0");
+
+   /* Attach a virtual device */
+   ret = rte_dev_probe("net_ring1");
+
+   /* Attach with arguments */
+   ret = rte_dev_probe("0000:05:00.0,txq_inline=256");
+
+Parsing Devargs in Drivers
+---------------------------
+
+PMD drivers can parse devargs using the kvargs library:
+
+.. code-block:: c
+
+   #include <rte_kvargs.h>
+
+   static int
+   my_driver_parse_devargs(struct rte_devargs *devargs)
+   {
+       struct rte_kvargs *kvlist;
+       const char *valid_args[] = {"arg1", "arg2", NULL};
+
+       if (devargs == NULL || devargs->args == NULL)
+           return 0;
+
+       kvlist = rte_kvargs_parse(devargs->args, valid_args);
+       if (kvlist == NULL) {
+           RTE_LOG(ERR, PMD, "Failed to parse devargs\n");
+           return -EINVAL;
+       }
+
+       /* Process each argument */
+       rte_kvargs_process(kvlist, "arg1", my_arg1_handler, NULL);
+       rte_kvargs_process(kvlist, "arg2", my_arg2_handler, NULL);
+
+       rte_kvargs_free(kvlist);
+       return 0;
+   }
+
+For Ethernet devices, use ``rte_eth_devargs_parse()`` to parse standard Ethernet arguments like representors:
+
+.. code-block:: c
+
+   struct rte_eth_devargs eth_da[RTE_MAX_ETHPORTS];
+   int n_devargs;
+
+   n_devargs = rte_eth_devargs_parse(devargs_str, eth_da, RTE_MAX_ETHPORTS);
+   if (n_devargs < 0) {
+       /* Handle error */
+   }
+
+Finding Devices by Devargs
+--------------------------
+
+Iterator helpers accept a devargs-style filter. Examples:
+
+.. code-block:: c
+
+   RTE_DEV_FOREACH(dev, "bus=pci", &it) {
+      /* Handle each PCI device */
+   }
+
+   /* Ethernet devices can also be filtered by class */
+   RTE_ETH_FOREACH_MATCHING_DEV(port_id, "class=eth,mac=00:11:22:33:44:55", &it) {
+      /* Handle each Ethernet device */
+   }
+
+Summary
+-------
+
+Device arguments provide a flexible and standardized way to specify and configure devices in DPDK:
+
+* **Unified syntax**: Works across different bus types
+* **Runtime and initialization**: Can be used both at EAL init and for hotplug
+* **Driver configuration**: Supports arbitrary driver-specific parameters
+* **Complex specifications**: Multi-layer syntax allows device filtering and configuration at bus, class, and driver levels
+
+For more information, see:
+
+* :doc:`../linux_gsg/linux_eal_parameters` - EAL command-line parameters
+* API documentation: ``rte_devargs_parse()``, ``rte_devargs_layers_parse()`` (in ``rte_devargs.h``)
+* API documentation: ``rte_eth_devargs_parse()`` (in ``ethdev_driver.h``)
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index c0b5f54c26..866b7c5012 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -73,6 +73,7 @@ Device Libraries
     :maxdepth: 1
     :numbered:
 
+    dev_args
     ethdev/index
     link_bonding_poll_mode_drv_lib
     vhost_lib
-- 
2.47.3

[PATCH v1 2/2] doc: add device hotplug documentation

[Anatoly Burakov]

Currently, device hotplug is not documented except in API headers. Add
documentation for device hotplug, both for user facing side of it, and a
high level overview of its internal workings.

Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
---
 doc/guides/prog_guide/dev_args.rst       |   3 +
 doc/guides/prog_guide/device_hotplug.rst | 305 +++++++++++++++++++++++
 doc/guides/prog_guide/index.rst          |   1 +
 3 files changed, 309 insertions(+)
 create mode 100644 doc/guides/prog_guide/device_hotplug.rst

diff --git a/doc/guides/prog_guide/dev_args.rst b/doc/guides/prog_guide/dev_args.rst
index 2997bcdbd3..f888bcef17 100644
--- a/doc/guides/prog_guide/dev_args.rst
+++ b/doc/guides/prog_guide/dev_args.rst
@@ -166,6 +166,8 @@ Devargs are used with hotplug APIs to attach devices dynamically:
    /* Attach with arguments */
    ret = rte_dev_probe("0000:05:00.0,txq_inline=256");
 
+See :doc:`device_hotplug` for detailed information on runtime device management.
+
 Parsing Devargs in Drivers
 ---------------------------
 
@@ -239,5 +241,6 @@ Device arguments provide a flexible and standardized way to specify and configur
 For more information, see:
 
 * :doc:`../linux_gsg/linux_eal_parameters` - EAL command-line parameters
+* :doc:`device_hotplug` - Runtime device management
 * API documentation: ``rte_devargs_parse()``, ``rte_devargs_layers_parse()`` (in ``rte_devargs.h``)
 * API documentation: ``rte_eth_devargs_parse()`` (in ``ethdev_driver.h``)
diff --git a/doc/guides/prog_guide/device_hotplug.rst b/doc/guides/prog_guide/device_hotplug.rst
new file mode 100644
index 0000000000..16da8b4192
--- /dev/null
+++ b/doc/guides/prog_guide/device_hotplug.rst
@@ -0,0 +1,305 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2025 Intel Corporation.
+
+.. _device_hotplug:
+
+Device Hotplug
+==============
+
+Introduction
+------------
+
+Device hotplug refers to the ability to attach and detach devices at runtime, after the initial EAL initialization has completed.
+This feature allows applications to dynamically add or remove physical or virtual devices while the DPDK application is running.
+
+.. note::
+   Device hotplug does not support multiprocess operation nor kernel device event notifications on platforms other than Linux.
+
+
+Basic Usage
+-----------
+
+The primary interface for device hotplug is through two complementary functions: ``rte_dev_probe()`` to attach a device using a devargs string, and ``rte_dev_remove()`` to detach a device.
+For detailed information about device argument format and syntax, see :doc:`dev_args`.
+
+A typical workflow for attaching a device is:
+
+.. code-block:: c
+
+   /* Probe a PCI device with specific parameters */
+   ret = rte_dev_probe("0000:02:00.0,arg1=value1");
+   if (ret < 0) {
+       /* Handle error */
+   }
+
+   /* Later, find the device and remove it */
+   struct rte_device *dev = /* find device */;
+   ret = rte_dev_remove(dev);
+
+For convenience, DPDK also provides ``rte_eal_hotplug_add()`` and ``rte_eal_hotplug_remove()`` functions, which accept separate bus name, device name, and arguments instead of a combined devargs string:
+
+.. code-block:: c
+
+   /* Attach a virtual device */
+   rte_eal_hotplug_add("vdev", "net_ring0", "");
+
+   /* Remove by bus and device name */
+   rte_eal_hotplug_remove("vdev", "net_ring0");
+
+
+Device Lifecycle Example
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``testpmd`` application provides a reference implementation of device hotplug through the ``port attach`` and ``port detach`` commands, demonstrating proper device lifecycle management.
+
+The following example demonstrates attaching a virtual ring PMD Ethernet device, configuring it, and then detaching it:
+
+.. code-block:: c
+
+   char *devargs = "net_ring0";
+   struct rte_eth_dev_info info;
+   struct rte_dev_iterator iterator;
+   unsigned port_id;
+
+   /* Probe the device */
+   rte_dev_probe(devargs);
+
+   /* Enumerate newly attached ports */
+   RTE_ETH_FOREACH_MATCHING_DEV(port_id, devargs, &iterator) {
+      /* Get device handle */
+      rte_eth_dev_info_get(port_id, &info);
+
+      /* Set up the device and use it */
+   }
+
+   /* Stop the port */
+   rte_eth_dev_stop(port_id);
+
+   /* Remove the device */
+   ret = rte_dev_remove(info.device);
+
+The key steps in this lifecycle are:
+
+1. **Attach**: Call ``rte_dev_probe()`` with the device identifier
+2. **Find the device**: Use device iterators (such as ``RTE_ETH_FOREACH_MATCHING_DEV()``) to find newly attached port
+3. **Configure and use**: Configure the port using normal device configuration/start flow
+4. **Detach**: Stop the device before calling ``rte_dev_remove()``
+
+
+Device Events
+-------------
+
+In addition to providing generic hotplug infrastructure to be used in the above described manner, EAL also offers a device event infrastructure.
+
+.. warning::
+   Because all events are always delivered within the context of an interrupt thread, attempting any memory allocations/deallocations within that context may cause deadlocks.
+   Therefore, it is recommended to set up a deferred application resource allocation/cleanup with ``rte_eal_alarm_set()`` API or otherwise trigger allocation/cleanup of application resources in another context.
+
+Ethernet Device Events
+~~~~~~~~~~~~~~~~~~~~~~
+
+When new Ethernet devices are added (hot plugged using device probe API) to EAL or removed (hot unplugged using device remove API) from EAL, the following events are delivered:
+
+* ``RTE_ETH_EVENT_NEW`` - delivered after device probe
+* ``RTE_ETH_EVENT_DESTROY`` - delivered after device removal
+
+The user may subscribe to these events using ``rte_eth_dev_callback_register()`` function.
+
+
+Kernel Device Events
+~~~~~~~~~~~~~~~~~~~~
+
+EAL may also subscribe to generic device events delivered from kernel uevent infrastructure. The following events are delivered:
+
+* ``RTE_DEV_EVENT_ADD`` - delivered whenever a new device becomes available for probing
+* ``RTE_DEV_EVENT_REMOVE`` - delivered whenever a device becomes unavailable (device failure, hot unplug, etc.)
+
+The kernel event monitoring is not enabled by default, so before using this feature the user must do the following:
+
+* Call ``rte_dev_hotplug_handle_enable()`` to enable ``SIGBUS`` handling in EAL for devices that were hot-unplugged
+* Call ``rte_dev_event_monitor_start()`` to enable kernel device event monitoring
+
+The user may then subscribe to kernel device events using ``rte_dev_event_callback_register()`` function.
+
+.. note::
+   Currently, for ``RTE_DEV_EVENT_ADD``, only PCI devices are monitored
+
+.. note::
+   The ``RTE_DEV_EVENT_ADD`` by itself does not probe the device, it is only a notification that the application may use ``rte_dev_probe()`` on the device in question.
+   When ``RTE_DEV_EVENT_REMOVE`` event is delivered, the EAL has already released all internal resources associated with the device.
+
+
+Event Notification Usage
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Example generic device event callback with deferred probe:
+
+.. code-block:: c
+
+   void
+   deferred_attach(void *arg)
+   {
+       const char *devname = (const char *)arg;
+       rte_dev_probe(devname);
+       /* match strdup with free */
+       free(devname);
+   }
+
+   int
+   device_event_callback(const char *device_name,
+                         enum rte_dev_event_type event,
+                         void *cb_arg)
+   {
+       if (event == RTE_DEV_EVENT_ADD) {
+           /* Schedule deferred attach - don't call rte_dev_probe() here! */
+           char *devname = strdup(device_name);
+           if (rte_eal_alarm_set(1, deferred_attach, devname) < 0) {
+               /* error */
+           }
+       } else if (event == RTE_DEV_EVENT_REMOVE) {
+           /* Handle device removal - schedule cleanup if needed */
+       }
+       return 0;
+   }
+
+   rte_dev_event_callback_register(NULL, device_event_callback, user_arg);  /* NULL = all devices */
+
+
+Implementation Details
+======================
+
+Attach and Detach
+-----------------
+
+When ``rte_dev_probe()`` is called, the following sequence occurs:
+
+1. **Devargs Parsing**:
+   The devargs string is parsed to extract the bus name, device name, and driver arguments, which are stored in an ``rte_devargs`` structure and inserted into the global devargs list.
+
+2. **Bus Scan**:
+   The appropriate bus driver's ``scan()`` method is invoked, causing the bus to search for the device.
+   For PCI devices, this may involve scanning the sysfs filesystem, while for virtual devices, this may create the device structure directly.
+
+3. **Device Discovery**:
+   After scanning, the bus's ``find_device()`` method locates the device by name, and the attach operation fails if the device is not found.
+
+4. **Device Probe**:
+   The bus's ``plug()`` method is called, which triggers the device driver's probe function.
+   The probe function typically allocates device-specific resources, maps device memory regions, initializes device hardware, and registers the device with the appropriate subsystem (e.g., ethdev for network devices).
+
+5. **Multi-process Synchronization**:
+   If successful in the primary process, an IPC message is sent to all secondary processes to attach the same device.
+   See `Multi-process Synchronization`_ for details.
+
+
+When ``rte_dev_remove()`` is called, the following sequence occurs:
+
+1. **Device Validation**:
+   The function verifies that the device is currently probed using ``rte_dev_is_probed()``.
+
+2. **Multi-process Coordination**:
+   In multi-process scenarios, the primary process first coordinates with all secondary processes to detach the device, and only if all secondaries successfully detach does the primary proceed.
+   See `Multi-process Synchronization`_ for details.
+
+3. **Device Unplug**:
+   The bus's ``unplug()`` method is called (``dev->bus->unplug()``), which triggers the driver's remove function.
+   This typically stops device operations, releases device resources, unmaps memory regions, and unregisters from subsystems.
+
+4. **Devargs Cleanup**:
+   The devargs associated with the device are removed from the global list.
+
+
+Multi-process Synchronization
+-----------------------------
+
+DPDK's hotplug implementation ensures that devices are attached or detached consistently across all processes in a multi-process deployment.
+Both primary and secondary processes can initiate hotplug operations (by calling ``rte_dev_probe()`` or ``rte_dev_remove()``), which will be synchronized across all processes.
+
+.. note::
+   Multiprocess operations are only supported on Linux
+
+**When Application Initiates from Primary**:
+
+1. Primary performs the local operation
+2. Primary broadcasts the request to all secondaries using IPC
+3. Primary waits for replies from all secondaries with a timeout
+4. If all secondaries succeed, the operation is complete
+5. If any secondary fails, primary initiates rollback
+
+**When Application Initiates from Secondary**:
+
+1. Secondary sends attach/detach request to primary via IPC
+2. Primary receives the request and performs the local operation
+3. Primary broadcasts the request to all other secondaries
+4. Primary waits for replies from all secondaries
+5. If all succeed, primary sends success reply to the requesting secondary
+6. If any fail, primary initiates rollback and sends failure reply to the requesting secondary
+
+**Secondary Process Flow** (when receiving request from primary):
+
+1. Secondary receives IPC request from primary
+2. Secondary performs the local attach/detach operation
+3. Secondary sends reply with success or failure status
+
+Rollback on Failure
+~~~~~~~~~~~~~~~~~~~
+
+If any step in the attach or detach process fails in a multi-process scenario, DPDK attempts to rollback the operation.
+For attach failures, the primary process sends rollback requests to detach the device from all secondary processes where it succeeded.
+For detach failures, the primary process sends rollback requests to all secondary processes to re-attach the device, restoring the previous state.
+
+Virtual Devices and Multi-process
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Virtual devices have special handling in multi-process scenarios.
+
+During initial startup, when a secondary process starts, it sends a scan request to the primary process via IPC, and the primary responds by sending the list of all virtual devices it has created.
+This synchronization happens during the bus scan phase.
+Unlike physical devices where both processes can independently discover hardware, virtual devices only exist in memory, so secondaries must obtain the device list from the primary.
+
+At runtime, virtual devices can be hotplugged from either primary or secondary processes using the standard hotplug flow described above, and will be synchronized across all processes.
+Note that secondary processes can specify virtual devices via ``--vdev`` on the command line during initialization, which creates process-local devices, but runtime hotplug operations using ``rte_dev_probe()`` always synchronize devices across all processes.
+
+
+Kernel Uevent Handling (Linux only)
+-----------------------------------
+
+DPDK's device event monitoring works by listening to Linux kernel uevents via a netlink socket. The application must explicitly start monitoring by calling ``rte_dev_event_monitor_start()``.
+When ``rte_dev_event_monitor_start()`` is called, DPDK creates a ``NETLINK_KOBJECT_UEVENT`` socket that receives notifications from the kernel about device state changes.
+
+The mechanism works as follows:
+
+1. **Netlink Socket Creation**: DPDK creates a netlink socket bound to receive all kernel kobject uevents (``nl_groups = 0xffffffff``).
+2. **Uevent Reception**: When a device is added or removed, the Linux kernel broadcasts a uevent message containing:
+   - ``ACTION=add`` or ``ACTION=remove``
+   - ``SUBSYSTEM=pci``, ``uio``, or ``vfio``
+   - ``PCI_SLOT_NAME=<device>`` (e.g., ``0000:02:00.0``)
+3. **Event Parsing**: DPDK parses these messages to extract the device name, action type, and subsystem, then invokes registered application callbacks.
+4. **Interrupt-driven**: The socket is registered with DPDK's interrupt framework, so uevent handling is asynchronous and doesn't require polling.
+
+This infrastructure only monitors physical devices managed by the kernel. Virtual devices created by DPDK do not generate kernel uevents.
+
+SIGBUS Handling
+---------------
+
+If the application attempts to access memory-mapped device registers after the device is removed, a ``SIGBUS`` signal may be generated.
+The ``rte_dev_hotplug_handle_enable()`` function registers a signal handler that identifies which device caused the fault using the faulting address, invokes the bus's signal handler to handle the error, and allows the application to continue rather than crashing.
+
+Summary
+=======
+
+DPDK's device hotplug infrastructure provides runtime device management for applications.
+The following facilities are available to applications (subject to platform support):
+
+* **Devargs-based API**: ``rte_dev_probe()`` / ``rte_dev_remove()`` or ``rte_eal_hotplug_add()`` / ``rte_eal_hotplug_remove()``.
+* **Multi-process Safe**: Synchronization of device awareness across all DPDK processes.
+* **Bus Agnostic**: Works with PCI, virtual (vdev), and most other bus types.
+* **Graceful and Forcible**: Supports both application-initiated and event-driven device addition/removal.
+
+For additional examples, see:
+
+* Testpmd application (``app/test-pmd/testpmd.c``) - ``attach_port()`` and ``detach_device()``
+* Multi-process hotplug example (``examples/multi_process/hotplug_mp/``)
+* Fail-safe PMD (``drivers/net/failsafe/``) - Uses hotplug for redundancy
+
+For device-specific considerations, consult the appropriate device documentation in :doc:`ethdev/index` or other device library documentation.
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index 866b7c5012..7388c11d8f 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -74,6 +74,7 @@ Device Libraries
     :numbered:
 
     dev_args
+    device_hotplug
     ethdev/index
     link_bonding_poll_mode_drv_lib
     vhost_lib
-- 
2.47.3

Re: [PATCH v1 1/2] doc: add devargs documentation

[Thomas Monjalon]

14/11/2025 13:13, Anatoly Burakov:
> Currently, the devargs syntax documentation is missing from the
> programmer's guide, and is only documented implicitly through the devargs
> API headers. Add a detailed description of the two supported devargs
> syntaxes.

Thank you for writing this. It is really important.

> +* **Bus identifier and arguments**: Which bus handles the device (e.g., ``pci``, ``vdev``) and bus-level parameters
> +* **Class identifier and arguments**: Device class (e.g., ``eth``, ``crypto``) and class-level parameters
> +* **Driver identifier and arguments**: The specific driver and its driver-specific parameters
> +
> +DPDK supports two devargs syntaxes:
> +
> +1. **Simplified syntax** - For common case targeting a specific device.
> +2. **Multi-layer syntax** - For device filtering by bus, class, or driver.

I would prefer we see the last one as a generic syntax.
Others are shortcuts.

> +
> +
> +Devargs Syntax
> +--------------
> +
> +Device-centric syntax
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +In most cases, devargs can be used with simplified format that targets specific devices:
> +
> +.. code-block:: none
> +
> +   [bus:]device_identifier[,arg1=val1,arg2=val2,...]
[...]
> +Driver-centric Syntax
> +~~~~~~~~~~~~~~~~~~~~~

If you give a PCI address or a vdev name, it targets a device.

> +
> +For advanced use cases that need to pass arguments to bus and/or class layers, or when matching multiple devices is required, DPDK supports a multi-layer syntax with three slash-separated segments:
> +
> +.. code-block:: none
> +
> +   bus=<busname>,<bus_args>/class=<classname>,<class_args>/driver=<drvname>,<driver_args>

I think we should present this syntax first, with supported bus and class args.
Then we can present shortcuts equivalents with the old syntax.

[...]
> +Summary
> +-------
> +
> +Device arguments provide a flexible and standardized way to specify and configure devices in DPDK:
> +
> +* **Unified syntax**: Works across different bus types
> +* **Runtime and initialization**: Can be used both at EAL init and for hotplug
> +* **Driver configuration**: Supports arbitrary driver-specific parameters
> +* **Complex specifications**: Multi-layer syntax allows device filtering and configuration at bus, class, and driver levels

I'm not sur a summary is a good idea in such a documentation.
General statements are better viewed as intro.

You did a good job, but I think we should move things around to avoid confusion.
Please let's work on it together.
Thank you

Re: [PATCH v1 1/2] doc: add devargs documentation

[Burakov, Anatoly]

On 11/30/2025 4:44 PM, Thomas Monjalon wrote:
> 14/11/2025 13:13, Anatoly Burakov:
>> Currently, the devargs syntax documentation is missing from the
>> programmer's guide, and is only documented implicitly through the devargs
>> API headers. Add a detailed description of the two supported devargs
>> syntaxes.
> 
> Thank you for writing this. It is really important.
> 
>> +* **Bus identifier and arguments**: Which bus handles the device (e.g., ``pci``, ``vdev``) and bus-level parameters
>> +* **Class identifier and arguments**: Device class (e.g., ``eth``, ``crypto``) and class-level parameters
>> +* **Driver identifier and arguments**: The specific driver and its driver-specific parameters
>> +
>> +DPDK supports two devargs syntaxes:
>> +
>> +1. **Simplified syntax** - For common case targeting a specific device.
>> +2. **Multi-layer syntax** - For device filtering by bus, class, or driver.
> 
> I would prefer we see the last one as a generic syntax.
> Others are shortcuts.
> 
>> +
>> +
>> +Devargs Syntax
>> +--------------
>> +
>> +Device-centric syntax
>> +~~~~~~~~~~~~~~~~~~~~~
>> +
>> +In most cases, devargs can be used with simplified format that targets specific devices:
>> +
>> +.. code-block:: none
>> +
>> +   [bus:]device_identifier[,arg1=val1,arg2=val2,...]
> [...]
>> +Driver-centric Syntax
>> +~~~~~~~~~~~~~~~~~~~~~
> 
> If you give a PCI address or a vdev name, it targets a device.
> 
>> +
>> +For advanced use cases that need to pass arguments to bus and/or class layers, or when matching multiple devices is required, DPDK supports a multi-layer syntax with three slash-separated segments:
>> +
>> +.. code-block:: none
>> +
>> +   bus=<busname>,<bus_args>/class=<classname>,<class_args>/driver=<drvname>,<driver_args>
> 
> I think we should present this syntax first, with supported bus and class args.
> Then we can present shortcuts equivalents with the old syntax.
> 
> [...]
>> +Summary
>> +-------
>> +
>> +Device arguments provide a flexible and standardized way to specify and configure devices in DPDK:
>> +
>> +* **Unified syntax**: Works across different bus types
>> +* **Runtime and initialization**: Can be used both at EAL init and for hotplug
>> +* **Driver configuration**: Supports arbitrary driver-specific parameters
>> +* **Complex specifications**: Multi-layer syntax allows device filtering and configuration at bus, class, and driver levels
> 
> I'm not sur a summary is a good idea in such a documentation.
> General statements are better viewed as intro.
> 
> You did a good job, but I think we should move things around to avoid confusion.
> Please let's work on it together.
> Thank you

Hi Thomas,

Agreed on all points. I'll prepare a v2 addressing feedback. Thanks for 
your review!

-- 
Thanks,
Anatoly

[PATCH v2 1/2] doc: add devargs documentation

[Anatoly Burakov]

Currently, the devargs syntax documentation is missing from the
programmer's guide, and is only documented implicitly through the devargs
API headers. Add a detailed description of the two supported devargs
syntaxes.

Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
---

Notes:
    v2:
    - Made generic syntax the primary syntax
    - Removed summary
    - Moved index link to after ethdev/index

 doc/guides/prog_guide/dev_args.rst | 234 +++++++++++++++++++++++++++++
 doc/guides/prog_guide/index.rst    |   1 +
 2 files changed, 235 insertions(+)
 create mode 100644 doc/guides/prog_guide/dev_args.rst

diff --git a/doc/guides/prog_guide/dev_args.rst b/doc/guides/prog_guide/dev_args.rst
new file mode 100644
index 0000000000..a8025d383b
--- /dev/null
+++ b/doc/guides/prog_guide/dev_args.rst
@@ -0,0 +1,234 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2025 Intel Corporation.
+
+.. _device_arguments:
+
+Device Arguments
+================
+
+Introduction
+------------
+
+Device arguments (devargs) provide a standardized way to specify and configure devices in DPDK applications.
+Devargs are used both at EAL initialization time (via command-line options) and at runtime (via hotplug APIs) to identify devices and pass configuration parameters to them.
+
+A devargs string can specify identifiers and arguments at multiple levels:
+
+* **Bus identifier and arguments**: Which bus handles the device (e.g., ``pci``, ``vdev``) and bus-level parameters
+* **Class identifier and arguments**: Device class (e.g., ``eth``, ``crypto``) and class-level parameters
+* **Driver identifier and arguments**: The specific driver and its driver-specific parameters
+
+DPDK supports two devargs syntaxes:
+
+1. **Multi-layer syntax** - Generic syntax for device filtering by bus, class, or driver.
+2. **Simplified syntax** - Legacy simplified syntax.
+
+
+Devargs Syntax
+--------------
+
+Generic Syntax
+~~~~~~~~~~~~~~
+
+Generic devargs syntax is meant to cover all use cases supported by devargs infrastructure, such as passing arguments to various layers or matching multiple devices.
+The basic syntax format is as follows:
+
+.. code-block:: none
+
+   bus=<busname>,<bus_args>/class=<classname>,<class_args>/driver=<drvname>,<driver_args>
+
+This allows the user to specify:
+
+* ``bus`` layer: bus identifier, as well as bus-level arguments
+* ``class`` layer: class identifier, as well as class-level arguments
+* ``driver`` layer: driver identifier, as well as driver-specific parameters
+
+.. note::
+   By default, multi-layer syntax is driver-centric and will apply to all devices using a particular bus, class, and driver combination.
+   To target a specific device, a device-identifying argument can be provided to the bus layer. The specific key depends on the bus:
+   for PCI use ``addr=`` (e.g. ``bus=pci,addr=0000:02:00.0``), for most other buses use ``name=`` (e.g. ``bus=vdev,name=net_ring0``).
+
+**Example**:
+
+.. code-block:: none
+
+   bus=pci/class=eth/driver=ice,representor=[0-3]
+
+The above example will pass "representor=[0-3]" devarg to each device matching the provided criteria (PCI bus, Ethernet class, in use by ``ice`` driver).
+
+Simplified syntax
+~~~~~~~~~~~~~~~~~
+
+In cases where the full syntax is not required, devargs can be used with simplified format that targets specific devices only:
+
+.. code-block:: none
+
+   [bus:]device_identifier[,arg1=val1,arg2=val2,...]
+
+Where:
+
+* ``bus:`` is an optional prefix specifying the bus name (pci, vdev, auxiliary, etc.)
+* ``device_identifier`` uniquely identifies the device on its bus
+* ``arg1=val1,arg2=val2,...`` are optional driver-specific configuration parameters
+
+The arguments are provided to the driver, but the driver name itself is inferred from the device and does not need to be specified.
+
+**Examples**:
+
+.. code-block:: none
+
+   0000:02:00.0                          # PCI device, no arguments
+   0000:02:00.0,txq_inline=128           # PCI device with driver arguments
+   pci:0000:02:00.0                      # Explicit bus prefix
+   net_ring0                             # Virtual device
+   vdev:net_pcap0,rx_pcap=input.pcap     # Virtual device with arguments and bus prefix
+
+If the bus prefix is omitted, DPDK tries each registered bus in turn to see if it can recognize the device identifier.
+
+
+Virtual Device Arguments
+------------------------
+Virtual devices (vdevs) are software-based devices that don't correspond to physical hardware.
+Unlike PCI or other hardware buses where devices are discovered by scanning, virtual devices must be explicitly created by specifying their driver name.
+
+Understanding Virtual Device Naming
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A virtual device name consists of:
+
+1. **Driver name**: The vdev driver to use (e.g., ``net_ring``, ``net_pcap``, ``crypto_null``)
+2. **Instance identifier**: A numeric suffix to create multiple instances of the same driver
+
+**Format**:
+
+.. code-block:: none
+
+   [vdev:]<driver_name><instance_number>[,arg=val,...]
+
+**Examples**:
+
+Create a ring-based virtual port:
+
+.. code-block:: none
+
+   net_ring0
+
+Create a PCAP virtual device with input file:
+
+.. code-block:: none
+
+   net_pcap0,rx_pcap=input.pcap
+
+
+Using Devargs in Applications
+------------------------------
+
+At EAL Initialization
+~~~~~~~~~~~~~~~~~~~~~
+
+Devargs can be specified on the command line when starting a DPDK application:
+
+**Allow-list (permit specific devices)**:
+
+.. code-block:: console
+
+   ./myapp -a 0000:02:00.0 -a 0000:03:00.0,txq_inline=128
+
+**Block-list (exclude specific devices)**:
+
+.. code-block:: console
+
+   ./myapp -b 0000:04:00.0
+
+**Virtual devices**:
+
+.. code-block:: console
+
+   ./myapp --vdev net_ring0 --vdev 'net_pcap0,rx_pcap=input.pcap'
+
+See :doc:`../linux_gsg/linux_eal_parameters` for complete EAL parameter documentation.
+
+At Runtime (Hotplug)
+~~~~~~~~~~~~~~~~~~~~
+
+Devargs are used with hotplug APIs to attach devices dynamically:
+
+.. code-block:: c
+
+   #include <rte_dev.h>
+
+   /* Attach a PCI device */
+   ret = rte_dev_probe("0000:05:00.0");
+
+   /* Attach a virtual device */
+   ret = rte_dev_probe("net_ring1");
+
+   /* Attach with arguments */
+   ret = rte_dev_probe("0000:05:00.0,txq_inline=256");
+
+Parsing Devargs in Drivers
+---------------------------
+
+PMD drivers can parse devargs using the kvargs library:
+
+.. code-block:: c
+
+   #include <rte_kvargs.h>
+
+   static int
+   my_driver_parse_devargs(struct rte_devargs *devargs)
+   {
+       struct rte_kvargs *kvlist;
+       const char *valid_args[] = {"arg1", "arg2", NULL};
+
+       if (devargs == NULL || devargs->args == NULL)
+           return 0;
+
+       kvlist = rte_kvargs_parse(devargs->args, valid_args);
+       if (kvlist == NULL) {
+           RTE_LOG(ERR, PMD, "Failed to parse devargs\n");
+           return -EINVAL;
+       }
+
+       /* Process each argument */
+       rte_kvargs_process(kvlist, "arg1", my_arg1_handler, NULL);
+       rte_kvargs_process(kvlist, "arg2", my_arg2_handler, NULL);
+
+       rte_kvargs_free(kvlist);
+       return 0;
+   }
+
+For Ethernet devices, use ``rte_eth_devargs_parse()`` to parse standard Ethernet arguments like representors:
+
+.. code-block:: c
+
+   struct rte_eth_devargs eth_da[RTE_MAX_ETHPORTS];
+   int n_devargs;
+
+   n_devargs = rte_eth_devargs_parse(devargs_str, eth_da, RTE_MAX_ETHPORTS);
+   if (n_devargs < 0) {
+       /* Handle error */
+   }
+
+Finding Devices by Devargs
+--------------------------
+
+Iterator helpers accept a devargs-style filter. Examples:
+
+.. code-block:: c
+
+   RTE_DEV_FOREACH(dev, "bus=pci", &it) {
+      /* Handle each PCI device */
+   }
+
+   /* Ethernet devices can also be filtered by class */
+   RTE_ETH_FOREACH_MATCHING_DEV(port_id, "class=eth,mac=00:11:22:33:44:55", &it) {
+      /* Handle each Ethernet device */
+   }
+
+
+For more information, see:
+
+* :doc:`../linux_gsg/linux_eal_parameters` - EAL command-line parameters
+* API documentation: ``rte_devargs_parse()``, ``rte_devargs_layers_parse()`` (in ``rte_devargs.h``)
+* API documentation: ``rte_eth_devargs_parse()`` (in ``ethdev_driver.h``)
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index c0b5f54c26..aacb67c125 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -74,6 +74,7 @@ Device Libraries
     :numbered:
 
     ethdev/index
+    dev_args
     link_bonding_poll_mode_drv_lib
     vhost_lib
     cryptodev_lib
-- 
2.47.3

[PATCH v2 2/2] doc: add device hotplug documentation

[Anatoly Burakov]

Currently, device hotplug is not documented except in API headers. Add
documentation for device hotplug, both for user facing side of it, and a
high level overview of its internal workings.

Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
---

Notes:
    v2:
    - Removed "summary" section

 doc/guides/prog_guide/dev_args.rst       |   3 +
 doc/guides/prog_guide/device_hotplug.rst | 286 +++++++++++++++++++++++
 doc/guides/prog_guide/index.rst          |   2 +
 3 files changed, 291 insertions(+)
 create mode 100644 doc/guides/prog_guide/device_hotplug.rst

diff --git a/doc/guides/prog_guide/dev_args.rst b/doc/guides/prog_guide/dev_args.rst
index a8025d383b..ee7bc3089d 100644
--- a/doc/guides/prog_guide/dev_args.rst
+++ b/doc/guides/prog_guide/dev_args.rst
@@ -166,6 +166,8 @@ Devargs are used with hotplug APIs to attach devices dynamically:
    /* Attach with arguments */
    ret = rte_dev_probe("0000:05:00.0,txq_inline=256");
 
+See :doc:`device_hotplug` for detailed information on runtime device management.
+
 Parsing Devargs in Drivers
 ---------------------------
 
@@ -230,5 +232,6 @@ Iterator helpers accept a devargs-style filter. Examples:
 For more information, see:
 
 * :doc:`../linux_gsg/linux_eal_parameters` - EAL command-line parameters
+* :doc:`device_hotplug` - Runtime device management
 * API documentation: ``rte_devargs_parse()``, ``rte_devargs_layers_parse()`` (in ``rte_devargs.h``)
 * API documentation: ``rte_eth_devargs_parse()`` (in ``ethdev_driver.h``)
diff --git a/doc/guides/prog_guide/device_hotplug.rst b/doc/guides/prog_guide/device_hotplug.rst
new file mode 100644
index 0000000000..3fb62c464f
--- /dev/null
+++ b/doc/guides/prog_guide/device_hotplug.rst
@@ -0,0 +1,286 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2025 Intel Corporation.
+
+.. _device_hotplug:
+
+Device Hotplug
+==============
+
+Introduction
+------------
+
+Device hotplug refers to the ability to attach and detach devices at runtime, after the initial EAL initialization has completed.
+This feature allows applications to dynamically add or remove physical or virtual devices while the DPDK application is running.
+
+.. note::
+   Device hotplug does not support multiprocess operation nor kernel device event notifications on platforms other than Linux.
+
+
+Basic Usage
+-----------
+
+The primary interface for device hotplug is through two complementary functions: ``rte_dev_probe()`` to attach a device using a devargs string, and ``rte_dev_remove()`` to detach a device.
+For detailed information about device argument format and syntax, see :doc:`dev_args`.
+
+A typical workflow for attaching a device is:
+
+.. code-block:: c
+
+   /* Probe a PCI device with specific parameters */
+   ret = rte_dev_probe("0000:02:00.0,arg1=value1");
+   if (ret < 0) {
+       /* Handle error */
+   }
+
+   /* Later, find the device and remove it */
+   struct rte_device *dev = /* find device */;
+   ret = rte_dev_remove(dev);
+
+For convenience, DPDK also provides ``rte_eal_hotplug_add()`` and ``rte_eal_hotplug_remove()`` functions, which accept separate bus name, device name, and arguments instead of a combined devargs string:
+
+.. code-block:: c
+
+   /* Attach a virtual device */
+   rte_eal_hotplug_add("vdev", "net_ring0", "");
+
+   /* Remove by bus and device name */
+   rte_eal_hotplug_remove("vdev", "net_ring0");
+
+
+Device Lifecycle Example
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``testpmd`` application provides a reference implementation of device hotplug through the ``port attach`` and ``port detach`` commands, demonstrating proper device lifecycle management.
+
+The following example demonstrates attaching a virtual ring PMD Ethernet device, configuring it, and then detaching it:
+
+.. code-block:: c
+
+   char *devargs = "net_ring0";
+   struct rte_eth_dev_info info;
+   struct rte_dev_iterator iterator;
+   unsigned port_id;
+
+   /* Probe the device */
+   rte_dev_probe(devargs);
+
+   /* Enumerate newly attached ports */
+   RTE_ETH_FOREACH_MATCHING_DEV(port_id, devargs, &iterator) {
+      /* Get device handle */
+      rte_eth_dev_info_get(port_id, &info);
+
+      /* Set up the device and use it */
+   }
+
+   /* Stop the port */
+   rte_eth_dev_stop(port_id);
+
+   /* Remove the device */
+   ret = rte_dev_remove(info.device);
+
+The key steps in this lifecycle are:
+
+1. **Attach**: Call ``rte_dev_probe()`` with the device identifier
+2. **Find the device**: Use device iterators (such as ``RTE_ETH_FOREACH_MATCHING_DEV()``) to find newly attached port
+3. **Configure and use**: Configure the port using normal device configuration/start flow
+4. **Detach**: Stop the device before calling ``rte_dev_remove()``
+
+
+Device Events
+-------------
+
+In addition to providing generic hotplug infrastructure to be used in the above described manner, EAL also offers a device event infrastructure.
+
+.. warning::
+   Because all events are always delivered within the context of an interrupt thread, attempting any memory allocations/deallocations within that context may cause deadlocks.
+   Therefore, it is recommended to set up a deferred application resource allocation/cleanup with ``rte_eal_alarm_set()`` API or otherwise trigger allocation/cleanup of application resources in another context.
+
+Ethernet Device Events
+~~~~~~~~~~~~~~~~~~~~~~
+
+When new Ethernet devices are added (hot plugged using device probe API) to EAL or removed (hot unplugged using device remove API) from EAL, the following events are delivered:
+
+* ``RTE_ETH_EVENT_NEW`` - delivered after device probe
+* ``RTE_ETH_EVENT_DESTROY`` - delivered after device removal
+
+The user may subscribe to these events using ``rte_eth_dev_callback_register()`` function.
+
+
+Kernel Device Events
+~~~~~~~~~~~~~~~~~~~~
+
+EAL may also subscribe to generic device events delivered from kernel uevent infrastructure. The following events are delivered:
+
+* ``RTE_DEV_EVENT_ADD`` - delivered whenever a new device becomes available for probing
+* ``RTE_DEV_EVENT_REMOVE`` - delivered whenever a device becomes unavailable (device failure, hot unplug, etc.)
+
+The kernel event monitoring is not enabled by default, so before using this feature the user must do the following:
+
+* Call ``rte_dev_hotplug_handle_enable()`` to enable ``SIGBUS`` handling in EAL for devices that were hot-unplugged
+* Call ``rte_dev_event_monitor_start()`` to enable kernel device event monitoring
+
+The user may then subscribe to kernel device events using ``rte_dev_event_callback_register()`` function.
+
+.. note::
+   Currently, for ``RTE_DEV_EVENT_ADD``, only PCI devices are monitored
+
+.. note::
+   The ``RTE_DEV_EVENT_ADD`` by itself does not probe the device, it is only a notification that the application may use ``rte_dev_probe()`` on the device in question.
+   When ``RTE_DEV_EVENT_REMOVE`` event is delivered, the EAL has already released all internal resources associated with the device.
+
+
+Event Notification Usage
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Example generic device event callback with deferred probe:
+
+.. code-block:: c
+
+   void
+   deferred_attach(void *arg)
+   {
+       const char *devname = (const char *)arg;
+       rte_dev_probe(devname);
+       /* match strdup with free */
+       free(devname);
+   }
+
+   int
+   device_event_callback(const char *device_name,
+                         enum rte_dev_event_type event,
+                         void *cb_arg)
+   {
+       if (event == RTE_DEV_EVENT_ADD) {
+           /* Schedule deferred attach - don't call rte_dev_probe() here! */
+           char *devname = strdup(device_name);
+           if (rte_eal_alarm_set(1, deferred_attach, devname) < 0) {
+               /* error */
+           }
+       } else if (event == RTE_DEV_EVENT_REMOVE) {
+           /* Handle device removal - schedule cleanup if needed */
+       }
+       return 0;
+   }
+
+   rte_dev_event_callback_register(NULL, device_event_callback, user_arg);  /* NULL = all devices */
+
+
+Implementation Details
+======================
+
+Attach and Detach
+-----------------
+
+When ``rte_dev_probe()`` is called, the following sequence occurs:
+
+1. **Devargs Parsing**:
+   The devargs string is parsed to extract the bus name, device name, and driver arguments, which are stored in an ``rte_devargs`` structure and inserted into the global devargs list.
+
+2. **Bus Scan**:
+   The appropriate bus driver's ``scan()`` method is invoked, causing the bus to search for the device.
+   For PCI devices, this may involve scanning the sysfs filesystem, while for virtual devices, this may create the device structure directly.
+
+3. **Device Discovery**:
+   After scanning, the bus's ``find_device()`` method locates the device by name, and the attach operation fails if the device is not found.
+
+4. **Device Probe**:
+   The bus's ``plug()`` method is called, which triggers the device driver's probe function.
+   The probe function typically allocates device-specific resources, maps device memory regions, initializes device hardware, and registers the device with the appropriate subsystem (e.g., ethdev for network devices).
+
+5. **Multi-process Synchronization**:
+   If successful in the primary process, an IPC message is sent to all secondary processes to attach the same device.
+   See `Multi-process Synchronization`_ for details.
+
+
+When ``rte_dev_remove()`` is called, the following sequence occurs:
+
+1. **Device Validation**:
+   The function verifies that the device is currently probed using ``rte_dev_is_probed()``.
+
+2. **Multi-process Coordination**:
+   In multi-process scenarios, the primary process first coordinates with all secondary processes to detach the device, and only if all secondaries successfully detach does the primary proceed.
+   See `Multi-process Synchronization`_ for details.
+
+3. **Device Unplug**:
+   The bus's ``unplug()`` method is called (``dev->bus->unplug()``), which triggers the driver's remove function.
+   This typically stops device operations, releases device resources, unmaps memory regions, and unregisters from subsystems.
+
+4. **Devargs Cleanup**:
+   The devargs associated with the device are removed from the global list.
+
+
+Multi-process Synchronization
+-----------------------------
+
+DPDK's hotplug implementation ensures that devices are attached or detached consistently across all processes in a multi-process deployment.
+Both primary and secondary processes can initiate hotplug operations (by calling ``rte_dev_probe()`` or ``rte_dev_remove()``), which will be synchronized across all processes.
+
+.. note::
+   Multiprocess operations are only supported on Linux
+
+**When Application Initiates from Primary**:
+
+1. Primary performs the local operation
+2. Primary broadcasts the request to all secondaries using IPC
+3. Primary waits for replies from all secondaries with a timeout
+4. If all secondaries succeed, the operation is complete
+5. If any secondary fails, primary initiates rollback
+
+**When Application Initiates from Secondary**:
+
+1. Secondary sends attach/detach request to primary via IPC
+2. Primary receives the request and performs the local operation
+3. Primary broadcasts the request to all other secondaries
+4. Primary waits for replies from all secondaries
+5. If all succeed, primary sends success reply to the requesting secondary
+6. If any fail, primary initiates rollback and sends failure reply to the requesting secondary
+
+**Secondary Process Flow** (when receiving request from primary):
+
+1. Secondary receives IPC request from primary
+2. Secondary performs the local attach/detach operation
+3. Secondary sends reply with success or failure status
+
+Rollback on Failure
+~~~~~~~~~~~~~~~~~~~
+
+If any step in the attach or detach process fails in a multi-process scenario, DPDK attempts to rollback the operation.
+For attach failures, the primary process sends rollback requests to detach the device from all secondary processes where it succeeded.
+For detach failures, the primary process sends rollback requests to all secondary processes to re-attach the device, restoring the previous state.
+
+Virtual Devices and Multi-process
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Virtual devices have special handling in multi-process scenarios.
+
+During initial startup, when a secondary process starts, it sends a scan request to the primary process via IPC, and the primary responds by sending the list of all virtual devices it has created.
+This synchronization happens during the bus scan phase.
+Unlike physical devices where both processes can independently discover hardware, virtual devices only exist in memory, so secondaries must obtain the device list from the primary.
+
+At runtime, virtual devices can be hotplugged from either primary or secondary processes using the standard hotplug flow described above, and will be synchronized across all processes.
+Note that secondary processes can specify virtual devices via ``--vdev`` on the command line during initialization, which creates process-local devices, but runtime hotplug operations using ``rte_dev_probe()`` always synchronize devices across all processes.
+
+
+Kernel Uevent Handling (Linux only)
+-----------------------------------
+
+DPDK's device event monitoring works by listening to Linux kernel uevents via a netlink socket. The application must explicitly start monitoring by calling ``rte_dev_event_monitor_start()``.
+When ``rte_dev_event_monitor_start()`` is called, DPDK creates a ``NETLINK_KOBJECT_UEVENT`` socket that receives notifications from the kernel about device state changes.
+
+The mechanism works as follows:
+
+1. **Netlink Socket Creation**: DPDK creates a netlink socket bound to receive all kernel kobject uevents (``nl_groups = 0xffffffff``).
+2. **Uevent Reception**: When a device is added or removed, the Linux kernel broadcasts a uevent message containing:
+   - ``ACTION=add`` or ``ACTION=remove``
+   - ``SUBSYSTEM=pci``, ``uio``, or ``vfio``
+   - ``PCI_SLOT_NAME=<device>`` (e.g., ``0000:02:00.0``)
+3. **Event Parsing**: DPDK parses these messages to extract the device name, action type, and subsystem, then invokes registered application callbacks.
+4. **Interrupt-driven**: The socket is registered with DPDK's interrupt framework, so uevent handling is asynchronous and doesn't require polling.
+
+This infrastructure only monitors physical devices managed by the kernel. Virtual devices created by DPDK do not generate kernel uevents.
+
+SIGBUS Handling
+---------------
+
+If the application attempts to access memory-mapped device registers after the device is removed, a ``SIGBUS`` signal may be generated.
+The ``rte_dev_hotplug_handle_enable()`` function registers a signal handler that identifies which device caused the fault using the faulting address, invokes the bus's signal handler to handle the error, and allows the application to continue rather than crashing.
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index aacb67c125..41865ee7d7 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -75,6 +75,8 @@ Device Libraries
 
     ethdev/index
     dev_args
+    device_hotplug
+    dev_args
     link_bonding_poll_mode_drv_lib
     vhost_lib
     cryptodev_lib
-- 
2.47.3

Re: [PATCH v2 1/2] doc: add devargs documentation

[Bruce Richardson]

On Fri, Dec 19, 2025 at 01:25:55PM +0000, Anatoly Burakov wrote:
> Currently, the devargs syntax documentation is missing from the
> programmer's guide, and is only documented implicitly through the devargs
> API headers. Add a detailed description of the two supported devargs
> syntaxes.
> 
> Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
> ---
> 
> Notes:
>     v2:
>     - Made generic syntax the primary syntax
>     - Removed summary
>     - Moved index link to after ethdev/index
> 
>  doc/guides/prog_guide/dev_args.rst | 234 +++++++++++++++++++++++++++++
>  doc/guides/prog_guide/index.rst    |   1 +
>  2 files changed, 235 insertions(+)
>  create mode 100644 doc/guides/prog_guide/dev_args.rst
> 
> diff --git a/doc/guides/prog_guide/dev_args.rst b/doc/guides/prog_guide/dev_args.rst
> new file mode 100644
> index 0000000000..a8025d383b
> --- /dev/null
> +++ b/doc/guides/prog_guide/dev_args.rst
> @@ -0,0 +1,234 @@
> +..  SPDX-License-Identifier: BSD-3-Clause
> +    Copyright(c) 2025 Intel Corporation.
> +
> +.. _device_arguments:
> +
> +Device Arguments
> +================
> +
> +Introduction
> +------------
> +
> +Device arguments (devargs) provide a standardized way to specify and configure devices in DPDK applications.
> +Devargs are used both at EAL initialization time (via command-line options) and at runtime (via hotplug APIs) to identify devices and pass configuration parameters to them.
> +
> +A devargs string can specify identifiers and arguments at multiple levels:
> +
> +* **Bus identifier and arguments**: Which bus handles the device (e.g., ``pci``, ``vdev``) and bus-level parameters
> +* **Class identifier and arguments**: Device class (e.g., ``eth``, ``crypto``) and class-level parameters
> +* **Driver identifier and arguments**: The specific driver and its driver-specific parameters
> +
> +DPDK supports two devargs syntaxes:
> +
> +1. **Multi-layer syntax** - Generic syntax for device filtering by bus, class, or driver.
> +2. **Simplified syntax** - Legacy simplified syntax.
> +
> +
> +Devargs Syntax
> +--------------
> +
> +Generic Syntax
> +~~~~~~~~~~~~~~
> +
> +Generic devargs syntax is meant to cover all use cases supported by devargs infrastructure, such as passing arguments to various layers or matching multiple devices.
> +The basic syntax format is as follows:
> +
> +.. code-block:: none
> +
> +   bus=<busname>,<bus_args>/class=<classname>,<class_args>/driver=<drvname>,<driver_args>
> +
> +This allows the user to specify:
> +
> +* ``bus`` layer: bus identifier, as well as bus-level arguments
> +* ``class`` layer: class identifier, as well as class-level arguments
> +* ``driver`` layer: driver identifier, as well as driver-specific parameters
> +
> +.. note::
> +   By default, multi-layer syntax is driver-centric and will apply to all devices using a particular bus, class, and driver combination.
> +   To target a specific device, a device-identifying argument can be provided to the bus layer. The specific key depends on the bus:
> +   for PCI use ``addr=`` (e.g. ``bus=pci,addr=0000:02:00.0``), for most other buses use ``name=`` (e.g. ``bus=vdev,name=net_ring0``).
> +
> +**Example**:
> +
> +.. code-block:: none
> +
> +   bus=pci/class=eth/driver=ice,representor=[0-3]
> +
> +The above example will pass "representor=[0-3]" devarg to each device matching the provided criteria (PCI bus, Ethernet class, in use by ``ice`` driver).
> +
> +Simplified syntax
> +~~~~~~~~~~~~~~~~~
> +
> +In cases where the full syntax is not required, devargs can be used with simplified format that targets specific devices only:
> +
> +.. code-block:: none
> +
> +   [bus:]device_identifier[,arg1=val1,arg2=val2,...]
> +
> +Where:
> +
> +* ``bus:`` is an optional prefix specifying the bus name (pci, vdev, auxiliary, etc.)
> +* ``device_identifier`` uniquely identifies the device on its bus
> +* ``arg1=val1,arg2=val2,...`` are optional driver-specific configuration parameters
> +
> +The arguments are provided to the driver, but the driver name itself is inferred from the device and does not need to be specified.
> +
> +**Examples**:
> +
> +.. code-block:: none
> +
> +   0000:02:00.0                          # PCI device, no arguments
> +   0000:02:00.0,txq_inline=128           # PCI device with driver arguments

I would look to include some examples with the "0000:" omitted at the start
of the PCI addresses, since that shortened form should work.

/Bruce

RE: [PATCH v2 2/2] doc: add device hotplug documentation

[Morten Brørup]

> +Device Hotplug
> +==============
> +
> +Introduction
> +------------
> +
> +Device hotplug refers to the ability to attach and detach devices at
> runtime, after the initial EAL initialization has completed.
> +This feature allows applications to dynamically add or remove physical
> or virtual devices while the DPDK application is running.
> +
> +.. note::
> +   Device hotplug does not support multiprocess operation nor kernel
> device event notifications on platforms other than Linux.

Does this mean:
Device hotplug does not support "multiprocess operation" nor "kernel device event notifications on platforms other than Linux".
Or:
Device hotplug does not support "multiprocess operation nor kernel device event notifications" on platforms other than Linux.

Please make this note more clear. My English skills are not good enough to understand.

Re: [PATCH v2 2/2] doc: add device hotplug documentation

[Burakov, Anatoly]

On 12/19/2025 3:01 PM, Morten Brørup wrote:
>> +Device Hotplug
>> +==============
>> +
>> +Introduction
>> +------------
>> +
>> +Device hotplug refers to the ability to attach and detach devices at
>> runtime, after the initial EAL initialization has completed.
>> +This feature allows applications to dynamically add or remove physical
>> or virtual devices while the DPDK application is running.
>> +
>> +.. note::
>> +   Device hotplug does not support multiprocess operation nor kernel
>> device event notifications on platforms other than Linux.
> 

Hi Morten,

> Does this mean:
> Device hotplug does not support "multiprocess operation" nor "kernel device event notifications on platforms other than Linux".
> Or:
> Device hotplug does not support "multiprocess operation nor kernel device event notifications" on platforms other than Linux.

Yes!

Jokes aside, it's the latter, and I'll make it more clear in the next 
revision. Thanks for the review!

> 
> Please make this note more clear. My English skills are not good enough to understand.
> 


-- 
Thanks,
Anatoly

[PATCH v3 1/2] doc: add devargs documentation

[Anatoly Burakov]

Currently, the devargs syntax documentation is missing from the
programmer's guide, and is only documented implicitly through the devargs
API headers. Add a detailed description of the two supported devargs
syntaxes.

Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
---

Notes:
    v2:
    - Made generic syntax the primary syntax
    - Removed summary
    - Moved index link to after ethdev/index

 doc/guides/prog_guide/dev_args.rst | 241 +++++++++++++++++++++++++++++
 doc/guides/prog_guide/index.rst    |   1 +
 2 files changed, 242 insertions(+)
 create mode 100644 doc/guides/prog_guide/dev_args.rst

diff --git a/doc/guides/prog_guide/dev_args.rst b/doc/guides/prog_guide/dev_args.rst
new file mode 100644
index 0000000000..035b8ae534
--- /dev/null
+++ b/doc/guides/prog_guide/dev_args.rst
@@ -0,0 +1,241 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2025 Intel Corporation.
+
+.. _device_arguments:
+
+Device Arguments
+================
+
+Introduction
+------------
+
+Device arguments (devargs) provide a standardized way to specify and configure devices in DPDK applications.
+Devargs are used both at EAL initialization time (via command-line options) and at runtime (via hotplug APIs) to identify devices and pass configuration parameters to them.
+
+A devargs string can specify identifiers and arguments at multiple levels:
+
+* **Bus identifier and arguments**: Which bus handles the device (e.g., ``pci``, ``vdev``) and bus-level parameters
+* **Class identifier and arguments**: Device class (e.g., ``eth``, ``crypto``) and class-level parameters
+* **Driver identifier and arguments**: The specific driver and its driver-specific parameters
+
+DPDK supports two devargs syntaxes:
+
+1. **Multi-layer syntax** - Generic syntax for device filtering by bus, class, or driver.
+2. **Simplified syntax** - Legacy simplified syntax.
+
+
+Devargs Syntax
+--------------
+
+Generic Syntax
+~~~~~~~~~~~~~~
+
+Generic devargs syntax is meant to cover all use cases supported by devargs infrastructure, such as passing arguments to various layers or matching multiple devices.
+The basic syntax format is as follows:
+
+.. code-block:: none
+
+   bus=<busname>,<bus_args>/class=<classname>,<class_args>/driver=<drvname>,<driver_args>
+
+This allows the user to specify:
+
+* ``bus`` layer: bus identifier, as well as bus-level arguments
+* ``class`` layer: class identifier, as well as class-level arguments
+* ``driver`` layer: driver identifier, as well as driver-specific parameters
+
+.. note::
+   By default, multi-layer syntax is driver-centric and will apply to all devices using a particular bus, class, and driver combination.
+   To target a specific device, a device-identifying argument can be provided to the bus layer. The specific key depends on the bus:
+   for PCI use ``addr=`` (e.g. ``bus=pci,addr=02:00.0``), for most other buses use ``name=`` (e.g. ``bus=vdev,name=net_ring0``).
+   As far as PCI BDFs go, the domain part (``0000:``) can be omitted if it is zero, so ``0000:02:00.0`` and ``02:00.0`` are equivalent.
+
+**Example**:
+
+.. code-block:: none
+
+   bus=pci/class=eth/driver=ice,representor=[0-3]
+
+The above example will pass "representor=[0-3]" devarg to each device matching the provided criteria (PCI bus, Ethernet class, in use by ``ice`` driver).
+
+.. code-block:: none
+
+   bus=pci,addr=02:00.0/driver=ice,representor=[0-3]
+
+The above example will pass "representor=[0-3]" devarg only to device corresponding to PCI address ``0000:02:00.0``, and only if it is managed by ``ice`` driver.
+
+Simplified syntax
+~~~~~~~~~~~~~~~~~
+
+In cases where the full syntax is not required, devargs can be used with simplified format that targets specific devices only:
+
+.. code-block:: none
+
+   [bus:]device_identifier[,arg1=val1,arg2=val2,...]
+
+Where:
+
+* ``bus:`` is an optional prefix specifying the bus name (pci, vdev, auxiliary, etc.)
+* ``device_identifier`` uniquely identifies the device on its bus
+* ``arg1=val1,arg2=val2,...`` are optional driver-specific configuration parameters
+
+The arguments are provided to the driver, but the driver name itself is inferred from the device and does not need to be specified.
+
+**Examples**:
+
+.. code-block:: none
+
+   0000:02:00.0                          # PCI device, no arguments
+   02:00.0,txq_inline=128                # PCI device with driver arguments
+   pci:0000:02:00.0                      # Explicit bus prefix
+   net_ring0                             # Virtual device
+   vdev:net_pcap0,rx_pcap=input.pcap     # Virtual device with arguments and bus prefix
+
+If the bus prefix is omitted, DPDK tries each registered bus in turn to see if it can recognize the device identifier.
+
+
+Virtual Device Arguments
+------------------------
+Virtual devices (vdevs) are software-based devices that don't correspond to physical hardware.
+Unlike PCI or other hardware buses where devices are discovered by scanning, virtual devices must be explicitly created by specifying their driver name.
+
+Understanding Virtual Device Naming
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A virtual device name consists of:
+
+1. **Driver name**: The vdev driver to use (e.g., ``net_ring``, ``net_pcap``, ``crypto_null``)
+2. **Instance identifier**: A numeric suffix to create multiple instances of the same driver
+
+**Format**:
+
+.. code-block:: none
+
+   [vdev:]<driver_name><instance_number>[,arg=val,...]
+
+**Examples**:
+
+Create a ring-based virtual port:
+
+.. code-block:: none
+
+   net_ring0
+
+Create a PCAP virtual device with input file:
+
+.. code-block:: none
+
+   net_pcap0,rx_pcap=input.pcap
+
+
+Using Devargs in Applications
+------------------------------
+
+At EAL Initialization
+~~~~~~~~~~~~~~~~~~~~~
+
+Devargs can be specified on the command line when starting a DPDK application:
+
+**Allow-list (permit specific devices)**:
+
+.. code-block:: console
+
+   ./myapp -a 0000:02:00.0 -a 03:00.0,txq_inline=128
+
+**Block-list (exclude specific devices)**:
+
+.. code-block:: console
+
+   ./myapp -b 04:00.0
+
+**Virtual devices**:
+
+.. code-block:: console
+
+   ./myapp --vdev net_ring0 --vdev 'net_pcap0,rx_pcap=input.pcap'
+
+See :doc:`../linux_gsg/linux_eal_parameters` for complete EAL parameter documentation.
+
+At Runtime (Hotplug)
+~~~~~~~~~~~~~~~~~~~~
+
+Devargs are used with hotplug APIs to attach devices dynamically:
+
+.. code-block:: c
+
+   #include <rte_dev.h>
+
+   /* Attach a PCI device */
+   ret = rte_dev_probe("0000:05:00.0");
+
+   /* Attach a virtual device */
+   ret = rte_dev_probe("net_ring1");
+
+   /* Attach with arguments */
+   ret = rte_dev_probe("05:00.0,txq_inline=256");
+
+Parsing Devargs in Drivers
+---------------------------
+
+PMD drivers can parse devargs using the kvargs library:
+
+.. code-block:: c
+
+   #include <rte_kvargs.h>
+
+   static int
+   my_driver_parse_devargs(struct rte_devargs *devargs)
+   {
+       struct rte_kvargs *kvlist;
+       const char *valid_args[] = {"arg1", "arg2", NULL};
+
+       if (devargs == NULL || devargs->args == NULL)
+           return 0;
+
+       kvlist = rte_kvargs_parse(devargs->args, valid_args);
+       if (kvlist == NULL) {
+           RTE_LOG(ERR, PMD, "Failed to parse devargs\n");
+           return -EINVAL;
+       }
+
+       /* Process each argument */
+       rte_kvargs_process(kvlist, "arg1", my_arg1_handler, NULL);
+       rte_kvargs_process(kvlist, "arg2", my_arg2_handler, NULL);
+
+       rte_kvargs_free(kvlist);
+       return 0;
+   }
+
+For Ethernet devices, use ``rte_eth_devargs_parse()`` to parse standard Ethernet arguments like representors:
+
+.. code-block:: c
+
+   struct rte_eth_devargs eth_da[RTE_MAX_ETHPORTS];
+   int n_devargs;
+
+   n_devargs = rte_eth_devargs_parse(devargs_str, eth_da, RTE_MAX_ETHPORTS);
+   if (n_devargs < 0) {
+       /* Handle error */
+   }
+
+Finding Devices by Devargs
+--------------------------
+
+Iterator helpers accept a devargs-style filter. Examples:
+
+.. code-block:: c
+
+   RTE_DEV_FOREACH(dev, "bus=pci", &it) {
+      /* Handle each PCI device */
+   }
+
+   /* Ethernet devices can also be filtered by class */
+   RTE_ETH_FOREACH_MATCHING_DEV(port_id, "class=eth,mac=00:11:22:33:44:55", &it) {
+      /* Handle each Ethernet device */
+   }
+
+
+For more information, see:
+
+* :doc:`../linux_gsg/linux_eal_parameters` - EAL command-line parameters
+* API documentation: ``rte_devargs_parse()``, ``rte_devargs_layers_parse()`` (in ``rte_devargs.h``)
+* API documentation: ``rte_eth_devargs_parse()`` (in ``ethdev_driver.h``)
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index c0b5f54c26..aacb67c125 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -74,6 +74,7 @@ Device Libraries
     :numbered:
 
     ethdev/index
+    dev_args
     link_bonding_poll_mode_drv_lib
     vhost_lib
     cryptodev_lib
-- 
2.47.3

[PATCH v3 2/2] doc: add device hotplug documentation

[Anatoly Burakov]

Currently, device hotplug is not documented except in API headers. Add
documentation for device hotplug, both for user facing side of it, and a
high level overview of its internal workings.

Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
---

Notes:
    v2:
    - Removed "summary" section

 doc/guides/prog_guide/dev_args.rst       |   3 +
 doc/guides/prog_guide/device_hotplug.rst | 286 +++++++++++++++++++++++
 doc/guides/prog_guide/index.rst          |   1 +
 3 files changed, 290 insertions(+)
 create mode 100644 doc/guides/prog_guide/device_hotplug.rst

diff --git a/doc/guides/prog_guide/dev_args.rst b/doc/guides/prog_guide/dev_args.rst
index 035b8ae534..182cb5ff83 100644
--- a/doc/guides/prog_guide/dev_args.rst
+++ b/doc/guides/prog_guide/dev_args.rst
@@ -173,6 +173,8 @@ Devargs are used with hotplug APIs to attach devices dynamically:
    /* Attach with arguments */
    ret = rte_dev_probe("05:00.0,txq_inline=256");
 
+See :doc:`device_hotplug` for detailed information on runtime device management.
+
 Parsing Devargs in Drivers
 ---------------------------
 
@@ -237,5 +239,6 @@ Iterator helpers accept a devargs-style filter. Examples:
 For more information, see:
 
 * :doc:`../linux_gsg/linux_eal_parameters` - EAL command-line parameters
+* :doc:`device_hotplug` - Runtime device management
 * API documentation: ``rte_devargs_parse()``, ``rte_devargs_layers_parse()`` (in ``rte_devargs.h``)
 * API documentation: ``rte_eth_devargs_parse()`` (in ``ethdev_driver.h``)
diff --git a/doc/guides/prog_guide/device_hotplug.rst b/doc/guides/prog_guide/device_hotplug.rst
new file mode 100644
index 0000000000..a5b4db3deb
--- /dev/null
+++ b/doc/guides/prog_guide/device_hotplug.rst
@@ -0,0 +1,286 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2025 Intel Corporation.
+
+.. _device_hotplug:
+
+Device Hotplug
+==============
+
+Introduction
+------------
+
+Device hotplug refers to the ability to attach and detach devices at runtime, after the initial EAL initialization has completed.
+This feature allows applications to dynamically add or remove physical or virtual devices while the DPDK application is running.
+
+.. note::
+   On platforms other than Linux, neither multiprocess operations nor hotplug notifications are supported.
+
+
+Basic Usage
+-----------
+
+The primary interface for device hotplug is through two complementary functions: ``rte_dev_probe()`` to attach a device using a devargs string, and ``rte_dev_remove()`` to detach a device.
+For detailed information about device argument format and syntax, see :doc:`dev_args`.
+
+A typical workflow for attaching a device is:
+
+.. code-block:: c
+
+   /* Probe a PCI device with specific parameters */
+   ret = rte_dev_probe("0000:02:00.0,arg1=value1");
+   if (ret < 0) {
+       /* Handle error */
+   }
+
+   /* Later, find the device and remove it */
+   struct rte_device *dev = /* find device */;
+   ret = rte_dev_remove(dev);
+
+For convenience, DPDK also provides ``rte_eal_hotplug_add()`` and ``rte_eal_hotplug_remove()`` functions, which accept separate bus name, device name, and arguments instead of a combined devargs string:
+
+.. code-block:: c
+
+   /* Attach a virtual device */
+   rte_eal_hotplug_add("vdev", "net_ring0", "");
+
+   /* Remove by bus and device name */
+   rte_eal_hotplug_remove("vdev", "net_ring0");
+
+
+Device Lifecycle Example
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``testpmd`` application provides a reference implementation of device hotplug through the ``port attach`` and ``port detach`` commands, demonstrating proper device lifecycle management.
+
+The following example demonstrates attaching a virtual ring PMD Ethernet device, configuring it, and then detaching it:
+
+.. code-block:: c
+
+   char *devargs = "net_ring0";
+   struct rte_eth_dev_info info;
+   struct rte_dev_iterator iterator;
+   unsigned port_id;
+
+   /* Probe the device */
+   rte_dev_probe(devargs);
+
+   /* Enumerate newly attached ports */
+   RTE_ETH_FOREACH_MATCHING_DEV(port_id, devargs, &iterator) {
+      /* Get device handle */
+      rte_eth_dev_info_get(port_id, &info);
+
+      /* Set up the device and use it */
+   }
+
+   /* Stop the port */
+   rte_eth_dev_stop(port_id);
+
+   /* Remove the device */
+   ret = rte_dev_remove(info.device);
+
+The key steps in this lifecycle are:
+
+1. **Attach**: Call ``rte_dev_probe()`` with the device identifier
+2. **Find the device**: Use device iterators (such as ``RTE_ETH_FOREACH_MATCHING_DEV()``) to find newly attached port
+3. **Configure and use**: Configure the port using normal device configuration/start flow
+4. **Detach**: Stop the device before calling ``rte_dev_remove()``
+
+
+Device Events
+-------------
+
+In addition to providing generic hotplug infrastructure to be used in the above described manner, EAL also offers a device event infrastructure.
+
+.. warning::
+   Because all events are always delivered within the context of an interrupt thread, attempting any memory allocations/deallocations within that context may cause deadlocks.
+   Therefore, it is recommended to set up a deferred application resource allocation/cleanup with ``rte_eal_alarm_set()`` API or otherwise trigger allocation/cleanup of application resources in another context.
+
+Ethernet Device Events
+~~~~~~~~~~~~~~~~~~~~~~
+
+When new Ethernet devices are added (hot plugged using device probe API) to EAL or removed (hot unplugged using device remove API) from EAL, the following events are delivered:
+
+* ``RTE_ETH_EVENT_NEW`` - delivered after device probe
+* ``RTE_ETH_EVENT_DESTROY`` - delivered after device removal
+
+The user may subscribe to these events using ``rte_eth_dev_callback_register()`` function.
+
+
+Kernel Device Events
+~~~~~~~~~~~~~~~~~~~~
+
+EAL may also subscribe to generic device events delivered from kernel uevent infrastructure. The following events are delivered:
+
+* ``RTE_DEV_EVENT_ADD`` - delivered whenever a new device becomes available for probing
+* ``RTE_DEV_EVENT_REMOVE`` - delivered whenever a device becomes unavailable (device failure, hot unplug, etc.)
+
+The kernel event monitoring is not enabled by default, so before using this feature the user must do the following:
+
+* Call ``rte_dev_hotplug_handle_enable()`` to enable ``SIGBUS`` handling in EAL for devices that were hot-unplugged
+* Call ``rte_dev_event_monitor_start()`` to enable kernel device event monitoring
+
+The user may then subscribe to kernel device events using ``rte_dev_event_callback_register()`` function.
+
+.. note::
+   Currently, for ``RTE_DEV_EVENT_ADD``, only PCI devices are monitored
+
+.. note::
+   The ``RTE_DEV_EVENT_ADD`` by itself does not probe the device, it is only a notification that the application may use ``rte_dev_probe()`` on the device in question.
+   When ``RTE_DEV_EVENT_REMOVE`` event is delivered, the EAL has already released all internal resources associated with the device.
+
+
+Event Notification Usage
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Example generic device event callback with deferred probe:
+
+.. code-block:: c
+
+   void
+   deferred_attach(void *arg)
+   {
+       const char *devname = (const char *)arg;
+       rte_dev_probe(devname);
+       /* match strdup with free */
+       free(devname);
+   }
+
+   int
+   device_event_callback(const char *device_name,
+                         enum rte_dev_event_type event,
+                         void *cb_arg)
+   {
+       if (event == RTE_DEV_EVENT_ADD) {
+           /* Schedule deferred attach - don't call rte_dev_probe() here! */
+           char *devname = strdup(device_name);
+           if (rte_eal_alarm_set(1, deferred_attach, devname) < 0) {
+               /* error */
+           }
+       } else if (event == RTE_DEV_EVENT_REMOVE) {
+           /* Handle device removal - schedule cleanup if needed */
+       }
+       return 0;
+   }
+
+   rte_dev_event_callback_register(NULL, device_event_callback, user_arg);  /* NULL = all devices */
+
+
+Implementation Details
+======================
+
+Attach and Detach
+-----------------
+
+When ``rte_dev_probe()`` is called, the following sequence occurs:
+
+1. **Devargs Parsing**:
+   The devargs string is parsed to extract the bus name, device name, and driver arguments, which are stored in an ``rte_devargs`` structure and inserted into the global devargs list.
+
+2. **Bus Scan**:
+   The appropriate bus driver's ``scan()`` method is invoked, causing the bus to search for the device.
+   For PCI devices, this may involve scanning the sysfs filesystem, while for virtual devices, this may create the device structure directly.
+
+3. **Device Discovery**:
+   After scanning, the bus's ``find_device()`` method locates the device by name, and the attach operation fails if the device is not found.
+
+4. **Device Probe**:
+   The bus's ``plug()`` method is called, which triggers the device driver's probe function.
+   The probe function typically allocates device-specific resources, maps device memory regions, initializes device hardware, and registers the device with the appropriate subsystem (e.g., ethdev for network devices).
+
+5. **Multi-process Synchronization**:
+   If successful in the primary process, an IPC message is sent to all secondary processes to attach the same device.
+   See `Multi-process Synchronization`_ for details.
+
+
+When ``rte_dev_remove()`` is called, the following sequence occurs:
+
+1. **Device Validation**:
+   The function verifies that the device is currently probed using ``rte_dev_is_probed()``.
+
+2. **Multi-process Coordination**:
+   In multi-process scenarios, the primary process first coordinates with all secondary processes to detach the device, and only if all secondaries successfully detach does the primary proceed.
+   See `Multi-process Synchronization`_ for details.
+
+3. **Device Unplug**:
+   The bus's ``unplug()`` method is called (``dev->bus->unplug()``), which triggers the driver's remove function.
+   This typically stops device operations, releases device resources, unmaps memory regions, and unregisters from subsystems.
+
+4. **Devargs Cleanup**:
+   The devargs associated with the device are removed from the global list.
+
+
+Multi-process Synchronization
+-----------------------------
+
+DPDK's hotplug implementation ensures that devices are attached or detached consistently across all processes in a multi-process deployment.
+Both primary and secondary processes can initiate hotplug operations (by calling ``rte_dev_probe()`` or ``rte_dev_remove()``), which will be synchronized across all processes.
+
+.. note::
+   Multiprocess operations are only supported on Linux
+
+**When Application Initiates from Primary**:
+
+1. Primary performs the local operation
+2. Primary broadcasts the request to all secondaries using IPC
+3. Primary waits for replies from all secondaries with a timeout
+4. If all secondaries succeed, the operation is complete
+5. If any secondary fails, primary initiates rollback
+
+**When Application Initiates from Secondary**:
+
+1. Secondary sends attach/detach request to primary via IPC
+2. Primary receives the request and performs the local operation
+3. Primary broadcasts the request to all other secondaries
+4. Primary waits for replies from all secondaries
+5. If all succeed, primary sends success reply to the requesting secondary
+6. If any fail, primary initiates rollback and sends failure reply to the requesting secondary
+
+**Secondary Process Flow** (when receiving request from primary):
+
+1. Secondary receives IPC request from primary
+2. Secondary performs the local attach/detach operation
+3. Secondary sends reply with success or failure status
+
+Rollback on Failure
+~~~~~~~~~~~~~~~~~~~
+
+If any step in the attach or detach process fails in a multi-process scenario, DPDK attempts to rollback the operation.
+For attach failures, the primary process sends rollback requests to detach the device from all secondary processes where it succeeded.
+For detach failures, the primary process sends rollback requests to all secondary processes to re-attach the device, restoring the previous state.
+
+Virtual Devices and Multi-process
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Virtual devices have special handling in multi-process scenarios.
+
+During initial startup, when a secondary process starts, it sends a scan request to the primary process via IPC, and the primary responds by sending the list of all virtual devices it has created.
+This synchronization happens during the bus scan phase.
+Unlike physical devices where both processes can independently discover hardware, virtual devices only exist in memory, so secondaries must obtain the device list from the primary.
+
+At runtime, virtual devices can be hotplugged from either primary or secondary processes using the standard hotplug flow described above, and will be synchronized across all processes.
+Note that secondary processes can specify virtual devices via ``--vdev`` on the command line during initialization, which creates process-local devices, but runtime hotplug operations using ``rte_dev_probe()`` always synchronize devices across all processes.
+
+
+Kernel Uevent Handling (Linux only)
+-----------------------------------
+
+DPDK's device event monitoring works by listening to Linux kernel uevents via a netlink socket. The application must explicitly start monitoring by calling ``rte_dev_event_monitor_start()``.
+When ``rte_dev_event_monitor_start()`` is called, DPDK creates a ``NETLINK_KOBJECT_UEVENT`` socket that receives notifications from the kernel about device state changes.
+
+The mechanism works as follows:
+
+1. **Netlink Socket Creation**: DPDK creates a netlink socket bound to receive all kernel kobject uevents (``nl_groups = 0xffffffff``).
+2. **Uevent Reception**: When a device is added or removed, the Linux kernel broadcasts a uevent message containing:
+   - ``ACTION=add`` or ``ACTION=remove``
+   - ``SUBSYSTEM=pci``, ``uio``, or ``vfio``
+   - ``PCI_SLOT_NAME=<device>`` (e.g., ``0000:02:00.0``)
+3. **Event Parsing**: DPDK parses these messages to extract the device name, action type, and subsystem, then invokes registered application callbacks.
+4. **Interrupt-driven**: The socket is registered with DPDK's interrupt framework, so uevent handling is asynchronous and doesn't require polling.
+
+This infrastructure only monitors physical devices managed by the kernel. Virtual devices created by DPDK do not generate kernel uevents.
+
+SIGBUS Handling
+---------------
+
+If the application attempts to access memory-mapped device registers after the device is removed, a ``SIGBUS`` signal may be generated.
+The ``rte_dev_hotplug_handle_enable()`` function registers a signal handler that identifies which device caused the fault using the faulting address, invokes the bus's signal handler to handle the error, and allows the application to continue rather than crashing.
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index aacb67c125..8fabb41c1b 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -75,6 +75,7 @@ Device Libraries
 
     ethdev/index
     dev_args
+    device_hotplug
     link_bonding_poll_mode_drv_lib
     vhost_lib
     cryptodev_lib
-- 
2.47.3

Re: [PATCH v3 2/2] doc: add device hotplug documentation

[Stephen Hemminger]

On Wed, 25 Feb 2026 11:52:25 +0000
Anatoly Burakov <anatoly.burakov@intel.com> wrote:

> Currently, device hotplug is not documented except in API headers. Add
> documentation for device hotplug, both for user facing side of it, and a
> high level overview of its internal workings.
> 
> Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
> ---
> 
> Notes:
>     v2:
>     - Removed "summary" section
> 
>  doc/guides/prog_guide/dev_args.rst       |   3 +
>  doc/guides/prog_guide/device_hotplug.rst | 286 +++++++++++++++++++++++
>  doc/guides/prog_guide/index.rst          |   1 +
>  3 files changed, 290 insertions(+)
>  create mode 100644 doc/guides/prog_guide/device_hotplug.rst


This is great to see. It would be the flow from kernel to udev/systemd was explained.
If I remember right, mlx does this through another IB mechanism.
Also mention this is Linux only.

AI review is good at finding grammar and other things.


---

**Overall assessment:** This is a solid and welcome addition. Device hotplug has long needed proper documentation beyond the API headers. The structure is logical, the code examples are helpful, and the multi-process synchronization section is particularly well done. A few issues worth addressing:

**Technical issues:**

1. **`device_event_callback` return type mismatch (line 289):** The callback is declared as returning `int`, but `rte_dev_event_cb_fn` is typedef'd as returning `void`. This will cause a compiler warning/error if anyone copies this example verbatim. Should be `void` with no return statement.

2. **Missing error check on `rte_dev_probe()` (line 205):** The "Device Lifecycle Example" calls `rte_dev_probe(devargs)` without checking the return value, while the "Basic Usage" example above it correctly shows error handling. For a reference example demonstrating "proper device lifecycle management," this is inconsistent. Should check the return.

3. **`port_id` type (line 203):** `port_id` is declared as `unsigned` but `RTE_ETH_FOREACH_MATCHING_DEV` expects `uint16_t`. Should be `uint16_t port_id;`.

4. **`rte_eal_hotplug_add()`/`rte_eal_hotplug_remove()` deprecation status (line 179):** Are these functions deprecated or planned for deprecation in favor of `rte_dev_probe()`/`rte_dev_remove()`? If so, worth mentioning. If not, it might still be good to indicate which API is preferred for new code.

**Documentation nits:**

5. **Line 152:** "after the initial EAL initialization has completed" — consider noting that `rte_eal_init()` must have returned successfully, since that's the specific precondition.

6. **Line 224:** "to find newly attached port" → "to find the newly attached port"

7. **Line 232:** "In addition to providing generic hotplug infrastructure to be used in the above described manner" — a bit wordy. Consider: "In addition to the hotplug APIs described above, EAL also offers a device event infrastructure."

8. **Line 269:** "When ``RTE_DEV_EVENT_REMOVE`` event is delivered, the EAL has already released all internal resources associated with the device." — Is this accurate? My understanding is that the uevent notification tells the application the kernel removed the device, but it's still up to the application to call `rte_dev_remove()` to clean up EAL resources. If the EAL had already cleaned up, there'd be nothing for the application to do. Please double-check this claim.

9. **Line 412, nl_groups:** The doc says `nl_groups = 0xffffffff`. This is an implementation detail that could change and may be more confusing than helpful for users reading the prog guide. Consider dropping it or noting it's an implementation note.

**Structural:**

10. **Placement in index.rst:** The new page is added right after `dev_args` under "Device Libraries," which makes sense given the cross-references. Good.

11. **The "Implementation Details" section** (line 308 onward) switches from user-facing guidance to internal architecture. This is useful for contributors but might be better as a separate subsection with a note that it describes internals. Currently the document transitions from "here's how to use it" to "here's how it works internally" without much signaling.

**Minor:**
- Copyright says 2025 (line 142) — should be 2026 given the submission date.

Re: [PATCH v3 2/2] doc: add device hotplug documentation

[Burakov, Anatoly]

On 2/25/2026 5:25 PM, Stephen Hemminger wrote:
> On Wed, 25 Feb 2026 11:52:25 +0000
> Anatoly Burakov <anatoly.burakov@intel.com> wrote:
> 
>> Currently, device hotplug is not documented except in API headers. Add
>> documentation for device hotplug, both for user facing side of it, and a
>> high level overview of its internal workings.
>>
>> Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
>> ---
>>
>> Notes:
>>      v2:
>>      - Removed "summary" section
>>
>>   doc/guides/prog_guide/dev_args.rst       |   3 +
>>   doc/guides/prog_guide/device_hotplug.rst | 286 +++++++++++++++++++++++
>>   doc/guides/prog_guide/index.rst          |   1 +
>>   3 files changed, 290 insertions(+)
>>   create mode 100644 doc/guides/prog_guide/device_hotplug.rst
> 
> 
> This is great to see. It would be the flow from kernel to udev/systemd was explained.

Strictly speaking this isn't DPDK scope, but I've added it to v4 anyway.

> If I remember right, mlx does this through another IB mechanism.
> Also mention this is Linux only.
> 

In the spirit of using AI for everything, since I have no idea how mlx 
works, I've offloaded writing this section to AI :P

-- 
Thanks,
Anatoly

[PATCH v4 1/2] doc: add devargs documentation

[Anatoly Burakov]

Currently, the devargs syntax documentation is missing from the
programmer's guide, and is only documented implicitly through the devargs
API headers. Add a detailed description of the two supported devargs
syntaxes.

Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
---

Notes:
    v2:
    - Made generic syntax the primary syntax
    - Removed summary
    - Moved index link to after ethdev/index

 doc/guides/prog_guide/dev_args.rst | 250 +++++++++++++++++++++++++++++
 doc/guides/prog_guide/index.rst    |   1 +
 2 files changed, 251 insertions(+)
 create mode 100644 doc/guides/prog_guide/dev_args.rst

diff --git a/doc/guides/prog_guide/dev_args.rst b/doc/guides/prog_guide/dev_args.rst
new file mode 100644
index 0000000000..4585095354
--- /dev/null
+++ b/doc/guides/prog_guide/dev_args.rst
@@ -0,0 +1,250 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2026 Intel Corporation.
+
+.. _device_arguments:
+
+Device Arguments
+================
+
+Introduction
+------------
+
+Device arguments (devargs) provide a standardized way to specify and configure devices in DPDK applications.
+Devargs are used both during EAL initialization (via ``rte_eal_init()`` command-line options) and at runtime (via hotplug APIs) to identify devices and pass configuration parameters to them.
+
+A devargs string can specify identifiers and arguments at multiple levels:
+
+* **Bus identifier and arguments**: Which bus handles the device (e.g., ``pci``, ``vdev``) and bus-level parameters
+* **Class identifier and arguments**: Device class (e.g., ``eth``, ``crypto``) and class-level parameters
+* **Driver identifier and arguments**: The specific driver and its driver-specific parameters
+
+DPDK supports two devargs syntaxes:
+
+1. **Multi-layer syntax** - Generic syntax for device filtering by bus, class, or driver.
+2. **Simplified syntax** - Legacy simplified syntax.
+
+
+Devargs Syntax
+--------------
+
+Generic Syntax
+~~~~~~~~~~~~~~
+
+Generic devargs syntax is meant to cover all use cases supported by devargs infrastructure, such as passing arguments to various layers or matching multiple devices.
+The basic syntax format is as follows:
+
+.. code-block:: none
+
+   bus=<busname>,<bus_args>/class=<classname>,<class_args>/driver=<drvname>,<driver_args>
+
+This allows the user to specify:
+
+* ``bus`` layer: bus identifier, as well as bus-level arguments
+* ``class`` layer: class identifier, as well as class-level arguments
+* ``driver`` layer: driver identifier, as well as driver-specific parameters
+
+.. note::
+   By default, multi-layer syntax is driver-centric and will match all devices using a particular bus, class, and driver combination.
+   To target a specific device, provide a device-identifying argument to the bus layer. The specific key depends on the bus:
+   for PCI use ``addr=`` (e.g. ``bus=pci,addr=02:00.0``), for most other buses use ``name=`` (e.g. ``bus=vdev,name=net_ring0``).
+   As far as PCI BDFs go, the domain part (``0000:``) can be omitted if it is zero, so ``0000:02:00.0`` and ``02:00.0`` are equivalent.
+
+**Example**:
+
+.. code-block:: none
+
+   bus=pci/class=eth/driver=ice,representor=[0-3]
+
+The above example will pass "representor=[0-3]" devarg to each device matching the provided criteria (PCI bus, Ethernet class, in use by ``ice`` driver).
+
+.. code-block:: none
+
+   bus=pci,addr=02:00.0/driver=ice,representor=[0-3]
+
+The above example will pass "representor=[0-3]" devarg only to device corresponding to PCI address ``0000:02:00.0``, and only if it is managed by ``ice`` driver.
+
+Simplified syntax
+~~~~~~~~~~~~~~~~~
+
+In cases where the full syntax is not required, devargs can be used with simplified format that targets specific devices only:
+
+.. code-block:: none
+
+   [bus:]device_identifier[,arg1=val1,arg2=val2,...]
+
+Where:
+
+* ``bus:`` is an optional prefix specifying the bus name (pci, vdev, auxiliary, etc.)
+* ``device_identifier`` uniquely identifies the device on its bus
+* ``arg1=val1,arg2=val2,...`` are optional driver-specific configuration parameters
+
+The arguments are provided to the driver, but the driver name itself is inferred from the device and does not need to be specified.
+
+**Examples**:
+
+.. code-block:: none
+
+   0000:02:00.0                          # PCI device, no arguments
+   02:00.0,txq_inline=128                # PCI device with driver arguments
+   pci:0000:02:00.0                      # Explicit bus prefix
+   net_ring0                             # Virtual device
+   vdev:net_pcap0,rx_pcap=input.pcap     # Virtual device with arguments and bus prefix
+
+If the bus prefix is omitted, DPDK tries each registered bus in turn to see if it can recognize the device identifier.
+
+
+Virtual Device Arguments
+------------------------
+Virtual devices (vdevs) are software-based devices that don't correspond to physical hardware.
+Unlike PCI or other hardware buses where devices are discovered by scanning, virtual devices must be explicitly created by specifying their driver name.
+
+Understanding Virtual Device Naming
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A virtual device name consists of:
+
+1. **Driver name**: The vdev driver to use (e.g., ``net_ring``, ``net_pcap``, ``crypto_null``)
+2. **Instance identifier**: A numeric suffix to create multiple instances of the same driver
+
+**Format**:
+
+.. code-block:: none
+
+   [vdev:]<driver_name><instance_number>[,arg=val,...]
+
+**Examples**:
+
+Create a ring-based virtual port:
+
+.. code-block:: none
+
+   net_ring0
+
+Create a PCAP virtual device with input file:
+
+.. code-block:: none
+
+   net_pcap0,rx_pcap=input.pcap
+
+
+Using Devargs in Applications
+------------------------------
+
+At EAL Initialization
+~~~~~~~~~~~~~~~~~~~~~
+
+Devargs can be specified on the command line when starting a DPDK application:
+
+**Allow-list (permit specific devices)**:
+
+.. code-block:: console
+
+   ./myapp -a 0000:02:00.0 -a 03:00.0,txq_inline=128
+
+**Block-list (exclude specific devices)**:
+
+.. code-block:: console
+
+   ./myapp -b 04:00.0
+
+**Virtual devices**:
+
+.. code-block:: console
+
+   ./myapp --vdev net_ring0 --vdev 'net_pcap0,rx_pcap=input.pcap'
+
+See :doc:`../linux_gsg/linux_eal_parameters` for complete EAL parameter documentation.
+
+At Runtime (Hotplug)
+~~~~~~~~~~~~~~~~~~~~
+
+Devargs are used with hotplug APIs to attach devices dynamically:
+
+.. code-block:: c
+
+   #include <rte_dev.h>
+
+   /* Attach a PCI device */
+   ret = rte_dev_probe("0000:05:00.0");
+   if (ret < 0) {
+       /* Handle error */
+   }
+
+   /* Attach a virtual device */
+   ret = rte_dev_probe("net_ring1");
+   if (ret < 0) {
+       /* Handle error */
+   }
+
+   /* Attach with arguments */
+   ret = rte_dev_probe("05:00.0,txq_inline=256");
+   if (ret < 0) {
+       /* Handle error */
+   }
+
+Parsing Devargs in Drivers
+---------------------------
+
+PMD drivers can parse devargs using the kvargs library:
+
+.. code-block:: c
+
+   #include <rte_kvargs.h>
+
+   static int
+   my_driver_parse_devargs(struct rte_devargs *devargs)
+   {
+       struct rte_kvargs *kvlist;
+       const char *valid_args[] = {"arg1", "arg2", NULL};
+
+       if (devargs == NULL || devargs->args == NULL)
+           return 0;
+
+       kvlist = rte_kvargs_parse(devargs->args, valid_args);
+       if (kvlist == NULL) {
+           RTE_LOG(ERR, PMD, "Failed to parse devargs\n");
+           return -EINVAL;
+       }
+
+       /* Process each argument */
+       rte_kvargs_process(kvlist, "arg1", my_arg1_handler, NULL);
+       rte_kvargs_process(kvlist, "arg2", my_arg2_handler, NULL);
+
+       rte_kvargs_free(kvlist);
+       return 0;
+   }
+
+For Ethernet devices, use ``rte_eth_devargs_parse()`` to parse standard Ethernet arguments like representors:
+
+.. code-block:: c
+
+   struct rte_eth_devargs eth_da[RTE_MAX_ETHPORTS];
+   int n_devargs;
+
+   n_devargs = rte_eth_devargs_parse(devargs_str, eth_da, RTE_MAX_ETHPORTS);
+   if (n_devargs < 0) {
+       /* Handle error */
+   }
+
+Finding Devices by Devargs
+--------------------------
+
+DPDK provides iterator helpers that accept devargs-style filters for device enumeration. Examples:
+
+.. code-block:: c
+
+   RTE_DEV_FOREACH(dev, "bus=pci", &it) {
+      /* Handle each PCI device */
+   }
+
+   /* Ethernet devices can also be filtered by class */
+   RTE_ETH_FOREACH_MATCHING_DEV(port_id, "class=eth,mac=00:11:22:33:44:55", &it) {
+      /* Handle each Ethernet device */
+   }
+
+
+For more information, see:
+
+* :doc:`../linux_gsg/linux_eal_parameters` - EAL command-line parameters
+* API documentation: ``rte_devargs_parse()``, ``rte_devargs_layers_parse()`` (in ``rte_devargs.h``)
+* API documentation: ``rte_eth_devargs_parse()`` (in ``ethdev_driver.h``)
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index c0b5f54c26..aacb67c125 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -74,6 +74,7 @@ Device Libraries
     :numbered:
 
     ethdev/index
+    dev_args
     link_bonding_poll_mode_drv_lib
     vhost_lib
     cryptodev_lib
-- 
2.47.3

[PATCH v4 2/2] doc: add device hotplug documentation

[Anatoly Burakov]

Currently, device hotplug is not documented except in API headers. Add
documentation for device hotplug, both for user facing side of it, and a
high level overview of its internal workings.

Signed-off-by: Anatoly Burakov <anatoly.burakov@intel.com>
---

Notes:
    v2:
    - Removed "summary" section

 doc/guides/prog_guide/dev_args.rst       |   3 +
 doc/guides/prog_guide/device_hotplug.rst | 316 +++++++++++++++++++++++
 doc/guides/prog_guide/index.rst          |   1 +
 3 files changed, 320 insertions(+)
 create mode 100644 doc/guides/prog_guide/device_hotplug.rst

diff --git a/doc/guides/prog_guide/dev_args.rst b/doc/guides/prog_guide/dev_args.rst
index 4585095354..e06c364afe 100644
--- a/doc/guides/prog_guide/dev_args.rst
+++ b/doc/guides/prog_guide/dev_args.rst
@@ -182,6 +182,8 @@ Devargs are used with hotplug APIs to attach devices dynamically:
        /* Handle error */
    }
 
+See :doc:`device_hotplug` for detailed information on runtime device management.
+
 Parsing Devargs in Drivers
 ---------------------------
 
@@ -246,5 +248,6 @@ DPDK provides iterator helpers that accept devargs-style filters for device enum
 For more information, see:
 
 * :doc:`../linux_gsg/linux_eal_parameters` - EAL command-line parameters
+* :doc:`device_hotplug` - Runtime device management
 * API documentation: ``rte_devargs_parse()``, ``rte_devargs_layers_parse()`` (in ``rte_devargs.h``)
 * API documentation: ``rte_eth_devargs_parse()`` (in ``ethdev_driver.h``)
diff --git a/doc/guides/prog_guide/device_hotplug.rst b/doc/guides/prog_guide/device_hotplug.rst
new file mode 100644
index 0000000000..34b66cf740
--- /dev/null
+++ b/doc/guides/prog_guide/device_hotplug.rst
@@ -0,0 +1,316 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2026 Intel Corporation.
+
+.. _device_hotplug:
+
+Device Hotplug
+==============
+
+Introduction
+------------
+
+Device hotplug refers to the ability to attach and detach devices at runtime, after the initial EAL initialization has completed (i.e., ``rte_eal_init()`` has returned successfully).
+This feature allows applications to dynamically add or remove physical or virtual devices while the DPDK application is running.
+
+.. note::
+   On platforms other than Linux, neither multiprocess operations nor hotplug notifications are supported.
+
+
+Basic Usage
+-----------
+
+The primary interface for device hotplug is through two complementary functions: ``rte_dev_probe()`` to attach a device using a devargs string, and ``rte_dev_remove()`` to detach a device.
+For detailed information about device argument format and syntax, see :doc:`dev_args`.
+
+A typical workflow for attaching a device is:
+
+.. code-block:: c
+
+   /* Probe a PCI device with specific parameters */
+   ret = rte_dev_probe("0000:02:00.0,arg1=value1");
+   if (ret < 0) {
+       /* Handle error */
+   }
+
+   /* Later, find the device and remove it */
+   struct rte_device *dev = /* find device */;
+   ret = rte_dev_remove(dev);
+
+For convenience, DPDK also provides ``rte_eal_hotplug_add()`` and ``rte_eal_hotplug_remove()`` functions, which accept separate bus name, device name, and arguments instead of a combined devargs string:
+
+.. code-block:: c
+
+   /* Attach a virtual device */
+   rte_eal_hotplug_add("vdev", "net_ring0", "");
+
+   /* Remove by bus and device name */
+   rte_eal_hotplug_remove("vdev", "net_ring0");
+
+
+Device Lifecycle Example
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``testpmd`` application provides a reference implementation of device hotplug through the ``port attach`` and ``port detach`` commands, demonstrating proper device lifecycle management.
+
+The following example demonstrates attaching a virtual ring PMD Ethernet device, configuring it, and then detaching it:
+
+.. code-block:: c
+
+   char *devargs = "net_ring0";
+   struct rte_eth_dev_info info;
+   struct rte_dev_iterator iterator;
+   uint16_t port_id;
+   int ret;
+
+   /* Probe the device */
+   ret = rte_dev_probe(devargs);
+   if (ret < 0) {
+      /* Handle error */
+      return ret;
+   }
+
+   /* Enumerate newly attached ports */
+   RTE_ETH_FOREACH_MATCHING_DEV(port_id, devargs, &iterator) {
+      /* Get device handle */
+      rte_eth_dev_info_get(port_id, &info);
+
+      /* Set up the device and use it */
+   }
+
+   /* Stop the port */
+   rte_eth_dev_stop(port_id);
+
+   /* Remove the device */
+   ret = rte_dev_remove(info.device);
+
+The key steps in this lifecycle are:
+
+1. **Attach**: Call ``rte_dev_probe()`` with the device identifier
+2. **Find the device**: Use device iterators (such as ``RTE_ETH_FOREACH_MATCHING_DEV()``) to find the newly attached port
+3. **Configure and use**: Configure the port using normal device configuration/start flow
+4. **Detach**: Stop the device before calling ``rte_dev_remove()``
+
+
+Device Events
+-------------
+
+In addition to the hotplug APIs described above, EAL also offers a device event infrastructure.
+
+.. warning::
+   Because all events are always delivered within the context of an interrupt thread, attempting any memory allocations/deallocations within that context may cause deadlocks.
+   Therefore, it is recommended to set up a deferred application resource allocation/cleanup with ``rte_eal_alarm_set()`` API or otherwise trigger allocation/cleanup of application resources in another context.
+
+Ethernet Device Events
+~~~~~~~~~~~~~~~~~~~~~~
+
+When new Ethernet devices are added (hot plugged using device probe API) to EAL or removed (hot unplugged using device remove API) from EAL, the following events are delivered:
+
+* ``RTE_ETH_EVENT_NEW`` - delivered after device probe
+* ``RTE_ETH_EVENT_DESTROY`` - delivered after device removal
+
+The user may subscribe to these events using ``rte_eth_dev_callback_register()`` function.
+
+
+Kernel Device Events
+~~~~~~~~~~~~~~~~~~~~
+
+EAL may also subscribe to generic device events delivered from kernel uevent infrastructure. The following events are delivered:
+
+* ``RTE_DEV_EVENT_ADD`` - delivered whenever a new device becomes available for probing
+* ``RTE_DEV_EVENT_REMOVE`` - delivered whenever a device becomes unavailable (device failure, hot unplug, etc.)
+
+.. note::
+   Kernel device event monitoring is only supported on Linux.
+
+The kernel event monitoring is not enabled by default, so before using this feature the user must do the following:
+
+* Call ``rte_dev_hotplug_handle_enable()`` to enable ``SIGBUS`` handling in EAL for devices that were hot-unplugged
+* Call ``rte_dev_event_monitor_start()`` to enable kernel device event monitoring
+
+The user may then subscribe to kernel device events using ``rte_dev_event_callback_register()`` function.
+
+.. note::
+   Currently, for ``RTE_DEV_EVENT_ADD``, only PCI devices are monitored
+
+.. note::
+   The ``RTE_DEV_EVENT_ADD`` by itself does not probe the device, it is only a notification that the application may use ``rte_dev_probe()`` on the device in question.
+   When ``RTE_DEV_EVENT_REMOVE`` event is delivered, it indicates that the kernel has removed the device; the application should call ``rte_dev_remove()`` to clean up EAL resources.
+
+
+Event Notification Usage
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Example generic device event callback with deferred probe:
+
+.. code-block:: c
+
+   void
+   deferred_attach(void *arg)
+   {
+       const char *devname = (const char *)arg;
+       rte_dev_probe(devname);
+       /* match strdup with free */
+       free(devname);
+   }
+
+   void
+   device_event_callback(const char *device_name,
+                         enum rte_dev_event_type event,
+                         void *cb_arg)
+   {
+       if (event == RTE_DEV_EVENT_ADD) {
+           /* Schedule deferred attach - don't call rte_dev_probe() here! */
+           char *devname = strdup(device_name);
+           if (rte_eal_alarm_set(1, deferred_attach, devname) < 0) {
+               /* error */
+           }
+       } else if (event == RTE_DEV_EVENT_REMOVE) {
+           /* Handle device removal - schedule cleanup if needed */
+       }
+   }
+
+   rte_dev_event_callback_register(NULL, device_event_callback, user_arg);  /* NULL = all devices */
+
+
+Implementation Details
+======================
+
+.. note::
+   The sections below describe the internal architecture and implementation of device hotplug.
+   This information is primarily intended for contributors and developers working on DPDK internals and/or drivers.
+
+Attach and Detach
+-----------------
+
+When ``rte_dev_probe()`` is called, the following sequence occurs:
+
+1. **Devargs Parsing**:
+   The devargs string is parsed to extract the bus name, device name, and driver arguments, which are stored in an ``rte_devargs`` structure and inserted into the global devargs list.
+
+2. **Bus Scan**:
+   The appropriate bus driver's ``scan()`` method is invoked, causing the bus to search for the device.
+   For PCI devices, this may involve scanning the sysfs filesystem, while for virtual devices, this may create the device structure directly.
+
+3. **Device Discovery**:
+   After scanning, the bus's ``find_device()`` method locates the device by name, and the attach operation fails if the device is not found.
+
+4. **Device Probe**:
+   The bus's ``plug()`` method is called, which triggers the device driver's probe function.
+   The probe function typically allocates device-specific resources, maps device memory regions, initializes device hardware, and registers the device with the appropriate subsystem (e.g., ethdev for network devices).
+
+5. **Multi-process Synchronization**:
+   If successful in the primary process, an IPC message is sent to all secondary processes to attach the same device.
+   See `Multi-process Synchronization`_ for details.
+
+
+When ``rte_dev_remove()`` is called, the following sequence occurs:
+
+1. **Device Validation**:
+   The function verifies that the device is currently probed using ``rte_dev_is_probed()``.
+
+2. **Multi-process Coordination**:
+   In multi-process scenarios, the primary process first coordinates with all secondary processes to detach the device, and only if all secondaries successfully detach does the primary proceed.
+   See `Multi-process Synchronization`_ for details.
+
+3. **Device Unplug**:
+   The bus's ``unplug()`` method is called (``dev->bus->unplug()``), which triggers the driver's remove function.
+   This typically stops device operations, releases device resources, unmaps memory regions, and unregisters from subsystems.
+
+4. **Devargs Cleanup**:
+   The devargs associated with the device are removed from the global list.
+
+
+Multi-process Synchronization
+-----------------------------
+
+DPDK's hotplug implementation ensures that devices are attached or detached consistently across all processes in a multi-process deployment.
+Both primary and secondary processes can initiate hotplug operations (by calling ``rte_dev_probe()`` or ``rte_dev_remove()``), which will be synchronized across all processes.
+
+.. note::
+   Multiprocess operations are only supported on Linux
+
+**When Application Initiates from Primary**:
+
+1. Primary performs the local operation
+2. Primary broadcasts the request to all secondaries using IPC
+3. Primary waits for replies from all secondaries with a timeout
+4. If all secondaries succeed, the operation is complete
+5. If any secondary fails, primary initiates rollback
+
+**When Application Initiates from Secondary**:
+
+1. Secondary sends attach/detach request to primary via IPC
+2. Primary receives the request and performs the local operation
+3. Primary broadcasts the request to all other secondaries
+4. Primary waits for replies from all secondaries
+5. If all succeed, primary sends success reply to the requesting secondary
+6. If any fail, primary initiates rollback and sends failure reply to the requesting secondary
+
+**Secondary Process Flow** (when receiving request from primary):
+
+1. Secondary receives IPC request from primary
+2. Secondary performs the local attach/detach operation
+3. Secondary sends reply with success or failure status
+
+Rollback on Failure
+~~~~~~~~~~~~~~~~~~~
+
+If any step in the attach or detach process fails in a multi-process scenario, DPDK attempts to rollback the operation.
+For attach failures, the primary process sends rollback requests to detach the device from all secondary processes where it succeeded.
+For detach failures, the primary process sends rollback requests to all secondary processes to re-attach the device, restoring the previous state.
+
+Virtual Devices and Multi-process
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Virtual devices have special handling in multi-process scenarios.
+
+During initial startup, when a secondary process starts, it sends a scan request to the primary process via IPC, and the primary responds by sending the list of all virtual devices it has created.
+This synchronization happens during the bus scan phase.
+Unlike physical devices where both processes can independently discover hardware, virtual devices only exist in memory, so secondaries must obtain the device list from the primary.
+
+At runtime, virtual devices can be hotplugged from either primary or secondary processes using the standard hotplug flow described above, and will be synchronized across all processes.
+Note that secondary processes can specify virtual devices via ``--vdev`` on the command line during initialization, which creates process-local devices, but runtime hotplug operations using ``rte_dev_probe()`` always synchronize devices across all processes.
+
+
+Kernel Uevent Handling (Linux only)
+-----------------------------------
+
+DPDK's device event monitoring works by listening to Linux kernel uevents via a netlink socket. The application must explicitly start monitoring by calling ``rte_dev_event_monitor_start()``.
+When ``rte_dev_event_monitor_start()`` is called, DPDK creates a ``NETLINK_KOBJECT_UEVENT`` socket that receives notifications from the kernel about device state changes.
+
+Uevent Flow
+~~~~~~~~~~~
+
+The flow from hardware event to application notification follows this path:
+
+1. **Hardware Event**: When a device is physically added or removed, the kernel detects the change (e.g., PCI hotplug event).
+
+2. **Kernel Uevent Generation**: The Linux kernel generates a uevent and broadcasts it via netlink to all listening processes.
+   User-space tools like ``udev`` or ``systemd-udevd`` typically listen to these events to perform system-level actions such as creating device nodes in ``/dev``, loading kernel modules, or changing permissions.
+
+3. **DPDK Netlink Reception**: DPDK's netlink socket receives the same uevent notifications in parallel with udev/systemd.
+   This allows DPDK to react to device changes independently of system-level device management.
+
+4. **Application Callback**: DPDK parses the uevent and invokes registered application callbacks, allowing the application to handle the device change.
+
+The mechanism works as follows:
+
+1. **Netlink Socket Creation**: DPDK creates a netlink socket bound to receive all kernel kobject uevents.
+2. **Uevent Reception**: When a device is added or removed, the Linux kernel broadcasts a uevent message containing:
+   - ``ACTION=add`` or ``ACTION=remove``
+   - ``SUBSYSTEM=pci``, ``uio``, or ``vfio``
+   - ``PCI_SLOT_NAME=<device>`` (e.g., ``0000:02:00.0``)
+3. **Event Parsing**: DPDK parses these messages to extract the device name, action type, and subsystem, then invokes registered application callbacks.
+4. **Interrupt-driven**: The socket is registered with DPDK's interrupt framework, so uevent handling is asynchronous and doesn't require polling.
+
+This infrastructure only monitors physical devices managed by the kernel. Virtual devices created by DPDK do not generate kernel uevents.
+
+.. note::
+   Some device types use alternative notification mechanisms.
+   For example, Mellanox NICs using the ``mlx4`` or ``mlx5`` PMDs may receive hotplug notifications through InfiniBand verbs events rather than kernel uevents, as these devices are managed by the IB subsystem in addition to the network stack.
+
+SIGBUS Handling
+---------------
+
+If the application attempts to access memory-mapped device registers after the device is removed, a ``SIGBUS`` signal may be generated.
+The ``rte_dev_hotplug_handle_enable()`` function registers a signal handler that identifies which device caused the fault using the faulting address, invokes the bus's signal handler to handle the error, and allows the application to continue rather than crashing.
diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
index aacb67c125..8fabb41c1b 100644
--- a/doc/guides/prog_guide/index.rst
+++ b/doc/guides/prog_guide/index.rst
@@ -75,6 +75,7 @@ Device Libraries
 
     ethdev/index
     dev_args
+    device_hotplug
     link_bonding_poll_mode_drv_lib
     vhost_lib
     cryptodev_lib
-- 
2.47.3

Re: [PATCH v4 2/2] doc: add device hotplug documentation

[Mcnamara, John]

[-- Attachment #1: Type: text/plain, Size: 476 bytes --]


________________________________
From: Anatoly Burakov <anatoly.burakov@intel.com>
Sent: Thursday, February 26, 2026 1:30 PM
To: dev@dpdk.org <dev@dpdk.org>
Subject: [PATCH v4 2/2] doc: add device hotplug documentation

Currently, device hotplug is not documented except in API headers. Add
documentation for device hotplug, both for user facing side of it, and a
high level overview of its internal workings.

Acked-by: John McNamara <john.mcnamara@intel.com>


[-- Attachment #2: Type: text/html, Size: 1491 bytes --]

Re: [PATCH v4 1/2] doc: add devargs documentation

[Mcnamara, John]

[-- Attachment #1: Type: text/plain, Size: 501 bytes --]




________________________________
From: Anatoly Burakov <anatoly.burakov@intel.com>
Sent: Thursday, February 26, 2026 1:30 PM
To: dev@dpdk.org <dev@dpdk.org>
Subject: [PATCH v4 1/2] doc: add devargs documentation

Currently, the devargs syntax documentation is missing from the
programmer's guide, and is only documented implicitly through the devargs
API headers. Add a detailed description of the two supported devargs
syntaxes.

Acked-by: John McNamara <john.mcnamara@intel.com>


[-- Attachment #2: Type: text/html, Size: 1595 bytes --]

Re: [PATCH v4 1/2] doc: add devargs documentation

[Thomas Monjalon]

> Currently, the devargs syntax documentation is missing from the
> programmer's guide, and is only documented implicitly through the devargs
> API headers. Add a detailed description of the two supported devargs
> syntaxes.
> 
> Acked-by: John McNamara <john.mcnamara@intel.com>

Acked-by: Thomas Monjalon <thomas@monjalon.net>

Series applied with a bit of formatting, thanks.