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