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