Skip to content

Commit

Permalink
doc(vhost-user-block): updated PATCH api docs
Browse files Browse the repository at this point in the history
Updated document about patching block devices
with info about vhost-user-block.

Signed-off-by: Egor Lazarchuk <yegorlz@amazon.co.uk>
  • Loading branch information
ShadowCurse committed Nov 20, 2023
1 parent 1076182 commit 88c361a
Showing 1 changed file with 15 additions and 13 deletions.
28 changes: 15 additions & 13 deletions docs/api_requests/patch-block.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,29 @@

Firecracker offers support to update attached block devices after the microVM
has been started. This is provided via PATCH /drives API which notifies
Firecracker that the underlying block file has been changed on the host. It
should be called when the path to the block device is changed or if the file
size has been modified. It is important to note that external changes to the
block device file do not automatically trigger a notification in Firecracker
so the explicit PATCH API call is mandatory.
Firecracker that the underlying block file has been changed on the host or
in the backend in vhost-user-block case. For virtio-block it should be called
when the path to the block device is changed or if the file size has been
modified. For vhost-user-block it should be called when the file size has
been modified. It is important to note that external changes to the block
device file or vhost-user-block backend do not automatically trigger a
notification in Firecracker so the explicit PATCH API call is mandatory.

### How it works

The implementation of the PATCH /drives API does not modify the host backing
file. It only updates the emulation layer block device properties, path and
length and then triggers a virtio device reconfiguration that is handled by the
guest driver which will update the size of the raw block device.
With that being said, a sequence which performs resizing/altering of the block
underlying host file followed by a PATCH /drives API call is not an atomic
operation as the guest can also modify the block file via emulation during
the sequence, if the raw block device is mounted or accessible.
file and does not update vhost-user-block backend. It only updates the emulation
layer block configuration and then triggers a virtio device reconfiguration
that is handled by the guest driver which will update the size of the raw block
device. With that being said, a sequence which performs resizing/altering of the
block underlying host file or backend followed by a PATCH /drives API call is
not an atomic operation as the guest can also modify the block file via emulation
during the sequence, if the raw block device is mounted or accessible.

### Supported use case

This feature was designed to work with a cooperative guest in order to
effectively simulate hot plug/unplug functionality for block devices.
effectively emulate hot plug/unplug functionality for block devices.

The following guarantees need to be provided:

Expand Down

0 comments on commit 88c361a

Please sign in to comment.