| 1 | Orange Pi PC (``orangepi-pc``) |
| 2 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 3 | |
| 4 | The Xunlong Orange Pi PC is an Allwinner H3 System on Chip |
| 5 | based embedded computer with mainline support in both U-Boot |
| 6 | and Linux. The board comes with a Quad Core Cortex-A7 @ 1.3GHz, |
| 7 | 1GiB RAM, 100Mbit ethernet, USB, SD/MMC, USB, HDMI and |
| 8 | various other I/O. |
| 9 | |
| 10 | Supported devices |
| 11 | """"""""""""""""" |
| 12 | |
| 13 | The 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 | |
| 31 | Limitations |
| 32 | """"""""""" |
| 33 | |
| 34 | Currently, 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 | |
| 40 | Also see the 'unimplemented' array in the Allwinner H3 SoC module |
| 41 | for a complete list of unimplemented I/O devices: ``./hw/arm/allwinner-h3.c`` |
| 42 | |
| 43 | Boot options |
| 44 | """""""""""" |
| 45 | |
| 46 | The Orange Pi PC machine can start using the standard -kernel functionality |
| 47 | for loading a Linux kernel or ELF executable. Additionally, the Orange Pi PC |
| 48 | machine can also emulate the BootROM which is present on an actual Allwinner H3 |
| 49 | based SoC, which loads the bootloader from a SD card, specified via the -sd argument |
| 50 | to qemu-system-arm. |
| 51 | |
| 52 | Machine-specific options |
| 53 | """""""""""""""""""""""" |
| 54 | |
| 55 | The 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 | |
| 70 | The above machine-specific options can be specified in qemu-system-arm |
| 71 | via 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 | |
| 78 | Running mainline Linux |
| 79 | """""""""""""""""""""" |
| 80 | |
| 81 | Mainline Linux kernels from 4.19 up to latest master are known to work. |
| 82 | To build a Linux mainline kernel that can be booted by the Orange Pi PC machine, |
| 83 | simply 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 | |
| 90 | To be able to use USB storage, you need to manually enable the corresponding |
| 91 | configuration item. Start the kconfig configuration tool: |
| 92 | |
| 93 | .. code-block:: bash |
| 94 | |
| 95 | $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make menuconfig |
| 96 | |
| 97 | Navigate to the following item, enable it and save your configuration: |
| 98 | |
| 99 | Device Drivers > USB support > USB Mass Storage support |
| 100 | |
| 101 | Build the Linux kernel with: |
| 102 | |
| 103 | .. code-block:: bash |
| 104 | |
| 105 | $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make |
| 106 | |
| 107 | To 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 | |
| 116 | Orange Pi PC images |
| 117 | """"""""""""""""""" |
| 118 | |
| 119 | Note that the mainline kernel does not have a root filesystem. You may provide it |
| 120 | with an official Orange Pi PC image from the official website: |
| 121 | |
| 122 | http://www.orangepi.org/html/serviceAndSupport/index.html |
| 123 | |
| 124 | Another possibility is to run an Armbian image for Orange Pi PC which |
| 125 | can be downloaded from: |
| 126 | |
| 127 | https://www.armbian.com/orange-pi-pc/ |
| 128 | |
| 129 | Alternatively, you can also choose to build you own image with buildroot |
| 130 | using the orangepi_pc_defconfig. Also see https://buildroot.org for more information. |
| 131 | |
| 132 | When using an image as an SD card, it must be resized to a power of two. This can be |
| 133 | done with the ``qemu-img`` command. It is recommended to only increase the image size |
| 134 | instead of shrinking it to a power of two, to avoid loss of data. For example, |
| 135 | to prepare a downloaded Armbian image, first extract it and then increase |
| 136 | its 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 | |
| 142 | You can choose to attach the selected image either as an SD card or as USB mass storage. |
| 143 | For example, to boot using the Orange Pi PC Debian image on SD card, simply add the -sd |
| 144 | argument 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 | |
| 154 | To attach the image as an USB mass storage device to the machine, |
| 155 | simply 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 | |
| 162 | Instead of providing a custom Linux kernel via the -kernel command you may also |
| 163 | choose to let the Orange Pi PC machine load the bootloader from SD card, just like |
| 164 | a real board would do using the BootROM. Simply pass the selected image via the -sd |
| 165 | argument 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 | |
| 172 | Note that both the official Orange Pi PC images and Armbian images start |
| 173 | a lot of userland programs via systemd. Depending on the host hardware and OS, |
| 174 | they may be slow to emulate, especially due to emulating the 4 cores. |
| 175 | To help reduce the performance slow down due to emulating the 4 cores, you can |
| 176 | give 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 | |
| 182 | Running U-Boot |
| 183 | """""""""""""" |
| 184 | |
| 185 | U-Boot mainline can be build and configured using the orangepi_pc_defconfig |
| 186 | using similar commands as describe above for Linux. Note that it is recommended |
| 187 | for 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 | |
| 191 | To start U-Boot using the Orange Pi PC machine, provide the |
| 192 | u-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 | |
| 199 | Use 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 | |
| 208 | Running NetBSD |
| 209 | """""""""""""" |
| 210 | |
| 211 | The NetBSD operating system also includes support for Allwinner H3 based boards, |
| 212 | including the Orange Pi PC. NetBSD 9.0 is known to work best for the Orange Pi PC |
| 213 | board and provides a fully working system with serial console, networking and storage. |
| 214 | For the Orange Pi PC machine, get the 'evbarm-earmv7hf' based image from: |
| 215 | |
| 216 | https://archive.netbsd.org/pub/NetBSD-archive/NetBSD-9.0/evbarm-earmv7hf/binary/gzimg/armv7.img.gz |
| 217 | |
| 218 | The image requires manually installing U-Boot in the image. Build U-Boot with |
| 219 | the orangepi_pc_defconfig configuration as described in the previous section. |
| 220 | Next, 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 | |
| 227 | Finally, before starting the machine the SD image must be extended such |
| 228 | that the size of the SD image is a power of two and that the NetBSD kernel |
| 229 | will 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 | |
| 235 | Start 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 | |
| 242 | At the U-Boot stage, interrupt the automatic boot process by pressing a key |
| 243 | and 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 | |
| 252 | Optionally you may save the environment variables to SD card with 'saveenv'. |
| 253 | To continue booting simply give the 'boot' command and NetBSD boots. |
| 254 | |
| 255 | Orange Pi PC functional tests |
| 256 | """"""""""""""""""""""""""""" |
| 257 | |
| 258 | The Orange Pi PC machine has several functional tests included. |
| 259 | To run the whole set of tests, build QEMU from source and simply |
| 260 | provide the following command from the build directory: |
| 261 | |
| 262 | .. code-block:: bash |
| 263 | |
| 264 | $ QEMU_TEST_ALLOW_LARGE_STORAGE=1 \ |
| 265 | pyvenv/bin/meson test --suite thorough func-arm-arm_orangepi |