1Orange Pi PC (``orangepi-pc``) 2^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 3 4The Xunlong Orange Pi PC is an Allwinner H3 System on Chip 5based embedded computer with mainline support in both U-Boot 6and Linux. The board comes with a Quad Core Cortex-A7 @ 1.3GHz, 71GiB RAM, 100Mbit ethernet, USB, SD/MMC, USB, HDMI and 8various other I/O. 9 10Supported devices 11""""""""""""""""" 12 13The Orange Pi PC machine supports the following devices: 14 15 * SMP (Quad Core Cortex-A7) 16 * Generic Interrupt Controller configuration 17 * SRAM mappings 18 * SDRAM controller 19 * Real Time Clock 20 * Timer device (re-used from Allwinner A10) 21 * UART 22 * SD/MMC storage controller 23 * EMAC ethernet 24 * USB 2.0 interfaces 25 * Clock Control Unit 26 * System Control module 27 * Security Identifier device 28 29Limitations 30""""""""""" 31 32Currently, Orange Pi PC does *not* support the following features: 33 34- Graphical output via HDMI, GPU and/or the Display Engine 35- Audio output 36- Hardware Watchdog 37 38Also see the 'unimplemented' array in the Allwinner H3 SoC module 39for a complete list of unimplemented I/O devices: ``./hw/arm/allwinner-h3.c`` 40 41Boot options 42"""""""""""" 43 44The Orange Pi PC machine can start using the standard -kernel functionality 45for loading a Linux kernel or ELF executable. Additionally, the Orange Pi PC 46machine can also emulate the BootROM which is present on an actual Allwinner H3 47based SoC, which loads the bootloader from a SD card, specified via the -sd argument 48to qemu-system-arm. 49 50Machine-specific options 51"""""""""""""""""""""""" 52 53The following machine-specific options are supported: 54 55- allwinner-rtc.base-year=YYYY 56 57 The Allwinner RTC device is automatically created by the Orange Pi PC machine 58 and uses a default base year value which can be overridden using the 'base-year' property. 59 The base year is the actual represented year when the RTC year value is zero. 60 This option can be used in case the target operating system driver uses a different 61 base year value. The minimum value for the base year is 1900. 62 63- allwinner-sid.identifier=abcd1122-a000-b000-c000-12345678ffff 64 65 The Security Identifier value can be read by the guest. 66 For example, U-Boot uses it to determine a unique MAC address. 67 68The above machine-specific options can be specified in qemu-system-arm 69via the '-global' argument, for example: 70 71.. code-block:: bash 72 73 $ qemu-system-arm -M orangepi-pc -sd mycard.img \ 74 -global allwinner-rtc.base-year=2000 75 76Running mainline Linux 77"""""""""""""""""""""" 78 79Mainline Linux kernels from 4.19 up to latest master are known to work. 80To build a Linux mainline kernel that can be booted by the Orange Pi PC machine, 81simply configure the kernel using the sunxi_defconfig configuration: 82 83.. code-block:: bash 84 85 $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make mrproper 86 $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make sunxi_defconfig 87 88To be able to use USB storage, you need to manually enable the corresponding 89configuration item. Start the kconfig configuration tool: 90 91.. code-block:: bash 92 93 $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make menuconfig 94 95Navigate to the following item, enable it and save your configuration: 96 97 Device Drivers > USB support > USB Mass Storage support 98 99Build the Linux kernel with: 100 101.. code-block:: bash 102 103 $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make 104 105To boot the newly build linux kernel in QEMU with the Orange Pi PC machine, use: 106 107.. code-block:: bash 108 109 $ qemu-system-arm -M orangepi-pc -nic user -nographic \ 110 -kernel /path/to/linux/arch/arm/boot/zImage \ 111 -append 'console=ttyS0,115200' \ 112 -dtb /path/to/linux/arch/arm/boot/dts/sun8i-h3-orangepi-pc.dtb 113 114Orange Pi PC images 115""""""""""""""""""" 116 117Note that the mainline kernel does not have a root filesystem. You may provide it 118with an official Orange Pi PC image from the official website: 119 120 http://www.orangepi.org/downloadresources/ 121 122Another possibility is to run an Armbian image for Orange Pi PC which 123can be downloaded from: 124 125 https://www.armbian.com/orange-pi-pc/ 126 127Alternatively, you can also choose to build you own image with buildroot 128using the orangepi_pc_defconfig. Also see https://buildroot.org for more information. 129 130When using an image as an SD card, it must be resized to a power of two. This can be 131done with the qemu-img command. It is recommended to only increase the image size 132instead of shrinking it to a power of two, to avoid loss of data. For example, 133to prepare a downloaded Armbian image, first extract it and then increase 134its size to one gigabyte as follows: 135 136.. code-block:: bash 137 138 $ qemu-img resize Armbian_19.11.3_Orangepipc_bionic_current_5.3.9.img 1G 139 140You can choose to attach the selected image either as an SD card or as USB mass storage. 141For example, to boot using the Orange Pi PC Debian image on SD card, simply add the -sd 142argument and provide the proper root= kernel parameter: 143 144.. code-block:: bash 145 146 $ qemu-system-arm -M orangepi-pc -nic user -nographic \ 147 -kernel /path/to/linux/arch/arm/boot/zImage \ 148 -append 'console=ttyS0,115200 root=/dev/mmcblk0p2' \ 149 -dtb /path/to/linux/arch/arm/boot/dts/sun8i-h3-orangepi-pc.dtb \ 150 -sd OrangePi_pc_debian_stretch_server_linux5.3.5_v1.0.img 151 152To attach the image as an USB mass storage device to the machine, 153simply append to the command: 154 155.. code-block:: bash 156 157 -drive if=none,id=stick,file=myimage.img \ 158 -device usb-storage,bus=usb-bus.0,drive=stick 159 160Instead of providing a custom Linux kernel via the -kernel command you may also 161choose to let the Orange Pi PC machine load the bootloader from SD card, just like 162a real board would do using the BootROM. Simply pass the selected image via the -sd 163argument and remove the -kernel, -append, -dbt and -initrd arguments: 164 165.. code-block:: bash 166 167 $ qemu-system-arm -M orangepi-pc -nic user -nographic \ 168 -sd Armbian_19.11.3_Orangepipc_buster_current_5.3.9.img 169 170Note that both the official Orange Pi PC images and Armbian images start 171a lot of userland programs via systemd. Depending on the host hardware and OS, 172they may be slow to emulate, especially due to emulating the 4 cores. 173To help reduce the performance slow down due to emulating the 4 cores, you can 174give the following kernel parameters via U-Boot (or via -append): 175 176.. code-block:: bash 177 178 => setenv extraargs 'systemd.default_timeout_start_sec=9000 loglevel=7 nosmp console=ttyS0,115200' 179 180Running U-Boot 181"""""""""""""" 182 183U-Boot mainline can be build and configured using the orangepi_pc_defconfig 184using similar commands as describe above for Linux. Note that it is recommended 185for development/testing to select the following configuration setting in U-Boot: 186 187 Device Tree Control > Provider for DTB for DT Control > Embedded DTB 188 189To start U-Boot using the Orange Pi PC machine, provide the 190u-boot binary to the -kernel argument: 191 192.. code-block:: bash 193 194 $ qemu-system-arm -M orangepi-pc -nic user -nographic \ 195 -kernel /path/to/uboot/u-boot -sd disk.img 196 197Use the following U-boot commands to load and boot a Linux kernel from SD card: 198 199.. code-block:: bash 200 201 => setenv bootargs console=ttyS0,115200 202 => ext2load mmc 0 0x42000000 zImage 203 => ext2load mmc 0 0x43000000 sun8i-h3-orangepi-pc.dtb 204 => bootz 0x42000000 - 0x43000000 205 206Running NetBSD 207"""""""""""""" 208 209The NetBSD operating system also includes support for Allwinner H3 based boards, 210including the Orange Pi PC. NetBSD 9.0 is known to work best for the Orange Pi PC 211board and provides a fully working system with serial console, networking and storage. 212For the Orange Pi PC machine, get the 'evbarm-earmv7hf' based image from: 213 214 https://cdn.netbsd.org/pub/NetBSD/NetBSD-9.0/evbarm-earmv7hf/binary/gzimg/armv7.img.gz 215 216The image requires manually installing U-Boot in the image. Build U-Boot with 217the orangepi_pc_defconfig configuration as described in the previous section. 218Next, unzip the NetBSD image and write the U-Boot binary including SPL using: 219 220.. code-block:: bash 221 222 $ gunzip armv7.img.gz 223 $ dd if=/path/to/u-boot-sunxi-with-spl.bin of=armv7.img bs=1024 seek=8 conv=notrunc 224 225Finally, before starting the machine the SD image must be extended such 226that the size of the SD image is a power of two and that the NetBSD kernel 227will not conclude the NetBSD partition is larger than the emulated SD card: 228 229.. code-block:: bash 230 231 $ qemu-img resize armv7.img 2G 232 233Start the machine using the following command: 234 235.. code-block:: bash 236 237 $ qemu-system-arm -M orangepi-pc -nic user -nographic \ 238 -sd armv7.img -global allwinner-rtc.base-year=2000 239 240At the U-Boot stage, interrupt the automatic boot process by pressing a key 241and set the following environment variables before booting: 242 243.. code-block:: bash 244 245 => setenv bootargs root=ld0a 246 => setenv kernel netbsd-GENERIC.ub 247 => setenv fdtfile dtb/sun8i-h3-orangepi-pc.dtb 248 => 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_addr_r} - ${fdt_addr_r}' 249 250Optionally you may save the environment variables to SD card with 'saveenv'. 251To continue booting simply give the 'boot' command and NetBSD boots. 252 253Orange Pi PC acceptance tests 254""""""""""""""""""""""""""""" 255 256The Orange Pi PC machine has several acceptance tests included. 257To run the whole set of tests, build QEMU from source and simply 258provide the following command: 259 260.. code-block:: bash 261 262 $ AVOCADO_ALLOW_LARGE_STORAGE=yes avocado --show=app,console run \ 263 -t machine:orangepi-pc tests/acceptance/boot_linux_console.py 264