docs/system/arm/orangepi.rst

   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/downloadresources/
 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://cdn.netbsd.org/pub/NetBSD/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 integration tests
 256 """"""""""""""""""""""""""""""
 257
 258 The Orange Pi PC machine has several integration tests included.
 259 To run the whole set of tests, build QEMU from source and simply
 260 provide 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