From patchwork Thu Apr 29 09:40:07 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bin Meng X-Patchwork-Id: 1471618 X-Patchwork-Delegate: bmeng.cn@gmail.com Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=lists.denx.de (client-ip=2a01:238:438b:c500:173d:9f52:ddab:ee01; helo=phobos.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=) Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.a=rsa-sha256 header.s=20161025 header.b=jcDQX018; dkim-atps=neutral Received: from phobos.denx.de (phobos.denx.de [IPv6:2a01:238:438b:c500:173d:9f52:ddab:ee01]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4FW9Tx5yBnz9sW1 for ; Thu, 29 Apr 2021 19:40:33 +1000 (AEST) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 9EA0C82CC9; Thu, 29 Apr 2021 11:40:20 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="jcDQX018"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 02A0482CC9; Thu, 29 Apr 2021 11:40:19 +0200 (CEST) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on phobos.denx.de X-Spam-Level: X-Spam-Status: No, score=-2.0 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,FREEMAIL_FROM,SPF_HELO_NONE autolearn=ham autolearn_force=no version=3.4.2 Received: from mail-ej1-x629.google.com (mail-ej1-x629.google.com [IPv6:2a00:1450:4864:20::629]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 7B8058188B for ; Thu, 29 Apr 2021 11:40:14 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=bmeng.cn@gmail.com Received: by mail-ej1-x629.google.com with SMTP id u21so98918654ejo.13 for ; Thu, 29 Apr 2021 02:40:14 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:subject:date:message-id:mime-version :content-transfer-encoding; bh=zYNWslp5rl/GnubnJ0fiMZzl1HEn+wmGnVE6d7Mpuj0=; b=jcDQX018abVJDYnKi2fdhy4qD/0joyMLEvHQGxr0kwQHcAJe7fRh0CPQN+8vgARK0S TkJUFJQKEsFaBVlzIYto2fMD5Qr3lnn6WvsZuXc+5PTcf9YpGZEFm/IJva8P3jG1+iop 2kLBfVvx+9ohoVjBnYSxn1JMFvAOaXAKdGN/ApVhz6yNdORa5VAQzEq1DlmjXp0mZhoL GQoWOrTJ7aEBgwchlfhQPcm1YkkbI7prfYBeiP5npizkU/CS0cj2P2dPqFS8dYBtPlgQ yaEF62GgZ+pc0ARvx/RPBh76KS6rI2dvGaW2uXZWJF7bo8H3cItlhjGuFzg/UHQXRHf4 2hWA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:mime-version :content-transfer-encoding; bh=zYNWslp5rl/GnubnJ0fiMZzl1HEn+wmGnVE6d7Mpuj0=; b=io7um1CAg12V6MLxoHXKWu3XSz+kxi9mxfwLlFr3RM8edxKo0Zmmew6VQeRF01C/nM wAjrCDN//xUIYtaWLcTCV25HvZyOu5aC16v+6yanoFbvjg/PV+RSn5t+t8jlg/xbnxbD b6DDq8OkxASBem8PYZdo2waUGuQ/tGv7lQrcznpvaupfPlnW+yNqXBpAW73VO+KS4I3h pdanWk4X5nuDcen956NDi4EaFxPjIPP5ikKvoOpZbpz4W9qM/wB+42lIHyo/VZnFh1LK Krz1C2MHktFsO+UnY4xB644U/RerjtM2UwVN7Rzz+czVvhMTXR8wSKjOXrJMdQJUkI9Q vEnQ== X-Gm-Message-State: AOAM532gTB7oEDq1+kbD0ITuczG35sxITJvRla+YsFttXMTylFuIhiTd RQEvr6Zp/GlpgdO3opJncMo= X-Google-Smtp-Source: ABdhPJztUft6EVmxDKbavT+lgZ/QTnCEcJuZfHlShHsmVsilSL7z0D2tnOqjuhG77RJAkd9vlfGvTA== X-Received: by 2002:a17:906:e096:: with SMTP id gh22mr11817613ejb.101.1619689213964; Thu, 29 Apr 2021 02:40:13 -0700 (PDT) Received: from pek-vx-bsp2.wrs.com (ec2-44-242-66-180.us-west-2.compute.amazonaws.com. [44.242.66.180]) by smtp.gmail.com with ESMTPSA id u19sm1880942edy.23.2021.04.29.02.40.11 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 29 Apr 2021 02:40:13 -0700 (PDT) From: Bin Meng To: Tom Rini , u-boot@lists.denx.de Subject: [PATCH 1/2] doc: develop: Convert README.virtio to reST Date: Thu, 29 Apr 2021 17:40:07 +0800 Message-Id: <20210429094008.1458660-1-bmeng.cn@gmail.com> X-Mailer: git-send-email 2.25.1 MIME-Version: 1.0 X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.34 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.102.4 at phobos.denx.de X-Virus-Status: Clean This convers the existing README.virtio to reST, and puts it under the develop/driver-model/ directory. Signed-off-by: Bin Meng --- doc/develop/driver-model/index.rst | 1 + .../driver-model/virtio.rst} | 90 +++++++++++++------ 2 files changed, 63 insertions(+), 28 deletions(-) rename doc/{README.virtio => develop/driver-model/virtio.rst} (86%) diff --git a/doc/develop/driver-model/index.rst b/doc/develop/driver-model/index.rst index fd4575db9b..10a76256b0 100644 --- 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 d3652f2e2f..8ac9c94caf 100644 --- 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 +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Bin Meng 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 / 4096 . 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