From nobody Wed Feb 11 00:37:06 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=gmail.com ARC-Seal: i=1; a=rsa-sha256; t=1583965703; cv=none; d=zohomail.com; s=zohoarc; b=g8Azj8iE5dVDPnW/yjITY10IMKqAPEmp2BGCrw1fBiZShuXshOAhEjEm5JZg9sMi9zEwkbIw6iGJ21TR61ueSL1RbbjsYJ8nDSn/vJBQrO3fAcBAoxb8V4gN9bnRlIpxR+huqk1xwJ6+s7HfN/c0yS81JmHHFp4JQi5C5tPuTr8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1583965703; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=RguScf1FniegYgxvxOFDzNoMeQXqsYwVI5JFQf6Z8Vo=; b=cpTH75k7hP3bgipKHnCkRcJSmwGdOszEl5iYisSUr6xSQGcZQHs45NxcSEEYrMbqM71GvQ9pQFDqO4UE7jIWYKQ6XPnxI0yXJspGZX4ofW5HhEEV8x3MLAzrUGpIbyUmJ5Z2Qb5gg6l+X7Hca6I7BzKTSbMhkzZox7H9gdut5a4= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1583965703800362.4422164542867; Wed, 11 Mar 2020 15:28:23 -0700 (PDT) Received: from localhost ([::1]:58894 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jC9pt-0004t9-Th for importer@patchew.org; Wed, 11 Mar 2020 18:28:21 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:59428) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jC9hD-00042O-AR for qemu-devel@nongnu.org; Wed, 11 Mar 2020 18:19:25 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jC9hA-00058k-Nv for qemu-devel@nongnu.org; Wed, 11 Mar 2020 18:19:23 -0400 Received: from mail-wr1-x444.google.com ([2a00:1450:4864:20::444]:37653) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jC9hA-00058I-GC; Wed, 11 Mar 2020 18:19:20 -0400 Received: by mail-wr1-x444.google.com with SMTP id 6so4806614wre.4; Wed, 11 Mar 2020 15:19:20 -0700 (PDT) Received: from pavilion.home ([2a02:a456:6be8:1:8edc:d4ff:fe8b:18b7]) by smtp.gmail.com with ESMTPSA id q7sm19346796wrd.54.2020.03.11.15.19.18 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 11 Mar 2020 15:19:18 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=RguScf1FniegYgxvxOFDzNoMeQXqsYwVI5JFQf6Z8Vo=; b=WEXSW1mBd50lwaE9KxhB8SEl9mee66Fiy7T68A5ONrPZQ/WQ8axwTY3bWDdvmwjaVN ctXlMFHOEC97OuiW/l01oMdAxrrb/L637l17dMualqyWVsJcHZfM+bVliJPMvTOwpvJE L2ZkMM/8hlBWhuHKyZIUlwpZCV0Lm6RuiIxwIkQzFulUVotGbsrs6toryAD63oFE5U24 IMM2xekwmJ7t5oi3gBE8Vxj/FIRbjEr9NlhSZaKx+efOyqG4IoDzOaqZzi/AzRW/i9fo nyHYC9O8myeHKcd7aAbA8OMYn/sH8bjISybbZNIEphyBcRLbFFdUMsCrNcjmrLc7utlV nLeQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=RguScf1FniegYgxvxOFDzNoMeQXqsYwVI5JFQf6Z8Vo=; b=X957l+YzHaH7RgM0RnGL8BvCCm8pUlalaemjkBxUyfQY81ktfw/fdPTB6KwsWX7JHR x61a6JZfVdJDE2GThnqnpBofwS9QYvQko96hto6hVdMNCs38gn02d0WwLmjH9vltOvy8 rf3viLH/UvqetV/EVOxBG+LoeD3eBzf0GvoPR6T+ohH/p+DgM0Zaci2Parn6S1Yv5BNq PmQNcqBk4OzeJ+rDcsv1NqrNipPKWbtzV4S/Y5W2wu4vWY2QgBPT0CXr+x/Gr4o+bBNo lv1FpbjTz7oBm2sv/yBfRXMXfLvjwJvqEws+CtB+IhZ7FJEtq/Z3/OmbxbHoCS+VWyxy zsbA== X-Gm-Message-State: ANhLgQ06v4oVwcr7K7OIgzTVvoEzk8Wg7ZZh88BQn3rNAzgb3PkWh4fB v7+T67bI3lAqENyHyNuRGhyNFfrR X-Google-Smtp-Source: ADFU+vtLO0iEbGFPOuagbGlesjhR1dYEJsnzJaUfXfcHyzPBnBisu2M2wUoLzFinqj2pq+trKbJLpw== X-Received: by 2002:a5d:42c8:: with SMTP id t8mr6688666wrr.415.1583965158975; Wed, 11 Mar 2020 15:19:18 -0700 (PDT) From: Niek Linnenbank To: qemu-devel@nongnu.org Subject: [PATCH v8 18/18] docs: add Orange Pi PC document Date: Wed, 11 Mar 2020 23:18:54 +0100 Message-Id: <20200311221854.30370-19-nieklinnenbank@gmail.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20200311221854.30370-1-nieklinnenbank@gmail.com> References: <20200311221854.30370-1-nieklinnenbank@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::444 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: peter.maydell@linaro.org, alex.bennee@linaro.org, jasowang@redhat.com, b.galvani@gmail.com, Niek Linnenbank , qemu-arm@nongnu.org, imammedo@redhat.com, philmd@redhat.com Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) The Xunlong Orange Pi PC machine is a functional ARM machine based on the Allwinner H3 System-on-Chip. It supports mainline Linux, U-Boot, NetBSD and is covered by acceptance tests. This commit adds a documentation text file with a description of the machine and instructions for the user. Signed-off-by: Niek Linnenbank Reviewed-by: Alex Benn=C3=A9e --- docs/system/orangepi.rst | 253 +++++++++++++++++++++++++++++++++++++ docs/system/target-arm.rst | 2 + MAINTAINERS | 1 + 3 files changed, 256 insertions(+) create mode 100644 docs/system/orangepi.rst diff --git a/docs/system/orangepi.rst b/docs/system/orangepi.rst new file mode 100644 index 0000000000..a76d52fb33 --- /dev/null +++ b/docs/system/orangepi.rst @@ -0,0 +1,253 @@ +Orange Pi PC Machine Type +^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Xunlong Orange Pi PC is an Allwinner H3 System on Chip +based embedded computer with mainline support in both U-Boot +and Linux. The board comes with a Quad Core Cortex-A7 @ 1.3GHz, +1GiB RAM, 100Mbit ethernet, USB, SD/MMC, USB, HDMI and +various other I/O. + +Supported devices +""""""""""""""""" + +The Orange Pi PC machine supports the following devices: + + * SMP (Quad Core Cortex-A7) + * Generic Interrupt Controller configuration + * SRAM mappings + * SDRAM controller + * Real Time Clock + * Timer device (re-used from Allwinner A10) + * UART + * SD/MMC storage controller + * EMAC ethernet + * USB 2.0 interfaces + * Clock Control Unit + * System Control module + * Security Identifier device + +Limitations +""""""""""" + +Currently, Orange Pi PC does *not* support the following features: + +- Graphical output via HDMI, GPU and/or the Display Engine +- Audio output +- Hardware Watchdog + +Also see the 'unimplemented' array in the Allwinner H3 SoC module +for a complete list of unimplemented I/O devices: ``./hw/arm/allwinner-h3.= c`` + +Boot options +"""""""""""" + +The Orange Pi PC machine can start using the standard -kernel functionality +for loading a Linux kernel or ELF executable. Additionally, the Orange Pi = PC +machine can also emulate the BootROM which is present on an actual Allwinn= er H3 +based SoC, which loads the bootloader from a SD card, specified via the -s= d argument +to qemu-system-arm. + +Machine-specific options +"""""""""""""""""""""""" + +The following machine-specific options are supported: + +- allwinner-rtc.base-year=3DYYYY + + The Allwinner RTC device is automatically created by the Orange Pi PC ma= chine + and uses a default base year value which can be overridden using the 'ba= se-year' property. + The base year is the actual represented year when the RTC year value is = zero. + This option can be used in case the target operating system driver uses = a different + base year value. The minimum value for the base year is 1900. + +- allwinner-sid.identifier=3Dabcd1122-a000-b000-c000-12345678ffff + + The Security Identifier value can be read by the guest. + For example, U-Boot uses it to determine a unique MAC address. + +The above machine-specific options can be specified in qemu-system-arm +via the '-global' argument, for example: + +.. code-block:: bash + + $ qemu-system-arm -M orangepi-pc -sd mycard.img \ + -global allwinner-rtc.base-year=3D2000 + +Running mainline Linux +"""""""""""""""""""""" + +Mainline Linux kernels from 4.19 up to latest master are known to work. +To build a Linux mainline kernel that can be booted by the Orange Pi PC ma= chine, +simply configure the kernel using the sunxi_defconfig configuration: + +.. code-block:: bash + + $ ARCH=3Darm CROSS_COMPILE=3Darm-linux-gnueabi- make mrproper + $ ARCH=3Darm CROSS_COMPILE=3Darm-linux-gnueabi- make sunxi_defconfig + +To be able to use USB storage, you need to manually enable the correspondi= ng +configuration item. Start the kconfig configuration tool: + +.. code-block:: bash + + $ ARCH=3Darm CROSS_COMPILE=3Darm-linux-gnueabi- make menuconfig + +Navigate to the following item, enable it and save your configuration: + + Device Drivers > USB support > USB Mass Storage support + +Build the Linux kernel with: + +.. code-block:: bash + + $ ARCH=3Darm CROSS_COMPILE=3Darm-linux-gnueabi- make + +To boot the newly build linux kernel in QEMU with the Orange Pi PC machine= , use: + +.. code-block:: bash + + $ qemu-system-arm -M orangepi-pc -nic user -nographic \ + -kernel /path/to/linux/arch/arm/boot/zImage \ + -append 'console=3DttyS0,115200' \ + -dtb /path/to/linux/arch/arm/boot/dts/sun8i-h3-orangepi-pc.dtb + +Orange Pi PC images +""""""""""""""""""" + +Note that the mainline kernel does not have a root filesystem. You may pro= vide it +with an official Orange Pi PC image from the official website: + + http://www.orangepi.org/downloadresources/ + +Another possibility is to run an Armbian image for Orange Pi PC which +can be downloaded from: + + https://www.armbian.com/orange-pi-pc/ + +Alternatively, you can also choose to build you own image with buildroot +using the orangepi_pc_defconfig. Also see https://buildroot.org for more i= nformation. + +You can choose to attach the selected image either as an SD card or as USB= mass storage. +For example, to boot using the Orange Pi PC Debian image on SD card, simpl= y add the -sd +argument and provide the proper root=3D kernel parameter: + +.. code-block:: bash + + $ qemu-system-arm -M orangepi-pc -nic user -nographic \ + -kernel /path/to/linux/arch/arm/boot/zImage \ + -append 'console=3DttyS0,115200 root=3D/dev/mmcblk0p2' \ + -dtb /path/to/linux/arch/arm/boot/dts/sun8i-h3-orangepi-pc.dtb \ + -sd OrangePi_pc_debian_stretch_server_linux5.3.5_v1.0.img + +To attach the image as an USB mass storage device to the machine, +simply append to the command: + +.. code-block:: bash + + -drive if=3Dnone,id=3Dstick,file=3Dmyimage.img \ + -device usb-storage,bus=3Dusb-bus.0,drive=3Dstick + +Instead of providing a custom Linux kernel via the -kernel command you may= also +choose to let the Orange Pi PC machine load the bootloader from SD card, j= ust like +a real board would do using the BootROM. Simply pass the selected image vi= a the -sd +argument and remove the -kernel, -append, -dbt and -initrd arguments: + +.. code-block:: bash + + $ qemu-system-arm -M orangepi-pc -nic user -nographic \ + -sd Armbian_19.11.3_Orangepipc_buster_current_5.3.9.img + +Note that both the official Orange Pi PC images and Armbian images start +a lot of userland programs via systemd. Depending on the host hardware and= OS, +they may be slow to emulate, especially due to emulating the 4 cores. +To help reduce the performance slow down due to emulating the 4 cores, you= can +give the following kernel parameters via U-Boot (or via -append): + +.. code-block:: bash + + =3D> setenv extraargs 'systemd.default_timeout_start_sec=3D9000 loglevel= =3D7 nosmp console=3DttyS0,115200' + +Running U-Boot +"""""""""""""" + +U-Boot mainline can be build and configured using the orangepi_pc_defconfig +using similar commands as describe above for Linux. Note that it is recomm= ended +for development/testing to select the following configuration setting in U= -Boot: + + Device Tree Control > Provider for DTB for DT Control > Embedded DTB + +To start U-Boot using the Orange Pi PC machine, provide the +u-boot binary to the -kernel argument: + +.. code-block:: bash + + $ qemu-system-arm -M orangepi-pc -nic user -nographic \ + -kernel /path/to/uboot/u-boot -sd disk.img + +Use the following U-boot commands to load and boot a Linux kernel from SD = card: + +.. code-block:: bash + + =3D> setenv bootargs console=3DttyS0,115200 + =3D> ext2load mmc 0 0x42000000 zImage + =3D> ext2load mmc 0 0x43000000 sun8i-h3-orangepi-pc.dtb + =3D> bootz 0x42000000 - 0x43000000 + +Running NetBSD +"""""""""""""" + +The NetBSD operating system also includes support for Allwinner H3 based b= oards, +including the Orange Pi PC. NetBSD 9.0 is known to work best for the Orang= e Pi PC +board and provides a fully working system with serial console, networking = and storage. +For the Orange Pi PC machine, get the 'evbarm-earmv7hf' based image from: + + https://cdn.netbsd.org/pub/NetBSD/NetBSD-9.0/evbarm-earmv7hf/binary/gzim= g/armv7.img.gz + +The image requires manually installing U-Boot in the image. Build U-Boot w= ith +the orangepi_pc_defconfig configuration as described in the previous secti= on. +Next, unzip the NetBSD image and write the U-Boot binary including SPL usi= ng: + +.. code-block:: bash + + $ gunzip armv7.img.gz + $ dd if=3D/path/to/u-boot-sunxi-with-spl.bin of=3Darmv7.img bs=3D1024 se= ek=3D8 conv=3Dnotrunc + +Finally, before starting the machine the SD image must be extended such +that the NetBSD kernel will not conclude the NetBSD partition is larger th= an +the emulated SD card: + +.. code-block:: bash + + $ dd if=3D/dev/zero bs=3D1M count=3D64 >> armv7.img + +Start the machine using the following command: + +.. code-block:: bash + + $ qemu-system-arm -M orangepi-pc -nic user -nographic \ + -sd armv7.img -global allwinner-rtc.base-year=3D2000 + +At the U-Boot stage, interrupt the automatic boot process by pressing a key +and set the following environment variables before booting: + +.. code-block:: bash + + =3D> setenv bootargs root=3Dld0a + =3D> setenv kernel netbsd-GENERIC.ub + =3D> setenv fdtfile dtb/sun8i-h3-orangepi-pc.dtb + =3D> setenv bootcmd 'fatload mmc 0:1 ${kernel_addr_r} ${kernel}; fatload= mmc 0:1 ${fdt_addr_r} ${fdtfile}; fdt addr ${fdt_addr_r}; bootm ${kernel_a= ddr_r} - ${fdt_addr_r}' + +Optionally you may save the environment variables to SD card with 'saveenv= '. +To continue booting simply give the 'boot' command and NetBSD boots. + +Orange Pi PC acceptance tests +""""""""""""""""""""""""""""" + +The Orange Pi PC machine has several acceptance tests included. +To run the whole set of tests, build QEMU from source and simply +provide the following command: + +.. code-block:: bash + + $ AVOCADO_ALLOW_LARGE_STORAGE=3Dyes avocado --show=3Dapp,console run \ + -t machine:orangepi-pc tests/acceptance/boot_linux_console.py diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst index d2a3b44ce8..f16465aa48 100644 --- a/docs/system/target-arm.rst +++ b/docs/system/target-arm.rst @@ -215,3 +215,5 @@ emulation includes the following elements: =20 A Linux 2.6 test image is available on the QEMU web site. More information is available in the QEMU mailing-list archive. + +.. include:: orangepi.rst diff --git a/MAINTAINERS b/MAINTAINERS index ba46545464..f700c21170 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -498,6 +498,7 @@ S: Maintained F: hw/*/allwinner-h3* F: include/hw/*/allwinner-h3* F: hw/arm/orangepi.c +F: docs/system/orangepi.rst =20 ARM PrimeCell and CMSDK devices M: Peter Maydell --=20 2.17.1