docs: Add device hotplugging documentation

Add documentation for the new PCI device hotplug/unplug feature
(developer preview) and update the CHANGELOG.

Signed-off-by: Ilias Stamatis <ilstam@amazon.com>

Author: ilstam

CHANGELOG.md

@@ -10,6 +10,12 @@ and this project adheres to
 
 ### Added
 
+- [#5786](https://github.com/firecracker-microvm/firecracker/pull/5786): Added
+  developer preview support for hotplugging and hot-unplugging PCI virtio
+  devices (block, pmem, net) on a running microVM. The guest must manually
+  rescan the PCI bus after hotplug and remove the device before unplug since no
+  automatic notification mechanism is implemented yet. More information can be
+  found in the [Device Hotplugging](docs/device-hotplug.md) documentation page.
 - [#5323](https://github.com/firecracker-microvm/firecracker/pull/5323): Add
   support for Vsock Unix domain socket path overriding on snapshot restore. More
   information can be found in the

README.md

@@ -116,6 +116,8 @@ The **API endpoint** can be used to:
 - Add a [entropy device](docs/entropy.md) to the microVM.
 - Add a [pmem device](docs/pmem.md) to the microVM.
 - Configure and manage [memory hotplugging](docs/memory-hotplug.md).
+- `[Developer Preview]` [Hot-plug and hot-unplug](docs/device-hotplug.md) virtio
+  PCI devices while the VM is running.
 - Start the microVM using a given kernel image, root file system, and boot
   arguments.
 - [x86_64 only] Stop the microVM.

docs/device-hotplug.md

@@ -0,0 +1,91 @@
+# Device Hotplugging [Developer Preview]
+
+> [!WARNING]
+>
+> This feature is currently in
+> [Developer Preview](RELEASE_POLICY.md#developer-preview-features). It may have
+> limitations, and its API or behavior may change in future releases.
+
+Device hotplugging allows attaching and detaching PCI virtio devices to a
+running microVM without requiring a reboot. Supported device types are:
+
+- `virtio-block`
+- `virtio-pmem`
+- `virtio-net`
+
+## Prerequisites
+
+- **PCI transport enabled**: Firecracker must be started with the `--enable-pci`
+  flag. Device hotplugging is not supported with MMIO transport.
+- **Guest kernel with PCI support**: The guest kernel must have PCI and the
+  relevant virtio drivers enabled. See the
+  [kernel policy documentation](kernel-policy.md) for details.
+
+## Limitations
+
+- **No automatic guest notification**: Firecracker does not currently deliver a
+  hotplug notification to the guest. After hotplugging a device, the guest must
+  manually rescan the PCI bus to discover it. Similarly, before unplugging, the
+  guest must manually remove the device.
+
+## Hotplugging a device
+
+Hotplugging uses the same API endpoints used for pre-boot device configuration.
+The only difference is that the request is issued after the VM has started.
+
+```console
+socket_location=/run/firecracker.socket
+
+curl --unix-socket $socket_location -i \
+    -X PUT 'http://localhost/drives/block1' \
+    -H 'Accept: application/json' \
+    -H 'Content-Type: application/json' \
+    -d '{
+        "drive_id": "block1",
+        "path_on_host": "/path/to/block.ext4",
+        "is_root_device": false,
+        "is_read_only": false
+    }'
+```
+
+### Discovering the device in the guest
+
+Since no hotplug notification is delivered to the guest, a PCI bus rescan is
+required to make the guest discover the new device:
+
+```bash
+echo 1 > /sys/bus/pci/rescan
+```
+
+After the rescan, the device will appear in `lspci` and the corresponding device
+node (e.g. `/dev/vdb`, `/dev/pmem1`) will be created by the guest kernel.
+
+## Hot-unplugging a device
+
+Hot-unplugging is a two-step process: first the guest must release the device,
+then the host issues the unplug request.
+
+### Step 1: Remove the device from the guest
+
+Before issuing the unplug API call, the guest must gracefully release the
+device. For example, unmount any mounted filesystems and remove the PCI device:
+
+```bash
+# Unmount the filesystem (if applicable)
+umount /mnt/block1
+
+# Remove the device from the guest
+echo 1 > /sys/bus/pci/devices/0000:00:01.0/remove
+```
+
+Replace `0000:00:01.0` with the actual PCI BDF (Bus:Device.Function) address of
+the device, which can be found via `lspci`.
+
+### Step 2: Unplug from the host
+
+Issue a `DELETE` request to the corresponding device endpoint:
+
+```console
+curl --unix-socket $socket_location -i \
+    -X DELETE 'http://localhost/drives/block1'
+```