[PATCH 8/8] Documentation: add Documentation on VirtIO for barebox

[Ahmad Fatoum]

Save users the trip to the commit log and reproduce some example qemu
invocations in the documentation. The text around it is adapted from
the U-Boot doc/README.virtio.

Signed-off-by: Ahmad Fatoum <ahmad at a3f.at>
---
 Documentation/user/user-manual.rst |  1 +
 Documentation/user/virtio.rst      | 80 ++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 Documentation/user/virtio.rst

diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
index 827683eaa0db..c80bfbf2639a 100644
--- a/Documentation/user/user-manual.rst
+++ b/Documentation/user/user-manual.rst
@@ -36,6 +36,7 @@ Contents:
    optee
    debugging
    watchdog
+   virtio
 
 * :ref:`search`
 * :ref:`genindex`
diff --git a/Documentation/user/virtio.rst b/Documentation/user/virtio.rst
new file mode 100644
index 000000000000..7233c001bcce
--- /dev/null
+++ b/Documentation/user/virtio.rst
@@ -0,0 +1,80 @@
+..
+  SPDX-License-Identifier: GPL-2.0+
+
+  Copyright (C) 2018, Bin Meng <bmeng.cn at gmail.com>
+  Copyright (C) 2021, Ahmad Fatoum
+
+.. _virtio:
+
+VirtIO Support
+==============
+
+This document describes the information about barebox support for VirtIO_
+devices, including supported boards, build instructions, driver details etc.
+
+What's VirtIO?
+--------------
+
+VirtIO is a virtualization standard for network and disk device drivers where
+just the guest's device driver "knows" it is running in a virtual environment,
+and cooperates with the hypervisor. This enables guests to get high performance
+network and disk operations, and gives most of the performance benefits of
+paravirtualization. In the barebox case, the guest is barebox itself, while the
+virtual environment will normally be QEMU_ targets like ARM, RISC-V and x86.
+
+Status
+------
+
+VirtIO can use various different buses, aka transports as described in the
+spec. While VirtIO devices are commonly implemented as PCI devices on x86,
+embedded devices models like ARM/RISC-V, which does not normally come with
+PCI support might use simple memory mapped device (MMIO) instead of the PCI
+device. The memory mapped virtio device behaviour is based on the PCI device
+specification. Therefore most operations including device initialization,
+queues configuration and buffer transfers are nearly identical. Only MMIO
+is currently supported in barebox.
+
+The VirtIO spec defines a lots of VirtIO device types, however at present only
+block, console and RNG devices are supported.
+
+Build Instructions
+------------------
+
+Building barebox for QEMU targets is no different from others.
+For example, we can do the following with the CROSS_COMPILE environment
+variable being properly set to a working toolchain for ARM::
+
+  $ make vexpress_defconfig
+  $ make
+
+Testing
+-------
+
+The following QEMU command line is used to get barebox up and running with
+a VirtIO console on ARM::
+
+  $ qemu-system-arm -m 256M -M virt -nographic             \
+  	-kernel ./images/barebox-dt-2nd.img                \
+  	-device virtio-serial-device                       \
+  	-chardev socket,path=/tmp/foo,server,nowait,id=foo \
+  	-device virtconsole,chardev=foo,name=console.foo
+
+Note the use of ``-kernel ./images/barebox-dt-2nd.img`` instead of
+``-bios ./images/barebox-$BOARD.img``. ``-kernel`` will cause QEMU
+to pass barebox a fixed-up device tree describing the ``virtio-mmio``
+rings.
+
+Except for the console, multiple instances of a VirtIO device can be created
+by appending more '-device' parameters. For example to create one HWRNG
+and 2 block devices::
+
+  $ qemu-system-arm -m 256M -M virt -nographic                  \
+    	-kernel ./images/barebox-dt-2nd.img                     \
+  	-device virtio-rng-device                               \
+  	-drive if=none,file=/tmp/first.hdimg,format=raw,id=hd0  \
+  	-device virtio-blk-device,drive=hd0		        \
+  	-drive if=none,file=/tmp/second.hdimg,format=raw,id=hd1 \
+  	-device virtio-blk-device,drive=hd1
+
+.. _VirtIO: http://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.pdf
+.. _qemu: https://www.qemu.org
-- 
2.30.0