diff options
author | Sascha Hauer <s.hauer@pengutronix.de> | 2021-02-22 10:39:52 +0100 |
---|---|---|
committer | Sascha Hauer <s.hauer@pengutronix.de> | 2021-02-22 10:39:52 +0100 |
commit | 2575ef9d523e8aa1f7a187c44cdff9dc8ee172d3 (patch) | |
tree | 214ac1a690a32e97b34c32f890b6269d53aa0dd6 /Documentation | |
parent | a97e0b863eefb4a1025e39429cabf67b3ea34b72 (diff) | |
parent | 8b357213cf4ba80cce86fcbee88d2b237d67e066 (diff) | |
download | barebox-2575ef9d523e8aa1f7a187c44cdff9dc8ee172d3.tar.gz barebox-2575ef9d523e8aa1f7a187c44cdff9dc8ee172d3.tar.xz |
Merge branch 'for-next/virtio'
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/user/user-manual.rst | 1 | ||||
-rw-r--r-- | Documentation/user/virtio.rst | 82 |
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 |