doc: develop: Convert README.virtio to reST

This converts the existing README.virtio to reST, and puts it under
the develop/driver-model/ directory.

Signed-off-by: Bin Meng <bmeng.cn@gmail.com>

diff --git a/doc/develop/driver-model/index.rst b/doc/develop/driver-model/index.rst
index fd4575db9b76b5499c69743ec62d4e753499abc8..10a76256b0dff247a77df2fd44e0f294640f1a8a 100644 (file)
--- a/doc/develop/driver-model/index.rst
+++ b/doc/develop/driver-model/index.rst
@@ -27,3 +27,4 @@ subsystems
    soc-framework
    spi-howto
    usb-info
+   virtio

diff --git a/doc/README.virtio b/doc/develop/driver-model/virtio.rst
similarity index 86%
rename from doc/README.virtio
rename to doc/develop/driver-model/virtio.rst
index d3652f2e2f8cbdf7f59f37f53d9ab9bce632c73f..8ac9c94cafe273e03deab0a63f22926f609d97fd 100644 (file)
--- a/doc/README.virtio
+++ b/doc/develop/driver-model/virtio.rst
@@ -1,11 +1,10 @@
-# SPDX-License-Identifier: GPL-2.0+
-#
-# Copyright (C) 2018, Bin Meng <bmeng.cn@gmail.com>
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Bin Meng <bmeng.cn@gmail.com>
 
 VirtIO Support
 ==============
 
-This document describes the information about U-Boot support for VirtIO [1]
+This document describes the information about U-Boot support for VirtIO_
 devices, including supported boards, build instructions, driver details etc.
 
 What's VirtIO?
@@ -15,7 +14,7 @@ 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 U-Boot case, the guest is U-Boot itself, while the
-virtual environment are normally QEMU [2] targets like ARM, RISC-V and x86.
+virtual environment are normally QEMU_ targets like ARM, RISC-V and x86.
 
 Status
 ------
@@ -49,6 +48,8 @@ Building U-Boot for pre-configured 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:
 
+.. code-block:: bash
+
   $ make qemu_arm_defconfig
   $ make
 
@@ -56,11 +57,13 @@ You can even create a QEMU ARM target with VirtIO devices showing up on both
 MMIO and PCI buses. In this case, you can enable the PCI transport driver
 from 'make menuconfig':
 
-Device Drivers  --->
-       ...
-       VirtIO Drivers  --->
-               ...
-               [*] PCI driver for virtio devices
+.. code-block:: none
+
+  Device Drivers  --->
+       ...
+       VirtIO Drivers  --->
+               ...
+               [*] PCI driver for virtio devices
 
 Other drivers are at the same location and can be tuned to suit the needs.
 
@@ -74,6 +77,8 @@ Testing
 The following QEMU command line is used to get U-Boot up and running with
 VirtIO net and block devices on ARM.
 
+.. code-block:: bash
+
   $ qemu-system-arm -nographic -machine virt -bios u-boot.bin \
     -netdev tap,ifname=tap0,id=net0 \
     -device virtio-net-device,netdev=net0 \
@@ -82,6 +87,8 @@ VirtIO net and block devices on ARM.
 
 On x86, command is slightly different to create PCI VirtIO devices.
 
+.. code-block:: bash
+
   $ qemu-system-i386 -nographic -bios u-boot.rom \
     -netdev tap,ifname=tap0,id=net0 \
     -device virtio-net-pci,netdev=net0 \
@@ -93,6 +100,8 @@ parameters. It is also possible to specify both MMIO and PCI VirtIO devices.
 For example, the following commnad creates 3 VirtIO devices, with 1 on MMIO
 and 2 on PCI bus.
 
+.. code-block:: bash
+
   $ qemu-system-arm -nographic -machine virt -bios u-boot.bin \
     -netdev tap,ifname=tap0,id=net0 \
     -device virtio-net-pci,netdev=net0 \
@@ -104,6 +113,8 @@ and 2 on PCI bus.
 By default QEMU creates VirtIO legacy devices by default. To create non-legacy
 (aka modern) devices, pass additional device property/value pairs like below:
 
+.. code-block:: bash
+
   $ qemu-system-i386 -nographic -bios u-boot.rom \
     -netdev tap,ifname=tap0,id=net0 \
     -device virtio-net-pci,netdev=net0,disable-legacy=true,disable-modern=false \
@@ -112,6 +123,8 @@ By default QEMU creates VirtIO legacy devices by default. To create non-legacy
 
 A 'virtio' command is provided in U-Boot shell.
 
+.. code-block:: none
+
   => virtio
   virtio - virtio block devices sub-system
 
@@ -127,10 +140,14 @@ A 'virtio' command is provided in U-Boot shell.
 
 To probe all the VirtIO devices, type:
 
+.. code-block:: none
+
   => virtio scan
 
 Then we can show the connected block device details by:
 
+.. code-block:: none
+
   => virtio info
   Device 0: QEMU VirtIO Block Device
               Type: Hard Disk
@@ -138,6 +155,8 @@ Then we can show the connected block device details by:
 
 And list the directories and files on the disk by:
 
+.. code-block:: none
+
   => ls virtio 0 /
   <DIR>       4096 .
   <DIR>       4096 ..
@@ -167,6 +186,8 @@ Driver Internals
 ----------------
 There are 3 level of drivers in the VirtIO driver family.
 
+.. code-block:: none
+
        +---------------------------------------+
        |        virtio device drivers          |
        |    +-------------+ +------------+     |
@@ -199,20 +220,26 @@ The transport drivers provide a set of ops (struct dm_virtio_ops) for the real
 virtio device driver to call. These ops APIs's parameter is designed to remind
 the caller to pass the correct 'struct udevice' id of the virtio device, eg:
 
-int virtio_get_status(struct udevice *vdev, u8 *status)
+.. code-block:: C
+
+  int virtio_get_status(struct udevice *vdev, u8 *status)
 
 So the parameter 'vdev' indicates the device should be the real virtio device.
 But we also have an API like:
 
-struct virtqueue *vring_create_virtqueue(unsigned int index, unsigned int num,
-                                        unsigned int vring_align,
-                                        struct udevice *udev)
+.. code-block:: C
+
+  struct virtqueue *vring_create_virtqueue(unsigned int index, unsigned int num,
+                                        unsigned int vring_align,
+                                        struct udevice *udev)
 
 Here the parameter 'udev' indicates the device should be the transport device.
 Similar naming is applied in other functions that are even not APIs, eg:
 
-static int virtio_uclass_post_probe(struct udevice *udev)
-static int virtio_uclass_child_pre_probe(struct udevice *vdev)
+.. code-block:: C
+
+  static int virtio_uclass_post_probe(struct udevice *udev)
+  static int virtio_uclass_child_pre_probe(struct udevice *vdev)
 
 So it's easy to tell which device these functions are operating on.
 
@@ -223,20 +250,29 @@ ID 2) are supported. If you want to develop new driver for new devices,
 please follow the guideline below.
 
 1. add new device ID in virtio.h
-#define VIRTIO_ID_XXX          X
+
+.. code-block:: C
+
+  #define VIRTIO_ID_XXX                X
 
 2. update VIRTIO_ID_MAX_NUM to be the largest device ID plus 1
 
 3. add new driver name string in virtio.h
-#define VIRTIO_XXX_DRV_NAME    "virtio-xxx"
+
+.. code-block:: C
+
+  #define VIRTIO_XXX_DRV_NAME  "virtio-xxx"
 
 4. create a new driver with name set to the name string above
-U_BOOT_DRIVER(virtio_xxx) = {
-       .name = VIRTIO_XXX_DRV_NAME,
-       ...
-       .remove = virtio_reset,
-       .flags = DM_FLAG_ACTIVE_DMA,
-}
+
+.. code-block:: C
+
+  U_BOOT_DRIVER(virtio_xxx) = {
+       .name = VIRTIO_XXX_DRV_NAME,
+       ...
+       .remove = virtio_reset,
+       .flags = DM_FLAG_ACTIVE_DMA,
+  }
 
 Note the driver needs to provide the remove method and normally this can be
 hooked to virtio_reset(). The driver flags should contain DM_FLAG_ACTIVE_DMA
@@ -247,7 +283,5 @@ for the remove method to be called before jumping to OS.
 
 6. do funny stuff with the driver
 
-References
-----------
-[1] http://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.pdf
-[2] https://www.qemu.org
+.. _VirtIO: http://docs.oasis-open.org/virtio/virtio/v1.0/virtio-v1.0.pdf
+.. _QEMU: https://www.qemu.org