hw/misc: Add npcm7xx random number generator
[qemu.git] / 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 When using an image as an SD card, it must be resized to a power of two. This can be
131 done with the qemu-img command. It is recommended to only increase the image size
132 instead of shrinking it to a power of two, to avoid loss of data. For example,
133 to prepare a downloaded Armbian image, first extract it and then increase
134 its size to one gigabyte as follows:
135
136 .. code-block:: bash
137
138   $ qemu-img resize Armbian_19.11.3_Orangepipc_bionic_current_5.3.9.img 1G
139
140 You can choose to attach the selected image either as an SD card or as USB mass storage.
141 For example, to boot using the Orange Pi PC Debian image on SD card, simply add the -sd
142 argument and provide the proper root= kernel parameter:
143
144 .. code-block:: bash
145
146   $ qemu-system-arm -M orangepi-pc -nic user -nographic \
147       -kernel /path/to/linux/arch/arm/boot/zImage \
148       -append 'console=ttyS0,115200 root=/dev/mmcblk0p2' \
149       -dtb /path/to/linux/arch/arm/boot/dts/sun8i-h3-orangepi-pc.dtb \
150       -sd OrangePi_pc_debian_stretch_server_linux5.3.5_v1.0.img
151
152 To attach the image as an USB mass storage device to the machine,
153 simply append to the command:
154
155 .. code-block:: bash
156
157   -drive if=none,id=stick,file=myimage.img \
158   -device usb-storage,bus=usb-bus.0,drive=stick
159
160 Instead of providing a custom Linux kernel via the -kernel command you may also
161 choose to let the Orange Pi PC machine load the bootloader from SD card, just like
162 a real board would do using the BootROM. Simply pass the selected image via the -sd
163 argument and remove the -kernel, -append, -dbt and -initrd arguments:
164
165 .. code-block:: bash
166
167   $ qemu-system-arm -M orangepi-pc -nic user -nographic \
168        -sd Armbian_19.11.3_Orangepipc_buster_current_5.3.9.img
169
170 Note that both the official Orange Pi PC images and Armbian images start
171 a lot of userland programs via systemd. Depending on the host hardware and OS,
172 they may be slow to emulate, especially due to emulating the 4 cores.
173 To help reduce the performance slow down due to emulating the 4 cores, you can
174 give the following kernel parameters via U-Boot (or via -append):
175
176 .. code-block:: bash
177
178   => setenv extraargs 'systemd.default_timeout_start_sec=9000 loglevel=7 nosmp console=ttyS0,115200'
179
180 Running U-Boot
181 """"""""""""""
182
183 U-Boot mainline can be build and configured using the orangepi_pc_defconfig
184 using similar commands as describe above for Linux. Note that it is recommended
185 for development/testing to select the following configuration setting in U-Boot:
186
187   Device Tree Control > Provider for DTB for DT Control > Embedded DTB
188
189 To start U-Boot using the Orange Pi PC machine, provide the
190 u-boot binary to the -kernel argument:
191
192 .. code-block:: bash
193
194   $ qemu-system-arm -M orangepi-pc -nic user -nographic \
195       -kernel /path/to/uboot/u-boot -sd disk.img
196
197 Use the following U-boot commands to load and boot a Linux kernel from SD card:
198
199 .. code-block:: bash
200
201   => setenv bootargs console=ttyS0,115200
202   => ext2load mmc 0 0x42000000 zImage
203   => ext2load mmc 0 0x43000000 sun8i-h3-orangepi-pc.dtb
204   => bootz 0x42000000 - 0x43000000
205
206 Running NetBSD
207 """"""""""""""
208
209 The NetBSD operating system also includes support for Allwinner H3 based boards,
210 including the Orange Pi PC. NetBSD 9.0 is known to work best for the Orange Pi PC
211 board and provides a fully working system with serial console, networking and storage.
212 For the Orange Pi PC machine, get the 'evbarm-earmv7hf' based image from:
213
214   https://cdn.netbsd.org/pub/NetBSD/NetBSD-9.0/evbarm-earmv7hf/binary/gzimg/armv7.img.gz
215
216 The image requires manually installing U-Boot in the image. Build U-Boot with
217 the orangepi_pc_defconfig configuration as described in the previous section.
218 Next, unzip the NetBSD image and write the U-Boot binary including SPL using:
219
220 .. code-block:: bash
221
222   $ gunzip armv7.img.gz
223   $ dd if=/path/to/u-boot-sunxi-with-spl.bin of=armv7.img bs=1024 seek=8 conv=notrunc
224
225 Finally, before starting the machine the SD image must be extended such
226 that the size of the SD image is a power of two and that the NetBSD kernel
227 will not conclude the NetBSD partition is larger than the emulated SD card:
228
229 .. code-block:: bash
230
231   $ qemu-img resize armv7.img 2G
232
233 Start the machine using the following command:
234
235 .. code-block:: bash
236
237   $ qemu-system-arm -M orangepi-pc -nic user -nographic \
238         -sd armv7.img -global allwinner-rtc.base-year=2000
239
240 At the U-Boot stage, interrupt the automatic boot process by pressing a key
241 and set the following environment variables before booting:
242
243 .. code-block:: bash
244
245   => setenv bootargs root=ld0a
246   => setenv kernel netbsd-GENERIC.ub
247   => setenv fdtfile dtb/sun8i-h3-orangepi-pc.dtb
248   => 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}'
249
250 Optionally you may save the environment variables to SD card with 'saveenv'.
251 To continue booting simply give the 'boot' command and NetBSD boots.
252
253 Orange Pi PC acceptance tests
254 """""""""""""""""""""""""""""
255
256 The Orange Pi PC machine has several acceptance tests included.
257 To run the whole set of tests, build QEMU from source and simply
258 provide the following command:
259
260 .. code-block:: bash
261
262   $ AVOCADO_ALLOW_LARGE_STORAGE=yes avocado --show=app,console run \
263      -t machine:orangepi-pc tests/acceptance/boot_linux_console.py