xref: /openbmc/qemu/docs/system/arm/orangepi.rst (revision c663fc9f)
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