diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/README.gpt | 17 | ||||
| -rw-r--r-- | doc/develop/driver-model/index.rst | 1 | ||||
| -rw-r--r-- | doc/develop/driver-model/virtio.rst (renamed from doc/README.virtio) | 90 | ||||
| -rw-r--r-- | doc/device-tree-bindings/sysinfo/gpio-sysinfo.txt | 37 | ||||
| -rw-r--r-- | doc/usage/exception.rst | 3 |
5 files changed, 120 insertions, 28 deletions
diff --git a/doc/README.gpt b/doc/README.gpt index ac975f66b88..91e397d06f8 100644 --- a/doc/README.gpt +++ b/doc/README.gpt @@ -237,6 +237,23 @@ doc/arch/index.rst: => gpt swap host 0 name othername [ . . . ] +Modifying GPT partition layout from U-Boot: +=========================================== + +The entire GPT partition layout can be exported to an environment +variable and then modified enmasse. Users can change the partition +numbers, offsets, names and sizes. The resulting variable can used to +reformat the device. Here is an example of reading the GPT partitions +into a variable and then modifying them: + +U-BOOT> gpt read mmc 0 current_partitions +U-BOOT> env edit current_partitions +edit: uuid_disk=[...];name=part1,start=0x4000,size=0x4000,uuid=[...]; +name=part2,start=0xc000,size=0xc000,uuid=[...];[ . . . ] + +U-BOOT> gpt write mmc 0 $current_partitions +U-BOOT> gpt verify mmc 0 $current_partitions + Partition type GUID: ==================== diff --git a/doc/develop/driver-model/index.rst b/doc/develop/driver-model/index.rst index fd4575db9b7..10a76256b0d 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 index d3652f2e2f8..8ac9c94cafe 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 <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 diff --git a/doc/device-tree-bindings/sysinfo/gpio-sysinfo.txt b/doc/device-tree-bindings/sysinfo/gpio-sysinfo.txt new file mode 100644 index 00000000000..b5739d94e9e --- /dev/null +++ b/doc/device-tree-bindings/sysinfo/gpio-sysinfo.txt @@ -0,0 +1,37 @@ +GPIO-based Sysinfo device + +This binding describes several GPIOs which specify a board revision. Each GPIO +forms a digit in a ternary revision number. This revision is then mapped to a +name using the revisions and names properties. + +Each GPIO may be floating, pulled-up, or pulled-down, mapping to digits 2, 1, +and 0, respectively. The first GPIO forms the least-significant digit of the +revision. For example, consider the property + + gpios = <&gpio 0>, <&gpio 1>, <&gpio 2>; + +If GPIO 0 is pulled-up, GPIO 1 is pulled-down, and GPIO 2 is floating, then the +revision would be + + 0t201 = 2*9 + 0*3 + 1*3 = 19 + +If instead GPIO 0 is floating, GPIO 1 is pulled-up, and GPIO 2 is pulled-down, +then the revision would be + + 0t012 = 0*9 + 1*3 + 2*1 = 5 + +Required properties: +- compatible: should be "gpio-sysinfo". +- gpios: should be a list of gpios forming the revision number, + least-significant-digit first +- revisions: a list of known revisions; any revisions not present will have the + name "unknown" +- names: the name of each revision in revisions + +Example: +sysinfo { + compatible = "gpio-sysinfo"; + gpios = <&gpio_a 15>, <&gpio_a 16>, <&gpio_a 17>; + revisions = <19>, <5>; + names = "rev_a", "foo"; +}; diff --git a/doc/usage/exception.rst b/doc/usage/exception.rst index db1490f0055..27df88bd5c9 100644 --- a/doc/usage/exception.rst +++ b/doc/usage/exception.rst @@ -31,6 +31,9 @@ type **RISC-V:** + ebreak + breakpoint exception + unaligned load address misaligned |