diff --git a/doc/developer-guides/hld/hld-emulated-devices.rst b/doc/developer-guides/hld/hld-emulated-devices.rst index 9723cc7a8..5a9aeca10 100644 --- a/doc/developer-guides/hld/hld-emulated-devices.rst +++ b/doc/developer-guides/hld/hld-emulated-devices.rst @@ -14,5 +14,4 @@ documented in this section. usb-virt-hld UART virtualization Watchdoc virtualization - random-virt-hld GVT-g GPU Virtualization diff --git a/doc/developer-guides/hld/images/rand-virt.png b/doc/developer-guides/hld/images/rand-virt.png deleted file mode 100644 index 0eb24bff1..000000000 Binary files a/doc/developer-guides/hld/images/rand-virt.png and /dev/null differ diff --git a/doc/developer-guides/hld/images/virtio-hld-image61.png b/doc/developer-guides/hld/images/virtio-hld-image61.png old mode 100644 new mode 100755 index e2417c4be..d41805977 Binary files a/doc/developer-guides/hld/images/virtio-hld-image61.png and b/doc/developer-guides/hld/images/virtio-hld-image61.png differ diff --git a/doc/developer-guides/hld/random-virt-hld.rst b/doc/developer-guides/hld/random-virt-hld.rst deleted file mode 100644 index 3e0036b15..000000000 --- a/doc/developer-guides/hld/random-virt-hld.rst +++ /dev/null @@ -1,76 +0,0 @@ -.. _random_virtualization: - -Random device virtualization -############################ - -The virtual random device virtio-rnd provides a virtual hardware random -source for UOS, based on virtio user mode framework. It simulates a PCI -device based on virtio specification. - -Architecture -************ - -:numref:`rand-virt-arch` shows the Random Device Virtualization Architecture in ACRN. -The green components are parts of the ACRN solution while the dark -components are parts of Linux software or third party tools. - -virtio-rnd is implemented as a virtio legacy device in the ACRN device -model (DM), and is registered as a PCI virtio device to the guest OS -(UOS). Tools such as :command:`od` (dump a file in octal or other format) can -be used to read random values from ``/dev/random``. This device file in -UOS is bound with the frontend virtio-rng driver. (The guest kernel must -be built with ``CONFIG_HW_RANDOM_VIRTIO=y``). The backend -virtio-rnd reads the HW random value from ``/dev/random`` in SOS and sends -them to frontend. - -.. figure:: images/rand-virt.png - :align: center - :name: rand-virt-arch - - Random Device Virtualization in ACRN - -How to Use -********** - -Add a pci slot to the device model acrn-dm command line, for example:: - - -s ,virtio-rnd - -Check if the frontend virtio_rng driver is available in UOS: - -.. code-block:: console - - # cat /sys/class/misc/hw_random/rng_available - virtio_rng.0 - -Check if frontend virtio_rng is currently connected to ``/dev/random``: - -.. code-block:: console - - # cat /sys/class/misc/hw_random/rng_current - virtio_rng.0 - -Read random values: - -.. code-block:: console - - # od /dev/random - 0000000 007265 175751 147323 164223 060601 057377 027072 106352 - 0000020 040765 045645 155773 111724 037572 152033 036001 056073 - 0000040 057164 065021 024005 031500 156630 026635 022440 000127 - 0000060 115071 046756 071656 106721 161340 106726 175275 072403 - 0000100 011265 000420 061137 103723 001107 006430 061151 132766 - 0000120 166216 015074 100505 015473 057324 102727 005126 051731 - 0000140 003727 071115 167622 071407 120301 002616 047451 120733 - 0000160 174117 133164 161231 035076 013700 164114 031627 001202 - 0000200 011467 055650 016365 140074 060277 150601 043610 006403 - 0000220 016170 071666 065540 026615 055073 162363 012002 112371 - 0000240 000767 157121 125007 141671 000327 173741 056415 155463 - 0000260 105504 066453 152754 136314 175213 063541 001420 053025 - 0000300 047631 167425 044125 063176 171334 177234 050063 031640 - ... - - -.. note:: HW randomness is a precious resource of the system. The - :command:`od` command will block and wait until there is randomness - available. diff --git a/doc/developer-guides/hld/virtio-rnd.rst b/doc/developer-guides/hld/virtio-rnd.rst index 1653583ed..afd237312 100644 --- a/doc/developer-guides/hld/virtio-rnd.rst +++ b/doc/developer-guides/hld/virtio-rnd.rst @@ -3,23 +3,24 @@ Virtio-rnd ########## -virtio-rnd provides a hardware random source for UOS. The -virtual random device is based on virtio user mode framework and -simulates a PCI device based on virtio specification. +Virtio-rnd provides a virtual hardware random source for UOS. It simulates a PCI device +followed virtio specification, and implemented base on virtio user mode framework. -:numref:`virtio-rnd-arch` shows the Random Device Virtualization -Architecture in ACRN. virtio-rnd is implemented as a virtio legacy -device in the ACRN device model (DM), and is registered as a PCI virtio -device to the guest OS (UOS). +Architecture +************ -When the FE driver requires some random bytes, the BE device will place -bytes of random data onto the virtqueue. +:numref:`virtio-rnd-arch` shows the Random Device Virtualization Architecture in ACRN. +The green components are parts of the ACRN solution while the gray +components are parts of Linux software or third party tools. -Tools such as ``od`` can be used to read randomness from -``/dev/random``. This device file in UOS is bound with frontend -virtio-rng driver (The guest kernel must be built with -``CONFIG_HW_RANDOM_VIRTIO=y``). The backend virtio-rnd reads the HW -randomness from ``/dev/random`` in SOS and sends them to frontend. +virtio-rnd is implemented as a virtio legacy device in the ACRN device +model (DM), and is registered as a PCI virtio device to the guest OS +(UOS). Tools such as :command:`od` (dump a file in octal or other format) can +be used to read random values from ``/dev/random``. This device file in +UOS is bound with the frontend virtio-rng driver. (The guest kernel must +be built with ``CONFIG_HW_RANDOM_VIRTIO=y``). The backend +virtio-rnd reads the HW random value from ``/dev/random`` in SOS and sends +them to frontend. .. figure:: images/virtio-hld-image61.png :align: center @@ -27,11 +28,48 @@ randomness from ``/dev/random`` in SOS and sends them to frontend. Virtio-rnd Architecture on ACRN -To launch the virtio-rnd device, use the following virtio command:: +How to Use +********** - -s ,virtio-rnd +Add a pci slot to the device model acrn-dm command line, for example:: -To verify the correctness in user OS, use the following -command:: + -s ,virtio-rnd - od /dev/random +Check if the frontend virtio_rng driver is available in UOS: + +.. code-block:: console + + # cat /sys/class/misc/hw_random/rng_available + virtio_rng.0 + +Check if frontend virtio_rng is currently connected to ``/dev/random``: + +.. code-block:: console + + # cat /sys/class/misc/hw_random/rng_current + virtio_rng.0 + +Read random values: + +.. code-block:: console + + # od /dev/random + 0000000 007265 175751 147323 164223 060601 057377 027072 106352 + 0000020 040765 045645 155773 111724 037572 152033 036001 056073 + 0000040 057164 065021 024005 031500 156630 026635 022440 000127 + 0000060 115071 046756 071656 106721 161340 106726 175275 072403 + 0000100 011265 000420 061137 103723 001107 006430 061151 132766 + 0000120 166216 015074 100505 015473 057324 102727 005126 051731 + 0000140 003727 071115 167622 071407 120301 002616 047451 120733 + 0000160 174117 133164 161231 035076 013700 164114 031627 001202 + 0000200 011467 055650 016365 140074 060277 150601 043610 006403 + 0000220 016170 071666 065540 026615 055073 162363 012002 112371 + 0000240 000767 157121 125007 141671 000327 173741 056415 155463 + 0000260 105504 066453 152754 136314 175213 063541 001420 053025 + 0000300 047631 167425 044125 063176 171334 177234 050063 031640 + ... + + +.. note:: HW randomness is a precious resource of the system. The + :command:`od` command will block and wait until there is randomness + available.