Documentation: add Documentation on VirtIO for barebox

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@a3f.at>
Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>

2 files changed, 83 insertions, 0 deletions

diff --git a/Documentation/user/user-manual.rst b/Documentation/user/user-manual.rst
index 827683eaa0..c80bfbf263 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 0000000000..5d2a8c8208
--- /dev/null
+++ b/Documentation/user/virtio.rst
@@ -0,0 +1,82 @@
+..
+  SPDX-License-Identifier: GPL-2.0+
+
+  Copyright (C) 2018, Bin Meng <bmeng.cn@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
+
+To access the console socket, you can use ``socat /tmp/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