[v3,17/17] 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>
---
 docs/orangepi.rst | 200 ++++++++++++++++++++++++++++++++++++++++++++++
 MAINTAINERS       |   1 +
 2 files changed, 201 insertions(+)
 create mode 100644 docs/orangepi.rst

On 1/8/20 9:00 PM, Niek Linnenbank wrote:
> 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>
> ---
>   docs/orangepi.rst | 200 ++++++++++++++++++++++++++++++++++++++++++++++
>   MAINTAINERS       |   1 +
>   2 files changed, 201 insertions(+)
>   create mode 100644 docs/orangepi.rst
> 
> diff --git a/docs/orangepi.rst b/docs/orangepi.rst
> new file mode 100644
> index 0000000000..5ac2a7b7cc
> --- /dev/null
> +++ b/docs/orangepi.rst
> @@ -0,0 +1,200 @@
> +=========================
> +Orange Pi PC Machine Type
> +=========================
> +
> +The Xunlong Orange Pi PC is an Allwinner H3 System on Chip
> +based embedded computer with mainline support in both U-Boot
> +and Linux. The board comes with a Quad Core Cortex A7 @ 1.3GHz,
> +512MB RAM, 100Mbit ethernet, USB, SD/MMC, USB, HDMI and
> +various other I/O.
> +
> +Supported devices
> +-----------------
> +
> +The Orange Pi PC machine type supports the following devices:

Maybe drop "type"?

> +
> + * SMP (Quad Core Cortex A7)
> + * Generic Interrupt Controller configuration
> + * SRAM mappings
> + * SDRAM controller
> + * Real Time Clock
> + * Timer device (re-used from Allwinner A10)
> + * UART
> + * SD/MMC storage controller
> + * EMAC ethernet connectivity

Drop "connectivity"?

> + * USB 2.0 interfaces
> + * Clock Control Unit
> + * System Control module
> + * Security Identifier device
> +
> +Limitations
> +-----------
> +
> +Currently, Orange Pi PC does *not* support the following features:
> +
> +- Graphical output via HDMI, GPU and/or the Display Engine
> +- Audio output
> +- Hardware Watchdog
> +
> +Also see the 'unimplemented' array in the Allwinner H3 SoC module
> +for a complete list of unimplemented I/O devices:
> +  ./hw/arm/allwinner-h3.c
> +
> +Using the Orange Pi PC machine type
> +-----------------------------------
> +
> +Boot options
> +~~~~~~~~~~~~
> +
> +The Orange Pi PC machine can start using the standard -kernel functionality
> +for loading a Linux kernel or ELF executable. Additionally, the Orange Pi PC
> +machine can also emulate the BootROM which is present on an actual Allwinner H3
> +based SoC, which loads the bootloader from SD card, specified via the -sd argument

"from a SD card"?

> +to qemu-system-arm.
> +
> +Running mainline Linux
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +Recently released mainline Linux kernels from 4.19 up to latest master

Drop "Recently released mainline" or only use "Mainline"?

> +are known to work. To build a Linux mainline kernel that can be booted
> +by the Orange Pi PC machine, simply configure the kernel using the
> +sunxi_defconfig configuration:
> +
> +  $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make mrproper
> +  $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make sunxi_defconfig
> +
> +To be able to use USB storage, you need to manually enable the corresponding
> +configuration item. Start the kconfig configuration tool:
> +
> +  $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make menuconfig
> +
> +Navigate to the following item, enable it and save your configuration:
> +
> +  Device Drivers > USB support > USB Mass Storage support

Isn't it simpler to run 'echo CONFIG_USB_STORAGE=y >> .config && make 
oldconfig'?

> +
> +Build the Linux kernel with:
> +
> +  $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make -j5

I'm not sure about recommending "-j5" in the doc, not all user have >=4 
SMP system. Maybe we don't care.

> +
> +To boot the newly build linux kernel in QEMU with the Orange Pi PC machine, use:
> +
> +  $ qemu-system-arm -M orangepi-pc -nic user -nographic \
> +      -kernel /path/to/linux/arch/arm/boot/zImage \
> +      -append 'console=ttyS0,115200' \
> +      -dtb /path/to/linux/arch/arm/boot/dts/sun8i-h3-orangepi-pc.dtb
> +
> +Orange Pi PC images
> +~~~~~~~~~~~~~~~~~~~
> +
> +Note that the mainline kernel does not have a root filesystem. You may provide it
> +with an official Orange Pi PC image from the official website:
> +
> +  http://www.orangepi.org/downloadresources/
> +
> +Another possibility is to run an Armbian image for Orange Pi PC which
> +can be downloaded from:
> +
> +   https://www.armbian.com/orange-pi-pc/
> +
> +Alternatively, you can also choose to build you own image with buildroot
> +using the orangepi_pc_defconfig. Also see https://buildroot.org for more information.
> +
> +You can choose to attach the selected image either as an SD card or as USB mass storage.
> +For example, to boot using the Orange Pi PC Debian image on SD card, simply add the -sd
> +argument and provide the proper root= kernel parameter:
> +
> +  $ qemu-system-arm -M orangepi-pc -nic user -nographic \
> +      -kernel /path/to/linux/arch/arm/boot/zImage \
> +      -append 'console=ttyS0,115200 root=/dev/mmcblk0p2' \
> +      -dtb /path/to/linux/arch/arm/boot/dts/sun8i-h3-orangepi-pc.dtb \
> +      -sd OrangePi_pc_debian_stretch_server_linux5.3.5_v1.0.img
> +
> +To attach the image as an USB mass storage device to the machine,
> +simply append to the command:
> +
> +  -drive if=none,id=stick,file=myimage.img \
> +  -device usb-storage,bus=usb-bus.0,drive=stick
> +
> +Instead of providing a custom Linux kernel via the -kernel command you may also
> +choose to let the Orange Pi PC machine load the bootloader from SD card, just like
> +a real board would do using the BootROM. Simply pass the selected image via the -sd
> +argument and remove the -kernel, -append, -dbt and -initrd arguments:
> +
> +  $ qemu-system-arm -M orangepi-pc -nic user -nographic \
> +       -sd Armbian_19.11.3_Orangepipc_buster_current_5.3.9.img
> +
> +Note that both the official Orange Pi PC images and Armbian images start
> +a lot of userland programs via systemd. Depending on the host hardware and OS,
> +they may be slow to emulate, especially due to emulating the 4 cores.
> +To help reduce the performance slow down due to emulating the 4 cores, you can
> +give the following kernel parameters (or via -append):
> +
> +  => setenv extraargs 'systemd.default_timeout_start_sec=9000 loglevel=7 nosmp console=ttyS0,115200'
> +
> +Running U-Boot
> +~~~~~~~~~~~~~~
> +
> +U-Boot mainline can be build and configured using the orangepi_pc_defconfig
> +using similar commands as describe above for Linux. Note that it is recommended
> +for development/testing to select the following configuration setting in U-Boot:
> +
> +  Device Tree Control > Provider for DTB for DT Control > Embedded DTB
> +
> +To start U-Boot using the Orange Pi PC machine, provide the
> +u-boot binary to the -kernel argument:
> +
> +  $ qemu-system-arm -M orangepi-pc -nic user -nographic \
> +      -kernel /path/to/uboot/u-boot -sd disk.img
> +
> +Use the following U-boot commands to load and boot a Linux kernel from SD card:
> +
> +  -> setenv bootargs console=ttyS0,115200
> +  -> ext2load mmc 0 0x42000000 zImage
> +  -> ext2load mmc 0 0x43000000 sun8i-h3-orangepi-pc.dtb
> +  -> bootz 0x42000000 - 0x43000000
> +
> +Running NetBSD
> +~~~~~~~~~~~~~~
> +
> +The NetBSD operating system also includes support for Allwinner H3 based boards,
> +including the Orange Pi PC. NetBSD 9.0 is known to work best for the Orange Pi PC
> +board and provides a fully working system with serial console, networking and storage.
> +
> +Currently NetBSD 9.0 is in testing, but release candidate 1 can be started
> +successfully on the Orange Pi PC machine. Get the 'evbarm-earmv7hf' based image from:
> +
> +  https://cdn.netbsd.org/pub/NetBSD/NetBSD-9.0_RC1/evbarm-earmv7hf/binary/gzimg/armv7.img.gz
> +
> +The image requires manually installing U-Boot in the image. Build U-Boot with
> +the orangepi_pc_defconfig configuration as described in the previous section.
> +Next, unzip the NetBSD image and write the U-Boot binary including SPL using:
> +
> +  $ gunzip armv7.img.gz
> +  $ dd if=/path/to/u-boot-sunxi-with-spl.bin of=armv7.img bs=1024 seek=8 conv=notrunc
> +
> +Start the machine using the following command:
> +
> +  $ qemu-system-arm -M orangepi-pc -nic user -nographic \
> +        -sd armv7.img
> +
> +At the U-Boot stage, interrupt the automatic boot process by pressing a key
> +and set the following environment variables before booting:
> +
> +  => setenv bootargs root=ld0a
> +  => setenv kernel netbsd-GENERIC.ub
> +  => setenv fdtfile dtb/sun8i-h3-orangepi-pc.dtb
> +  => 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}'
> +
> +Optionally you may save the environment variables to SD card with 'saveenv'.
> +To continue booting simply give the 'boot' command and NetBSD boots.
> +
> +Orange Pi PC acceptance tests
> +-----------------------------
> +
> +The Orange Pi PC machine has several acceptance tests included.
> +To run the whole set of tests, build QEMU from source and simply
> +provide the following command:
> +
> +  $ AVOCADO_ALLOW_LARGE_STORAGE=yes avocado --show=app,console run \
> +     -t machine:orangepi-pc tests/acceptance/boot_linux_console.py
> +
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 6e1b92b5fa..b52ac2fb9e 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -488,6 +488,7 @@ S: Maintained
>   F: hw/*/allwinner-h3*
>   F: include/hw/*/allwinner-h3*
>   F: hw/arm/orangepi.c
> +F: docs/orangepi.rst
>   
>   ARM PrimeCell and CMSDK devices
>   M: Peter Maydell <peter.maydell@linaro.org>
>

Hi Philippe,

On Sat, Jan 18, 2020 at 10:38 AM Philippe Mathieu-Daudé <philmd@redhat.com>
wrote:

> On 1/8/20 9:00 PM, Niek Linnenbank wrote:
> > 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>
> > ---
> >   docs/orangepi.rst | 200 ++++++++++++++++++++++++++++++++++++++++++++++
> >   MAINTAINERS       |   1 +
> >   2 files changed, 201 insertions(+)
> >   create mode 100644 docs/orangepi.rst
> >
> > diff --git a/docs/orangepi.rst b/docs/orangepi.rst
> > new file mode 100644
> > index 0000000000..5ac2a7b7cc
> > --- /dev/null
> > +++ b/docs/orangepi.rst
> > @@ -0,0 +1,200 @@
> > +=========================
> > +Orange Pi PC Machine Type
> > +=========================
> > +
> > +The Xunlong Orange Pi PC is an Allwinner H3 System on Chip
> > +based embedded computer with mainline support in both U-Boot
> > +and Linux. The board comes with a Quad Core Cortex A7 @ 1.3GHz,
> > +512MB RAM, 100Mbit ethernet, USB, SD/MMC, USB, HDMI and
> > +various other I/O.
> > +
> > +Supported devices
> > +-----------------
> > +
> > +The Orange Pi PC machine type supports the following devices:
>
> Maybe drop "type"?
>
> > +
> > + * SMP (Quad Core Cortex A7)
> > + * Generic Interrupt Controller configuration
> > + * SRAM mappings
> > + * SDRAM controller
> > + * Real Time Clock
> > + * Timer device (re-used from Allwinner A10)
> > + * UART
> > + * SD/MMC storage controller
> > + * EMAC ethernet connectivity
>
> Drop "connectivity"?
>
> > + * USB 2.0 interfaces
> > + * Clock Control Unit
> > + * System Control module
> > + * Security Identifier device
> > +
> > +Limitations
> > +-----------
> > +
> > +Currently, Orange Pi PC does *not* support the following features:
> > +
> > +- Graphical output via HDMI, GPU and/or the Display Engine
> > +- Audio output
> > +- Hardware Watchdog
> > +
> > +Also see the 'unimplemented' array in the Allwinner H3 SoC module
> > +for a complete list of unimplemented I/O devices:
> > +  ./hw/arm/allwinner-h3.c
> > +
> > +Using the Orange Pi PC machine type
> > +-----------------------------------
> > +
> > +Boot options
> > +~~~~~~~~~~~~
> > +
> > +The Orange Pi PC machine can start using the standard -kernel
> functionality
> > +for loading a Linux kernel or ELF executable. Additionally, the Orange
> Pi PC
> > +machine can also emulate the BootROM which is present on an actual
> Allwinner H3
> > +based SoC, which loads the bootloader from SD card, specified via the
> -sd argument
>
> "from a SD card"?
>
> > +to qemu-system-arm.
> > +
> > +Running mainline Linux
> > +~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +Recently released mainline Linux kernels from 4.19 up to latest master
>
> Drop "Recently released mainline" or only use "Mainline"?
>
> Thanks, I'll correct all comments above.


> > +are known to work. To build a Linux mainline kernel that can be booted
> > +by the Orange Pi PC machine, simply configure the kernel using the
> > +sunxi_defconfig configuration:
> > +
> > +  $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make mrproper
> > +  $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make sunxi_defconfig
> > +
> > +To be able to use USB storage, you need to manually enable the
> corresponding
> > +configuration item. Start the kconfig configuration tool:
> > +
> > +  $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make menuconfig
> > +
> > +Navigate to the following item, enable it and save your configuration:
> > +
> > +  Device Drivers > USB support > USB Mass Storage support
>
> Isn't it simpler to run 'echo CONFIG_USB_STORAGE=y >> .config && make
> oldconfig'?
>

Yes true, that is also a way to enable it. I just wrote it down like this
since using menuconfig
or xconfig is usually the way people are familiar with.


>
> > +
> > +Build the Linux kernel with:
> > +
> > +  $ ARCH=arm CROSS_COMPILE=arm-linux-gnueabi- make -j5
>
> I'm not sure about recommending "-j5" in the doc, not all user have >=4
> SMP system. Maybe we don't care.
>

Thanks, I'll remove the -j5.


>
> > +
> > +To boot the newly build linux kernel in QEMU with the Orange Pi PC
> machine, use:
> > +
> > +  $ qemu-system-arm -M orangepi-pc -nic user -nographic \
> > +      -kernel /path/to/linux/arch/arm/boot/zImage \
> > +      -append 'console=ttyS0,115200' \
> > +      -dtb /path/to/linux/arch/arm/boot/dts/sun8i-h3-orangepi-pc.dtb
> > +
> > +Orange Pi PC images
> > +~~~~~~~~~~~~~~~~~~~
> > +
> > +Note that the mainline kernel does not have a root filesystem. You may
> provide it
> > +with an official Orange Pi PC image from the official website:
> > +
> > +  http://www.orangepi.org/downloadresources/
> > +
> > +Another possibility is to run an Armbian image for Orange Pi PC which
> > +can be downloaded from:
> > +
> > +   https://www.armbian.com/orange-pi-pc/
> > +
> > +Alternatively, you can also choose to build you own image with buildroot
> > +using the orangepi_pc_defconfig. Also see https://buildroot.org for
> more information.
> > +
> > +You can choose to attach the selected image either as an SD card or as
> USB mass storage.
> > +For example, to boot using the Orange Pi PC Debian image on SD card,
> simply add the -sd
> > +argument and provide the proper root= kernel parameter:
> > +
> > +  $ qemu-system-arm -M orangepi-pc -nic user -nographic \
> > +      -kernel /path/to/linux/arch/arm/boot/zImage \
> > +      -append 'console=ttyS0,115200 root=/dev/mmcblk0p2' \
> > +      -dtb /path/to/linux/arch/arm/boot/dts/sun8i-h3-orangepi-pc.dtb \
> > +      -sd OrangePi_pc_debian_stretch_server_linux5.3.5_v1.0.img
> > +
> > +To attach the image as an USB mass storage device to the machine,
> > +simply append to the command:
> > +
> > +  -drive if=none,id=stick,file=myimage.img \
> > +  -device usb-storage,bus=usb-bus.0,drive=stick
> > +
> > +Instead of providing a custom Linux kernel via the -kernel command you
> may also
> > +choose to let the Orange Pi PC machine load the bootloader from SD
> card, just like
> > +a real board would do using the BootROM. Simply pass the selected image
> via the -sd
> > +argument and remove the -kernel, -append, -dbt and -initrd arguments:
> > +
> > +  $ qemu-system-arm -M orangepi-pc -nic user -nographic \
> > +       -sd Armbian_19.11.3_Orangepipc_buster_current_5.3.9.img
> > +
> > +Note that both the official Orange Pi PC images and Armbian images start
> > +a lot of userland programs via systemd. Depending on the host hardware
> and OS,
> > +they may be slow to emulate, especially due to emulating the 4 cores.
> > +To help reduce the performance slow down due to emulating the 4 cores,
> you can
> > +give the following kernel parameters (or via -append):
> > +
> > +  => setenv extraargs 'systemd.default_timeout_start_sec=9000
> loglevel=7 nosmp console=ttyS0,115200'
> > +
> > +Running U-Boot
> > +~~~~~~~~~~~~~~
> > +
> > +U-Boot mainline can be build and configured using the
> orangepi_pc_defconfig
> > +using similar commands as describe above for Linux. Note that it is
> recommended
> > +for development/testing to select the following configuration setting
> in U-Boot:
> > +
> > +  Device Tree Control > Provider for DTB for DT Control > Embedded DTB
> > +
> > +To start U-Boot using the Orange Pi PC machine, provide the
> > +u-boot binary to the -kernel argument:
> > +
> > +  $ qemu-system-arm -M orangepi-pc -nic user -nographic \
> > +      -kernel /path/to/uboot/u-boot -sd disk.img
> > +
> > +Use the following U-boot commands to load and boot a Linux kernel from
> SD card:
> > +
> > +  -> setenv bootargs console=ttyS0,115200
> > +  -> ext2load mmc 0 0x42000000 zImage
> > +  -> ext2load mmc 0 0x43000000 sun8i-h3-orangepi-pc.dtb
> > +  -> bootz 0x42000000 - 0x43000000
> > +
> > +Running NetBSD
> > +~~~~~~~~~~~~~~
> > +
> > +The NetBSD operating system also includes support for Allwinner H3
> based boards,
> > +including the Orange Pi PC. NetBSD 9.0 is known to work best for the
> Orange Pi PC
> > +board and provides a fully working system with serial console,
> networking and storage.
> > +
> > +Currently NetBSD 9.0 is in testing, but release candidate 1 can be
> started
> > +successfully on the Orange Pi PC machine. Get the 'evbarm-earmv7hf'
> based image from:
> > +
> > +
> https://cdn.netbsd.org/pub/NetBSD/NetBSD-9.0_RC1/evbarm-earmv7hf/binary/gzimg/armv7.img.gz
> > +
> > +The image requires manually installing U-Boot in the image. Build
> U-Boot with
> > +the orangepi_pc_defconfig configuration as described in the previous
> section.
> > +Next, unzip the NetBSD image and write the U-Boot binary including SPL
> using:
> > +
> > +  $ gunzip armv7.img.gz
> > +  $ dd if=/path/to/u-boot-sunxi-with-spl.bin of=armv7.img bs=1024
> seek=8 conv=notrunc
> > +
> > +Start the machine using the following command:
> > +
> > +  $ qemu-system-arm -M orangepi-pc -nic user -nographic \
> > +        -sd armv7.img
> > +
> > +At the U-Boot stage, interrupt the automatic boot process by pressing a
> key
> > +and set the following environment variables before booting:
> > +
> > +  => setenv bootargs root=ld0a
> > +  => setenv kernel netbsd-GENERIC.ub
> > +  => setenv fdtfile dtb/sun8i-h3-orangepi-pc.dtb
> > +  => 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}'
> > +
> > +Optionally you may save the environment variables to SD card with
> 'saveenv'.
> > +To continue booting simply give the 'boot' command and NetBSD boots.
> > +
> > +Orange Pi PC acceptance tests
> > +-----------------------------
> > +
> > +The Orange Pi PC machine has several acceptance tests included.
> > +To run the whole set of tests, build QEMU from source and simply
> > +provide the following command:
> > +
> > +  $ AVOCADO_ALLOW_LARGE_STORAGE=yes avocado --show=app,console run \
> > +     -t machine:orangepi-pc tests/acceptance/boot_linux_console.py
> > +
> > diff --git a/MAINTAINERS b/MAINTAINERS
> > index 6e1b92b5fa..b52ac2fb9e 100644
> > --- a/MAINTAINERS
> > +++ b/MAINTAINERS
> > @@ -488,6 +488,7 @@ S: Maintained
> >   F: hw/*/allwinner-h3*
> >   F: include/hw/*/allwinner-h3*
> >   F: hw/arm/orangepi.c
> > +F: docs/orangepi.rst
> >
> >   ARM PrimeCell and CMSDK devices
> >   M: Peter Maydell <peter.maydell@linaro.org>
> >
>
>
Regards,
Niek