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