u-boot/doc/README.virtio

1 # SPDX-License-Identifier: GPL-2.0+
5 VirtIO Support
8 This document describes the information about U-Boot support for VirtIO [1]
11 What's VirtIO?
12 --------------
13 VirtIO is a virtualization standard for network and disk device drivers where
17 paravirtualization. In the U-Boot case, the guest is U-Boot itself, while the
18 virtual environment are normally QEMU [2] targets like ARM, RISC-V and x86.
21 ------
22 VirtIO can use various different buses, aka transports as described in the
23 spec. While VirtIO devices are commonly implemented as PCI devices on x86,
24 embedded devices models like ARM/RISC-V, which does not normally come with
25 PCI support might use simple memory mapped device (MMIO) instead of the PCI
26 device. The memory mapped virtio device behaviour is based on the PCI device
29 and PCI transport options are supported in U-Boot.
31 The VirtIO spec defines a lots of VirtIO device types, however at present only
36   - qemu_arm_defconfig
37   - qemu_arm64_defconfig
38   - qemu-riscv32_defconfig
39   - qemu-riscv64_defconfig
40   - qemu-x86_defconfig
41   - qemu-x86_64_defconfig
43 Note ARM and RISC-V targets are configured with VirtIO MMIO transport driver,
44 and on x86 it's the PCI transport driver.
47 ------------------
48 Building U-Boot for pre-configured QEMU targets is no different from others.
55 You can even create a QEMU ARM target with VirtIO devices showing up on both
56 MMIO and PCI buses. In this case, you can enable the PCI transport driver
59 Device Drivers  --->
61 	VirtIO Drivers  --->
63 		[*] PCI driver for virtio devices
68 ------------
69 It is required that QEMU v2.5.0+ should be used to test U-Boot VirtIO support
70 on QEMU ARM and x86, and v2.12.0+ on QEMU RISC-V.
73 -------
74 The following QEMU command line is used to get U-Boot up and running with
75 VirtIO net and block devices on ARM.
77   $ qemu-system-arm -nographic -machine virt -bios u-boot.bin \
78     -netdev tap,ifname=tap0,id=net0 \
79     -device virtio-net-device,netdev=net0 \
80     -drive if=none,file=test.img,format=raw,id=hd0 \
81     -device virtio-blk-device,drive=hd0
83 On x86, command is slightly different to create PCI VirtIO devices.
85   $ qemu-system-i386 -nographic -bios u-boot.rom \
86     -netdev tap,ifname=tap0,id=net0 \
87     -device virtio-net-pci,netdev=net0 \
88     -drive if=none,file=test.img,format=raw,id=hd0 \
89     -device virtio-blk-pci,drive=hd0
91 Additional net and block devices can be created by appending more '-device'
92 parameters. It is also possible to specify both MMIO and PCI VirtIO devices.
93 For example, the following commnad creates 3 VirtIO devices, with 1 on MMIO
94 and 2 on PCI bus.
96   $ qemu-system-arm -nographic -machine virt -bios u-boot.bin \
97     -netdev tap,ifname=tap0,id=net0 \
98     -device virtio-net-pci,netdev=net0 \
99     -drive if=none,file=test0.img,format=raw,id=hd0 \
100     -device virtio-blk-device,drive=hd0 \
101     -drive if=none,file=test1.img,format=raw,id=hd1 \
102     -device virtio-blk-pci,drive=hd1
104 By default QEMU creates VirtIO legacy devices by default. To create non-legacy
107   $ qemu-system-i386 -nographic -bios u-boot.rom \
108     -netdev tap,ifname=tap0,id=net0 \
109     -device virtio-net-pci,netdev=net0,disable-legacy=true,disable-modern=false \
110     -drive if=none,file=test.img,format=raw,id=hd0 \
111     -device virtio-blk-pci,drive=hd0,disable-legacy=true,disable-modern=false
113 A 'virtio' command is provided in U-Boot shell.
115   => virtio
116   virtio - virtio block devices sub-system
119   virtio scan - initialize virtio bus
120   virtio info - show all available virtio block devices
121   virtio device [dev] - show or set current virtio block device
122   virtio part [dev] - print partition table of one or all virtio block devices
123   virtio read addr blk# cnt - read `cnt' blocks starting at block
125   virtio write addr blk# cnt - write `cnt' blocks starting at block
128 To probe all the VirtIO devices, type:
130   => virtio scan
134   => virtio info
135   Device 0: QEMU VirtIO Block Device
141   => ls virtio 0 /
167 ----------------
168 There are 3 level of drivers in the VirtIO driver family.
170 	+---------------------------------------+
171 	|	 virtio device drivers		|
172 	|    +-------------+ +------------+	|
173 	|    | virtio-net  | | virtio-blk |	|
174 	|    +-------------+ +------------+	|
175 	+---------------------------------------+
176 	+---------------------------------------+
177 	|	virtio transport drivers	|
178 	|    +-------------+ +------------+	|
179 	|    | virtio-mmio | | virtio-pci |	|
180 	|    +-------------+ +------------+	|
181 	+---------------------------------------+
182 		+----------------------+
183 		| virtio uclass driver |
184 		+----------------------+
186 The root one is the virtio uclass driver (virtio-uclass.c), which does lots of
188 virtio device is discovered in the transport driver's probe() method, and its
189 device ID is saved in the virtio uclass's private data of the transport device.
190 Then in the virtio uclass's post_probe() method, the real virtio device driver
194 virtio uclass driver help bring the virtio device driver online. They do things
196 for all virtio devices.
199 virtio device driver to call. These ops APIs's parameter is designed to remind
200 the caller to pass the correct 'struct udevice' id of the virtio device, eg:
204 So the parameter 'vdev' indicates the device should be the real virtio device.
220 ----------------
221 At present only VirtIO network card (device ID 1) and block device (device
225 1. add new device ID in virtio.h
230 3. add new driver name string in virtio.h
231 #define VIRTIO_XXX_DRV_NAME	"virtio-xxx"
251 ----------
252 [1] http://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.pdf