diff --git a/doc/developer-guides/primer.rst b/doc/developer-guides/primer.rst index a0d390c85..1471cdf49 100644 --- a/doc/developer-guides/primer.rst +++ b/doc/developer-guides/primer.rst @@ -795,6 +795,35 @@ To use the Virtio-blk device, use the following command: nohpet console=hvc0 no_timer_check ignore_loglevel \ log_buf_len=16M consoleblank=0 tsc=reliable" vm1 +Virtio-blk also supports rescan feature. Virtio-blk rescan is helpful +when the size/path of the Virtio-blk device's backing file (on the host) +changes and the guest needs to refresh its internal data structures to +pick up this change. Using rescan feature is simple, add Virtio-blk +device with dummy backend using "**nodisk**" keyword instead of a backing +file. + +To create a Virtio-blk device with dummy backend, +use the following command: + +.. code-block:: bash + + ./acrn-dm -A -m 1168M \ + -s 0:0,hostbridge \ + -s 1,virtio-blk,**nodisk** \ + -k bzImage -B "root=/dev/vda rw rootwait noxsave maxcpus=0 \ + nohpet console=hvc0 no_timer_check ignore_loglevel \ + log_buf_len=16M consoleblank=0 tsc=reliable" vm1 + +After VM launch, user can replace the dummy backend file with the +actual file using acrnctl "blkrescan" cmd as shown below, + +.. code-block:: bash + + acrnctl blkrescan vm1 1,actual_file.img + +Please refer to :ref:`acrnctl` for further details on +``acrnctl blkrescan`` command. + To verify the result, you should expect the user OS to boot successfully. diff --git a/tools/acrn-manager/README.rst b/tools/acrn-manager/README.rst index c78d82e16..6d69af2a8 100644 --- a/tools/acrn-manager/README.rst +++ b/tools/acrn-manager/README.rst @@ -32,6 +32,7 @@ You can see the available ``acrnctl`` commands by running: suspend resume reset + blkrescan Use acrnctl [cmd] help for details Here are some usage examples: @@ -93,6 +94,27 @@ Use the ``stop`` command to stop one or more running VM: # acrnctl stop vm-yocto vm1-14:59:30 vm-android +RESCAN BLOCK DEVICE +=================== + +Use the ``blkrescan`` command to trigger a rescan of +virtio-blk device by guest VM, in order to revalidate and +update the backend file. + +.. code-block:: none + + # acrnctl blkrescan vmname slot,newfilepath + vmname: Name of VM with dummy backend file attached to virtio-blk device. + slot: Slot number of the virtio-blk device. + newfilepath: File path for the backend of virtio-blk device. + + acrnctl blkrescan vm1 6,actual_file.img + +.. note:: blkrescan is only supported when VM is launched with + empty backend file (using **nodisk**) for virtio-blk device. + Replacing a valid backend file is not supported and will + result in error. + .. _acrnd: acrnd